@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/real-input-attempt.js

@@ -19,11 +19,11 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
-import { boxCenter, isPointerAction } from '../../portal/input/real-input.js';
+import { ActionType, DriveErrorCode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
-import { asRecord, asString } from '@reticlehq/core';
+import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act/act-helpers.js';
 import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
@@ -228,6 +228,13 @@ function synthetic(reason) {
         ? { result: undefined, settled: false }
         : { result: undefined, settled: false, reason };
 }
+/**
+ * Filler for the provider signature, which demands a box on every action.
+ *
+ * No coordinate is derived from it and none is reported back: `performGesture` returns before it
+ * reads the box on a press, because a key addresses focus rather than a point.
+ */
+const PRESS_HAS_NO_BOX = { x: 0, y: 0, width: 0, height: 0 };
 /**
  * Hover without a native pointer is a false success: synthetic mouseover reports dispatched and
  * settled while CSS `:hover` never applies. Same refusal shape as contenteditable — name the gap
@@ -258,8 +265,10 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (providerReady && provider !== undefined) {
         try {
             const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            // Hover always has a resolved box, so there is always a center to report: the provider's own
+            // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
             if (performed.performed)
-                return hoverSucceeded(performed.center);
+                return hoverSucceeded(performed.center ?? boxCenter(box));
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -295,7 +304,14 @@ export async function tryRealInput(deps, session, ref, action, args) {
         // real debugging time, because the tool description promises a reason is "never silent".
         return askedForNative ? synthetic(InputModeReason.NOT_CONFIGURED) : synthetic();
     }
-    if (!isPointerAction(action))
+    // Two `press`es this module will NOT drive, and neither is a fallback — the reason says which
+    // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
+    if (action === ActionType.PRESS) {
+        const unspellable = unspellablePressReason(ref, inner);
+        if (unspellable !== undefined)
+            return synthetic(unspellable);
+    }
+    if (!isRealInputAction(action))
         return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
     // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
     // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
@@ -307,11 +323,85 @@ export async function tryRealInput(deps, session, ref, action, args) {
     // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
     // rather than "page not correlated" / a silent provider-error fallback — those send the agent
     // hunting a dead context that is not dead.
-    if (session.versionSkew !== undefined) {
+    //
+    // `press` is exempt, and it is the one action where throwing would take something away: a
+    // document key is dispatched entirely in the page, so it does not need CDP at all and has always
+    // worked under skew. Routing it into real input made it reach this line for the first time, and
+    // throwing here would turn a working synthetic press into a hard failure. It falls through to
+    // `isAvailableFor` instead, and a driver that really is dead answers PROVIDER_ERROR with the
+    // usual `fellBack` — still a signal, just not a refusal.
+    if (action !== ActionType.PRESS && session.versionSkew !== undefined) {
         throw new Error(session.versionSkew);
     }
     if (!(await provider.isAvailableFor(session.url)))
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    const key = asString(inner['key']);
+    if (key !== undefined)
+        performArgs.key = key;
+    const modifiers = inner['modifiers'];
+    if (Array.isArray(modifiers)) {
+        performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
+    }
+    // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
+    // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
+    // drove the key instantly and reported a hold that never held.
+    const holdMs = asNumber(inner['holdMs']);
+    if (holdMs !== undefined)
+        performArgs.holdMs = holdMs;
+    // `keys` and `code` are read but not forwarded: both are routed away above — a multi-key sequence
+    // and an explicit physical code have no driver spelling — so carrying them into the provider would
+    // only invite it to guess at a gesture the caller did not ask for.
+    // A document key has no element of its own: skip INSPECT and the box entirely.
+    if (action === ActionType.PRESS) {
+        try {
+            const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
+            if (!performed.performed)
+                return synthetic(InputModeReason.PROVIDER_DECLINED);
+            // No `center`: a key addresses focus, not a point. The placeholder's zero happened nowhere.
+            //
+            // `heldMs` IS forwarded, and it is the whole reason this object is not just the three fields
+            // above: `reticle_act`'s description promises `effect.heldMs` reports the hold actually
+            // achieved, and on the real path the act result IS the `effect` block. Dropping it here made
+            // that promise true on the synthetic path and silently false on the one this release added
+            // `holdMs` to — an agent checking for an armed hold-to-confirm control read `undefined`.
+            return {
+                result: {
+                    performed: true,
+                    action,
+                    inputMode: performed.inputMode,
+                    ...(performed.heldMs !== undefined ? { heldMs: performed.heldMs } : {}),
+                },
+                settled: true,
+            };
+        }
+        catch (error) {
+            // The ONE failure that must not fall back. Every other throw means the gesture did not
+            // happen, and the synthetic path is the honest answer. A release that failed means the
+            // gesture DID happen and the key may still be down — replaying it synthetically presses the
+            // same key a second time on top of a keyboard that is already holding something, which is
+            // the corruption the release exists to prevent. Refusing is the only answer that cannot
+            // make it worse.
+            if (error instanceof DriveError && error.code === DriveErrorCode.RELEASE_FAILED) {
+                throw error;
+            }
+            // No skew re-throw here, unlike the pointer path below: this action has a working synthetic
+            // route (see the skew check above), so the honest answer to a driver that threw is the
+            // fallback, not a refusal.
+            return {
+                result: undefined,
+                settled: false,
+                fellBack: true,
+                reason: InputModeReason.PROVIDER_ERROR,
+            };
+        }
+    }
     const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
     assertNotDestructive(action, inner, inspected);
     const box = asBox(inspected);
@@ -332,13 +422,6 @@ export async function tryRealInput(deps, session, ref, action, args) {
         if (toBox === undefined)
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
     }
-    const performArgs = {};
-    const value = asString(inner['value']);
-    if (value !== undefined)
-        performArgs.value = value;
-    const text = asString(inner['text']);
-    if (text !== undefined)
-        performArgs.text = text;
     if (toBox !== undefined)
         performArgs.toBox = toBox;
     try {

package/dist/surface/tools/reticle-result.d.ts

@@ -0,0 +1,120 @@
+import { Verified, VerdictStatus, type FlowReplayResult, type JournalAction, type SuiteVerdict } from '@reticlehq/core';
+import type { TimedReplay } from '../../judgement/runs/verification-sync.js';
+import type { ToolDeps } from './tool-kit.js';
+export declare const ResultWord: {
+    readonly PROVED: "proved";
+    readonly NOT_PROVED: "not proved";
+    readonly FAILED: "failed";
+};
+export type ResultWord = (typeof ResultWord)[keyof typeof ResultWord];
+/** The output field every result that ends a verification carries. */
+export declare const RESULT_FIELD = "reticleResult";
+export interface ResultFacts {
+    yes: number;
+    no: number;
+    undecided: number;
+    /** The journeys or flows the checks covered. */
+    covered?: readonly string[];
+    /** The journeys, flows or claims that did not hold. */
+    failed?: readonly string[];
+    flowsReplayed?: number;
+    /** Harness journeys answered by replaying saved flows (no model), and driven by the model. */
+    journeysReplayed?: number;
+    journeysDriven?: number;
+    wallMs?: number;
+    screenshots?: readonly string[];
+    /** From `platformLine`. */
+    platform: string;
+}
+/**
+ * Each fact once. The headline carries the check count, so the metrics do not repeat it; with one
+ * check the headline is the whole tally, so the per-word count line is left out.
+ */
+export declare function buildReticleResult(f: ResultFacts): string;
+/**
+ * The same block under a verdict decided above the counts: `reticle_verify { change }` can turn a
+ * green suite into `no` (a channel disagreed) or `unknown` (the flows do not cover the files).
+ */
+export declare function retitleResult(block: string, verified: Verified, because: string): string;
+/** The platform line when the key was refused: one true sentence, and the fix. */
+export declare const KEY_REFUSED_HEAD = "Not on the platform: ";
+/** The line for a key refused for no reason the platform named. */
+export declare const KEY_REFUSED_LINE: string;
+/** The platform line: where the run lives when linked, what linking adds when not. One line. */
+export declare function platformLine(root: string, env: Record<string, string | undefined>, runId?: string): string;
+/**
+ * The block for a replayed suite: the flows are the journeys, each flow's verdict one check, decided
+ * as the run decides it (`mapReplayToFlowResult`): a green a channel contradicted is undecided, as
+ * the suite's `unverifiable` status says, never held.
+ */
+export declare function suiteResult(root: string, verdict: SuiteVerdict, timed: readonly TimedReplay[], runId: string | undefined): string;
+/**
+ * `reticle_verify { change }`'s answer with the block on it. Its verdict is decided ABOVE the suite
+ * (uncovered files, a disagreeing channel), so the suite's own block is retitled with that verdict
+ * and moved to the top level: a nested block saying "proved" under an outer `no` is a false green.
+ */
+export declare function changeResult(root: string, out: unknown): unknown;
+/**
+ * The block for one replayed flow: one check, decided as the synced run decides it — a pass whose
+ * flow asserts nothing, or whose channels disagreed, is undecided, never held.
+ */
+export declare function replayResult(root: string, replay: FlowReplayResult, durationMs: number, runId: string | undefined): string;
+/** What a Harness drive's answer says about itself, as the block reads it. */
+export interface DriveFacts {
+    checks: {
+        held: number;
+        failed: number;
+        undecided: number;
+    };
+    /** The end-state goals the Harness graded itself. */
+    goals: readonly {
+        verified: string;
+    }[];
+    goalMet?: boolean;
+    journeys?: readonly {
+        title: string;
+        status: string;
+        by?: string;
+    }[];
+    runIds?: readonly string[];
+}
+/**
+ * The block for a Harness drive: its checks and its graded goals are the checks; a plan's journeys
+ * are what it covered, with how many were replayed and how many the model drove. Checks that held
+ * over a goal the drive did not reach are not proved, as the answer's own `proved` says.
+ */
+export declare function exploreResult(root: string, drive: DriveFacts): string;
+/**
+ * The block for a session ending: every verdict the journal holds is one check. `no-fault` (nothing
+ * declared) counts as undecided, never as held — a session that proved nothing must not read as one
+ * that proved something.
+ */
+export declare function sessionResult(deps: ToolDeps, sessionId: string, actions: readonly JournalAction[], wallMs: number | undefined, runId?: string): string;
+/**
+ * What an ending agent session reports: its own calls since its previous end in the tab, never the
+ * Harness drives the tab also holds, and the run they are kept under.
+ */
+export declare function endedAgentSession(sessionId: string, actions: readonly JournalAction[], at: number | undefined, claim?: VerdictStatus): {
+    actions: JournalAction[];
+    runId: string;
+    wallMs?: number;
+};
+/**
+ * The agent's own claim beside what grading the session's checks gave: the comparison a dashboard
+ * makes, said where the agent can read it. The claim never becomes the verdict.
+ */
+export declare function claimAgainstGrade(claim: VerdictStatus, actions: readonly JournalAction[]): {
+    claimed: VerdictStatus;
+    graded: VerdictStatus;
+    agrees: boolean;
+};
+/**
+ * A verdict tool's call, remembered until it settles, so a session that ends meanwhile counts it.
+ * An agent ended its session while a `reticle_assert { wait }` was still waiting: the end folded
+ * first ("proved · 1 of 1"), a PASS on the dashboard, and the failure landed in the next run.
+ */
+export declare function trackVerdict<T>(tool: string, call: Promise<T>): Promise<T>;
+/** Resolves once every verdict in flight now has been decided (and journaled). */
+export declare function verdictsSettled(): Promise<void>;
+/** The block as a field, or no field: the block is advice, never the reason a result throws. */
+export declare function resultField(build: () => string): Partial<Record<typeof RESULT_FIELD, string>>;

package/dist/surface/tools/reticle-result.js

@@ -0,0 +1,364 @@
+/**
+ * The "Reticle result" block: what an agent pastes, verbatim, when it finishes verifying.
+ *
+ * Built by the server from facts it already holds, so the wording of a verdict is ours and not the
+ * agent's: an agent asked to summarise an `unknown` tends to summarise it into a pass. Three verdict
+ * words only — proved, not proved, failed — and an undecided check is never proved.
+ *
+ * The last line is the platform line, said once per result and never as a prompt: linked, where the
+ * run is on the dashboard; not linked, what the platform adds and the one command. Nothing here is
+ * measured that was not measured: a metric with no number is left out, never printed as a zero.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { JournalVerdictEffectSchema, ReticleDir, ReticleTool, RunFlowStatus, Verified, VerdictStatus, apiKeyFrom, } from '@reticlehq/core';
+import { JourneyBy } from '@reticlehq/core/artifacts';
+import { runVerdict } from '../../features/harness/drive-report.js';
+import { mapReplayToFlowResult } from '../../judgement/runs/artifact/replay-mapping.js';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { driveRunFrom, driveRunId, endAgentSession } from '../../judgement/runs/drive-run.js';
+import { computeVerdict } from '../../judgement/runs/artifact/build-verification-run.js';
+import { stepShotDir } from '../../memory/project/dir/reticle-dir.js';
+import { TRIAL_OFFER } from '@reticlehq/core/hud';
+import { KEY_REFUSED, dashboardRunUrl, keyRefusalAtLastSync, readDashboardUrl, } from '../../memory/project/sync-status.js';
+import { CONNECT } from './platform-moment.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+export const ResultWord = {
+    PROVED: 'proved',
+    NOT_PROVED: 'not proved',
+    FAILED: 'failed',
+};
+/** The output field every result that ends a verification carries. */
+export const RESULT_FIELD = 'reticleResult';
+/** Paths shown before the rest are counted: enough to open one, not enough to flood a reply. */
+const EVIDENCE_SHOWN = 3;
+const SEP = ' · ';
+const HEAD = '**Reticle result: ';
+const Said = {
+    NOTHING_CHECKED: 'nothing was checked',
+    CHECKS: 'Checks',
+    COVERED: 'Covered',
+    DID_NOT_HOLD: 'Did not hold',
+    METRICS: 'Metrics',
+    EVIDENCE: 'Evidence',
+    RUN_LINK: 'Run on the dashboard',
+    DASHBOARD: 'On the dashboard',
+    SYNCED: 'Saved: the daemon syncs this run to the Reticle platform',
+    PITCH: 'Kept on this machine only. The Reticle platform adds run history, your team and Reticle Harness',
+};
+const plural = (n, word) => `${String(n)} ${word}${1 === n ? '' : 's'}`;
+const seconds = (ms) => ms < 60_000
+    ? `${(ms / 1000).toFixed(1)}s`
+    : `${String(Math.floor(ms / 60_000))}m ${String(Math.round((ms % 60_000) / 1000))}s`;
+function headline(f) {
+    const total = f.yes + f.no + f.undecided;
+    if (0 < f.no)
+        return `${HEAD}${ResultWord.FAILED}**${SEP}${String(f.no)} of ${plural(total, 'check')} did not hold`;
+    if (0 === total)
+        return `${HEAD}${ResultWord.NOT_PROVED}**${SEP}${Said.NOTHING_CHECKED}`;
+    if (0 < f.undecided)
+        return `${HEAD}${ResultWord.NOT_PROVED}**${SEP}${String(f.undecided)} of ${plural(total, 'check')} undecided`;
+    return `${HEAD}${ResultWord.PROVED}**${SEP}${String(f.yes)} of ${plural(total, 'check')} held`;
+}
+/**
+ * The evidence line. Screenshots filed under one run share one folder, so the folder is named once
+ * with the count: three long paths cost a single replay more tokens than its verdict, and its answer
+ * already lists each step's own path.
+ */
+function evidenceLine(shots) {
+    if (0 === shots.length)
+        return [];
+    const dirs = new Set(shots.map((s) => dirname(s)));
+    const [dir] = dirs;
+    if (1 < shots.length && 1 === dirs.size && dir !== undefined)
+        return [`- ${Said.EVIDENCE}: ${plural(shots.length, 'screenshot')} in ${dir}`];
+    const more = shots.length - EVIDENCE_SHOWN;
+    return [
+        `- ${Said.EVIDENCE}: ${shots.slice(0, EVIDENCE_SHOWN).join(', ')}${0 < more ? ` (+${String(more)} more)` : ''}`,
+    ];
+}
+/**
+ * Each fact once. The headline carries the check count, so the metrics do not repeat it; with one
+ * check the headline is the whole tally, so the per-word count line is left out.
+ */
+export function buildReticleResult(f) {
+    const total = f.yes + f.no + f.undecided;
+    const metrics = [
+        ...(f.flowsReplayed === undefined ? [] : [`${plural(f.flowsReplayed, 'flow')} replayed`]),
+        ...(f.journeysReplayed === undefined
+            ? []
+            : [`${plural(f.journeysReplayed, 'journey')} replayed`]),
+        ...(f.journeysDriven === undefined ? [] : [`${plural(f.journeysDriven, 'journey')} driven`]),
+        ...(f.wallMs === undefined ? [] : [seconds(f.wallMs)]),
+    ];
+    return [
+        headline(f),
+        ...(1 < total
+            ? [
+                `- ${Said.CHECKS}: ${String(f.yes)} yes${SEP}${String(f.no)} no${SEP}${String(f.undecided)} undecided`,
+            ]
+            : []),
+        ...(0 < (f.covered?.length ?? 0) ? [`- ${Said.COVERED}: ${(f.covered ?? []).join(', ')}`] : []),
+        ...(0 < (f.failed?.length ?? 0)
+            ? [`- ${Said.DID_NOT_HOLD}: ${(f.failed ?? []).join(', ')}`]
+            : []),
+        ...(0 === metrics.length ? [] : [`- ${Said.METRICS}: ${metrics.join(SEP)}`]),
+        ...evidenceLine(f.screenshots ?? []),
+        f.platform,
+    ].join('\n');
+}
+const WORD_FOR = {
+    [Verified.YES]: ResultWord.PROVED,
+    [Verified.NO]: ResultWord.FAILED,
+    [Verified.UNKNOWN]: ResultWord.NOT_PROVED,
+    [Verified.NO_FAULT]: ResultWord.NOT_PROVED,
+};
+/**
+ * The same block under a verdict decided above the counts: `reticle_verify { change }` can turn a
+ * green suite into `no` (a channel disagreed) or `unknown` (the flows do not cover the files).
+ */
+export function retitleResult(block, verified, because) {
+    const [, ...rest] = block.split('\n');
+    return [`${HEAD}${WORD_FOR[verified]}**${SEP}${because}`, ...rest].join('\n');
+}
+/** The platform line when the key was refused: one true sentence, and the fix. */
+export const KEY_REFUSED_HEAD = 'Not on the platform: ';
+const keyRefusedLine = (why) => `${KEY_REFUSED_HEAD}${why.replace(/\.$/, '')}. Mint a new key in Settings → API keys; the run is kept on this machine`;
+/** The line for a key refused for no reason the platform named. */
+export const KEY_REFUSED_LINE = keyRefusedLine(KEY_REFUSED);
+/** The platform line: where the run lives when linked, what linking adds when not. One line. */
+export function platformLine(root, env, runId) {
+    // Before any link: a run the platform will refuse is not "saved" and not "on the dashboard".
+    const refusal = keyRefusalAtLastSync(root);
+    if (refusal !== undefined)
+        return `- ${keyRefusedLine(refusal)}`;
+    const dashboard = readDashboardUrl(root);
+    if (dashboard !== undefined)
+        return runId === undefined
+            ? `- ${Said.DASHBOARD}: ${dashboard}`
+            : `- ${Said.RUN_LINK}: ${dashboardRunUrl(dashboard, runId)}`;
+    if (existsSync(join(root, ReticleDir.CLOUD_LINK_FILE)) || apiKeyFrom(env) !== undefined)
+        return `- ${Said.SYNCED}.`;
+    return `- ${Said.PITCH} (${TRIAL_OFFER}): ${CONNECT}.`;
+}
+/** Screenshot paths a replay filed, in step order. */
+const replayShots = (replay) => replay.steps.flatMap((s) => s.screenshot !== undefined && 'path' in s.screenshot ? [s.screenshot.path] : []);
+/**
+ * The block for a replayed suite: the flows are the journeys, each flow's verdict one check, decided
+ * as the run decides it (`mapReplayToFlowResult`): a green a channel contradicted is undecided, as
+ * the suite's `unverifiable` status says, never held.
+ */
+export function suiteResult(root, verdict, timed, runId) {
+    const statuses = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs).status);
+    const count = (s) => statuses.filter((each) => s === each).length;
+    return buildReticleResult({
+        yes: count(RunFlowStatus.PASS),
+        no: count(RunFlowStatus.FAIL),
+        undecided: statuses.length - count(RunFlowStatus.PASS) - count(RunFlowStatus.FAIL),
+        covered: timed.map((t) => t.replay.name),
+        failed: verdict.failures.map((f) => f.flow),
+        flowsReplayed: timed.length,
+        wallMs: timed.reduce((sum, t) => sum + t.durationMs, 0),
+        screenshots: timed.flatMap((t) => replayShots(t.replay)),
+        platform: platformLine(root, process.env, runId),
+    });
+}
+/**
+ * `reticle_verify { change }`'s answer with the block on it. Its verdict is decided ABOVE the suite
+ * (uncovered files, a disagreeing channel), so the suite's own block is retitled with that verdict
+ * and moved to the top level: a nested block saying "proved" under an outer `no` is a false green.
+ */
+export function changeResult(root, out) {
+    if (null === out || 'object' !== typeof out)
+        return out;
+    const answer = out;
+    const verified = answer['verified'];
+    if (!Object.values(Verified).includes(verified))
+        return out;
+    const suite = answer['suite'];
+    const inner = null !== suite && 'object' === typeof suite
+        ? suite[RESULT_FIELD]
+        : undefined;
+    const block = 'string' === typeof inner
+        ? inner
+        : buildReticleResult({
+            yes: 0,
+            no: 0,
+            undecided: 0,
+            platform: platformLine(root, process.env),
+        });
+    const because = 'string' === typeof answer['because'] ? answer['because'] : '';
+    return {
+        ...answer,
+        ...('string' === typeof inner
+            ? {
+                suite: Object.fromEntries(Object.entries(suite).filter(([k]) => RESULT_FIELD !== k)),
+            }
+            : {}),
+        [RESULT_FIELD]: retitleResult(block, verified, because),
+    };
+}
+/** Claims named before the rest are counted: a session can hold dozens. */
+const COVERED_SHOWN = 5;
+const capped = (items, shown) => items.length <= shown
+    ? [...items]
+    : [...items.slice(0, shown), `(+${String(items.length - shown)} more)`];
+/** The step screenshots a drive filed under its run, or none: evidence is listed, never assumed. */
+function shotsOf(root, runId) {
+    try {
+        const dir = stepShotDir(root, runId);
+        return readdirSync(dir)
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The block for one replayed flow: one check, decided as the synced run decides it — a pass whose
+ * flow asserts nothing, or whose channels disagreed, is undecided, never held.
+ */
+export function replayResult(root, replay, durationMs, runId) {
+    const status = mapReplayToFlowResult(replay, durationMs).status;
+    const held = RunFlowStatus.PASS === status;
+    const failed = RunFlowStatus.FAIL === status;
+    return buildReticleResult({
+        yes: held ? 1 : 0,
+        no: failed ? 1 : 0,
+        undecided: held || failed ? 0 : 1,
+        covered: [replay.name],
+        ...(failed ? { failed: [replay.name] } : {}),
+        flowsReplayed: 1,
+        wallMs: durationMs,
+        screenshots: replayShots(replay),
+        platform: platformLine(root, process.env, runId),
+    });
+}
+const MSG_GOAL_NOT_REACHED = 'the drive did not reach its goal';
+/**
+ * The block for a Harness drive: its checks and its graded goals are the checks; a plan's journeys
+ * are what it covered, with how many were replayed and how many the model drove. Checks that held
+ * over a goal the drive did not reach are not proved, as the answer's own `proved` says.
+ */
+export function exploreResult(root, drive) {
+    // The checks, counted once and as the run's own summary counts them: the graded goals decide
+    // `goalMet` (and the headline below) and were added on top, so one run read "2 of 2 check(s)
+    // held" in its summary and "3 of 3" here.
+    const yes = drive.checks.held;
+    const no = drive.checks.failed;
+    const undecided = drive.checks.undecided;
+    const journeys = drive.journeys ?? [];
+    const by = (b) => journeys.filter((j) => b === j.by).length;
+    const answered = journeys.some((j) => j.by !== undefined);
+    const block = buildReticleResult({
+        yes,
+        no,
+        undecided,
+        ...(0 === journeys.length
+            ? {}
+            : {
+                covered: capped(journeys.map((j) => j.title), COVERED_SHOWN),
+                failed: journeys.filter((j) => 'failed' === j.status).map((j) => j.title),
+            }),
+        ...(answered
+            ? { journeysReplayed: by(JourneyBy.REPLAY), journeysDriven: by(JourneyBy.MODEL) }
+            : {}),
+        screenshots: (drive.runIds ?? []).flatMap((id) => shotsOf(root, id)),
+        platform: platformLine(root, process.env, drive.runIds?.[0]),
+    });
+    // A plan's verdict is its journeys' (the same line the run ends on), never a count beside it.
+    if (0 < journeys.length) {
+        const { verified: word, line } = runVerdict(drive.checks, drive.goalMet, journeys);
+        return WORD_FOR[word] === headWord(block)
+            ? block
+            : retitleResult(block, word, (line.split(' — ')[1] ?? line).replace(/\.$/, ''));
+    }
+    return 0 === no && 0 === undecided && 0 < yes && false === drive.goalMet
+        ? retitleResult(block, Verified.UNKNOWN, MSG_GOAL_NOT_REACHED)
+        : block;
+}
+/** The verdict word a block's headline carries. */
+function headWord(block) {
+    return block.slice(HEAD.length).split('**')[0];
+}
+/**
+ * The block for a session ending: every verdict the journal holds is one check. `no-fault` (nothing
+ * declared) counts as undecided, never as held — a session that proved nothing must not read as one
+ * that proved something.
+ */
+export function sessionResult(deps, sessionId, actions, wallMs, runId = driveRunId(sessionId)) {
+    const gap = gapSummary(actions);
+    const held = [
+        ...new Set(actions.flatMap((a) => {
+            const v = JournalVerdictEffectSchema.safeParse(a.effect);
+            return v.success && Verified.YES === v.data.verified ? [v.data.claim] : [];
+        })),
+    ];
+    // The session's project, never wherever the daemon was launched.
+    const root = sessionRoot(deps, sessionId);
+    return buildReticleResult({
+        yes: gap.held,
+        no: gap.failed,
+        undecided: gap.undecided + gap.nothingToProve,
+        covered: capped(held, COVERED_SHOWN),
+        failed: capped(gap.failures.map((f) => f.claim), COVERED_SHOWN),
+        ...(wallMs === undefined ? {} : { wallMs }),
+        screenshots: shotsOf(root, runId),
+        platform: platformLine(root, process.env, 0 < gap.claims ? runId : undefined),
+    });
+}
+/**
+ * What an ending agent session reports: its own calls since its previous end in the tab, never the
+ * Harness drives the tab also holds, and the run they are kept under.
+ */
+export function endedAgentSession(sessionId, actions, at, claim) {
+    return endAgentSession(sessionId, actions, at, claim);
+}
+/**
+ * The agent's own claim beside what grading the session's checks gave: the comparison a dashboard
+ * makes, said where the agent can read it. The claim never becomes the verdict.
+ */
+export function claimAgainstGrade(claim, actions) {
+    const run = driveRunFrom(actions, { runId: 'claim' });
+    // computeVerdict decides it, once: a failed check beside a passed one is a fail there too.
+    const graded = run === undefined ? VerdictStatus.UNKNOWN : computeVerdict(run).status;
+    return { claimed: claim, graded, agrees: claim === graded };
+}
+/** The tools whose verdicts an agent session's block counts: each one is one of its checks. */
+const SESSION_VERDICT_TOOLS = new Set([
+    ReticleTool.ACT_AND_WAIT,
+    // `reticle_act { steps }` dispatches under ACT's name: a journey still grading is waited for too.
+    ReticleTool.ACT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ASSERT,
+    ReticleTool.WAIT_FOR,
+]);
+/** Verdicts being decided right now. ponytail: daemon-wide, not per tab; an end waits for all. */
+const inFlight = new Set();
+/**
+ * A verdict tool's call, remembered until it settles, so a session that ends meanwhile counts it.
+ * An agent ended its session while a `reticle_assert { wait }` was still waiting: the end folded
+ * first ("proved · 1 of 1"), a PASS on the dashboard, and the failure landed in the next run.
+ */
+export function trackVerdict(tool, call) {
+    if (!SESSION_VERDICT_TOOLS.has(tool))
+        return call;
+    const settled = call.then(() => undefined, () => undefined);
+    inFlight.add(settled);
+    void settled.then(() => inFlight.delete(settled));
+    return call;
+}
+/** Resolves once every verdict in flight now has been decided (and journaled). */
+export async function verdictsSettled() {
+    await Promise.all([...inFlight]);
+}
+/** The block as a field, or no field: the block is advice, never the reason a result throws. */
+export function resultField(build) {
+    try {
+        return { [RESULT_FIELD]: build() };
+    }
+    catch {
+        return {};
+    }
+}