@reticlehq/server 3.9.0 → 3.10.1

package/dist/features/grade/grade-state.js

@@ -0,0 +1,93 @@
+/**
+ * Grade a finished run of an app from snapshots of its stored data. Pure.
+ *
+ * A snapshot is the state lines of `readStateSources`, and optionally a `url` line for the page the
+ * run ended on. Three snapshots go in: the reference (the app after the correct steps), again (the
+ * app after the same correct steps, from the same start), and the candidate (the app after the steps
+ * to grade). A line that differs between the two reference snapshots is noise and is ignored, and so
+ * is a change to a cell of a row that the two references wrote differently (see `grade-noise.ts`). Any
+ * other line that differs between the reference and the candidate is a difference, and the grade
+ * fails. A source that could not be read makes the grade unverified, never a pass.
+ *
+ * A row the candidate deleted and wrote again with a new id and the same values is not a difference
+ * (see `grade-renumber.ts`). The grade counts these rows.
+ *
+ * State lines are sorted rows, so the diff is a count of each line, not an ordered diff. That keeps
+ * the cost linear in the number of rows, and a source of many thousand rows is cheap.
+ */
+import { z } from 'zod';
+import { MSG_READ_FAILED } from '../compare/outside/state-sources.js';
+import { noiseCells, withoutNoiseCells } from './grade-noise.js';
+import { renumber } from './grade-renumber.js';
+export const GradeVerdict = {
+    PASS: 'pass',
+    FAIL: 'fail',
+    /** The grade proves nothing: a source could not be read, or the answer could not be checked. */
+    UNVERIFIED: 'unverified',
+};
+export const SnapshotSchema = z.strictObject({
+    lines: z.array(z.string()),
+});
+/** The line that holds the page a run ended on. */
+export const URL_PREFIX = 'url';
+/**
+ * The page a run ended on, as one line: the origin and path without a final slash, and the query
+ * values sorted by name. The fragment is removed. Text that is not a URL is kept as it is.
+ */
+export function urlLine(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `${URL_PREFIX} ${url.trim()}`;
+    }
+    parsed.searchParams.sort();
+    const path = parsed.pathname.replace(/\/+$/, '');
+    const query = parsed.searchParams.toString();
+    return `${URL_PREFIX} ${parsed.origin}${path}${'' === query ? '' : `?${query}`}`;
+}
+const counts = (lines) => {
+    const out = new Map();
+    for (const line of lines) {
+        out.set(line, (out.get(line) ?? 0) + 1);
+    }
+    return out;
+};
+/** The lines `a` has more times than `b`, once for each extra time. */
+function surplus(a, b) {
+    const left = counts(b);
+    const out = [];
+    for (const line of a) {
+        const n = left.get(line) ?? 0;
+        if (n > 0) {
+            left.set(line, n - 1);
+        }
+        else {
+            out.push(line);
+        }
+    }
+    return out;
+}
+export function gradeState(reference, again, candidate) {
+    const unread = [reference, again, candidate].flatMap((s) => s.lines.filter((line) => line.startsWith(MSG_READ_FAILED)));
+    const referenceOnly = surplus(reference.lines, again.lines);
+    const againOnly = surplus(again.lines, reference.lines);
+    const noise = new Set([...referenceOnly, ...againOnly]);
+    const all = {
+        removed: surplus(reference.lines, candidate.lines),
+        added: surplus(candidate.lines, reference.lines),
+    };
+    const removedKept = all.removed.filter((line) => !noise.has(line));
+    const byCell = withoutNoiseCells(all.added.filter((line) => !noise.has(line)), noiseCells(referenceOnly, againOnly));
+    const { removed, added, renumbered } = renumber(removedKept, byCell.added, reference.lines, candidate.lines);
+    const ignored = all.removed.length + all.added.length - removedKept.length - byCell.added.length;
+    let verdict = GradeVerdict.PASS;
+    if (unread.length > 0) {
+        verdict = GradeVerdict.UNVERIFIED;
+    }
+    else if (removed.length > 0 || added.length > 0) {
+        verdict = GradeVerdict.FAIL;
+    }
+    return { verdict, removed, added, ignored, unread, renumbered };
+}

package/dist/features/grade/grade-suggest.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Write the state declaration for an app, so nobody writes one by hand. Pure.
+ *
+ * Two steps:
+ * 1. `tableSources`: one `command` source for each table of a database, from a list of table names
+ *    and a command template with `{table}` in it. `skip` holds name prefixes. It removes the tables that hold no task data,
+ *    such as a message queue that a background worker empties at its own time.
+ * 2. `quietSources`: keep the sources that read the same on two runs of the same correct steps.
+ *    A source that changes between those two runs (a session table, a log) would make every
+ *    candidate fail, because the candidate's own new rows are lines that neither reference has. Such
+ *    a source is kept with a time pattern removed when that makes it read the same, else dropped.
+ *    Each dropped source is reported with the reason.
+ *
+ * A source the reference does not change is kept too: a change to it by the candidate is a
+ * change to a record the task did not name.
+ */
+import { type StateSource } from '../compare/outside/state-sources.js';
+/** The word in a command template that the table name replaces. */
+export declare const TABLE_SLOT = "{table}";
+/** A date and time, with optional fractions of a second: the most common noise in a row. */
+export declare const TIME_PATTERN = "\\d{4}-\\d\\d-\\d\\d[ T]\\d\\d:\\d\\d:\\d\\d(?:\\.\\d+)?";
+export interface Skipped {
+    label: string;
+    reason: string;
+}
+export declare function tableSources(names: readonly string[], template: string, container?: string, skip?: readonly string[]): {
+    sources: StateSource[];
+    skipped: Skipped[];
+};
+export declare function quietSources(sources: readonly StateSource[], reference: readonly string[], again: readonly string[]): {
+    sources: StateSource[];
+    dropped: Skipped[];
+};

package/dist/features/grade/grade-suggest.js

@@ -0,0 +1,98 @@
+/**
+ * Write the state declaration for an app, so nobody writes one by hand. Pure.
+ *
+ * Two steps:
+ * 1. `tableSources`: one `command` source for each table of a database, from a list of table names
+ *    and a command template with `{table}` in it. `skip` holds name prefixes. It removes the tables that hold no task data,
+ *    such as a message queue that a background worker empties at its own time.
+ * 2. `quietSources`: keep the sources that read the same on two runs of the same correct steps.
+ *    A source that changes between those two runs (a session table, a log) would make every
+ *    candidate fail, because the candidate's own new rows are lines that neither reference has. Such
+ *    a source is kept with a time pattern removed when that makes it read the same, else dropped.
+ *    Each dropped source is reported with the reason.
+ *
+ * A source the reference does not change is kept too: a change to it by the candidate is a
+ * change to a record the task did not name.
+ */
+import { MSG_READ_FAILED, MSG_ROWS_CUT, STATE_PREFIX, StateSourceKind, } from '../compare/outside/state-sources.js';
+/** The word in a command template that the table name replaces. */
+export const TABLE_SLOT = '{table}';
+/** A table name that is safe in a shell command and in SQL without quotes. */
+const TABLE_NAME = /^[A-Za-z0-9_$]+$/;
+/** A date and time, with optional fractions of a second: the most common noise in a row. */
+export const TIME_PATTERN = '\\d{4}-\\d\\d-\\d\\d[ T]\\d\\d:\\d\\d:\\d\\d(?:\\.\\d+)?';
+export function tableSources(names, template, container, skip = []) {
+    const sources = [];
+    const skipped = [];
+    for (const raw of names) {
+        const name = raw.trim();
+        if ('' === name) {
+            continue;
+        }
+        if (skip.some((prefix) => name.startsWith(prefix))) {
+            skipped.push({ label: name, reason: 'the name starts with a --skip prefix' });
+            continue;
+        }
+        if (!TABLE_NAME.test(name)) {
+            skipped.push({ label: name, reason: 'the name has a character other than A-Z, 0-9, _ or $' });
+            continue;
+        }
+        sources.push({
+            kind: StateSourceKind.COMMAND,
+            label: name,
+            command: template.replaceAll(TABLE_SLOT, name),
+            ...(container === undefined ? {} : { container }),
+        });
+    }
+    return { sources, skipped };
+}
+/** The rows of one source in a snapshot, and the read failure when there is one. */
+function rowsOf(lines, label) {
+    const row = `${STATE_PREFIX} ${label} `;
+    const cut = `${MSG_ROWS_CUT} ${label}: `;
+    const failed = lines.find((line) => line.startsWith(`${MSG_READ_FAILED} ${label}: `));
+    const rows = lines.filter((line) => line.startsWith(row) || line.startsWith(cut));
+    return failed === undefined ? { rows } : { rows, failed };
+}
+function sameRows(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    const x = [...a].sort();
+    const y = [...b].sort();
+    return x.every((line, i) => line === y[i]);
+}
+/** The first row that only one of the two runs has, to show why a source was dropped. */
+function firstDifference(a, b) {
+    const inA = new Set(a);
+    const inB = new Set(b);
+    return a.find((line) => !inB.has(line)) ?? b.find((line) => !inA.has(line)) ?? '';
+}
+export function quietSources(sources, reference, again) {
+    const kept = [];
+    const dropped = [];
+    const time = new RegExp(TIME_PATTERN, 'g');
+    for (const source of sources) {
+        const a = rowsOf(reference, source.label);
+        const b = rowsOf(again, source.label);
+        const failed = a.failed ?? b.failed;
+        if (failed !== undefined) {
+            dropped.push({ label: source.label, reason: failed });
+            continue;
+        }
+        if (sameRows(a.rows, b.rows)) {
+            kept.push(source);
+            continue;
+        }
+        const untimed = (rows) => rows.map((r) => r.replace(time, ''));
+        if (StateSourceKind.COMMAND === source.kind && sameRows(untimed(a.rows), untimed(b.rows))) {
+            kept.push({ ...source, ignore: [...(source.ignore ?? []), TIME_PATTERN] });
+            continue;
+        }
+        dropped.push({
+            label: source.label,
+            reason: `it changes between two runs of the same steps: ${firstDifference(a.rows, b.rows)}`,
+        });
+    }
+    return { sources: kept, dropped };
+}

package/dist/features/visual/visual-tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AppRuntime, ReticleCommand, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { AppRuntime, ReticleCommand, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, realmOf, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { ratioSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -34,6 +34,38 @@ function screenshotProvider(deps) {
         ? p
         : undefined;
 }
+/**
+ * Whether this call can photograph the session: a lease of this caller, a desktop shell, or a page
+ * that the driven browser has.
+ *
+ * A desktop shell counts before its capture is known to work. Only a CAPTURE command can tell, and
+ * a person who connected a desktop app most likely wants that window, not a lease beside it.
+ */
+async function canCapture(deps, session) {
+    // A lease of this caller. Another agent's lease is never this caller's to photograph (#1226).
+    if (true === deps.pool?.heldBy(session.id, deps.attachId)) {
+        return true;
+    }
+    if (realmOf(session.runtime).isDesktopShell) {
+        return true;
+    }
+    // A driven browser photographs only a page it has. Having a driven browser is not enough.
+    const driven = screenshotProvider(deps);
+    if (driven === undefined) {
+        return false;
+    }
+    return driven.isAvailableFor(session.url);
+}
+/**
+ * The one session this call photographs, chosen once (#1959).
+ *
+ * capture() and captureRoot() each resolve the id again. With no id, each could choose another
+ * session, and capture() never tried a lease at all. After this, they all get the same, named id.
+ */
+async function captureTarget(deps, args) {
+    const session = await deps.sessions.resolveServing(asString(args['sessionId']), (s) => canCapture(deps, s));
+    return session.id;
+}
 /** The "you need a driven browser" envelope, shared by both visual tools. */
 const noProvider = {
     ok: false,
@@ -42,8 +74,9 @@ const noProvider = {
 };
 /** The answer when no pixels came back: the shell's own recommendation over the web one. */
 function unavailable(reason, recommendation) {
-    if (recommendation !== undefined)
+    if (recommendation !== undefined) {
         return { ok: false, reason, recommendation };
+    }
     return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
 }
 function asBox(value) {
@@ -52,10 +85,12 @@ function asBox(value) {
     const y = asNumber(b['y']);
     const w = asNumber(b['width']);
     const h = asNumber(b['height']);
-    if (x === undefined || y === undefined || w === undefined || h === undefined)
+    if (x === undefined || y === undefined || w === undefined || h === undefined) {
         return undefined;
-    if (w <= 0 || h <= 0)
+    }
+    if (w <= 0 || h <= 0) {
         return undefined;
+    }
     return { x, y, width: w, height: h };
 }
 /** Build capture options from args: explicit clip > ref (resolved via INSPECT) > fullPage. */
@@ -64,16 +99,18 @@ async function buildOpts(deps, sessionId, args) {
     if (clipArg !== undefined) {
         const c = asRecord(clipArg);
         const box = asBox({ box: c });
-        if (box !== undefined)
+        if (box !== undefined) {
             return { clip: box };
+        }
     }
     const ref = asString(args['ref']);
     if (ref !== undefined) {
         const session = deps.sessions.resolve(sessionId);
         const res = await session.command(ReticleCommand.INSPECT, { ref });
         const box = res.ok ? asBox(res.result) : undefined;
-        if (box !== undefined)
+        if (box !== undefined) {
             return { clip: box };
+        }
     }
     return true === args['fullPage'] ? { fullPage: true } : {};
 }
@@ -88,14 +125,16 @@ async function buildOpts(deps, sessionId, args) {
 export async function driveFrame(deps, sessionId, jpegQuality) {
     try {
         const leased = await deps.pool?.screenshotLease(sessionId, { jpegQuality });
-        if (leased !== undefined)
+        if (leased !== undefined) {
             return leased;
+        }
         // The window `reticle drive` opened: neither a lease nor a desktop shell, but its page is ours.
         const url = deps.sessions.resolve(sessionId).url;
         if (true === (await deps.realInput?.isAvailableFor(url))) {
             const shot = await deps.realInput?.screenshot?.(url, { jpegQuality });
-            if (shot !== undefined)
+            if (shot !== undefined) {
                 return shot;
+            }
         }
         return (await desktopCapture(deps, sessionId, false)).png;
     }
@@ -153,8 +192,9 @@ async function capture(deps, sessionId, args) {
         // A driven browser renders the session's URL in a BROWSER — so the pixels are web even when the
         // session named is a desktop window. Scoping those under the desktop runtime would corrupt that
         // runtime's baseline with a picture of a different renderer.
-        if (png !== undefined)
+        if (png !== undefined) {
             return { png, runtime: AppRuntime.WEB };
+        }
     }
     // The window's own backing store, via the Electron/Tauri adapter — the only route whose pixels
     // really are the desktop app.
@@ -167,8 +207,9 @@ async function capture(deps, sessionId, args) {
         }
         return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
     }
-    if (desktop.reason !== undefined)
+    if (desktop.reason !== undefined) {
         return desktop;
+    }
     /*
      * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
      * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
@@ -182,20 +223,23 @@ async function capture(deps, sessionId, args) {
             // shot of a lease saved the whole viewport and answered `saved: true`.
             await deps.pool?.screenshotLease(sessionId, await buildOpts(deps, sessionId, args));
     // A leased page is a real browser page, whatever the session is.
-    if (leased !== undefined)
+    if (leased !== undefined) {
         return { png: leased, runtime: AppRuntime.WEB };
+    }
     return {
         reason: provider === undefined ? VisualReason.NO_PROVIDER : VisualReason.CAPTURE_FAILED,
     };
 }
 function rectsFrom(value) {
-    if (!Array.isArray(value))
+    if (!Array.isArray(value)) {
         return undefined;
+    }
     const rects = [];
     for (const r of value) {
         const box = asBox({ box: r });
-        if (box !== undefined)
+        if (box !== undefined) {
             rects.push(box);
+        }
     }
     return rects.length > 0 ? rects : undefined;
 }
@@ -237,10 +281,11 @@ export const VISUAL_TOOLS = [
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const sessionId = asString(args['sessionId']);
+            const sessionId = await captureTarget(deps, args);
             const { png, reason, recommendation, runtime } = await capture(deps, sessionId, args);
-            if (png === undefined)
+            if (png === undefined) {
                 return unavailable(reason, recommendation);
+            }
             const name = asString(args['name']) ?? 'default';
             // Beside the app that was captured. The tool RETURNS this path to the agent, so a wrong root
             // is not only a stray PNG — it is a path the agent is told to look at in a tree that has
@@ -290,22 +335,24 @@ export const VISUAL_TOOLS = [
         },
         handler: async (deps, args) => {
             const baseline = asString(args['baseline']) ?? '';
-            const store = new VisualStore(deps.fs, captureRoot(deps, asString(args['sessionId'])));
+            const sessionId = await captureTarget(deps, args);
+            const store = new VisualStore(deps.fs, captureRoot(deps, sessionId));
             // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
             // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
             // desktop session captured through a driven browser must be compared against the WEB baseline,
             // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
             // and a silently overwritten baseline in the other.
-            const sessionId = asString(args['sessionId']);
             const captured = await capture(deps, sessionId, args);
             const { png: current, runtime } = captured;
-            if (current === undefined)
+            if (current === undefined) {
                 return unavailable(captured.reason, captured.recommendation);
+            }
             // A baseline from another runtime is not missing by accident — it is a different rendering, and
             // "no baseline for this one" is the honest answer.
             const baselineBytes = await store.readBaseline(baseline, runtime);
-            if (baselineBytes === undefined)
+            if (baselineBytes === undefined) {
                 return { ok: false, reason: VisualReason.BASELINE_MISSING };
+            }
             const masks = rectsFrom(args['masks']);
             const threshold = asNumber(args['threshold']);
             const maxRatio = asNumber(args['maxRatio']);

package/dist/index.js

@@ -54,6 +54,7 @@ import { AGENT_ALREADY_DRIVING_ELSEWHERE, shouldGreetWithLeaseNotice, } from './
 import { LeaseReaper } from './portal/pool/lease-reaper.js';
 import { findProjectConfig, readJournalEnabled, readProjectId, } from './command/cli/ports/resolve/cli-port.js';
 import { probeLaunchableChromium } from './launch-chromium.js';
+import { portAcceptsConnection } from './portal/session/dev-server/dev-server-probe.js';
 import { attachJournal } from './wire-journal.js';
 import { reportOnboardingStep } from './telemetry/onboarding-funnel.js';
 import { readRetainPolicy } from './memory/journal/on-disk/retain-policy.js';
@@ -149,7 +150,7 @@ export async function start(options = {}) {
     // Then to the agent's own git worktree: every worktree declares the same projectId.
     bridge.sessions.setCheckoutScope(liveCheckoutSource());
     const baselines = new BaselineStore();
-    const recordings = new RecordingStore(() => currentDrivenBy() !== undefined);
+    const recordings = new RecordingStore(() => currentDrivenBy() !== undefined, (session) => bridge.sessions.successorId(session));
     // drive precedence: driveUrl (launch+own a browser) → CDP (attach) → none.
     let pool;
     let leaseReaper;
@@ -188,7 +189,7 @@ export async function start(options = {}) {
         const project = new ProjectStore(fs, reticleRoot, { now });
         attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
         const annotations = new AnnotationStore();
-        pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token), (leaseId, error) => pageErrorJournal.onPoolPageError(leaseId, error), (leaseId) => pageErrorJournal.onLeaseClosed(leaseId), bridge.nonces);
+        pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token), (leaseId, error) => pageErrorJournal.onPoolPageError(leaseId, error), (leaseId) => pageErrorJournal.onLeaseClosed(leaseId), bridge.nonces, (leaseId, dialog) => pageErrorJournal.onPoolDialog(leaseId, dialog));
         leaseReaper = new LeaseReaper(pool);
         leaseReaper.start();
         /*
@@ -227,6 +228,7 @@ export async function start(options = {}) {
             bridgePort: port,
             nonces: bridge.nonces,
             browserProbe: probeLaunchableChromium,
+            portAccepts: portAcceptsConnection,
             // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
             // belongs to a sibling app under the same daemon". contract_save refuses on the second.
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
@@ -365,7 +367,7 @@ export async function startDaemon(options = {}) {
     const flows = new FlowStore(fs, reticleRoot, { now }, { onWrote: () => syncNudge.run?.() });
     // Built here rather than inside `deps` below, so teardown can save what a drive recorded. Both
     // paths pass the same pair — `daemon-parity.test.ts` is what keeps them from drifting apart.
-    const recordings = new RecordingStore(() => currentDrivenBy() !== undefined);
+    const recordings = new RecordingStore(() => currentDrivenBy() !== undefined, (session) => bridge.sessions.successorId(session));
     /*
      * Bound AFTER the sync daemon exists, read only when a run is actually written.
      *
@@ -388,7 +390,7 @@ export async function startDaemon(options = {}) {
     const project = new ProjectStore(fs, reticleRoot, { now });
     attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
     const annotations = new AnnotationStore();
-    const pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token), (leaseId, error) => pageErrorJournal.onPoolPageError(leaseId, error), (leaseId) => pageErrorJournal.onLeaseClosed(leaseId), bridge.nonces);
+    const pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token), (leaseId, error) => pageErrorJournal.onPoolPageError(leaseId, error), (leaseId) => pageErrorJournal.onLeaseClosed(leaseId), bridge.nonces, (leaseId, dialog) => pageErrorJournal.onPoolDialog(leaseId, dialog));
     const leaseReaper = new LeaseReaper(pool);
     leaseReaper.start();
     /*
@@ -461,6 +463,7 @@ export async function startDaemon(options = {}) {
         bridgePort: port,
         nonces: bridge.nonces,
         browserProbe: probeLaunchableChromium,
+        portAccepts: portAcceptsConnection,
         ...agentWiring(bridge.sessions, leaseUrl),
         // A finished verification should not sit behind a one-minute timer — see ToolDeps.onRunPersisted.
         onRunPersisted: () => cloudSync.nudge(),

package/dist/judgement/capsule/causal-summary.js

@@ -94,6 +94,8 @@ export function causalSummary(events, context = {}) {
     const signals = [];
     const fieldsChanged = [];
     let layoutShift;
+    // The shift inside this window, summed from each entry's own `shift` (#1784).
+    let windowShift;
     let longTasks = 0;
     let ignoredBookkeeping = 0;
     for (const event of events) {
@@ -166,7 +168,11 @@ export function causalSummary(events, context = {}) {
                 pushUnique(fieldsChanged, data['field']);
                 break;
             case EventType.PERF:
-                if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
+                if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['shift']) {
+                    windowShift = (windowShift ?? 0) + data['shift'];
+                }
+                else if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
+                    // An SDK older than #1784 sends only the running total: the most it allows is its max.
                     layoutShift = Math.max(layoutShift ?? 0, data['value']);
                 }
                 else if (data['metric'] === PerfMetric.LONGTASK) {
@@ -182,6 +188,7 @@ export function causalSummary(events, context = {}) {
     // store, and shrinking it because the evidence was trimmed would make the transient window read as
     // narrower than it was — the one number here that must survive the trim intact.
     const settle = stateSettle(stateDiffs);
+    const shiftInWindow = windowShift ?? layoutShift;
     return {
         net: {
             total: netTotal,
@@ -204,7 +211,7 @@ export function causalSummary(events, context = {}) {
             ? {}
             : { fieldsChanged: cap(fieldsChanged, 'fieldsChanged', elided) }),
         ...(0 === Object.keys(elided).length ? {} : { elided }),
-        ...(layoutShift === undefined ? {} : { layoutShift }),
+        ...(shiftInWindow === undefined ? {} : { layoutShift: shiftInWindow }),
         longTasks,
         ...(true === context.stateUnwatched ? { stateUnwatched: true } : {}),
         ...(true === context.truncated ? { truncated: true } : {}),

package/dist/judgement/runs/artifact/replay-mapping.d.ts

@@ -4,8 +4,20 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, type FlowFile, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
+import { ReplayStatus, RunFlowStatus, type FlowFile, type FlowReplayResult, type RunFlowResult, type RunStepResult } from '@reticlehq/core';
 /** OK → PASS; UNVERIFIABLE → SKIPPED; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
+/** One step as synced: what it did, where, and whether it held. */
+/**
+ * A run step with how far a sequence got. Kept out of the shared run schema on purpose: that schema
+ * ships in the page SDK, where every byte counts, and only the CLI score in this same process reads
+ * the field. A schema reader strips it, which loses nothing it needs.
+ */
+export interface ScoredRunStep extends RunStepResult {
+    subSteps?: {
+        passed: number;
+        total: number;
+    };
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number, flow?: FlowFile): RunFlowResult;

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

@@ -15,7 +15,6 @@ export function runFlowStatusOf(status) {
     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. */
 function stepResultOf(step) {
     return {
         step: step.step,
@@ -26,6 +25,7 @@ function stepResultOf(step) {
         ...(step.consequence === undefined ? {} : { consequence: clip(step.consequence) }),
         ...(step.error === undefined ? {} : { error: clip(step.error) }),
         ...(step.drift === undefined ? {} : { drift: step.drift.reasonKind }),
+        ...(step.subSteps === undefined ? {} : { subSteps: step.subSteps }),
     };
 }
 /**

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

@@ -10,12 +10,26 @@
  * same artifact byte-for-byte.
  */
 import { reportRunTelemetry } from '../../telemetry/run-telemetry.js';
-import { boundFlowName, RunFlowStatus, VerifyPhase, } from '@reticlehq/core';
+import { boundFlowName, RunFlowStatus, VerifyPhase, ReplayStatus, } 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';
+/**
+ * A flow whose replay threw (its browser session was lost, the app stopped answering) proves
+ * nothing, and it must not take the other flows of the suite down with it. It is graded as a replay
+ * that could not be completed: skipped, never a pass, with the error as the reason.
+ */
+function replayThatCouldNotRun(name, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        name,
+        status: ReplayStatus.UNVERIFIABLE,
+        steps: [],
+        unverifiable: { reason: `the replay stopped before it could be graded: ${message}` },
+    };
+}
 export class ReticleRunner {
     #port;
     constructor(port) {
@@ -58,7 +72,7 @@ export class ReticleRunner {
                 name: boundFlowName(name),
                 at: start,
             });
-            const replay = await withShotRun(runId, () => this.#port.replayFlow(name));
+            const replay = await withShotRun(runId, () => this.#port.replayFlow(name)).catch((error) => replayThatCouldNotRun(name, error));
             replays.push(replay);
             const mapped = mapReplayToFlowResult(replay, this.#port.now() - start);
             flows.push(mapped);

package/dist/judgement/runs/runner-port.d.ts

@@ -12,4 +12,6 @@ export declare function createRunnerPort(deps: ToolDeps, sessionId?: string,
 /** `reticle verify --confirm-dangerous`: this run acknowledges the steps held as destructive. */
 opts?: {
     confirmDangerous?: boolean;
+    requireStartControl?: boolean;
+    sweep?: boolean;
 }): RunnerPort;

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

@@ -4,7 +4,10 @@
  * and a uuid generator. The ReticleRunner core (tested with a fake port) holds all the orchestration and
  * verdict logic, so this layer carries no decisions.
  */
+import { ReplayStatus } from '@reticlehq/core';
 import { replayAndLearn } from '../../language/flows/flow-learning.js';
+import { sessionUrlOf } from '../../language/flows/flow-lease.js';
+import { flowStartState } from '../../surface/tools/session-ports.js';
 import { flowsForSession } from '../../language/flows/flow-store-for-session.js';
 import { safeSessionTarget } from '../../memory/project/session-root.js';
 import { defaultRunId } from './default-run-id.js';
@@ -13,17 +16,32 @@ export { defaultRunId } from './default-run-id.js';
 export function createRunnerPort(deps, sessionId, 
 /** `reticle verify --confirm-dangerous`: this run acknowledges the steps held as destructive. */
 opts = {}) {
+    // Each flow starts from the state the run started in, so one that signs out cannot fail the rest.
+    const startState = flowStartState(deps.realInput, () => sessionUrlOf(deps, sessionId));
     return {
         // Resolved as replay resolves it, so every listed name is one replay can load.
         listFlows: () => {
             const target = safeSessionTarget(deps, sessionId);
             return flowsForSession(deps, target).flows.list(target.projectId);
         },
-        replayFlow: (name) => replayAndLearn(deps, {
-            flowName: name,
-            ...(sessionId === undefined ? {} : { sessionId }),
-            ...(true === opts.confirmDangerous ? { confirmDangerous: true } : {}),
-        }),
+        replayFlow: async (name) => {
+            const cannotStart = await startState();
+            if (cannotStart !== undefined) {
+                return {
+                    name,
+                    status: ReplayStatus.UNVERIFIABLE,
+                    steps: [],
+                    unverifiable: { reason: cannotStart },
+                };
+            }
+            return await replayAndLearn(deps, {
+                flowName: name,
+                ...(sessionId === undefined ? {} : { sessionId }),
+                ...(true === opts.confirmDangerous ? { confirmDangerous: true } : {}),
+                ...(true === opts.requireStartControl ? { requireStartControl: true } : {}),
+                ...(true === opts.sweep ? { sweep: true } : {}),
+            });
+        },
         now: () => deps.now(),
         newRunId: defaultRunId,
     };