@reticlehq/server 3.5.0 → 3.7.0

package/dist/judgement/runs/resume.js

@@ -0,0 +1,137 @@
+/**
+ * The resume block: what an agent needs back after its context was compacted, in under ~1k tokens.
+ *
+ * Reticle holds the memory, never the agent. After a compaction the agent's copy of the session is a
+ * summary written by a model, and a summary is exactly where "the checkout step failed" becomes
+ * "checkout was tested". So this is folded from the daemon's OWN records — the journal on disk, the
+ * intent ledger, the declared request, the app notes — and a claim whose latest verdict is not `yes`
+ * is listed as failed or not proved, however the agent remembers it.
+ *
+ * Served two ways from this one fold: `reticle_context { compact: true }` over MCP, and
+ * `reticle context --compact` at the terminal (no daemon needed), which a Claude Code SessionStart
+ * hook with matcher `compact` prints straight back into the fresh context.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { JournalVerdictEffectSchema, ReticleDir, Verified, } from '@reticlehq/core';
+import { PromptContextSchema } from '@reticlehq/core/artifacts';
+import { IntentStore } from '../../memory/intent/intent-store.js';
+import { readAppNotes } from '../../surface/tools/agent/app-notes.js';
+/** How many claims of each state are named before the rest are counted. Bounds the block. */
+const SHOWN = 5;
+/** Any one line, capped: the block must stay well under ~1k tokens whatever the journal holds. */
+const LINE_MAX = 160;
+/** The primer, short form. The full one lives in the agent's rules file (CLAUDE.md / AGENTS.md). */
+export const RESUME_PRIMER = [
+    'Only verified:"yes" passes; "unknown" and "no-fault" are neither pass nor fail.',
+    'Declare the consequence before acting: reticle_act_and_wait { target, action, until }. Several steps: one reticle_act { steps: [{ target, action, expect }] }, last expect = end state.',
+    'Text is exact-case (ignoreCase only when case does not matter); target by testid or role+name. On a failure read expected/observed/nearest first; never weaken a check.',
+];
+function cap(text) {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > LINE_MAX ? `${one.slice(0, LINE_MAX - 1)}…` : one;
+}
+function listed(label, items) {
+    if (0 === items.length)
+        return [];
+    const shown = items.slice(-SHOWN).map((item) => `  - ${cap(item)}`);
+    const more = items.length - Math.min(items.length, SHOWN);
+    return [
+        `${label} (${String(items.length)}):`,
+        ...(more > 0 ? [`  … ${String(more)} earlier`] : []),
+        ...shown,
+    ];
+}
+/** Each claim's LATEST verdict, in the order the claims were first made. */
+export function latestVerdicts(actions) {
+    const latest = new Map();
+    for (const action of actions) {
+        const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+        if (!parsed.success)
+            continue;
+        const { claim, verified, observed } = parsed.data;
+        latest.set(claim, { claim, verified, ...(observed === undefined ? {} : { observed }) });
+    }
+    return [...latest.values()];
+}
+/** The resume block, as lines. */
+export function resumeLines(facts) {
+    const verdicts = latestVerdicts(facts.actions);
+    const failed = verdicts
+        .filter((v) => Verified.NO === v.verified)
+        .map((v) => (v.observed === undefined ? v.claim : `${v.claim} — saw: ${v.observed}`));
+    const unproved = verdicts
+        .filter((v) => Verified.YES !== v.verified && Verified.NO !== v.verified)
+        .map((v) => `${v.claim} (${v.verified})`);
+    const held = verdicts.filter((v) => Verified.YES === v.verified).map((v) => v.claim);
+    const where = [
+        facts.sessionId === undefined ? undefined : `tab ${facts.sessionId}`,
+        facts.route === undefined ? undefined : `on ${facts.route}`,
+        facts.cursor === undefined ? undefined : `cursor ${String(facts.cursor)}`,
+    ].filter((p) => p !== undefined);
+    return [
+        `Reticle resume${0 === where.length ? '' : ` — ${where.join(', ')}`}. This is the daemon's record, not a summary: trust it over your memory.`,
+        ...(facts.request === undefined ? [] : [`Asked: ${cap(facts.request)}`]),
+        `Claims: ${String(held.length)} proved · ${String(failed.length)} failed · ${String(unproved.length)} not proved.`,
+        ...listed('FAILED — not done', failed),
+        ...listed('NOT PROVED — not done', unproved),
+        ...listed('Proved', held),
+        ...listed('Intents still owed', facts.openIntents),
+        ...listed('App notes (hints for targeting, never evidence)', facts.notes),
+        'Rules:',
+        ...RESUME_PRIMER.map((line) => `  - ${line}`),
+    ];
+}
+/** How long a declared request counts as this session's task (matches next-step.ts). */
+const REQUEST_FRESH_MS = 6 * 60 * 60 * 1000;
+/** The session whose action ledger was written most recently, if any. */
+export function newestSessionId(root) {
+    const dir = join(root, ReticleDir.SESSIONS_SUBDIR);
+    if (!existsSync(dir))
+        return undefined;
+    let newest;
+    for (const id of readdirSync(dir)) {
+        const ledger = join(dir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
+        if (!existsSync(ledger))
+            continue;
+        const at = statSync(ledger).mtimeMs;
+        if (newest === undefined || at > newest.at)
+            newest = { id, at };
+    }
+    return newest?.id;
+}
+/** The user's request, when one was declared recently enough to be this session's. */
+export function recentRequest(root, now) {
+    try {
+        const parsed = PromptContextSchema.safeParse(JSON.parse(readFileSync(join(root, ReticleDir.REQUEST_FILE), 'utf8')));
+        if (!parsed.success || parsed.data.request === undefined)
+            return undefined;
+        const at = parsed.data.at;
+        return at !== undefined && now - at <= REQUEST_FRESH_MS ? parsed.data.request : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Everything the resume block needs, read from disk — no daemon, which is what a SessionStart hook
+ * has the moment after a compaction. The caller supplies the journal reader: the MCP tool holds the
+ * live journal, the CLI reads the newest session's ledger.
+ */
+export async function resumeFromDisk(input) {
+    const sessionId = input.sessionId ?? newestSessionId(input.root);
+    // Asked even with no session on disk: a caller holding the live journal answers from it.
+    const actions = await input.readActions(sessionId ?? '').catch(() => []);
+    const open = await new IntentStore(input.fs, input.root, { now: () => input.now })
+        .open()
+        .catch(() => []);
+    return resumeLines({
+        actions,
+        openIntents: open.map((intent) => intent.statement),
+        request: recentRequest(input.root, input.now),
+        sessionId,
+        route: input.route,
+        cursor: input.cursor,
+        notes: readAppNotes(input.root),
+    });
+}

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

@@ -14,6 +14,7 @@ import { boundFlowName, RunFlowStatus, VerifyPhase, } from '@reticlehq/core';
 import { buildVerificationRun, } from './artifact/build-verification-run.js';
 import { mapReplayToFlowResult } from './artifact/replay-mapping.js';
 import { buildRepairPackets } from './repair-prompt.js';
+import { withShotRun } from './default-run-id.js';
 import { buildRisks, classifyChangedFiles, } from './risk-classify.js';
 export class ReticleRunner {
     #port;
@@ -44,6 +45,8 @@ export class ReticleRunner {
         // Announced BEFORE the loop: "step 3" without "of 12" does not answer the only question a
         // person watching is actually asking, which is whether to keep waiting.
         emit({ phase: VerifyPhase.FLOWS_FOUND, total, at: this.#port.now() });
+        // Minted first, so each replayed step's screenshot is filed under the run it belongs to.
+        const runId = this.#port.newRunId();
         const replays = [];
         const flows = [];
         for (const [index, name] of names.entries()) {
@@ -55,7 +58,7 @@ export class ReticleRunner {
                 name: boundFlowName(name),
                 at: start,
             });
-            const replay = await this.#port.replayFlow(name);
+            const replay = await withShotRun(runId, () => this.#port.replayFlow(name));
             replays.push(replay);
             const mapped = mapReplayToFlowResult(replay, this.#port.now() - start);
             flows.push(mapped);
@@ -75,7 +78,7 @@ export class ReticleRunner {
         const risks = buildRisks(changedFiles, opts.policy);
         const failurePackets = buildRepairPackets(replays);
         const input = {
-            runId: this.#port.newRunId(),
+            runId,
             durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
             profile: opts.profile,
             project: opts.project,
@@ -85,7 +88,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/runner-port.d.ts

@@ -8,4 +8,8 @@ import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 import type { RunnerPort } from './reticle-runner.js';
 export { defaultRunId } from './default-run-id.js';
 /** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
-export declare function createRunnerPort(deps: ToolDeps, sessionId?: string): RunnerPort;
+export declare function createRunnerPort(deps: ToolDeps, sessionId?: string, 
+/** `reticle verify --confirm-dangerous`: this run acknowledges the steps held as destructive. */
+opts?: {
+    confirmDangerous?: boolean;
+}): RunnerPort;

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

@@ -8,10 +8,16 @@ import { replayAndLearn } from '../../language/flows/flow-learning.js';
 import { defaultRunId } from './default-run-id.js';
 export { defaultRunId } from './default-run-id.js';
 /** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
-export function createRunnerPort(deps, sessionId) {
+export function createRunnerPort(deps, sessionId, 
+/** `reticle verify --confirm-dangerous`: this run acknowledges the steps held as destructive. */
+opts = {}) {
     return {
         listFlows: () => deps.flows.list(),
-        replayFlow: (name) => replayAndLearn(deps, sessionId !== undefined ? { flowName: name, sessionId } : { flowName: name }),
+        replayFlow: (name) => replayAndLearn(deps, {
+            flowName: name,
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(true === opts.confirmDangerous ? { confirmDangerous: true } : {}),
+        }),
         now: () => deps.now(),
         newRunId: defaultRunId,
     };

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 {
@@ -7,9 +8,11 @@ export interface TimedReplay {
     /** The flow file that was replayed, so the synced run can carry its recording. */
     flow?: FlowFile;
 }
+/** The MCP client name `reticle verify` (the command line, CI's path) connects to a daemon as. */
+export declare const CLI_CLIENT_NAME = "reticle-cli";
 /**
  * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
  * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
  * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
  */
-export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], projectId: ProjectId | undefined): Promise<string | undefined>;
+export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], target: ProjectTarget): Promise<string | undefined>;

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

@@ -8,42 +8,58 @@
  * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
  * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
  */
-import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
-import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { callerClientName } from '../../hooks/coding-agents.js';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { RunAgentKind, RunFramework, RunProfile, RunTrigger, asRunId, } from '@reticlehq/core';
 import { homedir } from 'node:os';
 import { buildVerificationRun, } from './artifact/build-verification-run.js';
 import { mapReplayToFlowResult } from './artifact/replay-mapping.js';
 import { defaultRunId } from './default-run-id.js';
+import { currentShotRun } from './default-run-id.js';
 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';
+/** The MCP client name `reticle verify` (the command line, CI's path) connects to a daemon as. */
+export const CLI_CLIENT_NAME = 'reticle-cli';
+/**
+ * Who ran a suite, and why. The command line is the pipeline, whichever daemon replays for it:
+ * through a running daemon its runs read as a coding agent, trigger manual, credited to whoever
+ * minted the key, while the path that boots its own daemon said pipeline.
+ */
+function agentAndTrigger(client) {
+    return CLI_CLIENT_NAME === client
+        ? { agent: { id: client, kind: RunAgentKind.OEM_PIPELINE }, trigger: { kind: RunTrigger.OEM } }
+        : {
+            agent: { id: client ?? RETICLE_MCP_AGENT_ID, kind: RunAgentKind.CODING_AGENT },
+            trigger: { kind: RunTrigger.MANUAL },
+        };
+}
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
-function assembleRun(deps, timed, projectId) {
+function assembleRun(deps, timed, 
+/** The dashboard project this checkout is linked to, else the session's own id. */
+projectName) {
     const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs, t.flow));
     const input = {
-        runId: defaultRunId(),
+        // The run its replays' screenshots were filed under, when the verify minted one first.
+        runId: asRunId(currentShotRun() ?? defaultRunId()),
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
         profile: RunProfile.DEV,
-        project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
+        project: { name: projectName ?? 'reticle', framework: RunFramework.OTHER },
         /*
          * WHICH agent drove this, not merely THAT one did.
          *
          * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
          * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
          * this, Cursor broke it" — which is the question a team actually has once more than one agent
-         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
-         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
-         * admitting we do not know.
+         * touches the repo. The name is the client's own claim from the MCP handshake, for the call that
+         * ran this suite only; a plain CLI run, or a dashboard Re-verify no agent made, keeps the old id,
+         * because inventing a vendor there would be worse than admitting we do not know.
          */
-        agent: {
-            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
-            kind: RunAgentKind.CODING_AGENT,
-        },
-        trigger: { kind: RunTrigger.MANUAL },
+        ...agentAndTrigger(callerClientName()),
         changedFiles: [],
         flows,
         checks: [],
@@ -57,18 +73,25 @@ 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;
+    // A replay the Harness made inside its own drive is part of that drive's run: written on its own
+    // it was a second row ("Passed · Flow replay · Your agent") beside the plan run it belonged to.
+    if (currentDrivenBy() !== undefined)
+        return undefined;
     let run;
     // The project the suite ran for, not the directory the daemon was started in. Both halves below
     // take it: the artifact `reticle_run` reads back through `sessionRoot`, and the cloud link that
     // 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);
+    const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
     try {
-        run = assembleRun(deps, timed, projectId);
+        // Named after the dashboard project the checkout is linked to: a Re-verify run read "reticle".
+        run = assembleRun(deps, timed, cloud.projectId ?? projectId);
         await new RunStore(deps.fs, root).write(run);
     }
     catch (error) {
@@ -78,7 +101,6 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
         return undefined;
     }
     // Per-project cloud: only push when THIS project has cloud attached AND its policy allows runs.
-    const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
     const result = await syncRunToCloud(run, cloud.config, cloudFetch);

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
@@ -136,7 +165,8 @@ invoked = new Map()) {
             ...(fix !== undefined ? { suggestedFix: fix } : {}),
             nextAction: fix !== undefined
                 ? `${fix}, or update the flow if the change was intended.`
-                : `inspect ${where ?? 'the step'} — the anchored element is gone; rebind or update the flow.`,
+                : `inspect ${where ?? 'the step'} — the anchored element is not on the page and nothing there looks like a rename. ` +
+                    'If the replay began somewhere the recording did not (signed out, another route), record the steps that reach this one; otherwise rebind or update the flow.',
         };
     }
     // status error: an action failed, or the success oracle was not satisfied (green-but-wrong).
@@ -207,6 +237,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/fields/flow-secret-field.d.ts

@@ -1,4 +1,6 @@
+import { z } from 'zod';
 import { type FlowAnchor, type FlowFile } from '@reticlehq/core';
+import { CALL_SECRETS_ARG } from '../../../surface/tools/tool-kit.js';
 /**
  * What the anchor CALLS the field it points at.
  *
@@ -20,6 +22,8 @@ export declare function anchorFieldName(anchor: FlowAnchor): string | undefined;
  * reader what to do: the value belongs in the environment, not in a file they are about to commit.
  */
 export declare const REDACTED_FILL = "<redacted: supply at replay>";
+/** The arg a saved redacted fill names its variable in. Dropped before the step reaches the page. */
+export declare const SECRET_NAME_ARG = "secret";
 /**
  * The environment variable that supplies one redacted field.
  *
@@ -33,6 +37,14 @@ export declare const REDACTED_FILL = "<redacted: supply at replay>";
  * saying it had to stay together.
  */
 export declare const secretEnvKey: (field: string) => string;
+/** The schema of that argument, shared by every tool that replays a flow. */
+export { CALL_SECRETS_ARG };
+export declare const callSecretsArg: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+/**
+ * One secret's value: supplied with this call (by field or by variable name), else from the
+ * daemon's environment.
+ */
+export declare function secretValue(envKey: string, env: Record<string, string | undefined>): string | undefined;
 /** One field a flow needs supplied, and the variable that supplies it. */
 export interface UnsuppliedSecret {
     field: string;

package/dist/language/flows/fields/flow-secret-field.js

@@ -1,4 +1,6 @@
+import { z } from 'zod';
 import { AnchorKind } from '@reticlehq/core';
+import { CALL_SECRETS_ARG, callSecrets } from '../../../surface/tools/tool-kit.js';
 /**
  * What the anchor CALLS the field it points at.
  *
@@ -28,6 +30,10 @@ export function anchorFieldName(anchor) {
  * reader what to do: the value belongs in the environment, not in a file they are about to commit.
  */
 export const REDACTED_FILL = '<redacted: supply at replay>';
+/** The arg a saved redacted fill names its variable in. Dropped before the step reaches the page. */
+export const SECRET_NAME_ARG = 'secret';
+/** The prefix every secret's variable carries. */
+const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
 /**
  * The environment variable that supplies one redacted field.
  *
@@ -40,7 +46,24 @@ export const REDACTED_FILL = '<redacted: supply at replay>';
  * rules must not be able to drift. It used to sit in `replay.ts`, one import away from the sentence
  * saying it had to stay together.
  */
-export const secretEnvKey = (field) => `RETICLE_SECRET_${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+export const secretEnvKey = (field) => `${SECRET_ENV_PREFIX}${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+/** The schema of that argument, shared by every tool that replays a flow. */
+export { CALL_SECRETS_ARG };
+export const callSecretsArg = z
+    .record(z.string())
+    .optional()
+    .describe('Redacted fields\' values, this call only, never kept: { "auth-password": "…" }');
+/**
+ * One secret's value: supplied with this call (by field or by variable name), else from the
+ * daemon's environment.
+ */
+export function secretValue(envKey, env) {
+    for (const [key, value] of Object.entries(callSecrets() ?? {})) {
+        if (envKey === (key.startsWith(SECRET_ENV_PREFIX) ? key : secretEnvKey(key)))
+            return value;
+    }
+    return env[envKey];
+}
 /**
  * Every credential this flow will replay as the literal placeholder.
  *
@@ -63,7 +86,7 @@ export function unsuppliedSecrets(flow, env) {
         if (field === undefined)
             continue;
         const envKey = secretEnvKey(field);
-        const supplied = env[envKey];
+        const supplied = secretValue(envKey, env);
         if (supplied !== undefined && supplied.length > 0)
             continue;
         if (seen.has(envKey))

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

@@ -16,8 +16,13 @@ import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 export declare function editDistance(a: string, b: string): number;
 /**
  * The closest present testid to a missing one, by case-insensitive edit distance, ties broken
- * by shortest length then lexically. Returns null only when nothing is present — so a drift
- * record always names a fix when one exists ("whose fault is it": here is the closest survivor).
+ * by shortest length then lexically — when it is close enough to be a rename. Null when nothing
+ * present is, so a drift record names a fix only when one plausibly exists.
+ *
+ * It used to name the closest survivor however far away it was. A replay that started signed out
+ * missed `compose-prompt` on the login screen and advised rebinding it to `login-submit`: eleven
+ * edits away, a different control on a different page, offered as the fix. Half the longer name is
+ * the ceiling — `chat-send` → `chat-submit` and `checkout-btn` → `checkout-button` stay in.
  */
 export declare function nearestTestid(missing: string, present: string[]): string | null;
 /**
@@ -29,17 +34,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.
+ *
+ * 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.
+ *
+ * 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 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.
  *
- * `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.
+ * 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.
  *
- * `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.
+ * `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 ambiguousAnchorDrift(value: string, matches: number): Drift;
+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.
  *