@reticlehq/server 3.2.0 → 3.4.0

package/dist/language/flows/learned-sources.js

@@ -0,0 +1,84 @@
+/**
+ * Learn a flow step's source file from the element its anchor resolved to on a replay.
+ *
+ * A step recorded before the build stamped the app names no file, so a scoped re-verify cannot say
+ * which edits it covers. Every replay already asks the page for each anchor's element, and that
+ * element carries its stamp now: this records the answer at the one place every resolution passes
+ * through (the session's QUERY), rather than threading it through each step runner.
+ */
+import { ReticleCommand, asRecord, asString } from '@reticlehq/core';
+import { anchorQueryArgs } from './flow-step-runners.js';
+/** `src/Pay.tsx:12:4` or `src/Pay.tsx:12` → `{file, line}`; anything else is not a location. */
+export function parseCompactSource(value) {
+    const match = /^(.+?):(\d+)(?::\d+)?$/.exec(value);
+    const file = match?.[1];
+    const line = match?.[2];
+    if (file === undefined || line === undefined)
+        return undefined;
+    return { file, line: Number(line) };
+}
+function keyOf(args) {
+    if (args === undefined)
+        return undefined;
+    const by = asString(args['by']);
+    const value = asString(args['value']);
+    if (by === undefined || value === undefined)
+        return undefined;
+    return JSON.stringify([by, value, asString(args['name']) ?? null]);
+}
+/** The one element a query found, when exactly one was found and it carries a stamp. */
+function soleSource(result) {
+    const elements = asRecord(result)?.['elements'];
+    if (!Array.isArray(elements) || elements.length !== 1)
+        return undefined;
+    const source = asString(asRecord(elements[0])?.['source']);
+    return source === undefined ? undefined : parseCompactSource(source);
+}
+/** Wrap a replay session so every anchor QUERY that resolves to one stamped element is remembered. */
+export function recordingSources(inner) {
+    const sources = new Map();
+    const session = new Proxy(inner, {
+        // Bound to the target, never the proxy: a real Session keeps `#private` state, and a method
+        // called with the proxy as `this` throws reading it.
+        get(target, prop) {
+            if (prop !== 'command') {
+                const value = Reflect.get(target, prop, target);
+                return 'function' === typeof value ? value.bind(target) : value;
+            }
+            return async (name, args) => {
+                const result = await target.command(name, args);
+                const key = name === ReticleCommand.QUERY ? keyOf(args) : undefined;
+                const source = result.ok ? soleSource(result.result) : undefined;
+                if (key !== undefined && source !== undefined)
+                    sources.set(key, source);
+                return result;
+            };
+        },
+    });
+    return { session, sources };
+}
+function learnSteps(steps, sources) {
+    let changed = false;
+    const next = steps.map((step) => {
+        const nested = step.steps === undefined ? undefined : learnSteps(step.steps, sources);
+        const learned = step.source === undefined
+            ? sources.get(keyOf(anchorQueryArgs(step.anchor) ?? undefined) ?? '')
+            : undefined;
+        if (learned === undefined && nested?.changed !== true)
+            return step;
+        changed = true;
+        return {
+            ...step,
+            ...(learned === undefined ? {} : { source: learned }),
+            ...(nested === undefined ? {} : { steps: nested.steps }),
+        };
+    });
+    return { steps: next, changed };
+}
+/** The flow with every sourceless step given the file its anchor resolved to; undefined if none was. */
+export function withLearnedSources(flow, sources) {
+    if (0 === sources.size)
+        return undefined;
+    const { steps, changed } = learnSteps(flow.steps, sources);
+    return changed ? { ...flow, steps } : undefined;
+}

package/dist/language/flows/recording/recording-backtrack.d.ts

@@ -7,13 +7,6 @@
  * stop/save can warn instead of writing a flow that fails on the next click.
  */
 import { type ReticleEvent } from '@reticlehq/core';
-/**
- * The page a recording step sat on, comparable across path routers and hash routers.
- *
- * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
- * Without this, every hash-router page compares as `/` and a backtrack is invisible.
- */
-export declare function recordingRouteOf(pathname: string, hash?: string): string;
 /**
  * Warn when the journey left a page and came back. Linear A→B→C is silent: that still cannot
  * replay either if a later click needs a previous page, but the reported failure is specifically

package/dist/language/flows/recording/recording-backtrack.js

@@ -17,7 +17,7 @@ function asString(value) {
  * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
  * Without this, every hash-router page compares as `/` and a backtrack is invisible.
  */
-export function recordingRouteOf(pathname, hash = '') {
+function recordingRouteOf(pathname, hash = '') {
     const hashIdx = pathname.indexOf('#/');
     if (hashIdx >= 0) {
         return routePathOf(pathname.slice(0, hashIdx) || '/', pathname.slice(hashIdx));

package/dist/language/flows/recording/replay-halt.d.ts

@@ -12,7 +12,7 @@
  */
 import type { FlowStepResult } from '@reticlehq/core';
 /** Set on a replay that stopped early; omitted entirely otherwise, so a clean pass stays flat. */
-export interface ReplayHalt {
+interface ReplayHalt {
     /** Index of the step that stopped the run. */
     atStep: number;
     /** How many of the flow's steps were never attempted because of it. */
@@ -24,3 +24,4 @@ export interface ReplayHalt {
  * defect restated as its own fix.
  */
 export declare function haltedFrom(results: readonly FlowStepResult[], total: number): ReplayHalt | undefined;
+export {};

package/dist/language/flows/recording/replay-halt.js

@@ -21,7 +21,9 @@ export function haltedFrom(results, total) {
         return undefined;
     if (last.ok && last.drift === undefined)
         return undefined;
-    const notAttempted = total - results.length;
+    // From the step's own index, not the count of results: a resumed replay does not report its setup
+    // prefix, so the results array no longer starts at step 0.
+    const notAttempted = total - (last.step + 1);
     // A failure on the FINAL step is not a halt: nothing was left to attempt, and `notAttempted: 0`
     // would send a reader looking for steps that do not exist.
     if (notAttempted <= 0)

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -1,4 +1,4 @@
-import { type FlowExpect } from '@reticlehq/core';
+import { type FlowFile, type Predicate } from '@reticlehq/core';
 /** One captured agent action, normalized for replay. */
 export interface RecordedStep {
     /** ReticleTool.ACT | ReticleTool.ACT_SEQUENCE */
@@ -8,7 +8,7 @@ export interface RecordedStep {
     /** false if any ref could not be normalized to a testid (replay only valid in-session). */
     stable: boolean;
     /** Optional post-condition annotation carried into the on-disk flow's expect. */
-    expect?: FlowExpect;
+    expect?: Predicate;
     /**
      * The route this step ran on. RECORDER-INTERNAL: it never reaches the on-disk flow.
      *
@@ -27,6 +27,12 @@ export interface RecordedStep {
      * `invoke` first and treats the step as a call.
      */
     invoke?: string;
+    /** The page this step ran on. Written to the saved step (unlike `route`, which cuts journeys). */
+    page?: string;
+    /** The page it ended on once it settled — see `markEnded`. */
+    endPage?: string;
+    /** Why the agent took this step: the `intent` it declared on the action. Names the saved flow. */
+    intent?: string;
 }
 interface ActiveRecording {
     cursor: number;
@@ -59,6 +65,8 @@ export interface CompiledProgram {
      * format change.
      */
     routes?: string[];
+    /** Who made it — see FlowFile.author. Stamped by the caller that knows. */
+    author?: FlowFile['author'];
 }
 /**
  * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
@@ -105,6 +113,27 @@ export declare class RecordingStore {
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
     capture(step: RecordedStep, route?: string): void;
+    /**
+     * Add a consequence to the last captured step of every active recording.
+     *
+     * A separate `reticle_assert` after an act is how an agent proves what the act did, and it never
+     * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
+     * the proof. What the step already declared is kept; the new check joins it under `allOf`.
+     */
+    attachExpect(expect: Predicate): void;
+    /**
+     * A navigation happened. Navigating records no step, so until the next one is captured, a check
+     * proved now is about the page the navigation opened, not about the last step — and kept on that
+     * step, replay would ask it right after the click, of a page it was never true on.
+     */
+    markNavigated(): void;
+    /**
+     * The page the step just captured ended on, once its action settled.
+     *
+     * Fills only a step that has none, so calling it after an action that captured nothing leaves the
+     * previous step's own answer alone.
+     */
+    markEnded(page: string | undefined): void;
     /**
      * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
      *

package/dist/language/flows/recording/tape/recordings.js

@@ -1,4 +1,4 @@
-import { FlowStepTool } from '@reticlehq/core';
+import { FlowStepTool, PredicateKind } from '@reticlehq/core';
 /**
  * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
  *
@@ -31,6 +31,8 @@ const AMBIENT_STEP_CAP = 400;
 export class RecordingStore {
     #active = new Map();
     #compiled = new Map();
+    /** A navigation came after the last captured step — see markNavigated. */
+    #navigatedSinceStep = false;
     start(name, cursor, startPath) {
         const openedOver = new Map();
         for (const [outer, rec] of this.#active)
@@ -67,6 +69,7 @@ export class RecordingStore {
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
     capture(step, route) {
+        this.#navigatedSinceStep = false;
         if (!this.#active.has(AMBIENT_RECORDING)) {
             this.#active.set(AMBIENT_RECORDING, {
                 cursor: 0,
@@ -83,12 +86,63 @@ export class RecordingStore {
             // opened on purpose is not capped — they said when it starts and they say when it stops.
             if (AMBIENT_RECORDING === name && rec.steps.length >= AMBIENT_STEP_CAP)
                 continue;
+            // A step nobody marked ended where the next one began.
+            const previous = rec.steps.at(-1);
+            if (previous !== undefined && previous.endPage === undefined && step.page !== undefined) {
+                previous.endPage = step.page;
+            }
             // The route rides on the AMBIENT tape only: a recording somebody opened deliberately is
             // already one journey by construction, and stamping a route on its steps would change what a
             // deliberate recording contains.
             rec.steps.push(AMBIENT_RECORDING === name && route !== undefined ? { ...step, route } : step);
         }
     }
+    /**
+     * Add a consequence to the last captured step of every active recording.
+     *
+     * A separate `reticle_assert` after an act is how an agent proves what the act did, and it never
+     * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
+     * the proof. What the step already declared is kept; the new check joins it under `allOf`.
+     */
+    attachExpect(expect) {
+        if (this.#navigatedSinceStep)
+            return;
+        for (const rec of this.#active.values()) {
+            const last = rec.steps.at(-1);
+            if (last === undefined)
+                continue;
+            const held = last.expect;
+            last.expect =
+                held === undefined
+                    ? expect
+                    : PredicateKind.ALL_OF === held.kind
+                        ? { ...held, predicates: [...held.predicates, expect] }
+                        : { kind: PredicateKind.ALL_OF, predicates: [held, expect] };
+        }
+    }
+    /**
+     * A navigation happened. Navigating records no step, so until the next one is captured, a check
+     * proved now is about the page the navigation opened, not about the last step — and kept on that
+     * step, replay would ask it right after the click, of a page it was never true on.
+     */
+    markNavigated() {
+        this.#navigatedSinceStep = true;
+    }
+    /**
+     * The page the step just captured ended on, once its action settled.
+     *
+     * Fills only a step that has none, so calling it after an action that captured nothing leaves the
+     * previous step's own answer alone.
+     */
+    markEnded(page) {
+        if (page === undefined)
+            return;
+        for (const rec of this.#active.values()) {
+            const last = rec.steps.at(-1);
+            if (last !== undefined && last.endPage === undefined)
+                last.endPage = page;
+        }
+    }
     /**
      * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
      *

package/dist/language/flows/replay.d.ts

@@ -1,3 +1,4 @@
+import { type Predicate } from '@reticlehq/core';
 import { type CommandResult } from '@reticlehq/core';
 import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
 import type { Session } from '../../portal/session/session.js';
@@ -27,6 +28,13 @@ export declare function queryRefs(result: CommandResult): string[];
  * an empty box fails identically and tells the reader nothing.
  */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
+/**
+ * The pathname of a session's live url, or undefined when it has none yet.
+ *
+ * Pathname rather than the whole url, because that is what `startPath` is compared against and what
+ * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ */
+export declare function pathOf(url: string | undefined): string | undefined;
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -40,6 +48,17 @@ export declare function captureAct(recordings: {
 }, args: Record<string, unknown>, res: unknown, 
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
 route?: string): void;
+/**
+ * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
+ * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
+ * a regression test asserting something never once observed to hold because of the action. The
+ * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ */
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined): void;
+/** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
+export declare function captureAssertion(recordings: {
+    attachExpect: (expect: Predicate) => void;
+}, raw: unknown): void;
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
  * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's

package/dist/language/flows/replay.js

@@ -1,9 +1,8 @@
 import { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
+import { FlowPredicateSchema, Verified } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
-import { predicateToExpect, enforcedOnReplay } from '../../judgement/outcome/predicate-to-expect.js';
-import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -72,6 +71,22 @@ function sourceFromResult(res) {
         out['column'] = source['column'];
     return out;
 }
+/**
+ * The pathname of a session's live url, or undefined when it has none yet.
+ *
+ * Pathname rather than the whole url, because that is what `startPath` is compared against and what
+ * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ */
+export function pathOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -88,33 +103,58 @@ route) {
     // — "recording is a property of the system rather than a rule an agent has to remember" — was true
     // about the intent and false about the code, and every drive nobody wrapped by hand was discarded.
     //
-    // That is the whole supply of regression tests this product could have had for free: the corpus
-    // measures 3 of 33 flows mutation-testable and 6 of 112 steps declaring a consequence, and a drive
-    // that is never recorded cannot contribute to either.
+    // That is the whole supply of regression tests this product could have had for free: few saved
+    // flows are mutation-testable and few steps declare a consequence, and a drive that is never
+    // recorded cannot contribute to either.
     const step = compileActStep(args, res);
     // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
     // success means — the large majority of calls carry one — and dropping it produced a flow graded
     // "assertion-free: it will pass even if the feature is broken", which is the regression-suite
-    // story failing at its last step. Only kinds FlowExpect can express survive; see
-    // predicate-to-expect.ts.
+    // story failing at its last step. See enforceableExpect below.
     const expect = enforceableExpect(args['until'] ?? args['predicate']);
     if (expect !== undefined)
         step.expect = expect;
+    if (route !== undefined)
+        step.page = route;
+    const intent = asString(args['intent'])?.trim();
+    if (intent !== undefined && intent.length > 0)
+        step.intent = intent;
     recordings.capture(step, route);
 }
+/**
+ * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
+ * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
+ * a regression test asserting something never once observed to hold because of the action. The
+ * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ */
+export function captureVerdictedAct(recordings, args, res, route, verified) {
+    const { until: _until, predicate: _predicate, ...unproved } = args;
+    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route);
+}
+/** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
+export function captureAssertion(recordings, raw) {
+    const expect = enforceableExpect(raw);
+    if (expect !== undefined)
+        recordings.attachExpect(expect);
+}
 /**
  * A declared predicate, as a recorded expectation — or nothing.
  *
- * The ONE place this conversion happens, because it is the rule that decides whether a saved flow
- * proves anything, and two copies of it would drift. Only kinds a replay actually CHECKS survive:
- * recording an unenforced assertion grades the flow "asserted" while nothing verifies it, which is a
- * false green inside the feature built to prevent them. See enforcedOnReplay.
+ * It is now the SAME OBJECT. A step's `expect` is a `Predicate`, so what the agent declared in
+ * `until` is what the flow file stores, and there is no conversion left to lose anything in.
+ *
+ * What was here before was a lossy round trip through a flat struct with one slot per kind. An
+ * `allOf[netA, netB]` saved as one of the two with nothing said; anything the struct could not
+ * express was dropped, and a filter then removed the kinds replay would not have checked anyway.
+ * Every one of those was a claim the agent made and the file did not keep.
  */
 function enforceableExpect(raw) {
     if (raw === undefined)
         return undefined;
-    const parsed = PredicateSchema.safeParse(raw);
-    return parsed.success ? enforcedOnReplay(predicateToExpect(parsed.data)) : undefined;
+    // The flow file's own schema, so capture keeps exactly what a load would accept — a predicate
+    // holding a session ref is refused by both, rather than recorded here and rejected on read.
+    const parsed = FlowPredicateSchema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
 }
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor

package/dist/language/flows/stores/annotation-store.d.ts

@@ -1,22 +1,22 @@
-import type { FlowExpect } from '@reticlehq/core';
+import type { Predicate } from '@reticlehq/core';
 export declare class AnnotationStore {
     #private;
     /** Testids whose CONTENT must not be asserted at replay (mark-dynamic). Copy, never the live array. */
     dynamic(name: string): string[];
     /** The flow's golden end-condition (success-state), or undefined. */
-    success(name: string): FlowExpect | undefined;
+    success(name: string): Predicate | undefined;
     /** The flow's declared business goal (intent annotation), or undefined. */
     intent(name: string): string | undefined;
     /** Per-step expect predicates compiled from assert-* annotations, keyed by step index. */
-    stepExpect(name: string): Map<number, FlowExpect>;
+    stepExpect(name: string): Map<number, Predicate>;
     /** Append a dynamic testid (mark-dynamic). De-duped so repeated marks stay idempotent. */
     addDynamic(name: string, testid: string): void;
     /** Set the flow's success expectation (success-state); a later set overwrites. */
-    setSuccess(name: string, expect: FlowExpect): void;
+    setSuccess(name: string, expect: Predicate): void;
     /** Set the flow's declared business goal (intent); a later set overwrites. */
     setIntent(name: string, text: string): void;
     /** Set one step's expect (assert-signal / assert-visible); a later set on the same index wins. */
-    setStepExpect(name: string, index: number, expect: FlowExpect): void;
+    setStepExpect(name: string, index: number, expect: Predicate): void;
     /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
     clear(name: string): void;
 }

package/dist/language/flows/stores/assertion-tiers-store.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../../../memory/project/fs/write-atomic.js';
 import { z } from 'zod';
 import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
 import { withFileLock } from '../../../memory/project/file-lock.js';
@@ -77,9 +78,7 @@ export class AssertionTiersStore {
     async save(tiers) {
         await this.#fs.mkdir(dirname(this.#path));
         const body = `${JSON.stringify({ version: ASSERTION_TIERS_VERSION, flows: tiers }, null, 2)}\n`;
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
     /** Record one flow's assertion shape + covered sources after it PASSED. Never breaks a replay. */
     async recordPassing(name, steps, sources = []) {

package/dist/language/flows/stores/flake-store.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../../../memory/project/fs/write-atomic.js';
 import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
 import { FlakeFileSchema, emptyRecord, isFlaky, recordOutcome, } from '../recording/flake.js';
 const FLAKE_FILE_VERSION = 1;
@@ -38,9 +39,7 @@ export class FlakeStore {
     async save(ledger) {
         await this.#fs.mkdir(dirname(this.#path));
         const body = `${JSON.stringify({ version: FLAKE_FILE_VERSION, flows: ledger }, null, 2)}\n`;
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
     /** Accrue one unchanged-code replay outcome for a flow and persist. */
     async record(flow, passed) {

package/dist/language/flows/suite/coverage.d.ts

@@ -24,7 +24,7 @@ interface CoverageDimension {
     /** Declared-but-never-exercised members — what "everything" is silently missing. */
     uncovered: string[];
 }
-export interface Coverage {
+interface Coverage {
     testids: CoverageDimension;
     signals: CoverageDimension;
     flows: CoverageDimension;

package/dist/language/flows/suite/parallel-suite.d.ts

@@ -9,7 +9,7 @@
  * - one flow throwing never sinks the run — it is captured as that item's outcome, because a suite that
  * aborts on the first crash tells you nothing about the other 199 flows.
  */
-export interface Outcome<T> {
+interface Outcome<T> {
     ok: boolean;
     value?: T;
     error?: string;
@@ -24,3 +24,4 @@ export declare function mapWithConcurrency<I, T>(items: readonly I[], limit: num
  * and never below 1. Explicit `requested` (the tool's `parallel` arg) wins when it is a sane number.
  */
 export declare function resolveConcurrency(flowCount: number, poolCapacity: number, requested?: number): number;
+export {};

package/dist/language/flows/verify-change-tools.js

@@ -172,9 +172,12 @@ export const VERIFY_CHANGE_TOOLS = [
             const extra = await inspectAfterReplay(deps, args, cursor);
             if (extra.contradictions.length > 0) {
                 const kinds = extra.contradictions.map((c) => c.kind).join(', ');
+                const earned = attributedFailures(affected, unknownProvenance).length > 0;
                 return {
-                    verified: Verified.NO,
-                    because: `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`,
+                    verified: earned ? Verified.NO : Verified.UNKNOWN,
+                    because: earned
+                        ? `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`
+                        : `channels disagreed during the replay (${kinds}), but Reticle cannot tell which sources any of the flows that ran cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
                     changedFiles,
                     flowsRun: affected,
                     suite,
@@ -184,6 +187,19 @@ export const VERIFY_CHANGE_TOOLS = [
                     measured: extra.measured,
                 };
             }
+            // The mirror of `earnedNo`: a green from flows that ran only because their sources are unknown
+            // says nothing about these files either. At least one attributed flow has to have passed.
+            if (0 === attributedFailures(affected, unknownProvenance).length) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    because: `the flows that ran passed, but Reticle cannot tell which sources any of them cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    measured: extra.measured,
+                };
+            }
             return {
                 verified: Verified.YES,
                 because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
@@ -226,6 +242,7 @@ async function inspectAfterReplay(deps, args, cursor) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
+            background: session.background,
             // The replay is the action, and the cursor is where it started.
             actionSince: cursor,
         });

package/dist/launch-chromium.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The ONE place a Reticle-owned Chromium is launched — the pooled lease browser
+ * (`playwright-launcher`) and the drive browser (`real-input`) both come through here.
+ *
+ * Why it is more than `chromium.launch`: on a fresh machine the `playwright` package is present
+ * (npx pulled it in with the server) but its browser build is not, because that is a separate
+ * ~150 MiB download nobody told the user about. Every lease, `reticle verify`, `open` and `drive`
+ * then refused with "Chromium is not installed for Playwright. Run: npx playwright@… install
+ * chromium" — the first run stopped on a human step a machine could do. Most machines already have
+ * a Chrome or an Edge, and Playwright drives either through `channel`, so that is tried before any
+ * download; only a machine with neither gets the pinned install, run for them and announced.
+ *
+ * Announcements go to STDERR, never stdout: `reticle mcp` speaks JSON-RPC on stdout and one stray
+ * line there corrupts the client's stream.
+ */
+import { type ChromiumLaunchOptions } from './chromium-launch-options.js';
+import { type ChromiumProbe } from './command/cli/doctor/browser/chromium-hint.js';
+/** The installed-browser channels Playwright can drive in place of its own build. */
+export declare const ChromiumChannel: {
+    readonly CHROME: "chrome";
+    readonly MSEDGE: "msedge";
+};
+export type ChromiumChannel = (typeof ChromiumChannel)[keyof typeof ChromiumChannel];
+export declare const CHANNEL_LABEL: Record<ChromiumChannel, string>;
+/** Candidate executable paths for a channel on this platform; empty where it is not installable. */
+export declare function channelExecutableCandidates(channel: ChromiumChannel, platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string[];
+/** The first installed Chrome/Edge on this machine, or undefined. Looks only; installs nothing. */
+export declare function findInstalledChannel(deps: Pick<ChromiumTargetDeps, 'exists' | 'platform' | 'env'>): ChromiumChannel | undefined;
+/** Everything the resolver touches, injected so it runs against a fake machine in tests. */
+export interface ChromiumTargetDeps {
+    /** Where the bundled playwright expects its Chromium build. */
+    executablePath: () => string;
+    exists: (path: string) => boolean;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** Run the pinned Chromium install; resolves true when it succeeded. */
+    install: () => Promise<boolean>;
+    /** A progress line for a human — stderr in production. */
+    announce: (line: string) => void;
+}
+/** Which browser to launch: the bundled build (no channel), an installed channel, or none at all. */
+export type ChromiumTarget = {
+    found: true;
+    channel?: ChromiumChannel;
+} | {
+    found: false;
+};
+/**
+ * Decide which browser a launch will use, installing the pinned Chromium only as the last resort.
+ * Order: bundled build on disk → installed Chrome → installed Edge → install, then bundled.
+ */
+export declare function resolveChromiumTarget(deps: ChromiumTargetDeps): Promise<ChromiumTarget>;
+/** The subset of Playwright's `BrowserType` this file needs, so tests can pass a fake. */
+export interface LaunchableChromium<B> {
+    executablePath: () => string;
+    launch: (options: ChromiumLaunchOptions) => Promise<B>;
+}
+/**
+ * A progress writer that says each distinct line once. The Chrome/Edge fallback line was written on
+ * every launch, and the pool launches per context, so one daemon repeated the same notice into the
+ * terminal of whoever started it.
+ */
+export declare function announceOnce(write: (line: string) => void): (line: string) => void;
+/**
+ * Launch a Chromium with the shared options, on whichever browser this machine can offer. When none
+ * can be found or installed, launch anyway: Playwright's own error is what `chromiumLaunchHint`
+ * turns into the pinned install command, so the user still gets the one line that fixes it.
+ */
+export declare function launchChromium<B>(chromium: LaunchableChromium<B>, headless: boolean, deps?: ChromiumTargetDeps): Promise<B>;
+/**
+ * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
+ * and the automatic install. Without this the preflight would refuse a lease on a machine the
+ * launcher itself could serve. Falls back to the plain probe so a real refusal keeps its evidence.
+ */
+export declare function probeLaunchableChromium(): Promise<ChromiumProbe>;
+/**
+ * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
+ * bundled build is missing. Never installs — a diagnostic that downloads 150 MiB is not one.
+ */
+export declare function probeChromiumWithFallback(): Promise<ChromiumProbe>;