autokap 1.9.5 → 1.9.6

package/dist/action-verifier.d.ts

@@ -27,9 +27,42 @@ export interface ActionChange {
 /**
  * Captures AKTree state before and after an action to detect changes.
  */
+/**
+ * F2: outcome of a SET_THEME / SET_LOCALE effect probe. These opcodes used to
+ * report clean success even when the app ignored the requested theme/locale
+ * (e.g. an app that themes via a `class`/`data-theme`/storage key but never
+ * reads `prefers-color-scheme`). The probe reads back an observable signal from
+ * the live AKTree — node styling for theme, visible text for locale — and, when
+ * no change is observed (or the signal can't be read), flags the result
+ * low-confidence. It NEVER hard-fails: a missing signal only downgrades trust.
+ */
+export interface ThemeLocaleEffectResult {
+    /** Whether a deterministic, observable change confirmed the effect applied. */
+    observed: boolean;
+    /** Human-readable reason for logging / low-confidence attribution. */
+    summary: string;
+}
 export declare class ActionVerifier {
     private beforeTree;
     private beforeUrl;
+    /** F2: pre-action signal for SET_THEME (style) / SET_LOCALE (text). */
+    private themeLocaleBaseline;
     captureBeforeState(adapter: RuntimeAdapter): Promise<void>;
     verifyAfterAction(adapter: RuntimeAdapter): Promise<ActionVerification>;
+    /**
+     * F2: capture the pre-action signal for a SET_THEME / SET_LOCALE effect probe.
+     * `theme` reads aggregate visible node styling (background/foreground colors);
+     * `locale` reads aggregate visible text. Best-effort: a failed AKTree read
+     * leaves the baseline null, and `verifyThemeLocaleEffect` then reports the
+     * effect unverifiable (low-confidence) rather than asserting success.
+     */
+    captureThemeLocaleBaseline(adapter: RuntimeAdapter, kind: 'theme' | 'locale'): Promise<void>;
+    /**
+     * F2: compare the post-action signal against the baseline captured by
+     * `captureThemeLocaleBaseline`. Returns `observed:true` only when a real,
+     * deterministic change is seen. A missing baseline, an unreadable after-tree,
+     * or an unchanged signal all return `observed:false` so the caller flags the
+     * capture low-confidence. NEVER throws and NEVER signals a hard failure.
+     */
+    verifyThemeLocaleEffect(adapter: RuntimeAdapter, kind: 'theme' | 'locale'): Promise<ThemeLocaleEffectResult>;
 }

package/dist/action-verifier.js

@@ -4,12 +4,11 @@
  * Post-action validation: diff AKTree before/after an action
  * to detect whether the action had a real effect or was intercepted.
  */
-/**
- * Captures AKTree state before and after an action to detect changes.
- */
 export class ActionVerifier {
     beforeTree = null;
     beforeUrl = null;
+    /** F2: pre-action signal for SET_THEME (style) / SET_LOCALE (text). */
+    themeLocaleBaseline = null;
     async captureBeforeState(adapter) {
         try {
             this.beforeTree = await adapter.getAKTree();
@@ -25,11 +24,19 @@ export class ActionVerifier {
         }
     }
     async verifyAfterAction(adapter) {
+        // B2: a transient AKTree read failure during captureBeforeState left us with
+        // no baseline to diff against, so the effect cannot be verified. We assume
+        // the action had an effect (the action itself already returned success), but
+        // — like the after-illisible path below — flag it low-confidence so a no-op
+        // action on a flaky baseline read can't pass the effect gate as a clean
+        // success. We do NOT recapture the baseline here: the action has already run,
+        // so a fresh "before" would equal "after" and spuriously report no effect.
         if (!this.beforeTree || !this.beforeUrl) {
             return {
                 hadEffect: true, // assume effect if no before state
                 changes: [],
-                summary: 'no before state captured, assuming action had effect',
+                summary: 'no before state captured, assuming action had effect (low-confidence)',
+                lowConfidence: true,
             };
         }
         // AUT-240 (decision 2): "assume OK, but smart". A first `page.evaluate`
@@ -155,6 +162,50 @@ export class ActionVerifier {
         this.beforeUrl = null;
         return { hadEffect, changes, summary };
     }
+    /**
+     * F2: capture the pre-action signal for a SET_THEME / SET_LOCALE effect probe.
+     * `theme` reads aggregate visible node styling (background/foreground colors);
+     * `locale` reads aggregate visible text. Best-effort: a failed AKTree read
+     * leaves the baseline null, and `verifyThemeLocaleEffect` then reports the
+     * effect unverifiable (low-confidence) rather than asserting success.
+     */
+    async captureThemeLocaleBaseline(adapter, kind) {
+        try {
+            const tree = await adapter.getAKTree();
+            this.themeLocaleBaseline = kind === 'theme'
+                ? collectStyleSignature(tree.root)
+                : collectTextSignature(tree.root);
+        }
+        catch {
+            this.themeLocaleBaseline = null;
+        }
+    }
+    /**
+     * F2: compare the post-action signal against the baseline captured by
+     * `captureThemeLocaleBaseline`. Returns `observed:true` only when a real,
+     * deterministic change is seen. A missing baseline, an unreadable after-tree,
+     * or an unchanged signal all return `observed:false` so the caller flags the
+     * capture low-confidence. NEVER throws and NEVER signals a hard failure.
+     */
+    async verifyThemeLocaleEffect(adapter, kind) {
+        const baseline = this.themeLocaleBaseline;
+        this.themeLocaleBaseline = null;
+        if (baseline === null) {
+            return { observed: false, summary: `${kind} baseline unavailable; effect unverified` };
+        }
+        let after;
+        try {
+            const tree = await adapter.getAKTree();
+            after = kind === 'theme' ? collectStyleSignature(tree.root) : collectTextSignature(tree.root);
+        }
+        catch {
+            return { observed: false, summary: `${kind} after-state unreadable; effect unverified` };
+        }
+        if (after !== baseline) {
+            return { observed: true, summary: `${kind} applied (observable ${kind === 'theme' ? 'styling' : 'text'} change)` };
+        }
+        return { observed: false, summary: `no observable ${kind === 'theme' ? 'styling' : 'text'} change; app may ignore the requested ${kind}` };
+    }
 }
 // ── Helpers ─────────────────────────────────────────────────────────
 function countVisibleNodes(node) {
@@ -164,6 +215,54 @@ function countVisibleNodes(node) {
     }
     return count;
 }
+/**
+ * F2: aggregate the visible node styling (background/foreground colors) into a
+ * stable signature. A real theme flip changes computed colors across the tree;
+ * an app that ignores the requested theme leaves the signature identical.
+ * Bounded so a huge tree can't blow the string up.
+ */
+function collectStyleSignature(root) {
+    const parts = [];
+    function walk(node) {
+        if (node.visible && (node.style.bgColor || node.style.fgColor)) {
+            parts.push(`${node.style.bgColor ?? ''}/${node.style.fgColor ?? ''}`);
+            if (parts.length >= 400)
+                return;
+        }
+        for (const child of node.children) {
+            if (parts.length >= 400)
+                return;
+            walk(child);
+        }
+    }
+    walk(root);
+    return parts.join('|');
+}
+/**
+ * F2: aggregate the visible node text (label / own text) into a stable
+ * signature. A real locale switch retranslates visible copy; an app that
+ * ignores the requested locale leaves the signature identical. Bounded.
+ */
+function collectTextSignature(root) {
+    const parts = [];
+    function walk(node) {
+        if (node.visible) {
+            const text = (node.attributes.__ownText ?? node.label ?? '').trim();
+            if (text) {
+                parts.push(text);
+                if (parts.length >= 400)
+                    return;
+            }
+        }
+        for (const child of node.children) {
+            if (parts.length >= 400)
+                return;
+            walk(child);
+        }
+    }
+    walk(root);
+    return parts.join('
');
+}
 function collectVisibleInteractiveIds(node) {
     const ids = [];
     function walk(n) {

package/dist/browser.js

@@ -2828,6 +2828,52 @@ export class Browser {
                 }
                 return attrs;
             };
+            // A node "blocks interaction" only when it actually intercepts clicks into
+            // the page content — i.e. it (or one of its descendants) sits at the
+            // viewport centre under a real hit-test AND it covers a meaningful portion
+            // of the viewport. `pointerEvents !== 'none'` alone is true for almost the
+            // entire DOM, so it would flag ordinary fixed chrome (navbar, sidebar,
+            // sticky CTA) as a blocking overlay. We additionally exclude that chrome by
+            // role/landmark and by shape (thin top strip, thin side rail).
+            const computeBlocksInteraction = (el, style, rect, coverage) => {
+                if (style.pointerEvents === 'none')
+                    return false;
+                // Ordinary page chrome is not a blocking overlay.
+                const role = (el.getAttribute('role') || '').toLowerCase();
+                const tag = el.tagName.toUpperCase();
+                if (['NAV', 'HEADER', 'FOOTER', 'ASIDE'].includes(tag))
+                    return false;
+                if (['navigation', 'banner', 'contentinfo', 'complementary', 'toolbar'].includes(role))
+                    return false;
+                if (el.closest('nav, header, footer, aside, [role="navigation"], [role="banner"], [role="contentinfo"], [role="complementary"]')) {
+                    return false;
+                }
+                const vw = window.innerWidth;
+                const vh = window.innerHeight;
+                if (vw <= 0 || vh <= 0)
+                    return false;
+                // Thin top strip (navbar) or thin side rail (sidebar): not a blocker.
+                const coversWidth = rect.width >= vw * 0.6;
+                const coversHeight = rect.height >= vh * 0.6;
+                const isTopStrip = rect.top <= 4 && rect.height <= vh * 0.25;
+                const isSideRail = rect.left <= 4 && rect.width <= vw * 0.35 && coversHeight;
+                if (isTopStrip || isSideRail)
+                    return false;
+                // Must cover a meaningful portion of the viewport AND span enough of one
+                // axis to plausibly trap the user (a small sticky CTA does neither).
+                if (coverage < 25)
+                    return false;
+                if (!coversWidth && !coversHeight)
+                    return false;
+                // Real hit-test: does this node (or a descendant) actually sit under the
+                // viewport centre? If the main content shows through, it isn't blocking.
+                const cx = Math.round(vw / 2);
+                const cy = Math.round(vh / 2);
+                const hit = document.elementFromPoint(cx, cy);
+                if (!hit)
+                    return false;
+                return hit === el || el.contains(hit);
+            };
             const parseNode = (element) => {
                 if (!(element instanceof HTMLElement))
                     return null;
@@ -2873,7 +2919,7 @@ export class Browser {
                 attributes.__hasBorder = visualChrome.border ? 'true' : 'false';
                 attributes.__hasShadow = visualChrome.shadow ? 'true' : 'false';
                 attributes.__coveragePercent = String(Math.round(coveragePercent));
-                attributes.__blocksInteraction = style.pointerEvents !== 'none' ? 'true' : 'false';
+                attributes.__blocksInteraction = computeBlocksInteraction(element, style, rect, coveragePercent) ? 'true' : 'false';
                 return {
                     tagName: element.tagName,
                     role: element.getAttribute('role'),
@@ -3116,15 +3162,20 @@ export class Browser {
                 }
                 return { changed: false, value: input };
             };
-            let nextValue = candidate;
+            let nextValue;
             try {
                 const parsed = JSON.parse(current);
                 const rewritten = rewrite(parsed);
-                if (rewritten.changed) {
-                    nextValue = JSON.stringify(rewritten.value);
-                }
+                // The current value is structured JSON. Only write back if a whitelisted
+                // locale/theme field was actually rewritten — never clobber a structured
+                // object with the bare candidate string (that destroys unrelated data and
+                // falsely reports success). No writable key found → report no-op.
+                if (!rewritten.changed)
+                    return false;
+                nextValue = JSON.stringify(rewritten.value);
             }
             catch {
+                // Current value is a bare (non-JSON) string: replace it wholesale.
                 nextValue = candidate;
             }
             storage.setItem(key, nextValue);
@@ -4465,7 +4516,21 @@ export class Browser {
     async resolveActivationTarget(selector) {
         const page = this.ensurePage();
         try {
-            return await page.locator(selector).first().evaluate((node) => {
+            // An explicit selector that matches exactly one element is a deliberate
+            // capture target (the generator chose `#id` / `[data-testid]` / a class
+            // pointing at this specific node). Treat it like `data-ak`: honor the
+            // matched node, never dive into a descendant control. The descendant dive
+            // is reserved for selector-less / index resolution where `start` is just a
+            // structural anchor and the real control may be nested inside it.
+            const explicitUnique = await page.evaluate((sel) => {
+                try {
+                    return document.querySelectorAll(sel).length === 1;
+                }
+                catch {
+                    return false;
+                }
+            }, selector);
+            return await page.locator(selector).first().evaluate((node, allowDescendantDive) => {
                 const ACTIONABLE_SELECTOR = [
                     'button',
                     'a[href]',
@@ -4498,6 +4563,20 @@ export class Browser {
                     return ['button', 'link', 'menuitem', 'option', 'radio', 'switch', 'tab'].includes(role);
                 };
                 const findActivationNode = (start) => {
+                    // An element carrying `data-ak`/`data-ak-interact` is an EXPLICIT
+                    // capture target the generator deliberately tagged to be clicked.
+                    // Click it directly and let native DOM bubbling (and label forwarding)
+                    // do the rest. Never walk up to a different control or dive into the
+                    // first actionable DESCENDANT — that hijacks the click, e.g. a clickable
+                    // `<div data-ak onClick>` card whose first inner button opens a menu and
+                    // stops propagation, so the card's own navigation never runs.
+                    if (start instanceof HTMLElement
+                        && (start.hasAttribute('data-ak') || start.hasAttribute('data-ak-interact'))) {
+                        if (start instanceof HTMLLabelElement && start.control instanceof HTMLElement) {
+                            return start.control;
+                        }
+                        return start;
+                    }
                     let current = start;
                     while (current) {
                         if (current instanceof HTMLLabelElement) {
@@ -4513,9 +4592,16 @@ export class Browser {
                     if (labelAncestor instanceof HTMLLabelElement) {
                         return labelAncestor.control instanceof HTMLElement ? labelAncestor.control : labelAncestor;
                     }
-                    const nested = start.querySelector(ACTIONABLE_SELECTOR);
-                    if (nested instanceof HTMLElement)
-                        return nested;
+                    // Only dive into the first actionable DESCENDANT for selector-less /
+                    // index resolution, where `start` is a structural anchor and the real
+                    // control is nested inside it. For an explicit, uniquely-matched
+                    // selector (or `data-ak`), `start` IS the intended target — diving
+                    // would hijack the click into the wrong child control.
+                    if (allowDescendantDive) {
+                        const nested = start.querySelector(ACTIONABLE_SELECTOR);
+                        if (nested instanceof HTMLElement)
+                            return nested;
+                    }
                     return start;
                 };
                 const target = findActivationNode(node);
@@ -4538,7 +4624,7 @@ export class Browser {
                     role: target.getAttribute('role') || '',
                     inputType: target instanceof HTMLInputElement ? target.type : target.getAttribute('type'),
                 };
-            });
+            }, !explicitUnique);
         }
         catch {
             return null;

package/dist/cli-runner.js

@@ -238,22 +238,39 @@ export async function runCapture(options) {
         }
     }
     let interrupted = false;
-    let abortNotified = false;
-    const notifyAborted = async () => {
-        if (abortNotified || !isLocalRegisteredRun)
-            return;
-        abortNotified = true;
-        await postRunAborted(config, runId, program.presetId, options.env);
+    // Memoize the terminal notification so the eager call from the signal handler
+    // and the finally-block call share ONE in-flight PATCH: the handler fires it
+    // the instant Ctrl-C lands, and every awaiter (the finally, a second Ctrl-C)
+    // waits on that same promise instead of racing, re-sending, or dropping it.
+    // postRunAborted never rejects (it swallows its own errors), so the memoized
+    // promise always settles — `void`-ing it can't leak an unhandled rejection.
+    let abortNotifyPromise = null;
+    const notifyAborted = () => {
+        if (!isLocalRegisteredRun)
+            return Promise.resolve();
+        if (!abortNotifyPromise) {
+            abortNotifyPromise = postRunAborted(config, runId, program.presetId, options.env);
+        }
+        return abortNotifyPromise;
     };
     const onInterrupt = (signal) => {
         if (interrupted) {
-            // Second interrupt: the user wants out now. Hard-exit with the
-            // conventional 128+SIGINT(2) code; the best-effort notify already fired.
-            process.exit(130);
+            // Second interrupt: the user wants out now. Exit with the conventional
+            // 128+SIGINT(2) code, but only AFTER the abort notification (fired on the
+            // first press) settles. Force-quitting before the PATCH lands is exactly
+            // what used to leave the preset stuck "capturing" until the 15-min cutoff.
+            void notifyAborted().finally(() => process.exit(130));
+            return;
         }
         interrupted = true;
         logger.warn(`[capture] ${signal} received — stopping the run and notifying AutoKap…`);
         abortController.abort(new Error('User interrupted (Ctrl-C)'));
+        // Tell the server NOW, not from the finally block. The in-flight opcode is
+        // not interruptible (the abort signal is only checked between opcodes), so
+        // executeProgram can take many seconds to unwind — and a second Ctrl-C
+        // during that window force-quits before the finally runs. Firing here clears
+        // the "capturing" badge even if the process never reaches a clean exit.
+        void notifyAborted();
     };
     if (isLocalRegisteredRun) {
         process.on('SIGINT', onInterrupt);

package/dist/cookie-dismiss.d.ts

@@ -1,4 +1,13 @@
 import type { Page } from 'playwright';
+/**
+ * Decides whether a container's attributes identify it as a real cookie /
+ * consent / privacy surface. Used by Strategy 2 to avoid clicking ordinary CTAs
+ * (Continue / OK / Got it) inside unrelated containers.
+ *
+ * Exported for testing. The predicate is also stringified and injected into the
+ * in-browser `page.evaluate` walker so there is a single source of truth.
+ */
+export declare function isCookieConsentContainer(combinedAttrs: string, role: string): boolean;
 export declare const CAPTURE_HIDE_STYLE_ID = "autokap-capture-hide-style";
 export declare function getCaptureHideCSS(): string;
 export declare function ensureCaptureHideStyles(page: Page): Promise<void>;

package/dist/cookie-dismiss.js

@@ -111,6 +111,25 @@ const DEV_TOOL_SELECTORS = [
     '[data-replit-devtools]',
     '#replit-devtools',
 ];
+/**
+ * Decides whether a container's attributes identify it as a real cookie /
+ * consent / privacy surface. Used by Strategy 2 to avoid clicking ordinary CTAs
+ * (Continue / OK / Got it) inside unrelated containers.
+ *
+ * Exported for testing. The predicate is also stringified and injected into the
+ * in-browser `page.evaluate` walker so there is a single source of truth.
+ */
+export function isCookieConsentContainer(combinedAttrs, role) {
+    return (combinedAttrs.includes('cookie') ||
+        combinedAttrs.includes('consent') ||
+        combinedAttrs.includes('gdpr') ||
+        combinedAttrs.includes('privacy') ||
+        // Only treat dialogs as cookie surfaces when they carry a real cookie/consent
+        // signal. A bare "banner" token, or the previous "co" substring (which matched
+        // confirm/account/connect/contact...), wrongly hijacked ordinary app dialogs.
+        ((role === 'dialog' || role === 'alertdialog') &&
+            (combinedAttrs.includes('cookie') || combinedAttrs.includes('consent'))));
+}
 export const CAPTURE_HIDE_STYLE_ID = 'autokap-capture-hide-style';
 export function getCaptureHideCSS() {
     return [...HIDE_SELECTORS, ...DEV_TOOL_SELECTORS].map(selector => `${selector} { display: none !important; visibility: hidden !important; pointer-events: none !important; }`).join('\n');
@@ -158,11 +177,15 @@ export async function dismissCookiesAndWidgets(page) {
     }
     // Strategy 2: Find accept buttons by text in cookie-like containers
     try {
-        const dismissed = await page.evaluate((patterns) => {
+        const dismissed = await page.evaluate(({ patterns, predicateSource }) => {
             const regexPatterns = patterns.map(p => {
                 const match = p.match(/^\/(.*)\/([gimsuy]*)$/);
                 return match ? new RegExp(match[1], match[2]) : new RegExp(p, 'i');
             });
+            // Reconstruct the container predicate from its stringified source so the
+            // in-browser walker and the unit tests share a single source of truth.
+            // eslint-disable-next-line no-new-func
+            const isCookieConsentContainer = new Function(`return (${predicateSource})`)();
             // Find all visible buttons and links
             const candidates = document.querySelectorAll('button, a, [role="button"], input[type="submit"]');
             for (const el of candidates) {
@@ -186,22 +209,32 @@ export async function dismissCookiesAndWidgets(page) {
                     const role = (parent.getAttribute('role') || '').toLowerCase();
                     const ariaLabel = (parent.getAttribute('aria-label') || '').toLowerCase();
                     const combinedAttrs = `${id} ${className} ${ariaLabel}`;
-                    if (combinedAttrs.includes('cookie') || combinedAttrs.includes('consent') ||
-                        combinedAttrs.includes('gdpr') || combinedAttrs.includes('privacy') ||
-                        combinedAttrs.includes('banner') ||
-                        ((role === 'dialog' || role === 'alertdialog') && combinedAttrs.includes('co'))) {
+                    if (isCookieConsentContainer(combinedAttrs, role)) {
                         isCookieContainer = true;
                         break;
                     }
                     parent = parent.parentElement;
                 }
-                if (isCookieContainer) {
-                    htmlEl.click();
-                    return text;
-                }
+                if (!isCookieContainer)
+                    continue;
+                // Only click a candidate that is actually interactable. Mirrors the
+                // isVisible() guard on the CMP-selector path — an invisible, aria-hidden
+                // or disabled match must be skipped, not clicked, so a hidden cookie node
+                // can't trigger a parasitic click on the live page.
+                const isVisible = htmlEl.offsetParent !== null || htmlEl.getClientRects().length > 0;
+                const isHidden = htmlEl.getAttribute('aria-hidden') === 'true';
+                const isDisabled = htmlEl.disabled === true ||
+                    htmlEl.getAttribute('aria-disabled') === 'true';
+                if (!isVisible || isHidden || isDisabled)
+                    continue;
+                htmlEl.click();
+                return text;
             }
             return null;
-        }, ACCEPT_PATTERNS.map(rx => rx.toString()));
+        }, {
+            patterns: ACCEPT_PATTERNS.map(rx => rx.toString()),
+            predicateSource: isCookieConsentContainer.toString(),
+        });
         if (dismissed) {
             logger.info(`Cookie dismissed via text match: "${dismissed}"`);
             await page.waitForTimeout(500);

package/dist/opcode-runner.js

@@ -103,12 +103,58 @@ function getOpcodeActionEffectPolicy(opcode) {
     }
     return { captureBefore: true, requireEffect: true, noEffectMode: 'fail' };
 }
+/**
+ * F2: maps SET_THEME / SET_LOCALE to the effect-probe kind so the runner reads
+ * back an observable signal (node styling for theme, visible text for locale)
+ * after the action. Returns undefined for every other opcode.
+ */
+function getThemeLocaleEffectKind(opcode) {
+    if (opcode.kind === 'SET_THEME')
+        return 'theme';
+    if (opcode.kind === 'SET_LOCALE')
+        return 'locale';
+    return undefined;
+}
 function resolveRuntimePostcondition(opcode) {
-    if (opcode.kind === 'ASSERT_ROUTE' || opcode.kind === 'ASSERT_SURFACE') {
+    // ASSERT opcodes carry their source of truth on the opcode itself (urlPattern /
+    // selectors+matchAll), NOT in `postcondition` (validated to `always` or an
+    // equivalent spec). On the MAIN path the assertion runs inside
+    // `executeOpcodeAction`, so this postcondition is informational. On the
+    // RECOVERY recheck path the recovery replays a no-op for ASSERT, so this is
+    // the ONLY validation left — it must re-check the real source of truth, not
+    // vacuously pass (B1). For the multi-selector matchAll case a single
+    // `PostconditionSpec` cannot express it; the recovery path uses
+    // `evaluateAssertionRecheck` instead and never reaches this branch.
+    if (opcode.kind === 'ASSERT_ROUTE') {
+        return { type: 'route_matches', pattern: opcode.urlPattern };
+    }
+    if (opcode.kind === 'ASSERT_SURFACE') {
+        if (opcode.selectors.length === 1) {
+            return { type: 'element_visible', selector: opcode.selectors[0] };
+        }
         return { type: 'always' };
     }
     return opcode.postcondition;
 }
+/**
+ * Re-runs the real ASSERT source-of-truth check (used on the recovery recheck
+ * path, where the recovery replay no-ops the assertion). Mirrors the main-path
+ * assertion in `executeOpcodeAction`, including ASSERT_SURFACE matchAll
+ * semantics. Returns a `PostconditionResult` so the recovery path treats it like
+ * any other postcondition recheck. B1: prevents a failed ASSERT (e.g. redirect
+ * to /login) from being reported as `recovered`.
+ */
+async function evaluateAssertionRecheck(adapter, opcode) {
+    if (opcode.kind === 'ASSERT_ROUTE') {
+        // Immediate re-check (waitMs: 1) — mirrors the main-path assertion. The
+        // recovery replay no-ops the assertion, so there is nothing to poll for.
+        return evaluatePostcondition(adapter, { type: 'route_matches', pattern: opcode.urlPattern, waitMs: 1 });
+    }
+    const result = await evaluateSurfaceAssertion(adapter, opcode.selectors, opcode.matchAll);
+    return result.success
+        ? { passed: true, reason: 'ASSERT_SURFACE selectors satisfied' }
+        : { passed: false, reason: result.error ?? 'ASSERT_SURFACE failed' };
+}
 /** Mark the variant low-confidence once (keeps the first reason). */
 function recordLowConfidence(state, reason) {
     if (state.lowConfidence)
@@ -431,6 +477,14 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             await verifier.captureBeforeState(adapter);
             logger.debug(`[opcode ${index}] captureBeforeState took ${Date.now() - beforeStart}ms`);
         }
+        // F2: snapshot the theme/locale effect baseline before the action runs so we
+        // can later confirm the app actually reacted (an app that themes via
+        // class/data-theme/storage ignores prefers-color-scheme and would otherwise
+        // record a wrong-theme screenshot as clean success).
+        const themeLocaleKind = getThemeLocaleEffectKind(opcode);
+        if (themeLocaleKind) {
+            await verifier.captureThemeLocaleBaseline(adapter, themeLocaleKind);
+        }
         // `WAIT_FOR` is a pure wait: it extends while the page is progressing, up to
         // the global deadline. Artifact-producing capture opcodes (CAPTURE_SCREENSHOT,
         // END_CLIP) also run against the global deadline, NOT the narrow compiled
@@ -542,6 +596,19 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
                 }
             }
         }
+        // F2: confirm SET_THEME / SET_LOCALE actually took effect on the live page.
+        // Conservative by design — a missing or unchanged signal only flags the
+        // capture low-confidence (so post-capture verification scrutinizes a possibly
+        // wrong-theme/locale screenshot); it NEVER hard-fails these opcodes.
+        if (themeLocaleKind) {
+            const effect = await verifier.verifyThemeLocaleEffect(adapter, themeLocaleKind);
+            if (!effect.observed) {
+                recordLowConfidence(executionState, `${opcode.kind} effect unverified: ${effect.summary}`);
+            }
+            else {
+                logger.debug(`[opcode ${index}] ${opcode.kind} effect confirmed: ${effect.summary}`);
+            }
+        }
         // Record successful mock data application
         if (opcode.kind === 'INJECT_MOCK_DATA') {
             if (!telemetry.mockDataGroupResults)
@@ -689,8 +756,14 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
                 error: `${errorMsg} (recovery succeeded but postcondition could not be rechecked before timeout after ${effectiveTimeoutMs}ms)`,
             };
         }
+        // B1: ASSERT opcodes no-op on the recovery replay, so this recheck is the
+        // only validation left. Re-run the real source-of-truth assertion (route /
+        // surface, incl. matchAll) instead of the vacuous `always` recheck that
+        // turned a failed assertion (e.g. redirect to /login) into `recovered`.
         const runtimePostcondition = resolveRuntimePostcondition(opcode);
-        const postcondition = await evaluatePostconditionWithProgress(adapter, runtimePostcondition, Date.now(), globalDeadlineMs, getProgress);
+        const postcondition = opcode.kind === 'ASSERT_ROUTE' || opcode.kind === 'ASSERT_SURFACE'
+            ? await evaluateAssertionRecheck(adapter, opcode)
+            : await evaluatePostconditionWithProgress(adapter, runtimePostcondition, Date.now(), globalDeadlineMs, getProgress);
         if (postcondition.lowConfidence) {
             recordLowConfidence(executionState, `postcondition ${runtimePostcondition.type}: ${postcondition.reason}`);
         }