autokap 1.8.6 → 1.8.7

package/dist/execution-schema.js

@@ -4,6 +4,7 @@
  * Validates ExecutionProgram at compile output (server) and CLI input boundaries.
  */
 import { z } from 'zod';
+import { upgradeProgram } from './program-migrations.js';
 // ── Postcondition ───────────────────────────────────────────────────
 export const PostconditionSpecSchema = z.object({
     type: z.enum([
@@ -596,6 +597,8 @@ export const PreconditionSpecSchema = z.object({
     storageState: StorageStateSchema.optional(),
     sessionStorage: z.record(z.string(), z.record(z.string(), z.string())).optional(),
     cookies: z.array(cookieSchema).optional(),
+    // AUT-239: active scenario id; runner injects a signed __ak_scenario cookie.
+    scenario: z.string().min(1).optional(),
 }).strict();
 // ── Artifact spec ───────────────────────────────────────────────────
 const ResolutionSchema = z.object({
@@ -603,7 +606,6 @@ const ResolutionSchema = z.object({
     height: z.number().int().positive(),
 }).strict();
 const DEFAULT_VIDEO_DELIVERY_RESOLUTION = { width: 1920, height: 1080 };
-const LEGACY_VIDEO_CAPTURE_RESOLUTION = { width: 2560, height: 1440 };
 function resolutionEquals(a, b) {
     return a.width === b.width && a.height === b.height;
 }
@@ -623,14 +625,14 @@ export const ArtifactSpecSchema = z.object({
 }).strict().superRefine((value, ctx) => {
     if (value.mediaMode === 'video') {
         const res = value.format?.captureResolution;
-        const matchesDefault = res ? resolutionEquals(res, DEFAULT_VIDEO_DELIVERY_RESOLUTION) : false;
-        const matchesLegacy = res ? resolutionEquals(res, LEGACY_VIDEO_CAPTURE_RESOLUTION) : false;
-        if (!res || (!matchesDefault && !matchesLegacy)) {
+        // Legacy 2560×1440 programs are normalized to 1920×1080 by migrate-on-read
+        // (program-migrations.ts, migrate_0→1) BEFORE this schema runs, so only the
+        // canonical resolution reaches validation here.
+        if (!res || !resolutionEquals(res, DEFAULT_VIDEO_DELIVERY_RESOLUTION)) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ['format', 'captureResolution'],
-                message: "mediaMode='video' requires format.captureResolution = { width: 1920, height: 1080 }; " +
-                    'legacy 2560x1440 programs are accepted and normalized at runtime',
+                message: "mediaMode='video' requires format.captureResolution = { width: 1920, height: 1080 }",
             });
         }
     }
@@ -638,7 +640,17 @@ export const ArtifactSpecSchema = z.object({
 // ── Full program ────────────────────────────────────────────────────
 export const ExecutionProgramSchema = z.object({
     presetId: z.string().min(1),
+    // Content-revision counter bumped by the healer; orthogonal to programSchemaVersion (form).
     programVersion: z.number().int().positive(),
+    // FORM version. migrate-on-read (upgradeProgram, run inside parseProgram)
+    // stamps this to the current value before validation. Intentionally optional
+    // and WITHOUT a Zod default: this schema is reused inside signature
+    // verification (program-signing.ts), where injecting a default would mutate
+    // the signed payload and break signature symmetry for programs signed without
+    // the field. Presence at runtime is guaranteed by upgradeProgram, not here.
+    programSchemaVersion: z.number().int().positive().optional(),
+    // Provenance: engine semantics the generator targeted. Informational only.
+    engineVersion: z.number().int().positive().optional(),
     mediaMode: z.enum(['screenshot', 'clip', 'video']),
     baseUrl: StrictUrlSchema,
     maxParallelCaptures: z.number().int().positive().optional(),
@@ -685,12 +697,51 @@ export const HealerPatchSchema = z.object({
 }).strict();
 // ── Typed parse helpers ─────────────────────────────────────────────
 export function parseProgram(data) {
-    return ExecutionProgramSchema.parse(data);
+    // migrate-on-read: bring any stored FORM up to the current shape before the
+    // strict schema runs, so legacy presets parse instead of being rejected en bloc.
+    return ExecutionProgramSchema.parse(upgradeProgram(data));
 }
 export function parseOpcode(data) {
     return ExecutionOpcodeSchema.parse(data);
 }
 export function safeParseProgramResult(data) {
-    return ExecutionProgramSchema.safeParse(data);
+    return ExecutionProgramSchema.safeParse(upgradeProgram(data));
+}
+/**
+ * Returns every NAVIGATE opcode located between a BEGIN_CLIP and its END_CLIP.
+ * Pure and mode-agnostic — mirrors the runtime clip window exactly.
+ */
+export function findNavigateInClipViolations(program) {
+    const violations = [];
+    let insideClip = false;
+    program.steps.forEach((step, index) => {
+        if (step.kind === 'BEGIN_CLIP') {
+            insideClip = true;
+            return;
+        }
+        if (step.kind === 'END_CLIP') {
+            insideClip = false;
+            return;
+        }
+        if (insideClip && step.kind === 'NAVIGATE') {
+            violations.push({
+                stepIndex: index,
+                message: `NAVIGATE at step ${index} is inside a clip (between BEGIN_CLIP and END_CLIP) and would cause a ` +
+                    `white-flash cut in the recording. Move it before BEGIN_CLIP (off-camera warmup), or CLICK an ` +
+                    `in-app <Link> the router intercepts instead.`,
+            });
+        }
+    });
+    return violations;
+}
+/**
+ * Hard-rejection variant for authoring boundaries (preset create/update).
+ * Throws with an actionable message if any NAVIGATE sits inside a clip.
+ */
+export function assertNoNavigateInClip(program) {
+    const violations = findNavigateInClipViolations(program);
+    if (violations.length > 0) {
+        throw new Error(violations.map((v) => v.message).join(' '));
+    }
 }
 //# sourceMappingURL=execution-schema.js.map

package/dist/execution-types.d.ts

@@ -487,6 +487,14 @@ export interface PreconditionSpec {
         domain: string;
         path?: string;
     }>;
+    /**
+     * Active AutoKap Scenario id (AUT-239). When set and `AUTOKAP_SCENARIO_SECRET`
+     * is configured, the runner injects a signed `__ak_scenario=<id>.<sig>` cookie
+     * before navigation, so the client app's cooperative scenario layer reads it
+     * server-side (SSR-safe) and serves the named state's fixtures. Inert if the
+     * secret is absent.
+     */
+    scenario?: string;
 }
 export declare const MEDIA_MODES: readonly ["screenshot", "clip", "video"];
 export type MediaMode = (typeof MEDIA_MODES)[number];
@@ -534,7 +542,26 @@ export interface ArtifactSpec {
 }
 export interface ExecutionProgram {
     presetId: string;
+    /**
+     * Content-revision counter, bumped ONLY by the healer after a selector repair
+     * (program-patcher.ts). Orthogonal to `programSchemaVersion` — it tracks
+     * content changes, never the form of the program.
+     */
     programVersion: number;
+    /**
+     * FORM version of the program, driving migrate-on-read (program-migrations.ts).
+     * Optional on the type so hand-built literals (fixtures) stay terse; guaranteed
+     * present at runtime by `upgradeProgram` (run inside parseProgram), which stamps
+     * it to the current value. Absent = v0 (oldest form). Read with
+     * `?? CURRENT_PROGRAM_SCHEMA_VERSION` when stamping.
+     */
+    programSchemaVersion?: number;
+    /**
+     * Provenance stamp: the engine semantics version the generator compiled this
+     * program against. Informational only — the runtime engine always applies the
+     * current semantics regardless. Absent = legacy (pre-versioning) program.
+     */
+    engineVersion?: number;
     mediaMode: MediaMode;
     baseUrl: string;
     /** Server-resolved concurrency cap for this run, derived from the owner's plan. */
@@ -673,6 +700,22 @@ export interface ArtifactResult {
     /** Favicon extracted from the captured page */
     tabIconData?: Buffer;
     tabIconMimeType?: string;
+    /**
+     * AUT-240 (Layer 4): the capture was produced under a degraded signal — an
+     * AKTree probe that kept throwing was assumed-OK as a last resort, or the page
+     * never reached a visually-stable state. "Assume OK, but flag it." Q4 decision:
+     * produce-only for now (a downstream consumer in gallery / post-capture
+     * verification is a later phase); no LLM is forced off this flag.
+     */
+    lowConfidence?: boolean;
+    /** Why the artifact was flagged low-confidence (human-readable). */
+    lowConfidenceReason?: string;
+    /**
+     * AUT-241 — navigation-watcher warnings captured while this clip/video was
+     * recording (e.g. a full document load mid-take = white flash + cursor loss).
+     * Carried up to `RunResult.warnings`; diagnostic only, never fails the run.
+     */
+    warnings?: string[];
 }
 export type LLMStepType = 'capture_verification' | 'alt_text_generation' | 'healer_invocation';
 export interface LLMStepUsage {
@@ -763,6 +806,13 @@ export interface RunResult {
      * with the version actually captured on the page.
      */
     detectedAppVersion?: string | null;
+    /**
+     * AUT-241 — non-fatal warnings aggregated from every clip/video recording in
+     * the run (full document loads mid-take, unexpected page-side navigations).
+     * Empty/undefined when nothing was flagged. Anti-cut policy surfaces these
+     * instead of masking the cut; deployed presets are grandfathered at run.
+     */
+    warnings?: string[];
     error?: string;
 }
 export interface WaitCondition {
@@ -770,6 +820,38 @@ export interface WaitCondition {
     state: 'visible' | 'attached';
     timeoutMs: number;
 }
+/**
+ * Cheap, side-effect-free snapshot of page activity (AUT-240, Layer C).
+ * Compared across polls by the runner's progress watchdog to distinguish a
+ * slow-but-progressing page (extend the wait) from a genuinely stuck one (cut).
+ */
+export interface ProgressSnapshot {
+    /**
+     * Monotonic count of FIRST-PARTY network lifecycle events
+     * (request/finished/failed) — same site as the live page origin. Third-party
+     * telemetry is excluded so it cannot masquerade as progress.
+     */
+    networkEventCount: number;
+    /** First-party requests issued but not yet finished or failed. */
+    inflightRequests: number;
+    /** `Date.now()` of the last observed first-party network lifecycle event. */
+    lastNetworkActivityAtMs: number;
+    /** `document.readyState`, or 'unknown' if unreadable. */
+    readyState: string;
+    /** Total element count — a cheap DOM-churn signal — or -1 if unreadable. */
+    domNodeCount: number;
+    /** True when the readability probe threw (itself a sign of navigation). */
+    navigating?: boolean;
+}
+/** Result of `RuntimeAdapter.waitForVisuallyStable` (AUT-240, Layer B). */
+export interface VisualStabilityResult {
+    /** Whether the page reached a clean, stable state before the deadline. */
+    stable: boolean;
+    /** Human-readable explanation (which signal stayed noisy, if any). */
+    reason: string;
+    /** Total time spent stabilizing (ms). */
+    waitedMs: number;
+}
 export interface ClickOptions {
     /** Force click even if element is covered */
     force?: boolean;
@@ -822,6 +904,12 @@ export interface RecordingResult {
     durationMs: number;
     mimeType: string;
     trimStartMs?: number;
+    /**
+     * AUT-241 — human-readable warnings collected by the navigation watcher
+     * during this recording window (e.g. a full document load = white flash +
+     * cursor loss). Surfaced up to `RunResult.warnings`; never fails the run.
+     */
+    warnings?: string[];
 }
 export interface TypeOptions {
     /**
@@ -887,6 +975,14 @@ export interface RuntimeAdapter {
      * adapters that cannot resolve a title should leave this method off.
      */
     getPageTitle?(): Promise<string | null>;
+    /**
+     * Text content of the first element matching `selector`, read live from the
+     * DOM via Playwright (`locator().first().textContent()`). Preferred over the
+     * AKTree for `text_contains` postconditions (AUT-240, Layer A). Returns null
+     * if the selector misses or the read fails. Optional — adapters without it
+     * make `text_contains` fall back to the AKTree.
+     */
+    getTextContent?(selector: string): Promise<string | null>;
     /**
      * Read the captured app's version from the live page (meta tag, window
      * global, or data attribute). Mirrors `extractAppVersionFromHtml` server-side
@@ -989,4 +1085,24 @@ export interface RuntimeAdapter {
     clickHidden?(opts: {
         selector: string;
     }): Promise<void>;
+    /**
+     * Cheap snapshot of page activity used by the runner's progress watchdog to
+     * decide whether a wait is "slow-but-progressing" (keep waiting) or "stuck"
+     * (cut). Must never reject — implementations catch internally and set
+     * `navigating: true` when the readability probe throws. Adapters that cannot
+     * provide it leave it off; the runner then falls back to fixed budgets.
+     */
+    getProgressSnapshot?(): Promise<ProgressSnapshot>;
+    /**
+     * Wait for the page to be visually stable before a screenshot (Layer B):
+     * fonts ready, images loaded, no semantic loaders ([aria-busy]/progressbar)
+     * visible, DOM quiet, with a bounded pixel-convergence fallback. Best-effort —
+     * never throws and never blocks the capture: when it cannot reach a clean
+     * state it returns `stable: false` with a reason and the runner captures
+     * anyway. Adapters that cannot provide it leave it off; the runner falls back
+     * to the legacy `smartWaitForStability`.
+     */
+    waitForVisuallyStable?(options?: {
+        maxWaitMs?: number;
+    }): Promise<VisualStabilityResult>;
 }

package/dist/opcode-runner.d.ts

@@ -5,7 +5,7 @@
  * Executes opcodes sequentially, verifies postconditions,
  * delegates to recovery chain on failure, and respects circuit breaker.
  */
-import type { ExecutionProgram, ExecutionOpcode, RuntimeAdapter, OpcodeResultStatus, RunResult, HealerPatch, VariantSpec } from './execution-types.js';
+import type { ExecutionProgram, ExecutionOpcode, RuntimeAdapter, OpcodeResultStatus, RunResult, HealerPatch, VariantSpec, ProgressSnapshot } from './execution-types.js';
 import type { LLMProviderConfig, LLMCallResult } from './llm-provider.js';
 export interface RecoveryChain {
     attempt(failedOpcode: ExecutionOpcode, opcodeIndex: number, adapter: RuntimeAdapter, options?: RecoveryAttemptOptions): Promise<RecoveryAttemptResult>;
@@ -19,6 +19,13 @@ export interface RecoveryAttemptResult {
 }
 export interface RecoveryAttemptOptions {
     remainingTimeMs?: number;
+    /**
+     * AUT-240 (Phase 5): absolute global wait deadline. Lets recovery re-checks
+     * extend-on-progress (like the main path) instead of replaying a fixed budget.
+     */
+    globalDeadlineMs?: number;
+    /** Progress probe for the recovery watchdog (omitted ⇒ fixed budgets). */
+    getProgress?: () => Promise<ProgressSnapshot | null>;
     maxDeterministicRetries?: number;
     currentVariant?: VariantSpec;
     allowPageReload?: boolean;

package/dist/opcode-runner.js

@@ -6,7 +6,8 @@
  * delegates to recovery chain on failure, and respects circuit breaker.
  */
 import { isSoftOpcodeKind } from './execution-types.js';
-import { evaluatePostcondition } from './postcondition.js';
+import { evaluatePostcondition, evaluatePostconditionWithProgress } from './postcondition.js';
+import { WAIT_CONTRACT_VERSION, resolveGlobalWaitDeadlineMs, runWithProgressBudget, } from './wait-contract.js';
 import { ActionVerifier } from './action-verifier.js';
 import { CircuitBreaker } from './circuit-breaker.js';
 import { smartWaitForStability } from './smart-wait.js';
@@ -98,6 +99,14 @@ function resolveRuntimePostcondition(opcode) {
     }
     return opcode.postcondition;
 }
+/** Mark the variant low-confidence once (keeps the first reason). */
+function recordLowConfidence(state, reason) {
+    if (state.lowConfidence)
+        return;
+    state.lowConfidence = true;
+    state.lowConfidenceReason = reason;
+    logger.debug(`[run] low-confidence flagged: ${reason}`);
+}
 // ── Main execution function ─────────────────────────────────────────
 export async function executeProgram(program, createAdapter, options = {}) {
     const recoveryChain = options.recoveryChain ?? new NoOpRecoveryChain();
@@ -117,6 +126,7 @@ export async function executeProgram(program, createAdapter, options = {}) {
         healerInvocations: 0,
         circuitBreakerTrips: 0,
     };
+    logger.debug(`[run] wait contract v${WAIT_CONTRACT_VERSION} (adaptive budgets + visual stability)`);
     let nextVariantIndex = 0;
     const workerCount = Math.min(maxParallelVariants, program.variants.length);
     const workers = Array.from({ length: workerCount }, async () => {
@@ -148,6 +158,9 @@ export async function executeProgram(program, createAdapter, options = {}) {
     const aborted = options.abortSignal?.aborted && completedVariantResults.length < program.variants.length;
     const success = !aborted && completedVariantResults.length > 0 && completedVariantResults.every(v => v.success);
     const detectedAppVersion = completedVariantResults.reduce((acc, variantResult) => acc ?? (variantResult.detectedAppVersion ?? null), null);
+    // AUT-241 — surface (don't mask) cuts: aggregate every recording warning from
+    // each variant's clip/video artifacts. Diagnostic only; never affects success.
+    const aggregatedWarnings = completedVariantResults.flatMap((v) => v.artifacts.flatMap((a) => a.warnings ?? []));
     return {
         programId: program.presetId,
         success,
@@ -157,6 +170,7 @@ export async function executeProgram(program, createAdapter, options = {}) {
         opcodeTimings,
         totalDurationMs: Date.now() - startTime,
         detectedAppVersion,
+        warnings: aggregatedWarnings.length ? aggregatedWarnings : undefined,
         error: aborted ? 'aborted' : (success ? undefined : completedVariantResults.find(v => !v.success)?.error),
     };
 }
@@ -302,6 +316,13 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
     const startTime = Date.now();
     const effectiveTimeoutMs = resolveOpcodeTimeoutMs(opcode);
     const deadlineMs = startTime + effectiveTimeoutMs;
+    // AUT-240 (Layer C): a hard, per-media global deadline for adaptive waits,
+    // separate from the compiled per-opcode timeout. The compiled timeout acts as
+    // a FLOOR (never a ceiling), so `WAIT_FOR` and postconditions can extend while
+    // the page is still progressing, up to this deadline. Interactions stay on the
+    // narrow `deadlineMs` (Playwright auto-waiting handles those).
+    const globalDeadlineMs = resolveGlobalWaitDeadlineMs(startTime, effectiveTimeoutMs, artifactPlan.mediaMode);
+    const getProgress = makeProgressGetter(adapter);
     const actionEffectPolicy = getOpcodeActionEffectPolicy(opcode);
     const isSoft = isSoftOpcodeKind(opcode.kind);
     // Track page context for circuit breaker
@@ -318,21 +339,41 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             await verifier.captureBeforeState(adapter);
             logger.debug(`[opcode ${index}] captureBeforeState took ${Date.now() - beforeStart}ms`);
         }
-        const actionBudgetMs = getRemainingTimeMs(deadlineMs);
+        // `WAIT_FOR` is a pure wait: it extends while the page is progressing, up to
+        // the global deadline. All other opcodes are interactions bounded by the
+        // narrow per-opcode deadline (Playwright auto-waiting covers them).
+        const isPureWait = opcode.kind === 'WAIT_FOR';
+        const actionDeadlineMs = isPureWait ? globalDeadlineMs : deadlineMs;
+        const actionBudgetMs = getRemainingTimeMs(actionDeadlineMs);
         if (actionBudgetMs <= 0) {
             const reason = `timeout after ${effectiveTimeoutMs}ms`;
-            logger.debug(`[opcode ${index}] no budget left after captureBeforeState (deadline=${deadlineMs}, now=${Date.now()})`);
+            logger.debug(`[opcode ${index}] no budget left after captureBeforeState (deadline=${actionDeadlineMs}, now=${Date.now()})`);
             if (isSoft)
                 return softSkipResult(opcode, index, startTime, reason, telemetry);
-            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, reason);
         }
         // For mediaMode='video', capture pre-action timing + bbox metadata inside
         // the active clip window only. Opcodes outside a clip are not part of the
         // video output.
         const preTiming = await capturePreActionTiming(opcode, adapter, executionState.activeClip, artifactPlan);
-        logger.debug(`[opcode ${index}] action exec start — actionBudget ${actionBudgetMs}ms`);
+        logger.debug(`[opcode ${index}] action exec start — actionBudget ${actionBudgetMs}ms${isPureWait ? ' (adaptive)' : ''}`);
         const actionStart = Date.now();
-        const result = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), actionBudgetMs);
+        let result;
+        if (opcode.kind === 'WAIT_FOR' && getProgress) {
+            // Extend-on-progress: give the wait a generous budget (up to the global
+            // deadline) and let the watchdog cut it early only when the page is truly
+            // stuck. A slow-but-progressing page no longer trips a fixed timeout.
+            const waited = await runWithProgressBudget((budgetMs) => executeOpcodeAction({ ...opcode, timeoutMs: Math.max(1, Math.round(budgetMs)) }, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), { startedAtMs: startTime, globalDeadlineMs, minBudgetMs: effectiveTimeoutMs, getProgress });
+            result = waited.result ?? {
+                success: false,
+                error: waited.cut === 'stuck'
+                    ? `WAIT_FOR cut: page stuck (no progress for ${Math.round(waited.waitedMs)}ms)`
+                    : `WAIT_FOR cut: global deadline reached, page never settled`,
+            };
+        }
+        else {
+            result = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), actionBudgetMs);
+        }
         logger.debug(`[opcode ${index}] action exec end — took ${Date.now() - actionStart}ms, success=${result.success}${result.error ? `, error=${result.error}` : ''}`);
         if (preTiming) {
             const keystrokeOffsetsMs = result.keystrokeTimestampsMs && result.keystrokeTimestampsMs.length > 0
@@ -358,39 +399,46 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             const reason = result.error ?? 'action failed';
             if (isSoft)
                 return softSkipResult(opcode, index, startTime, reason, telemetry);
-            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, reason);
         }
-        // Verify postcondition
-        const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
+        // Verify postcondition — extend-on-progress up to the global deadline so a
+        // slow action no longer starves it (failure mode #3: clamped to ~1ms).
+        const postconditionBudgetMs = getRemainingTimeMs(globalDeadlineMs);
         if (postconditionBudgetMs <= 0) {
             const reason = `timeout after ${effectiveTimeoutMs}ms`;
             logger.debug(`[opcode ${index}] no budget left for postcondition check`);
             if (isSoft)
                 return softSkipResult(opcode, index, startTime, reason, telemetry);
-            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, reason);
         }
         const runtimePostcondition = resolveRuntimePostcondition(opcode);
         const postStart = Date.now();
-        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(runtimePostcondition, postconditionBudgetMs));
+        const postcondition = await evaluatePostconditionWithProgress(adapter, runtimePostcondition, postStart, globalDeadlineMs, getProgress);
         logger.debug(`[opcode ${index}] postcondition (${runtimePostcondition.type}) took ${Date.now() - postStart}ms — passed=${postcondition.passed}, reason="${postcondition.reason}"`);
+        if (postcondition.lowConfidence) {
+            recordLowConfidence(executionState, `postcondition ${runtimePostcondition.type}: ${postcondition.reason}`);
+        }
         if (!postcondition.passed) {
             const reason = `postcondition failed: ${postcondition.reason}`;
             if (isSoft)
                 return softSkipResult(opcode, index, startTime, reason, telemetry);
-            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, reason);
         }
         // Verify action effects through the shared policy. Weak `any_change`
         // postconditions are only meaningful if this verifier observes a real
         // URL/tree/state/scroll change.
         if (actionEffectPolicy.captureBefore) {
             const verification = await verifier.verifyAfterAction(adapter);
+            if (verification.lowConfidence) {
+                recordLowConfidence(executionState, `action effect unverified: ${verification.summary}`);
+            }
             if (!verification.hadEffect && actionEffectPolicy.requireEffect) {
                 if (opcode.kind === 'PRESS_KEY' && actionEffectPolicy.noEffectMode === 'allow') {
                     logger.debug(`[opcode ${index}] PRESS_KEY had no DOM effect (${verification.summary}) — ` +
                         `postcondition passed, treating as redundant-but-successful`);
                 }
                 else {
-                    return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, `action had no effect: ${verification.summary}`);
+                    return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, `action had no effect: ${verification.summary}`);
                 }
             }
         }
@@ -424,7 +472,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
         const errorMsg = err instanceof Error ? err.message : String(err);
         if (isSoft)
             return softSkipResult(opcode, index, startTime, errorMsg, telemetry);
-        return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg);
+        return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, errorMsg);
     }
 }
 /** Post-action breathing room (ms) injected between visible interactions
@@ -450,8 +498,9 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 // ── Failure handling with recovery ──────────────────────────────────
-async function handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg) {
+async function handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, errorMsg) {
     const actionEffectPolicy = getOpcodeActionEffectPolicy(opcode);
+    const getProgress = makeProgressGetter(adapter);
     const breakerState = breaker.recordFailure(index, opcode.maxFailures);
     if (breakerState.tripped) {
         telemetry.circuitBreakerTrips++;
@@ -464,7 +513,11 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
             error: `${errorMsg} (circuit breaker: ${breakerState.reason})`,
         };
     }
-    const remainingTimeMs = getRemainingTimeMs(deadlineMs);
+    // AUT-240 (Phase 5): recovery budgets to the GLOBAL deadline, not the narrow
+    // compiled one. Otherwise an adaptive WAIT_FOR that consumed its compiled
+    // budget would leave zero for recovery (failure mode #1) — and selector-repair
+    // / healer strategies that could actually fix the failure would never run.
+    const remainingTimeMs = getRemainingTimeMs(globalDeadlineMs);
     if (remainingTimeMs <= 0) {
         return {
             opcodeIndex: index,
@@ -490,6 +543,8 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
     }
     const recovery = await recoveryChain.attempt(opcode, index, adapter, {
         remainingTimeMs,
+        globalDeadlineMs,
+        getProgress,
         maxDeterministicRetries: Math.max(0, opcode.maxFailures - breakerState.opcodeFailures),
         currentVariant,
         allowPageReload: !executionState.activeClip,
@@ -511,7 +566,7 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
         if (recovery.patch) {
             healerPatches.push(recovery.patch);
         }
-        const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
+        const postconditionBudgetMs = getRemainingTimeMs(globalDeadlineMs);
         if (postconditionBudgetMs <= 0) {
             return {
                 opcodeIndex: index,
@@ -523,7 +578,10 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
             };
         }
         const runtimePostcondition = resolveRuntimePostcondition(opcode);
-        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(runtimePostcondition, postconditionBudgetMs));
+        const postcondition = await evaluatePostconditionWithProgress(adapter, runtimePostcondition, Date.now(), globalDeadlineMs, getProgress);
+        if (postcondition.lowConfidence) {
+            recordLowConfidence(executionState, `postcondition ${runtimePostcondition.type}: ${postcondition.reason}`);
+        }
         if (!postcondition.passed) {
             return {
                 opcodeIndex: index,
@@ -536,6 +594,9 @@ async function handleFailure(opcode, index, adapter, verifier, breaker, recovery
         }
         if (actionEffectPolicy.captureBefore) {
             const verification = await verifier.verifyAfterAction(adapter);
+            if (verification.lowConfidence) {
+                recordLowConfidence(executionState, `action effect unverified: ${verification.summary}`);
+            }
             if (!verification.hadEffect && actionEffectPolicy.requireEffect) {
                 return {
                     opcodeIndex: index,
@@ -611,13 +672,34 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                 assertSurfacePostconditionSource(opcode);
                 return evaluateSurfaceAssertion(adapter, opcode.selectors, opcode.matchAll);
             case 'CAPTURE_SCREENSHOT': {
-                const stability = await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                // AUT-240 (Layer B): stabilize visually before capture but NEVER fail the
+                // capture on it. Prefer the adapter's adaptive stabilizer (fonts/images/
+                // semantic loaders/DOM-quiet + bounded pixel fallback); fall back to the
+                // legacy smart-wait for adapters that don't implement it. A page that
+                // never fully settles (e.g. a perpetual animation) is captured anyway.
+                const stabilize = (maxWaitMs) => adapter.waitForVisuallyStable
+                    ? adapter.waitForVisuallyStable({ maxWaitMs })
+                    : smartWaitForStability(adapter, { maxWaitMs }).then((r) => ({
+                        stable: r.stable,
+                        reason: r.waitedFor.join(', ') || 'unknown',
+                    }));
+                const stability = await stabilize(5000);
+                if (!stability.stable) {
+                    logger.debug(`[opcode ${opcodeIndex}] capturing despite unstable page: ${stability.reason}`);
+                }
+                // AUT-240 (Layer 4): flag the capture low-confidence if a faux-vert was
+                // assumed-OK earlier in this variant, or if the page never reached a
+                // visually-stable state before this shot. "Assume OK, but flag it." Keep
+                // both reasons when both apply (don't let one mask the other).
+                const captureLowConfidence = Boolean(executionState.lowConfidence) || !stability.stable;
+                const lowConfidenceReasons = [];
+                if (executionState.lowConfidence && executionState.lowConfidenceReason) {
+                    lowConfidenceReasons.push(executionState.lowConfidenceReason);
+                }
                 if (!stability.stable) {
-                    return {
-                        success: false,
-                        error: `page not stable before screenshot; unresolved loaders: ${stability.waitedFor.join(', ') || 'unknown'}`,
-                    };
+                    lowConfidenceReasons.push(`captured before visual stability: ${stability.reason}`);
                 }
+                const captureLowConfidenceReason = lowConfidenceReasons.join('; ') || undefined;
                 const captureUrl = await adapter.getCurrentUrl();
                 const takeBuffer = async () => {
                     if (opcode.elementSelector && adapter.takeElementScreenshot) {
@@ -648,7 +730,7 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                         });
                     }
                     if (!verification.passed) {
-                        await smartWaitForStability(adapter, { maxWaitMs: 8000 });
+                        await stabilize(8000);
                         const retryBuffer = await takeBuffer();
                         const retryVerification = await verifyCaptureQuality(retryBuffer, {
                             expectedDescription: opcode.description,
@@ -733,6 +815,8 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     variantId: currentVariant?.id,
                     tabIconData,
                     tabIconMimeType,
+                    lowConfidence: captureLowConfidence || undefined,
+                    lowConfidenceReason: captureLowConfidence ? captureLowConfidenceReason : undefined,
                 });
                 break;
             }
@@ -781,6 +865,8 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     stepDescription: opcode.description,
                     stepIndex: opcodeIndex,
                     variantId: currentVariant?.id,
+                    // AUT-241 — full-load / unexpected-nav warnings seen during this take.
+                    warnings: recording.warnings,
                 });
                 break;
             }
@@ -888,11 +974,16 @@ function resolveClipIdentity(activeClip, opcode) {
         clipName: opcode.clipName ?? activeClip?.clipName ?? opcode.description,
     };
 }
-function withClampedPostconditionTimeout(spec, maxWaitMs) {
-    return {
-        ...spec,
-        waitMs: Math.max(1, Math.min(spec.waitMs ?? maxWaitMs, maxWaitMs)),
-    };
+/**
+ * Bind the adapter's optional progress probe for the watchdog, or return
+ * undefined when the adapter has none (graceful degradation: waits then fall
+ * back to fixed compiled budgets). See `runWithProgressBudget`.
+ */
+function makeProgressGetter(adapter) {
+    if (!adapter.getProgressSnapshot)
+        return undefined;
+    const getSnapshot = adapter.getProgressSnapshot.bind(adapter);
+    return () => getSnapshot();
 }
 function evaluateImmediateAssertion(result, prefix) {
     return result.passed