@reticlehq/server 3.4.0 → 3.6.0

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

@@ -6,9 +6,13 @@
  */
 import { ReplayStatus, RUN_RECORDING_MAX_BYTES, RUN_STEP_RESULTS_MAX, RUN_TEXT_MAX, RunFlowStatus, } from '@reticlehq/core';
 import { SUCCESS_STEP_TOOL } from '../../../language/flows/flow-success.js';
-/** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
+/** OK → PASS; UNVERIFIABLE → SKIPPED; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export function runFlowStatusOf(status) {
-    return status === ReplayStatus.OK ? RunFlowStatus.PASS : RunFlowStatus.FAIL;
+    if (status === ReplayStatus.OK)
+        return RunFlowStatus.PASS;
+    if (status === ReplayStatus.UNVERIFIABLE)
+        return RunFlowStatus.SKIPPED;
+    return RunFlowStatus.FAIL;
 }
 const clip = (text) => text.length > RUN_TEXT_MAX ? `${text.slice(0, RUN_TEXT_MAX - 1)}…` : text;
 /** One step as synced: what it did, where, and whether it held. */
@@ -39,9 +43,12 @@ function recordingOf(flow) {
 }
 /** 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 returns OK with no steps. Nothing ran, so it is SKIPPED — which
-    // every reader of a run (the verdict, the gate) already refuses to count as a pass.
-    const status = replay.unverifiable === undefined ? runFlowStatusOf(replay.status) : RunFlowStatus.SKIPPED;
+    // 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
+        ? RunFlowStatus.SKIPPED
+        : runFlowStatusOf(replay.status);
     const failureReason = replay.unverifiable !== undefined
         ? replay.unverifiable.reason
         : status === RunFlowStatus.FAIL
@@ -49,13 +56,16 @@ export function mapReplayToFlowResult(replay, durationMs, flow) {
                 replay.decision?.summary ??
                 replay.error?.message ??
                 'flow failed')
-            : undefined;
+            : 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.
     const oracle = replay.steps.find((s) => s.tool === SUCCESS_STEP_TOOL)?.anchor;
     return {
         name: replay.name,
+        ...(flow?.template === undefined ? {} : { template: flow.template }),
         status,
         steps: replay.steps.length,
         durationMs,

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

@@ -38,7 +38,7 @@ export declare class RunStore {
      * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
      * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
      */
-    write(run: ReticleVerificationRun): Promise<void>;
+    write(given: ReticleVerificationRun): Promise<void>;
     /** Never throws. Invalid id / missing → MISSING; bad JSON or failed schema → MALFORMED. */
     read(runId: RunId): Promise<ReadRunResult>;
     /** List run ids on disk (filenames minus.json). Empty when the runs dir is absent. */

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

@@ -6,10 +6,13 @@
  * needs no clock.
  */
 import { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, } from '@reticlehq/core';
+import { PromptContextSchema } from '@reticlehq/core/artifacts';
 import { reticleDirPaths, isValidRunId, runPath } from '../../../memory/project/dir/reticle-dir.js';
 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;
 export class RunStore {
     #fs;
     #root;
@@ -28,11 +31,15 @@ export class RunStore {
      * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
      * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
      */
-    async write(run) {
+    async write(given) {
+        let run = given;
         if (!isValidRunId(run.runId)) {
             throw new Error(`refusing to write run with unsafe runId: ${JSON.stringify(run.runId)}`);
         }
         await this.#fs.mkdir(reticleDirPaths(this.#root).runs);
+        const context = run.context ?? (await this.#recentRequest(run.createdAt));
+        if (context !== undefined)
+            run = { ...run, context };
         // 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);
@@ -49,6 +56,24 @@ export class RunStore {
         }
         await this.#pruneOld();
     }
+    /**
+     * 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) {
+        try {
+            const parsed = PromptContextSchema.safeParse(JSON.parse(await this.#fs.readFile(reticleDirPaths(this.#root).request)));
+            if (!parsed.success)
+                return undefined;
+            const given = parsed.data.at;
+            return given !== undefined && 0 <= at - given && at - given <= REQUEST_RELEVANT_MS
+                ? parsed.data
+                : undefined;
+        }
+        catch {
+            return undefined; // no request recorded: the common case
+        }
+    }
     /**
      * Keep .reticle/runs/ bounded. Only acts once the count exceeds RUN_RETENTION + SLACK, then deletes the
      * oldest (by createdAt) back down to RUN_RETENTION — so the read-all is amortized, not per-write.

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

@@ -59,3 +59,25 @@ export declare function driveRunId(sessionId: string): string;
  * 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;
+/** What a Harness run says drove it, in the dashboard's "Driven by" line. */
+export declare function harnessAgentId(driver: string): string;
+/**
+ * The id of the run a Harness drive syncs as, so whoever started the drive can find it again (the
+ * platform's chat folds the run into the check it asked for). Undefined for an id no run can carry.
+ */
+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.
+ */
+export declare function noteHarnessGoal(harness: string, met: boolean | undefined): void;
+/**
+ * Every run a session's journal holds: the connected agent's drive, and one per Harness drive.
+ *
+ * They used to be one. A Harness drive dispatches through the same tools in the same tab, so its
+ * verdicts folded into the agent's run, and the dashboard showed one blended row that credited the
+ * agent with what the Harness proved and named neither.
+ */
+export declare function driveRunsFrom(actions: readonly JournalAction[], deps: DriveRunDeps): VerificationRunInput[];

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

@@ -24,7 +24,7 @@
  */
 import { isValidRunId } from '../../memory/project/dir/reticle-dir.js';
 import { defaultRunId } from './runner-port.js';
-import { JournalVerdictEffectSchema, RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { JournalVerdictEffectSchema, RunAgentKind, RunFramework, RunProfile, RunTrigger, RunFlowStatus, Verified, } 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';
@@ -133,3 +133,101 @@ export function driveRunFrom(actions, deps) {
         evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
     };
 }
+/** Marks a run as one Harness drive, so it never collides with the session's own `drive-` run. */
+const HARNESS_RUN_PREFIX = 'harness-';
+/** What a Harness run says drove it, in the dashboard's "Driven by" line. */
+export function harnessAgentId(driver) {
+    return 'server' === driver ? 'Reticle Harness (platform)' : `Reticle Harness (${driver})`;
+}
+/**
+ * The id of the run a Harness drive syncs as, so whoever started the drive can find it again (the
+ * platform's chat folds the run into the check it asked for). Undefined for an id no run can carry.
+ */
+export function harnessRunId(harness) {
+    const candidate = `${HARNESS_RUN_PREFIX}${harness}`;
+    return isValidRunId(candidate) ? candidate : undefined;
+}
+/** The journey a Harness drive was named for, or what it did when nobody named one. */
+const UNNAMED_JOURNEY = 'Harness drive';
+/** Goal verdicts kept for the drives a session has not yet been graded on. */
+const MAX_GOALS_HELD = 200;
+const goalsMissed = new Map();
+/**
+ * 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.
+ */
+export function noteHarnessGoal(harness, met) {
+    if (met === undefined)
+        return;
+    const before = goalsMissed.get(harness);
+    if (false === before)
+        return;
+    if (MAX_GOALS_HELD <= goalsMissed.size && !goalsMissed.has(harness)) {
+        const oldest = goalsMissed.keys().next().value;
+        if (oldest !== undefined)
+            goalsMissed.delete(oldest);
+    }
+    goalsMissed.set(harness, met);
+}
+/**
+ * One Harness drive, as its own run: named for the journey it was asked to complete, and credited to
+ * the Harness rather than to the agent whose tab it shared. The journey reads as one flow, failed
+ * when any check it declared came back no, passed when one came back yes and none failed.
+ */
+function harnessRunFrom(by, actions, deps) {
+    const input = driveRunFrom(actions, {
+        ...deps,
+        runId: harnessRunId(by.harness) ?? defaultRunId(),
+    });
+    if (input === undefined)
+        return undefined;
+    const statuses = input.checks.map((check) => check.status);
+    const status = statuses.includes(Verified.NO) || false === goalsMissed.get(by.harness)
+        ? RunFlowStatus.FAIL
+        : statuses.includes(Verified.YES)
+            ? RunFlowStatus.PASS
+            : RunFlowStatus.SKIPPED;
+    const first = actions.reduce((min, action) => Math.min(min, action.at), Number.MAX_SAFE_INTEGER);
+    return {
+        ...input,
+        durationMs: Math.max(0, input.durationMs - first),
+        agent: { id: harnessAgentId(by.driver), kind: RunAgentKind.CODING_AGENT },
+        trigger: {
+            kind: RunTrigger.EDIT,
+            note: `driven by the Harness${by.persona === undefined ? '' : `: ${by.persona}`}`,
+        },
+        flows: [
+            {
+                name: by.persona ?? UNNAMED_JOURNEY,
+                status,
+                steps: actions.length,
+                durationMs: Math.max(0, input.durationMs - first),
+            },
+        ],
+    };
+}
+/**
+ * Every run a session's journal holds: the connected agent's drive, and one per Harness drive.
+ *
+ * They used to be one. A Harness drive dispatches through the same tools in the same tab, so its
+ * verdicts folded into the agent's run, and the dashboard showed one blended row that credited the
+ * agent with what the Harness proved and named neither.
+ */
+export function driveRunsFrom(actions, deps) {
+    const own = actions.filter((action) => action.drivenBy === undefined);
+    const drives = new Map();
+    for (const action of actions) {
+        const by = action.drivenBy;
+        if (by === undefined)
+            continue;
+        const held = drives.get(by.harness) ?? { by, actions: [] };
+        held.actions.push(action);
+        drives.set(by.harness, held);
+    }
+    return [
+        driveRunFrom(own, deps),
+        ...[...drives.values()].map((drive) => harnessRunFrom(drive.by, drive.actions, deps)),
+    ].filter((run) => run !== undefined);
+}

package/dist/judgement/runs/repair-prompt.js

@@ -46,7 +46,7 @@ function deviationHeadline(deviation) {
     return undefined;
 }
 export function buildRepairPacket(replay) {
-    if (replay.status === ReplayStatus.OK)
+    if (replay.status === ReplayStatus.OK || replay.status === ReplayStatus.UNVERIFIABLE)
         return undefined;
     const decision = replay.decision;
     const baseActual = decision?.whatChanged ?? replay.error?.message ?? 'the flow failed';

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

@@ -85,7 +85,14 @@ export class ReticleRunner {
             flows,
             checks: [],
             risks,
-            evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
+            // What the replay windows saw. An empty list written here regardless read as a clean
+            // console on a run whose steps had counted errors (#1344).
+            evidence: {
+                consoleErrors: replays.flatMap((r) => r.steps.flatMap((step) => step.consoleErrors ?? [])),
+                networkAnomalies: [],
+                stateAssertions: [],
+                timeline: [],
+            },
             ...(failurePackets.length > 0 ? { repair: { failurePackets } } : {}),
         };
         const run = buildVerificationRun(input, () => this.#port.now());

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

@@ -1,4 +1,5 @@
-import { type ProjectId, type FlowFile, type FlowReplayResult } from '@reticlehq/core';
+import { type FlowFile, type FlowReplayResult } from '@reticlehq/core';
+import { type ProjectTarget } from '../../memory/project/session-root.js';
 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 {
@@ -12,4 +13,4 @@ export interface TimedReplay {
  * 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>;
+export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], target: ProjectTarget): Promise<string | undefined>;

package/dist/judgement/runs/verification-sync.js

@@ -18,7 +18,7 @@ import { RunStore } from './artifact/run-store.js';
 import { cloudFetch, syncRunToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
 import { log } from '../../log.js';
-import { rootForProjectId } from '../../memory/project/session-root.js';
+import { rootForTarget } from '../../memory/project/session-root.js';
 /** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
 const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
@@ -57,7 +57,8 @@ function assembleRun(deps, timed, projectId) {
  * 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 async function persistAndSyncVerificationRun(deps, timed, projectId) {
+export async function persistAndSyncVerificationRun(deps, timed, target) {
+    const { projectId } = target;
     if (0 === timed.length)
         return undefined;
     let run;
@@ -66,7 +67,7 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     // decides WHICH DASHBOARD this run is pushed to. The daemon's own directory has no link file, so
     // a misrouted read silently meant "not attached" — and where it DID have one, the run was pushed
     // to a dashboard belonging to whoever that checkout was linked to.
-    const root = rootForProjectId(deps, projectId);
+    const root = rootForTarget(deps, target);
     try {
         run = assembleRun(deps, timed, projectId);
         await new RunStore(deps.fs, root).write(run);

package/dist/language/flows/change/gate.d.ts

@@ -5,6 +5,7 @@
  * unexplained flake that blocks a merge destroys trust in the red. Pure decision; the CLI computes the
  * inputs (git diff → affected → run artifacts + flake ledger) and maps `pass` to the exit code.
  */
+import { type RunFlowResult } from '@reticlehq/core';
 /** A flow whose assertions were WEAKENED since its last passing run. */
 interface DowngradedFlow {
     flow: string;
@@ -56,4 +57,13 @@ interface GateResult {
     unexecuted: string[];
 }
 export declare function gateDecision(input: GateInput): GateResult;
+/**
+ * The flows a run lets the gate count as passing.
+ *
+ * Every PASS or HEALED flow by its own name, as before. A generated copy of a template also credits
+ * the template, but only on a STRICT pass that proved a consequence (#1321): a suite replays runtime
+ * copies with fixture parameters and deletes them, so their own names match no saved flow. A healed
+ * anchor, a failed or unverifiable replay, and a pass that checked nothing credit nothing.
+ */
+export declare function passingFlowNames(flows: readonly RunFlowResult[]): string[];
 export {};

package/dist/language/flows/change/gate.js

@@ -5,6 +5,7 @@
  * unexplained flake that blocks a merge destroys trust in the red. Pure decision; the CLI computes the
  * inputs (git diff → affected → run artifacts + flake ledger) and maps `pass` to the exit code.
  */
+import { RunFlowStatus } from '@reticlehq/core';
 export function gateDecision(input) {
     const passing = new Set(input.passing);
     const flaky = new Set(input.flaky ?? []);
@@ -42,3 +43,24 @@ export function gateDecision(input) {
         unexecuted,
     };
 }
+/**
+ * The flows a run lets the gate count as passing.
+ *
+ * Every PASS or HEALED flow by its own name, as before. A generated copy of a template also credits
+ * the template, but only on a STRICT pass that proved a consequence (#1321): a suite replays runtime
+ * copies with fixture parameters and deletes them, so their own names match no saved flow. A healed
+ * anchor, a failed or unverifiable replay, and a pass that checked nothing credit nothing.
+ */
+export function passingFlowNames(flows) {
+    const names = new Set();
+    for (const f of flows) {
+        if (f.status !== RunFlowStatus.PASS && f.status !== RunFlowStatus.HEALED)
+            continue;
+        names.add(f.name);
+        const proved = f.oracle !== undefined ||
+            (f.stepResults ?? []).some((s) => s.ok && s.consequence !== undefined);
+        if (f.template !== undefined && f.status === RunFlowStatus.PASS && proved)
+            names.add(f.template);
+    }
+    return [...names];
+}

package/dist/language/flows/decision.js

@@ -123,6 +123,35 @@ invoked = new Map()) {
                     : 'the action ran and the expected consequence never appeared — check the handler behind it, or whether this flow needs a state it did not start in. The locator is not the problem.',
             };
         }
+        /*
+         * An anchor that matched SEVERAL elements is not an element that is gone, and the advice below
+         * says it is.
+         *
+         * `ANCHOR_AMBIGUOUS` carries `nearest: null` and `ambiguous: true`, so it fell through to the
+         * last line of this branch — "the anchored element is gone; rebind or update the flow" — for a
+         * locator that resolved several times over and lost nothing. Rebind TO WHAT is the question the
+         * drift just refused to answer; sending the reader looking for a replacement locator is the
+         * opposite of the fix, which is a NARROWER anchor on the one they already have.
+         *
+         * The same sentence was already wrong for a testid ambiguity (it is why `ambiguous: true` exists
+         * on that drift at all), and the role and component runners make it reachable for two more
+         * anchor kinds. The distinction this branch has to keep is the one it was written for: a
+         * CONSEQUENCE that never appeared has no anchor problem, an AMBIGUOUS anchor has nothing else.
+         */
+        if (DriftReason.ANCHOR_AMBIGUOUS === drift.reasonKind) {
+            return {
+                verdict: 'drift',
+                summary: withIntent(`"${name}" drifted at step ${step.step} (${step.anchor}) — the anchor is ambiguous.`, intentSaid),
+                whatChanged: drift.reason,
+                // The step's OWN anchor is the thing at fault here, so its source file is the right place to
+                // look — unlike the consequence case above, where the recorded source belongs to the element
+                // that was acted on and the anchor is not what failed.
+                ...(where !== undefined ? { whereInSource: where } : {}),
+                nextAction: 'the anchor matched several elements, so which one the recording meant is not decidable. ' +
+                    'Narrow the anchor on this step — a unique testid, or a role+name that only one control ' +
+                    'has — rather than rebinding it; nothing here says the element was renamed or removed.',
+            };
+        }
         const fix = drift.nearest !== null && drift.ambiguous !== true
             ? `rebind the anchor to "${drift.nearest}" (closest survivor)`
             : drift.nearest !== null
@@ -207,6 +236,11 @@ isolation) {
     const unverifiable = [];
     let passed = 0;
     for (const { replay, flow } of runs) {
+        if (replay.status === ReplayStatus.UNVERIFIABLE) {
+            const reason = replay.unverifiable?.reason ?? unverifiableReason(flow) ?? 'the flow could not be graded';
+            unverifiable.push({ flow: replay.name, reason });
+            continue;
+        }
         if (replay.status === ReplayStatus.OK) {
             /*
              * The REPLAY's own answer first, then the grader's.

package/dist/language/flows/flow-anchor.d.ts

@@ -29,17 +29,63 @@ export declare function nearestIsAmbiguous(missing: string, present: string[]):
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
 export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
 /**
- * Build the drift for a step whose anchor matched MORE THAN ONE live element.
+ * What the stale-ref retry found when it ran the locator again.
  *
- * `ambiguous: true` is set because that is exactly what it is, and it is the field heal already
- * reads to refuse an auto-rebind -- an ambiguous drift must never be healed to an arbitrary pick,
- * which is the same reasoning that made this a drift instead of a note in the first place.
+ * A discriminated result rather than the bare `string | undefined` this started as, because the two
+ * ways of getting no ref back are different answers and were arriving as one. `{ drift }` says the
+ * locator now names SEVERAL elements — the re-render turned an unambiguous anchor into an ambiguous
+ * one, and the fix is a NARROWER anchor. `undefined` says it named none, or named one and the second
+ * dispatch failed too; both of those are already told truthfully by the stale-ref error the first
+ * attempt produced, so there is nothing to add.
  *
- * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
- * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
- * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ * Collapsed together, the ambiguous case was reported as "ref 'e-orig' no longer resolves to an
+ * element" — a sentence about an element that is GONE, sent for an element that is now three. An
+ * agent reading it hunts for a rename or re-records the flow; the truth is that the anchor needs
+ * narrowing, which is the whole reason `ANCHOR_AMBIGUOUS` exists as its own reason kind.
  */
-export declare function ambiguousAnchorDrift(value: string, matches: number): Drift;
+export type Reresolved = {
+    readonly ref: string;
+} | {
+    readonly drift: Drift;
+};
+/**
+ * The ambiguity rule itself: an anchor that matched several live elements is DRIFT, never a guess.
+ *
+ * Returns null when the locator named zero or one element, so a runner reads it as
+ * `const drift = ambiguityDrift(anchor, refs); if (drift !== null) return { …, ok: false, drift };`
+ * and never has to reconstruct the record itself.
+ *
+ * ONE function, because three anchor kinds ask the same question and each used to answer for itself.
+ * testid was fixed first and role second, and role's fix was written as a copy of testid's — so "is
+ * this ambiguous" had two answers and COMPONENT had none at all. `runComponentStep` took `refs[0]`,
+ * dispatched and returned `ok: true` whenever `by:'component'` matched several elements, which is the
+ * ordinary case for a component rendered once per row (a table row's action button). The verdict
+ * reads `drift` and `ok` and nothing else, so that green was indistinguishable from a replay that did
+ * what it did before — the #1227 defect, one anchor kind over.
+ *
+ * The caller must not dispatch before checking. Acting and then reporting drift would leave the app
+ * changed by a click nobody can attribute, which is worse than the ambiguity it reports.
+ */
+export declare function ambiguityDrift(anchor: FlowAnchor, refs: readonly string[]): Drift | null;
+/**
+ * The one ref a step means: the only match, or the recorded position among same-named controls
+ * while the page still has exactly as many of them as when it was recorded. Otherwise undefined.
+ */
+export declare function refFor(anchor: object, refs: readonly string[]): string | undefined;
+/**
+ * The anchor as the stale-ref RETRY found it: one ref to dispatch at, an ambiguity to report, or
+ * neither.
+ *
+ * The same rule as `ambiguityDrift`, one layer deeper, and shared for the same reason: a re-render
+ * can turn an unambiguous anchor into an ambiguous one between the two dispatches, and dispatching
+ * at the first of the new matches would re-make the guess the caller's own check exists to refuse —
+ * in a place the caller cannot see. Written once so the three runners cannot answer it differently,
+ * which is how the component runner came to have no answer at all.
+ *
+ * `refs[0]` is read only after `ambiguityDrift` has cleared the several-match case, so the only way
+ * it is undefined here is zero matches.
+ */
+export declare function reresolved(anchor: FlowAnchor, refs: readonly string[]): Reresolved | undefined;
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

package/dist/language/flows/flow-anchor.js

@@ -139,6 +139,34 @@ export function testidDrift(value, hint) {
         drift.ambiguous = true;
     return drift;
 }
+/**
+ * How an anchor is ADDRESSED — the sentence that names it, and the label a result row carries.
+ *
+ * Two different strings, and neither can be derived from the other: `value` is a raw testid for one
+ * anchor kind and a human-readable label for the others, so one sentence cannot name both. Calling a
+ * role anchor `testid "button "View result""` sends the reader to edit a locator that does not exist
+ * on that step, which is the same misdirection the drift reason exists to remove.
+ *
+ * Derived from the anchor rather than passed in by the caller. The first version of the role fix took
+ * a `described` argument and wrote `ambiguousAnchorDrift(label, n, \`role anchor ${label}\`)` — the
+ * same string twice, so the `anchor` field and the sentence could drift apart with nothing to catch
+ * it, and the next anchor kind would have had to remember the convention on its own.
+ */
+function anchorAddress(anchor) {
+    if (anchor.kind === AnchorKind.TESTID) {
+        return { described: `testid "${anchor.value}"`, label: anchor.value };
+    }
+    if (anchor.kind === AnchorKind.ROLE) {
+        // Kind named explicitly: `button "View result"` alone reads as a testid that happens to contain
+        // a space, and the reader would go looking for a locator nothing on the step declares.
+        const label = `${anchor.role} "${String(anchor.name)}"`;
+        return { described: `role anchor ${label}`, label };
+    }
+    // A component needs no such qualifier: `componentLabel` already answers
+    // `NewDeployButton@Deployments.tsx:107`, which no reader mistakes for a testid.
+    const label = anchor.kind === AnchorKind.COMPONENT ? componentLabel(anchor) : anchorLabel(anchor);
+    return { described: `anchor ${label}`, label };
+}
 /**
  * Build the drift for a step whose anchor matched MORE THAN ONE live element.
  *
@@ -149,16 +177,73 @@ export function testidDrift(value, hint) {
  * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
  * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
  * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ *
+ * Private: callers reach it through `ambiguityDrift`, which is the RULE rather than the record.
+ * Exported, it had three call sites and a fourth anchor kind that never called it at all.
  */
-export function ambiguousAnchorDrift(value, matches) {
+function ambiguousAnchorDrift(anchor, matches) {
+    const { described, label } = anchorAddress(anchor);
     return {
         reasonKind: DriftReason.ANCHOR_AMBIGUOUS,
-        reason: `testid "${value}" matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
-        anchor: value,
+        reason: `${described} matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
+        anchor: label,
         nearest: null,
         ambiguous: true,
     };
 }
+/**
+ * The ambiguity rule itself: an anchor that matched several live elements is DRIFT, never a guess.
+ *
+ * Returns null when the locator named zero or one element, so a runner reads it as
+ * `const drift = ambiguityDrift(anchor, refs); if (drift !== null) return { …, ok: false, drift };`
+ * and never has to reconstruct the record itself.
+ *
+ * ONE function, because three anchor kinds ask the same question and each used to answer for itself.
+ * testid was fixed first and role second, and role's fix was written as a copy of testid's — so "is
+ * this ambiguous" had two answers and COMPONENT had none at all. `runComponentStep` took `refs[0]`,
+ * dispatched and returned `ok: true` whenever `by:'component'` matched several elements, which is the
+ * ordinary case for a component rendered once per row (a table row's action button). The verdict
+ * reads `drift` and `ok` and nothing else, so that green was indistinguishable from a replay that did
+ * what it did before — the #1227 defect, one anchor kind over.
+ *
+ * The caller must not dispatch before checking. Acting and then reporting drift would leave the app
+ * changed by a click nobody can attribute, which is worse than the ambiguity it reports.
+ */
+export function ambiguityDrift(anchor, refs) {
+    return refs.length > 1 && refFor(anchor, refs) === undefined
+        ? ambiguousAnchorDrift(anchor, refs.length)
+        : null;
+}
+/**
+ * The one ref a step means: the only match, or the recorded position among same-named controls
+ * while the page still has exactly as many of them as when it was recorded. Otherwise undefined.
+ */
+export function refFor(anchor, refs) {
+    if (1 === refs.length)
+        return refs[0];
+    const { nth, of } = { ...anchor };
+    return 'number' === typeof nth && of === refs.length ? refs[nth] : undefined;
+}
+/**
+ * The anchor as the stale-ref RETRY found it: one ref to dispatch at, an ambiguity to report, or
+ * neither.
+ *
+ * The same rule as `ambiguityDrift`, one layer deeper, and shared for the same reason: a re-render
+ * can turn an unambiguous anchor into an ambiguous one between the two dispatches, and dispatching
+ * at the first of the new matches would re-make the guess the caller's own check exists to refuse —
+ * in a place the caller cannot see. Written once so the three runners cannot answer it differently,
+ * which is how the component runner came to have no answer at all.
+ *
+ * `refs[0]` is read only after `ambiguityDrift` has cleared the several-match case, so the only way
+ * it is undefined here is zero matches.
+ */
+export function reresolved(anchor, refs) {
+    const drift = ambiguityDrift(anchor, refs);
+    if (drift !== null)
+        return { drift };
+    const ref = refFor(anchor, refs);
+    return ref === undefined ? undefined : { ref };
+}
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

package/dist/language/flows/flow-cross-step.d.ts

@@ -0,0 +1,15 @@
+import type { Contradiction, FlowStepResult } from '@reticlehq/core';
+/** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
+export declare const CROSS_STEP_INDEX = -1;
+/**
+ * The contradictions the whole-span pass found that no individual step could.
+ *
+ * A step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+ * step 5 is invisible to every per-step window: step 2's closed before the answer came and step 5
+ * never saw it start. Re-running the detectors over the whole replay span finds those — and re-finds
+ * everything the steps already reported, which is what the subtraction is for. Reporting a finding
+ * twice teaches a reader that the count is noise.
+ *
+ * Exported for its own test: the subtraction is the whole rule, and it is pure.
+ */
+export declare function crossStepOnly(whole: readonly Contradiction[], steps: readonly FlowStepResult[]): Contradiction[];