autokap 1.9.2 → 1.9.4

package/dist/cli-runner.js

@@ -217,12 +217,51 @@ export async function runCapture(options) {
     // badge on the preset while it captures. Best-effort + local-only: skip dry
     // runs and cloud runs (AUTOKAP_RUN_ID is set on cloud runners, which own
     // their own capture_runs row). A failure here must never block the capture.
-    if (!options.dryRun && !process.env.AUTOKAP_RUN_ID) {
+    const isLocalRegisteredRun = !options.dryRun && !process.env.AUTOKAP_RUN_ID;
+    if (isLocalRegisteredRun) {
         await postRunStart(config, runId, program.presetId, program.variants.length, options.env);
     }
+    // Ctrl-C handling: a local run that registered itself server-side must never
+    // leave the preset stuck on the "En cours" badge. On SIGINT/SIGTERM we abort
+    // the in-flight capture (so the finally-block cleanup runs) and best-effort
+    // tell the server the run was interrupted — otherwise the capture_runs row
+    // sits in `running` and the preset stays "capturing" until the 15-min stale
+    // cutoff. A caller-supplied abortSignal is forwarded into the same controller
+    // so both paths converge on one cancellation.
+    const abortController = new AbortController();
+    if (options.abortSignal) {
+        if (options.abortSignal.aborted) {
+            abortController.abort(options.abortSignal.reason);
+        }
+        else {
+            options.abortSignal.addEventListener('abort', () => abortController.abort(options.abortSignal.reason), { once: true });
+        }
+    }
+    let interrupted = false;
+    let abortNotified = false;
+    const notifyAborted = async () => {
+        if (abortNotified || !isLocalRegisteredRun)
+            return;
+        abortNotified = true;
+        await postRunAborted(config, runId, program.presetId, options.env);
+    };
+    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);
+        }
+        interrupted = true;
+        logger.warn(`[capture] ${signal} received — stopping the run and notifying AutoKap…`);
+        abortController.abort(new Error('User interrupted (Ctrl-C)'));
+    };
+    if (isLocalRegisteredRun) {
+        process.on('SIGINT', onInterrupt);
+        process.on('SIGTERM', onInterrupt);
+    }
     const runOptions = {
         recoveryChain,
-        abortSignal: options.abortSignal,
+        abortSignal: abortController.signal,
         maxParallelVariants,
         llmConfig,
         presetName: program.presetId,
@@ -292,15 +331,30 @@ export async function runCapture(options) {
     };
     let runResult;
     let cliResult;
+    let runAborted = false;
     try {
         runResult = await executeProgram(program, createAdapter, runOptions);
+        runAborted = interrupted || runResult.error === 'aborted';
         if (runResult.success) {
             logger.info(`[capture] Run completed successfully — ${runResult.telemetry.totalOpcodes} opcodes, ${runResult.telemetry.recoveredOpcodes} recovered, ${runResult.totalDurationMs}ms`);
         }
+        else if (runAborted) {
+            logger.warn('[capture] Run interrupted by the user — skipping artifact upload.');
+        }
         else {
             logger.error(`[capture] Run failed: ${runResult.error}`);
         }
-        if (options.dryRun) {
+        if (runAborted) {
+            // Don't upload partial artifacts for a cancelled run; the server is told
+            // separately (notifyAborted) so the preset leaves the "capturing" state.
+            cliResult = {
+                success: false,
+                runId,
+                runResult,
+                error: 'Capture interrupted (Ctrl-C)',
+            };
+        }
+        else if (options.dryRun) {
             logger.info(`[capture] DRY RUN complete — ${runResult.telemetry.totalOpcodes} opcodes executed, 0 captures, 0 credits charged`);
             cliResult = { success: runResult.success, runId, runResult };
         }
@@ -354,6 +408,16 @@ export async function runCapture(options) {
         }
     }
     finally {
+        if (isLocalRegisteredRun) {
+            process.off('SIGINT', onInterrupt);
+            process.off('SIGTERM', onInterrupt);
+        }
+        // On interruption, mark the run terminal server-side regardless of the
+        // user's debug-log preference, so the preset never stays stuck "capturing".
+        // Idempotent with the error-log flush below (same capture_failed dedupeKey).
+        if (runAborted) {
+            await notifyAborted();
+        }
         // AUT-149: export structured debug logs to AutoKap on capture failure.
         // Best-effort — the LogCollector swallows network errors.
         const shouldExport = options.exportDebugLogs !== false
@@ -693,6 +757,29 @@ async function postRunStart(config, runId, presetId, variantCount, env) {
         logger.warn(`[capture] Run registration error: ${message}`);
     }
 }
+// Best-effort terminal notification when a local run is interrupted (Ctrl-C).
+// Marks the run failed server-side and clears the preset's "capturing" badge,
+// so an aborted capture can't leave the preset stuck "En cours". Never throws.
+async function postRunAborted(config, runId, presetId, env) {
+    try {
+        const response = await fetch(`${config.apiBaseUrl}/api/cli/runs`, {
+            method: 'PATCH',
+            headers: {
+                'Authorization': `Bearer ${config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ runId, presetId, status: 'aborted', env }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            logger.warn(`[capture] Failed to report interruption (HTTP ${response.status}); the preset may show "in progress" until the stale cutoff`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[capture] Interruption report error: ${message}`);
+    }
+}
 async function uploadResults(config, program, result, runId, sessionId, provenance) {
     const artifactJobs = result.variantResults.flatMap((variant) => {
         const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);

package/dist/execution-types.d.ts

@@ -600,10 +600,11 @@ export interface ExecutionProgram {
      */
     deviceConfigs?: Record<string, DeviceConfig>;
     /**
-     * Project-level public URL used to decorate browser mockups. The CLI
+     * Project-level decorative URL used to decorate browser mockups. The CLI
      * substitutes the captured origin (typically a local dev server) with this
      * value via `transformBrowserUrl` before baking it into the browser bar.
-     * Server-resolved from `projects.public_url`.
+     * AUT-269: derived automatically from the project's prod environment base
+     * URL (absent when no prod environment is configured), not a separate field.
      */
     publicUrl?: string;
     /**

package/dist/opcode-actions.d.ts

@@ -54,5 +54,15 @@ export interface OpcodeActionResult {
      * click instead of when the cursor was still travelling.
      */
     clickTimestampsMs?: number[];
+    /**
+     * For CAPTURE_SCREENSHOT: index in the variant's `artifacts` array of the
+     * screenshot this action just delivered. The deterministic capture pushes the
+     * artifact immediately; LLM enrichment (quality verification + alt text) runs
+     * afterwards in `executeOpcode` and mutates this artifact in place, so it can
+     * never void an already-captured screenshot or trip the action timeout.
+     */
+    captureArtifactIndex?: number;
+    /** For CAPTURE_SCREENSHOT: page URL at capture time, reused by enrichment. */
+    captureUrl?: string;
 }
 export declare function executeOpcodeCoreAction(opcode: ExecutionOpcode, adapter: RuntimeAdapter, context?: OpcodeActionContext): Promise<OpcodeActionResult>;

package/dist/opcode-runner.js

@@ -55,6 +55,15 @@ export class NoOpRecoveryChain {
 }
 const MIN_CLIP_FINALIZATION_TIMEOUT_MS = 30000;
 const DEFAULT_VIDEO_RECORDING_RESOLUTION = { width: 1920, height: 1080 };
+/**
+ * The compiled per-opcode action budget. For CAPTURE_SCREENSHOT this governs
+ * ONLY the deterministic capture (visual stabilize + screenshot + favicon/title
+ * + artifact push); LLM enrichment (quality verification + alt text) runs AFTER
+ * the action under the global wait deadline (see `enrichCaptureArtifact`) and
+ * must never be folded back under this timeout — that is the regression this
+ * separation prevents. END_CLIP finalization gets a floor since muxing a
+ * recording is inherently slow.
+ */
 function resolveOpcodeTimeoutMs(opcode) {
     if (opcode.kind === 'END_CLIP') {
         return Math.max(opcode.timeoutMs, MIN_CLIP_FINALIZATION_TIMEOUT_MS);
@@ -156,8 +165,31 @@ export async function executeProgram(program, createAdapter, options = {}) {
     });
     await Promise.all(workers);
     const completedVariantResults = variantResults.filter((result) => Boolean(result));
-    const aborted = options.abortSignal?.aborted && completedVariantResults.length < program.variants.length;
-    const success = !aborted && completedVariantResults.length > 0 && completedVariantResults.every(v => v.success);
+    const aborted = Boolean(options.abortSignal?.aborted) && completedVariantResults.length < program.variants.length;
+    // Fail-closed on incomplete delivery. Previously `success` was computed purely
+    // from the SURVIVING variant results, so a run that silently dropped variants
+    // (a variant finishing "ok" while persisting no artifact) was recorded as a
+    // clean success — a 4-of-24 capture looked identical to a full run, got billed,
+    // was never retried, and surfaced nothing. Require that every variant ran,
+    // succeeded, AND produced its expected number of artifacts; name the deficient
+    // variants so the failure is actionable and the runtime cause is diagnosable
+    // straight from the run log. Dry runs intentionally skip capture opcodes (and
+    // programs with no capture points have nothing to enforce), so they are exempt
+    // from the artifact check but still require every variant to succeed.
+    const expectedArtifactsPerVariant = program.steps.filter((step) => isArtifactProducingOpcode(step.kind)).length;
+    const enforceArtifactCompleteness = !options.dryRun && expectedArtifactsPerVariant > 0;
+    const deficientVariants = program.variants
+        .map((variant, index) => ({ variant, result: variantResults[index] }))
+        .filter(({ result }) => !result
+        || !result.success
+        || (enforceArtifactCompleteness && result.artifacts.length < expectedArtifactsPerVariant))
+        .map(({ variant, result }) => !result
+        ? `${variant.id} (not executed)`
+        : !result.success
+            ? `${variant.id} (failed: ${result.error ?? 'unknown error'})`
+            : `${variant.id} (${result.artifacts.length}/${expectedArtifactsPerVariant} artifacts)`);
+    const incompleteDelivery = deficientVariants.length > 0;
+    const success = !aborted && completedVariantResults.length > 0 && !incompleteDelivery;
     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.
@@ -172,7 +204,11 @@ export async function executeProgram(program, createAdapter, options = {}) {
         totalDurationMs: Date.now() - startTime,
         detectedAppVersion,
         warnings: aggregatedWarnings.length ? aggregatedWarnings : undefined,
-        error: aborted ? 'aborted' : (success ? undefined : completedVariantResults.find(v => !v.success)?.error),
+        error: aborted
+            ? 'aborted'
+            : success
+                ? undefined
+                : `incomplete run: ${deficientVariants.length}/${program.variants.length} variant(s) did not deliver expected artifacts — ${deficientVariants.join('; ')}`,
         failureKind: success ? undefined : completedVariantResults.find(v => v.failureKind)?.failureKind,
     };
 }
@@ -320,6 +356,13 @@ function softSkipResult(opcode, index, startTime, reason, telemetry) {
         error: reason,
     };
 }
+/** Opcodes whose ACTION produces a persisted artifact (a screenshot or a finalized
+ * video clip). A passing postcondition does NOT imply the artifact exists, so these
+ * get special handling on the recovery path (executeOpcode → failWithRecovery) and
+ * in the run-level completeness gate (executeProgram). */
+function isArtifactProducingOpcode(kind) {
+    return kind === 'CAPTURE_SCREENSHOT' || kind === 'END_CLIP';
+}
 async function executeOpcode(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, opcodeTimings, artifacts, options, variantId, executionState, artifactPlan, mockDataGroups, currentVariant, credentials) {
     const startTime = Date.now();
     const effectiveTimeoutMs = resolveOpcodeTimeoutMs(opcode);
@@ -333,6 +376,47 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
     const getProgress = makeProgressGetter(adapter);
     const actionEffectPolicy = getOpcodeActionEffectPolicy(opcode);
     const isSoft = isSoftOpcodeKind(opcode.kind);
+    // Snapshot so we can tell whether THIS opcode produced its artifact. A recovered
+    // CAPTURE_SCREENSHOT must not pass as a phantom success when no screenshot was
+    // taken — the postcondition (e.g. element_visible) can pass without a capture.
+    const artifactCountAtStart = artifacts.length;
+    // Wraps handleFailure: when recovery succeeds for an artifact-producing opcode
+    // that pushed NO artifact for itself, re-run the capture once so the artifact
+    // truly exists; hard-fail if it still can't. END_CLIP finalization is stateful,
+    // so it hard-fails without re-running. Without this a "recovered"
+    // CAPTURE_SCREENSHOT finishes ok with no screenshot — the silent partial loss.
+    const failWithRecovery = async (reason) => {
+        const failureResult = await handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, reason);
+        if (failureResult.status !== 'recovered'
+            || !isArtifactProducingOpcode(opcode.kind)
+            || artifacts.length > artifactCountAtStart) {
+            return failureResult;
+        }
+        if (opcode.kind === 'CAPTURE_SCREENSHOT') {
+            const recaptureBudgetMs = getRemainingTimeMs(globalDeadlineMs);
+            if (recaptureBudgetMs > 0) {
+                let recapture;
+                try {
+                    recapture = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), recaptureBudgetMs);
+                }
+                catch (err) {
+                    recapture = { success: false, error: err instanceof Error ? err.message : String(err) };
+                }
+                if (recapture.success && artifacts.length > artifactCountAtStart) {
+                    logger.debug(`[opcode ${index}] re-captured screenshot after recovery (${reason})`);
+                    return failureResult;
+                }
+            }
+        }
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'failed',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: failureResult.recoveryAttempts ?? 1,
+            error: `recovery succeeded but produced no ${opcode.kind === 'END_CLIP' ? 'clip' : 'screenshot'} artifact: ${reason}`,
+        };
+    };
     // Track page context for circuit breaker
     try {
         const url = await adapter.getCurrentUrl();
@@ -358,7 +442,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, globalDeadlineMs, effectiveTimeoutMs, reason);
+            return failWithRecovery(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
@@ -407,7 +491,7 @@ 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, globalDeadlineMs, effectiveTimeoutMs, reason);
+            return failWithRecovery(reason);
         }
         // Verify postcondition — extend-on-progress up to the global deadline so a
         // slow action no longer starves it (failure mode #3: clamped to ~1ms).
@@ -417,7 +501,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, globalDeadlineMs, effectiveTimeoutMs, reason);
+            return failWithRecovery(reason);
         }
         const runtimePostcondition = resolveRuntimePostcondition(opcode);
         const postStart = Date.now();
@@ -430,7 +514,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, globalDeadlineMs, effectiveTimeoutMs, reason);
+            return failWithRecovery(reason);
         }
         // Verify action effects through the shared policy. Weak `any_change`
         // postconditions are only meaningful if this verifier observes a real
@@ -446,7 +530,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
                         `postcondition passed, treating as redundant-but-successful`);
                 }
                 else {
-                    return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, globalDeadlineMs, effectiveTimeoutMs, `action had no effect: ${verification.summary}`);
+                    return failWithRecovery(`action had no effect: ${verification.summary}`);
                 }
             }
         }
@@ -468,6 +552,18 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             await sleep(VIDEO_POST_ACTION_SETTLE_MS);
         }
         breaker.recordSuccess(index);
+        // Enrich the just-captured screenshot OFF the timed action path: quality
+        // verification + alt text run here, under the global wait deadline, and
+        // mutate the artifact in place — so slow LLM calls can never void a
+        // delivered screenshot (the failure this fixes). Recaptured screenshots from
+        // the recovery path are intentionally left un-enriched (recovery stays
+        // deterministic and fast).
+        if (opcode.kind === 'CAPTURE_SCREENSHOT'
+            && options.llmConfig
+            && result.captureArtifactIndex !== undefined
+            && result.captureUrl !== undefined) {
+            await enrichCaptureArtifact(artifacts[result.captureArtifactIndex], opcode, adapter, result.captureUrl, currentVariant, options, telemetry, globalDeadlineMs);
+        }
         return {
             opcodeIndex: index,
             kind: opcode.kind,
@@ -480,7 +576,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, globalDeadlineMs, effectiveTimeoutMs, errorMsg);
+        return failWithRecovery(errorMsg);
     }
 }
 /** Post-action breathing room (ms) injected between visible interactions
@@ -685,13 +781,7 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                 // 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);
+                const stability = await stabilizeForCapture(adapter, 5000);
                 if (!stability.stable) {
                     logger.debug(`[opcode ${opcodeIndex}] capturing despite unstable page: ${stability.reason}`);
                 }
@@ -709,85 +799,7 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                 }
                 const captureLowConfidenceReason = lowConfidenceReasons.join('; ') || undefined;
                 const captureUrl = await adapter.getCurrentUrl();
-                const takeBuffer = async () => {
-                    if (opcode.elementSelector && adapter.takeElementScreenshot) {
-                        return adapter.takeElementScreenshot(opcode.elementSelector, opcode.outscale);
-                    }
-                    if (opcode.elementSelector) {
-                        throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);
-                    }
-                    return adapter.takeScreenshot();
-                };
-                let buffer = await takeBuffer();
-                if (runOptions?.llmConfig) {
-                    const verification = await verifyCaptureQuality(buffer, {
-                        expectedDescription: opcode.description,
-                        url: captureUrl,
-                        locale: currentVariant?.locale,
-                        theme: currentVariant?.theme,
-                    }, runOptions.llmConfig);
-                    if (verification.llmResult) {
-                        telemetry.llmCallCount++;
-                        telemetry.llmCostEur += verification.llmResult.costEur;
-                        telemetry.llmStepUsages.push({
-                            stepType: 'capture_verification',
-                            generationId: verification.llmResult.generationId,
-                            model: verification.llmResult.model,
-                            promptTokens: verification.llmResult.promptTokens,
-                            completionTokens: verification.llmResult.completionTokens,
-                        });
-                    }
-                    if (!verification.passed) {
-                        await stabilize(8000);
-                        const retryBuffer = await takeBuffer();
-                        const retryVerification = await verifyCaptureQuality(retryBuffer, {
-                            expectedDescription: opcode.description,
-                            url: captureUrl,
-                            locale: currentVariant?.locale,
-                            theme: currentVariant?.theme,
-                        }, runOptions.llmConfig);
-                        if (retryVerification.llmResult) {
-                            telemetry.llmCallCount++;
-                            telemetry.llmCostEur += retryVerification.llmResult.costEur;
-                            telemetry.llmStepUsages.push({
-                                stepType: 'capture_verification',
-                                generationId: retryVerification.llmResult.generationId,
-                                model: retryVerification.llmResult.model,
-                                promptTokens: retryVerification.llmResult.promptTokens,
-                                completionTokens: retryVerification.llmResult.completionTokens,
-                            });
-                        }
-                        if (retryVerification.passed) {
-                            buffer = retryBuffer;
-                        }
-                    }
-                }
-                let altText;
-                if (runOptions?.llmConfig) {
-                    try {
-                        const altResult = await generateAltText(buffer, {
-                            description: opcode.description,
-                            url: captureUrl,
-                            locale: currentVariant?.locale,
-                            presetName: runOptions.presetName,
-                        }, runOptions.llmConfig);
-                        altText = altResult.altText;
-                        if (altResult.llmResult) {
-                            telemetry.llmCallCount++;
-                            telemetry.llmCostEur += altResult.llmResult.costEur;
-                            telemetry.llmStepUsages.push({
-                                stepType: 'alt_text_generation',
-                                generationId: altResult.llmResult.generationId,
-                                model: altResult.llmResult.model,
-                                promptTokens: altResult.llmResult.promptTokens,
-                                completionTokens: altResult.llmResult.completionTokens,
-                            });
-                        }
-                    }
-                    catch {
-                        // Alt text generation failed — non-fatal
-                    }
-                }
+                const buffer = await takeCaptureBuffer(adapter, opcode);
                 // Extract page favicon for browser bar mockup
                 let tabIconData;
                 let tabIconMimeType;
@@ -817,7 +829,7 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     captureId: opcode.captureId,
                     captureName: opcode.captureName ?? opcode.description,
                     elementSelector: opcode.elementSelector,
-                    altText,
+                    altText: undefined,
                     stepDescription: opcode.description,
                     stepIndex: opcodeIndex,
                     variantId: currentVariant?.id,
@@ -826,7 +838,11 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     lowConfidence: captureLowConfidence || undefined,
                     lowConfidenceReason: captureLowConfidence ? captureLowConfidenceReason : undefined,
                 });
-                break;
+                // Deliver the screenshot artifact NOW. LLM enrichment (quality
+                // verification + alt text) runs afterwards in `executeOpcode`, off this
+                // timed action path, and mutates the artifact in place — it can never
+                // void a captured screenshot or push the action past its timeout.
+                return { success: true, captureArtifactIndex: artifacts.length - 1, captureUrl };
             }
             case 'BEGIN_CLIP': {
                 if (executionState.activeClip) {
@@ -892,6 +908,127 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
         };
     }
 }
+// ── Capture: deterministic capture + best-effort enrichment ─────────
+/**
+ * Re-stabilize budget for the verification retry. Sized for the post-action
+ * enrichment budget (under the ~30s global deadline), not the tight per-opcode
+ * action timeout — it only needs to clear transient skeletons/spinners before a
+ * second look. Was 8000ms when this ran inside the 10s action; that starved the
+ * capture and is exactly what this separation removes.
+ */
+const VERIFY_RETRY_STABILIZE_MS = 3000;
+/** Visual stabilization shared by the capture action and the verify retry.
+ * Never fails the capture — a page that never settles is captured anyway. */
+function stabilizeForCapture(adapter, maxWaitMs) {
+    return adapter.waitForVisuallyStable
+        ? adapter.waitForVisuallyStable({ maxWaitMs })
+        : smartWaitForStability(adapter, { maxWaitMs }).then((r) => ({
+            stable: r.stable,
+            reason: r.waitedFor.join(', ') || 'unknown',
+        }));
+}
+/** Take the screenshot buffer for a CAPTURE_SCREENSHOT opcode (element clip or
+ * full page). Shared by the capture action and the verify retry. */
+function takeCaptureBuffer(adapter, opcode) {
+    if (opcode.elementSelector && adapter.takeElementScreenshot) {
+        return adapter.takeElementScreenshot(opcode.elementSelector, opcode.outscale);
+    }
+    if (opcode.elementSelector) {
+        throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);
+    }
+    return adapter.takeScreenshot();
+}
+function recordCaptureVerificationTelemetry(telemetry, llmResult) {
+    if (!llmResult)
+        return;
+    telemetry.llmCallCount++;
+    telemetry.llmCostEur += llmResult.costEur;
+    telemetry.llmStepUsages.push({
+        stepType: 'capture_verification',
+        generationId: llmResult.generationId,
+        model: llmResult.model,
+        promptTokens: llmResult.promptTokens,
+        completionTokens: llmResult.completionTokens,
+    });
+}
+/**
+ * Best-effort LLM enrichment of an already-delivered screenshot artifact:
+ * quality verification (with one budget-bounded re-stabilize + re-shoot) and
+ * alt text. Runs AFTER the deterministic capture action, off its timed path,
+ * and mutates the artifact in place. By construction it never changes
+ * `artifacts.length`, so it can never turn a captured screenshot into a
+ * "no artifact" failure — the regression this fixes.
+ *
+ * Bounded by the per-opcode global wait deadline. If the budget elapses
+ * mid-call the in-flight LLM promise is orphaned; `settled` makes any late
+ * in-place write a no-op so it cannot mutate an artifact the runner moved past.
+ */
+async function enrichCaptureArtifact(artifact, opcode, adapter, captureUrl, currentVariant, runOptions, telemetry, globalDeadlineMs) {
+    const llmConfig = runOptions.llmConfig;
+    if (!llmConfig)
+        return;
+    const budgetMs = getRemainingTimeMs(globalDeadlineMs);
+    if (budgetMs <= 0)
+        return;
+    let settled = false;
+    const verificationContext = {
+        expectedDescription: opcode.description,
+        url: captureUrl,
+        locale: currentVariant?.locale,
+        theme: currentVariant?.theme,
+    };
+    try {
+        await withTimeout(async () => {
+            const verification = await verifyCaptureQuality(artifact.buffer, verificationContext, llmConfig);
+            recordCaptureVerificationTelemetry(telemetry, verification.llmResult);
+            // On a failed verdict, give the page a brief settle and re-shoot once,
+            // bounded by the remaining global budget. Swap the buffer in place only if
+            // the second shot verifies clean.
+            if (!verification.passed) {
+                const retryStabilizeMs = Math.min(VERIFY_RETRY_STABILIZE_MS, getRemainingTimeMs(globalDeadlineMs));
+                if (retryStabilizeMs > 0) {
+                    await stabilizeForCapture(adapter, retryStabilizeMs);
+                    const retryBuffer = await takeCaptureBuffer(adapter, opcode);
+                    const retryVerification = await verifyCaptureQuality(retryBuffer, verificationContext, llmConfig);
+                    recordCaptureVerificationTelemetry(telemetry, retryVerification.llmResult);
+                    if (retryVerification.passed && !settled) {
+                        artifact.buffer = retryBuffer;
+                    }
+                }
+            }
+            try {
+                const altResult = await generateAltText(artifact.buffer, {
+                    description: opcode.description,
+                    url: captureUrl,
+                    locale: currentVariant?.locale,
+                    presetName: runOptions.presetName,
+                }, llmConfig);
+                if (!settled)
+                    artifact.altText = altResult.altText;
+                if (altResult.llmResult) {
+                    telemetry.llmCallCount++;
+                    telemetry.llmCostEur += altResult.llmResult.costEur;
+                    telemetry.llmStepUsages.push({
+                        stepType: 'alt_text_generation',
+                        generationId: altResult.llmResult.generationId,
+                        model: altResult.llmResult.model,
+                        promptTokens: altResult.llmResult.promptTokens,
+                        completionTokens: altResult.llmResult.completionTokens,
+                    });
+                }
+            }
+            catch {
+                // Alt text generation failed — non-fatal.
+            }
+        }, budgetMs);
+    }
+    catch (err) {
+        logger.debug(`[opcode CAPTURE_SCREENSHOT] enrichment skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        settled = true;
+    }
+}
 /**
  * Snapshot per-opcode timing + element bbox before the action runs. Returns
  * null when no timing should be emitted (mediaMode != video, or no active

package/dist/postcondition.js

@@ -100,8 +100,8 @@ function compileRoutePattern(pattern) {
     // Support glob-like patterns: ** matches anything (incl. slashes / empty),
     // * matches a single path segment, ? matches one non-slash char.
     // Tokenize in one pass so the `*` rewrite doesn't clobber the `*` produced
-    // by the `**` rewrite (e.g. `/home**` must compile to `^/home.*$`, not
-    // `^/home.[^/]*$` which would reject `/home` itself).
+    // by the `**` rewrite (e.g. `/home**` must compile to `/home.*`, not
+    // `/home.[^/]*` which would reject `/home` itself).
     let regexStr = '';
     for (let i = 0; i < pattern.length; i++) {
         const ch = pattern[i];
@@ -122,7 +122,14 @@ function compileRoutePattern(pattern) {
             regexStr += ch;
         }
     }
-    return new RegExp(`^${regexStr}$`);
+    // Substring (contains) match — NOT anchored. Generated programs author bare
+    // patterns that are either a prefix of the real path (`/projects/` ⊂
+    // `/projects/<id>`) or a nested segment (`/tracking` ⊂
+    // `/projects/<id>/tracking`). An anchored `^…$` could match neither, which
+    // surfaced as a misleading "page stuck, no progress" failure after the
+    // navigation had actually succeeded. Callers needing strict matching pass an
+    // anchored regex (handled above).
+    return new RegExp(regexStr);
 }
 async function checkElementVisible(adapter, selector) {
     // Primary check: use Playwright waitFor (fast, reliable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",