donobu 5.46.0 → 5.47.0

package/dist/cli/donobu-cli.js

@@ -960,6 +960,12 @@ function applyJsonReportEnv(env, outputDir) {
  */
 function evaluateAutoHealEligibility(plans) {
     const eligiblePlans = plans.filter((record) => {
+        // Respect the per-project `autoHeal: false` setting here (rather than
+        // suppressing the diagnosis): such tests still get a treatment plan for the
+        // report, but are never re-run.
+        if (record.evidence?.failureContext?.testCase?.autoHealEnabled === false) {
+            return false;
+        }
         const directives = record.plan.automationDirectives;
         return (record.plan.shouldRetryAutomation === true &&
             directives !== undefined &&
@@ -1194,11 +1200,12 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
         const testLabel = evidence.failureContext.testCase.title ??
             evidence.failureContext.testCase.file ??
             'unknown test';
-        if (evidence.failureContext.testCase.autoHealEnabled === false) {
-            Logger_1.appLogger.info(`Skipping treatment plan for "${testLabel}" — auto-heal is disabled for this test's project.`);
-            continue;
-        }
-        Logger_1.appLogger.info(`Detected test failure for "${testLabel}". Generating treatment plan to facilitate healing...`);
+        // Generate a treatment plan (diagnosis) for every failure, independent of
+        // whether auto-heal is enabled for the test's project. Triage is a
+        // standalone diagnostic surfaced in the reports; the per-project
+        // `autoHeal: false` setting suppresses only the auto-heal *rerun*, which is
+        // enforced separately in `evaluateAutoHealEligibility`.
+        Logger_1.appLogger.info(`Detected test failure for "${testLabel}". Generating treatment plan...`);
         const heuristicFallback = () => {
             const h = evidence.failureContext.heuristics;
             return {
@@ -1499,7 +1506,12 @@ async function relocateTemporaryAttachments(report, outputDir) {
  * outcome. Reads the output path from the sidecar written by the reporter
  * during the initial run; does nothing if the reporter wasn't configured.
  */
-async function regenerateDonobuReports(mergedReport) {
+async function regenerateDonobuReports(mergedReport, options = {}) {
+    // Slack regeneration also (re-)posts to the webhook. Callers where the Slack
+    // reporter already posted during the initial run (e.g. triage without
+    // auto-heal) pass `includeSlack: false` to avoid a duplicate post — the Slack
+    // summary carries no triage detail, so there is nothing to refresh anyway.
+    const { includeSlack = true } = options;
     const outputs = mergedReport.metadata?.donobuOutputs;
     if (!outputs) {
         return;
@@ -1510,7 +1522,7 @@ async function regenerateDonobuReports(mergedReport) {
     if (outputs.markdown?.outputFile) {
         await regenerateMarkdownOutput(mergedReport, outputs.markdown.outputFile);
     }
-    if (outputs.slack?.outputFile) {
+    if (includeSlack && outputs.slack?.outputFile) {
         await regenerateSlackOutput(mergedReport, outputs.slack.outputFile);
     }
 }
@@ -1744,6 +1756,15 @@ async function runTestCommand(cliArgs) {
         Logger_1.appLogger.info('Running with Page.AI cache clearing enabled for this run.');
     }
     let triageEnabled = options.triageEnabled;
+    // Auto-heal is built on triage: it acts on the treatment plans triage
+    // produces, so it cannot function without it. If the user explicitly disabled
+    // triage (--no-triage) while enabling auto-heal, honor auto-heal and
+    // re-enable triage with a warning rather than running an inert auto-heal.
+    if (options.autoHeal && !triageEnabled) {
+        Logger_1.appLogger.warn('--no-triage was ignored because --auto-heal requires triage to produce ' +
+            'the treatment plans it acts on; continuing with triage enabled.');
+        triageEnabled = true;
+    }
     let triageContext = null;
     if (triageEnabled) {
         try {
@@ -1793,19 +1814,18 @@ async function runTestCommand(cliArgs) {
     const { userHadJson, jsonOutputFile } = jsonReporterInfo;
     let generatedPlans = [];
     try {
-        if (exitCode === 0 || !effectiveOptions.autoHeal) {
-            // Auto-heal wasn't attempted (either tests passed or the user disabled
-            // it). If a Slack reporter deferred its POST waiting for us, deliver the
-            // initial run's payload now — nothing further will be re-rendered.
+        // Tests passed → nothing to triage or heal. If a Slack reporter deferred
+        // its POST for us (auto-heal mode), deliver the initial run's payload now.
+        if (exitCode === 0) {
             if (effectiveOptions.autoHeal) {
                 await postDeferredSlackFromInitialRun(playwrightOutputDir);
             }
             return exitCode;
         }
-        // Tests failed and auto-heal is enabled — load the initial report into
-        // memory so we can merge it with the heal-run report later. Prefer the
-        // Donobu reporter's state file (carries Donobu-specific metadata like the
-        // HTML output path); fall back to reading the user's JSON file directly.
+        // Tests failed. Load the initial report so we can merge it with an auto-heal
+        // rerun and/or regenerate reports enriched with triage. Prefer the Donobu
+        // reporter's state file (carries Donobu-specific metadata like output
+        // paths); fall back to the user's JSON file.
         let initialDonobuReport = null;
         if (triageEnabled) {
             const stateReport = await readJsonIfExists(path.join(playwrightOutputDir, model_1.DONOBU_REPORT_STATE_FILENAME));
@@ -1815,28 +1835,64 @@ async function runTestCommand(cliArgs) {
                         ? await readJsonIfExists(jsonOutputFile)
                         : null);
         }
+        // Triage (evidence → treatment plans) runs on failures whenever enabled,
+        // independent of auto-heal. Auto-heal consumes these plans; standalone
+        // triage surfaces the diagnosis in the reports for humans.
         if (triageEnabled && triageContext) {
             generatedPlans = await postProcessTriageRun(triageContext, playwrightArgs, jsonOutputFile ?? undefined);
         }
-        const autoHealOutcome = await attemptAutoHealRun({
-            options: effectiveOptions,
-            playwrightArgs,
-            playwrightOutputDir,
-            generatedPlans,
-            currentExitCode: exitCode,
-            initialReport: initialDonobuReport,
-            initialReportSourcePath: jsonOutputFile ?? undefined,
-            triageRunDir: triageContext?.runDir,
-            userJsonOutputFile: userHadJson ? jsonOutputFile : null,
-        });
-        // When auto-heal was eligible-checked but didn't actually run a rerun (no
-        // actionable directives), nothing downstream re-renders the Slack payload —
-        // deliver the pre-heal payload now so we honor the "one post per run"
-        // guarantee the reporter was deferring for.
-        if (!autoHealOutcome.attempted) {
-            await postDeferredSlackFromInitialRun(playwrightOutputDir);
-        }
-        return autoHealOutcome.exitCode;
+        if (effectiveOptions.autoHeal) {
+            const autoHealOutcome = await attemptAutoHealRun({
+                options: effectiveOptions,
+                playwrightArgs,
+                playwrightOutputDir,
+                generatedPlans,
+                currentExitCode: exitCode,
+                initialReport: initialDonobuReport,
+                initialReportSourcePath: jsonOutputFile ?? undefined,
+                triageRunDir: triageContext?.runDir,
+                userJsonOutputFile: userHadJson ? jsonOutputFile : null,
+            });
+            // When auto-heal was eligible-checked but didn't actually run a rerun (no
+            // actionable directives — e.g. triage classified the failures as
+            // application/product defects), nothing downstream re-renders the reports.
+            if (!autoHealOutcome.attempted) {
+                // The initial reports were rendered before triage finished, so they
+                // carry no triage analysis. Regenerate them from the initial report
+                // enriched with the triage run dir so the diagnosis surfaces. The
+                // regeneration also performs the single authoritative Slack post the
+                // reporter deferred for.
+                const triageRunDir = triageContext?.runDir;
+                const enrichedInitialReport = triageRunDir && initialDonobuReport?.metadata?.donobuOutputs
+                    ? {
+                        ...initialDonobuReport,
+                        metadata: { ...initialDonobuReport.metadata, triageRunDir },
+                    }
+                    : null;
+                if (enrichedInitialReport) {
+                    await regenerateDonobuReports(enrichedInitialReport);
+                }
+                else {
+                    // No triage data to inject (no Donobu reporter configured). Deliver
+                    // the pre-heal Slack payload so we honor the "one post per run"
+                    // guarantee the reporter was deferring for.
+                    await postDeferredSlackFromInitialRun(playwrightOutputDir);
+                }
+            }
+            return autoHealOutcome.exitCode;
+        }
+        // Auto-heal disabled: no rerun, and the Slack reporter already posted during
+        // the initial run (its POST was not deferred). Regenerate the HTML/Markdown
+        // reports so the triage analysis is visible, but leave Slack untouched to
+        // avoid a duplicate post (the Slack summary carries no triage detail).
+        const triageRunDir = triageContext?.runDir;
+        if (triageRunDir && initialDonobuReport?.metadata?.donobuOutputs) {
+            await regenerateDonobuReports({
+                ...initialDonobuReport,
+                metadata: { ...initialDonobuReport.metadata, triageRunDir },
+            }, { includeSlack: false });
+        }
+        return exitCode;
     }
     finally {
         // Clean up the JSON artifacts Donobu created for its own internal use.

package/dist/esm/cli/donobu-cli.js

@@ -960,6 +960,12 @@ function applyJsonReportEnv(env, outputDir) {
  */
 function evaluateAutoHealEligibility(plans) {
     const eligiblePlans = plans.filter((record) => {
+        // Respect the per-project `autoHeal: false` setting here (rather than
+        // suppressing the diagnosis): such tests still get a treatment plan for the
+        // report, but are never re-run.
+        if (record.evidence?.failureContext?.testCase?.autoHealEnabled === false) {
+            return false;
+        }
         const directives = record.plan.automationDirectives;
         return (record.plan.shouldRetryAutomation === true &&
             directives !== undefined &&
@@ -1194,11 +1200,12 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
         const testLabel = evidence.failureContext.testCase.title ??
             evidence.failureContext.testCase.file ??
             'unknown test';
-        if (evidence.failureContext.testCase.autoHealEnabled === false) {
-            Logger_1.appLogger.info(`Skipping treatment plan for "${testLabel}" — auto-heal is disabled for this test's project.`);
-            continue;
-        }
-        Logger_1.appLogger.info(`Detected test failure for "${testLabel}". Generating treatment plan to facilitate healing...`);
+        // Generate a treatment plan (diagnosis) for every failure, independent of
+        // whether auto-heal is enabled for the test's project. Triage is a
+        // standalone diagnostic surfaced in the reports; the per-project
+        // `autoHeal: false` setting suppresses only the auto-heal *rerun*, which is
+        // enforced separately in `evaluateAutoHealEligibility`.
+        Logger_1.appLogger.info(`Detected test failure for "${testLabel}". Generating treatment plan...`);
         const heuristicFallback = () => {
             const h = evidence.failureContext.heuristics;
             return {
@@ -1499,7 +1506,12 @@ async function relocateTemporaryAttachments(report, outputDir) {
  * outcome. Reads the output path from the sidecar written by the reporter
  * during the initial run; does nothing if the reporter wasn't configured.
  */
-async function regenerateDonobuReports(mergedReport) {
+async function regenerateDonobuReports(mergedReport, options = {}) {
+    // Slack regeneration also (re-)posts to the webhook. Callers where the Slack
+    // reporter already posted during the initial run (e.g. triage without
+    // auto-heal) pass `includeSlack: false` to avoid a duplicate post — the Slack
+    // summary carries no triage detail, so there is nothing to refresh anyway.
+    const { includeSlack = true } = options;
     const outputs = mergedReport.metadata?.donobuOutputs;
     if (!outputs) {
         return;
@@ -1510,7 +1522,7 @@ async function regenerateDonobuReports(mergedReport) {
     if (outputs.markdown?.outputFile) {
         await regenerateMarkdownOutput(mergedReport, outputs.markdown.outputFile);
     }
-    if (outputs.slack?.outputFile) {
+    if (includeSlack && outputs.slack?.outputFile) {
         await regenerateSlackOutput(mergedReport, outputs.slack.outputFile);
     }
 }
@@ -1744,6 +1756,15 @@ async function runTestCommand(cliArgs) {
         Logger_1.appLogger.info('Running with Page.AI cache clearing enabled for this run.');
     }
     let triageEnabled = options.triageEnabled;
+    // Auto-heal is built on triage: it acts on the treatment plans triage
+    // produces, so it cannot function without it. If the user explicitly disabled
+    // triage (--no-triage) while enabling auto-heal, honor auto-heal and
+    // re-enable triage with a warning rather than running an inert auto-heal.
+    if (options.autoHeal && !triageEnabled) {
+        Logger_1.appLogger.warn('--no-triage was ignored because --auto-heal requires triage to produce ' +
+            'the treatment plans it acts on; continuing with triage enabled.');
+        triageEnabled = true;
+    }
     let triageContext = null;
     if (triageEnabled) {
         try {
@@ -1793,19 +1814,18 @@ async function runTestCommand(cliArgs) {
     const { userHadJson, jsonOutputFile } = jsonReporterInfo;
     let generatedPlans = [];
     try {
-        if (exitCode === 0 || !effectiveOptions.autoHeal) {
-            // Auto-heal wasn't attempted (either tests passed or the user disabled
-            // it). If a Slack reporter deferred its POST waiting for us, deliver the
-            // initial run's payload now — nothing further will be re-rendered.
+        // Tests passed → nothing to triage or heal. If a Slack reporter deferred
+        // its POST for us (auto-heal mode), deliver the initial run's payload now.
+        if (exitCode === 0) {
             if (effectiveOptions.autoHeal) {
                 await postDeferredSlackFromInitialRun(playwrightOutputDir);
             }
             return exitCode;
         }
-        // Tests failed and auto-heal is enabled — load the initial report into
-        // memory so we can merge it with the heal-run report later. Prefer the
-        // Donobu reporter's state file (carries Donobu-specific metadata like the
-        // HTML output path); fall back to reading the user's JSON file directly.
+        // Tests failed. Load the initial report so we can merge it with an auto-heal
+        // rerun and/or regenerate reports enriched with triage. Prefer the Donobu
+        // reporter's state file (carries Donobu-specific metadata like output
+        // paths); fall back to the user's JSON file.
         let initialDonobuReport = null;
         if (triageEnabled) {
             const stateReport = await readJsonIfExists(path.join(playwrightOutputDir, model_1.DONOBU_REPORT_STATE_FILENAME));
@@ -1815,28 +1835,64 @@ async function runTestCommand(cliArgs) {
                         ? await readJsonIfExists(jsonOutputFile)
                         : null);
         }
+        // Triage (evidence → treatment plans) runs on failures whenever enabled,
+        // independent of auto-heal. Auto-heal consumes these plans; standalone
+        // triage surfaces the diagnosis in the reports for humans.
         if (triageEnabled && triageContext) {
             generatedPlans = await postProcessTriageRun(triageContext, playwrightArgs, jsonOutputFile ?? undefined);
         }
-        const autoHealOutcome = await attemptAutoHealRun({
-            options: effectiveOptions,
-            playwrightArgs,
-            playwrightOutputDir,
-            generatedPlans,
-            currentExitCode: exitCode,
-            initialReport: initialDonobuReport,
-            initialReportSourcePath: jsonOutputFile ?? undefined,
-            triageRunDir: triageContext?.runDir,
-            userJsonOutputFile: userHadJson ? jsonOutputFile : null,
-        });
-        // When auto-heal was eligible-checked but didn't actually run a rerun (no
-        // actionable directives), nothing downstream re-renders the Slack payload —
-        // deliver the pre-heal payload now so we honor the "one post per run"
-        // guarantee the reporter was deferring for.
-        if (!autoHealOutcome.attempted) {
-            await postDeferredSlackFromInitialRun(playwrightOutputDir);
-        }
-        return autoHealOutcome.exitCode;
+        if (effectiveOptions.autoHeal) {
+            const autoHealOutcome = await attemptAutoHealRun({
+                options: effectiveOptions,
+                playwrightArgs,
+                playwrightOutputDir,
+                generatedPlans,
+                currentExitCode: exitCode,
+                initialReport: initialDonobuReport,
+                initialReportSourcePath: jsonOutputFile ?? undefined,
+                triageRunDir: triageContext?.runDir,
+                userJsonOutputFile: userHadJson ? jsonOutputFile : null,
+            });
+            // When auto-heal was eligible-checked but didn't actually run a rerun (no
+            // actionable directives — e.g. triage classified the failures as
+            // application/product defects), nothing downstream re-renders the reports.
+            if (!autoHealOutcome.attempted) {
+                // The initial reports were rendered before triage finished, so they
+                // carry no triage analysis. Regenerate them from the initial report
+                // enriched with the triage run dir so the diagnosis surfaces. The
+                // regeneration also performs the single authoritative Slack post the
+                // reporter deferred for.
+                const triageRunDir = triageContext?.runDir;
+                const enrichedInitialReport = triageRunDir && initialDonobuReport?.metadata?.donobuOutputs
+                    ? {
+                        ...initialDonobuReport,
+                        metadata: { ...initialDonobuReport.metadata, triageRunDir },
+                    }
+                    : null;
+                if (enrichedInitialReport) {
+                    await regenerateDonobuReports(enrichedInitialReport);
+                }
+                else {
+                    // No triage data to inject (no Donobu reporter configured). Deliver
+                    // the pre-heal Slack payload so we honor the "one post per run"
+                    // guarantee the reporter was deferring for.
+                    await postDeferredSlackFromInitialRun(playwrightOutputDir);
+                }
+            }
+            return autoHealOutcome.exitCode;
+        }
+        // Auto-heal disabled: no rerun, and the Slack reporter already posted during
+        // the initial run (its POST was not deferred). Regenerate the HTML/Markdown
+        // reports so the triage analysis is visible, but leave Slack untouched to
+        // avoid a duplicate post (the Slack summary carries no triage detail).
+        const triageRunDir = triageContext?.runDir;
+        if (triageRunDir && initialDonobuReport?.metadata?.donobuOutputs) {
+            await regenerateDonobuReports({
+                ...initialDonobuReport,
+                metadata: { ...initialDonobuReport.metadata, triageRunDir },
+            }, { includeSlack: false });
+        }
+        return exitCode;
     }
     finally {
         // Clean up the JSON artifacts Donobu created for its own internal use.

package/dist/esm/lib/test/testExtension.js

@@ -843,6 +843,40 @@ async function attachStepScreenshots(sharedState, testInfo) {
         contentType: 'application/json',
     });
 }
+/**
+ * Capture a live screenshot of the flow's final visual state at teardown (page
+ * still open) and persist it as a per-flow file — the single source of truth
+ * for "what the page looked like when this run ended." It is read both as the
+ * current run's failure screenshot (when this run failed) and as the baseline
+ * for a later failing run (when this run succeeded), keeping the two symmetric.
+ * See `fetchBaselineScreenshot` / `gatherTestFailureEvidence` in
+ * triageTestFailure.ts.
+ *
+ * Runs for any meaningful end state; skipped only for `skipped` tests (no real
+ * page state), when triage is disabled, or for V1 (legacy self-heal) tests.
+ * Best-effort and fails open.
+ */
+async function captureAndPersistFinalState(page, testInfo) {
+    if (testInfo.status === 'skipped' ||
+        process.env.DONOBU_TRIAGE_DISABLED === '1' ||
+        isV1Test(testInfo)) {
+        return;
+    }
+    const flowId = page._dnb?.donobuFlowMetadata?.id;
+    const persistence = page._dnb?.persistence;
+    if (!flowId || !persistence) {
+        return;
+    }
+    try {
+        const screenshot = await (0, triageTestFailure_1.captureLivePageScreenshot)(page);
+        if (screenshot) {
+            await persistence.setFlowFile(flowId, triageTestFailure_1.TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot, screenshot);
+        }
+    }
+    catch (error) {
+        Logger_1.appLogger.error(`Failed to persist final-state screenshot for flow ${flowId}.`, error);
+    }
+}
 async function finalizeTest(page, testInfo, logBuffer, videoOption) {
     const sharedState = page._dnb;
     // Kick off video persistence early in teardown. The actual file copy is
@@ -919,6 +953,10 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
     catch (error) {
         Logger_1.appLogger.error(`Error during cleanup for test ${testInfo.title}:`, error);
     }
+    // Capture the flow's final visual state before the status-specific handling
+    // below: triage (failed branch) reads it as the failure screenshot, and a
+    // future failing run reads a successful run's copy as its baseline.
+    await captureAndPersistFinalState(page, testInfo);
     if (testInfo.status === 'failed') {
         if (isV1Test(testInfo)) {
             if (isV1SelfHealingEnabled(testInfo) &&

package/dist/esm/lib/test/utils/triageTestFailure.d.ts

@@ -28,9 +28,10 @@ import type { DonobuExtendedPage } from '../../page/DonobuExtendedPage';
  *      history from the persistence layer.
  *   3. Fetches **historical runs** of the same flow (by name) from the flows manager to
  *      detect flakiness, regression patterns, and prior self-heal success.
- *   4. Captures the **failure screenshot** (last tool call screenshot from the current
- *      run) and the **baseline screenshot** (last tool call screenshot from the most
- *      recent successful historical run) for visual comparison.
+ *   4. Captures the **failure screenshot** (a live screenshot taken at triage time, while
+ *      the page is still open during teardown, so it reflects the true final state) and the
+ *      **baseline screenshot** (last tool call screenshot from the most recent successful
+ *      historical run) for visual comparison.
  *   5. Reads the source of the failing test case for contextual grounding.
  *   6. Runs the **heuristic classifier** (`deriveHeuristicAssessment`) which uses
  *      rule-based pattern matching over errors, tool calls, stale-cache indicators,
@@ -70,7 +71,7 @@ import type { DonobuExtendedPage } from '../../page/DonobuExtendedPage';
  * | Flow metadata           | `DonobuExtendedPage._dnb`     | Run mode, objective, allowed tools, timing         |
  * | Stale cache indicators  | Derived from above            | Whether page.ai cache staleness is the root cause  |
  * | Historical flow runs    | `DonobuFlowsManager.getFlows` | Flakiness, regression patterns, prior self-heal    |
- * | Failure screenshot      | Last tool call screenshot     | Visual state of the page when the failure occurred |
+ * | Failure screenshot      | Live capture at triage time   | True final visual state of the page when it failed |
  * | Baseline screenshot     | Last successful run's screenshot | Visual reference for what the page *should* look like |
  * | Test source snippet     | TypeScript AST parsing        | The test's expectations and structure               |
  *
@@ -408,6 +409,14 @@ declare const TRIAGE_PERSISTENCE_FILE_IDS: {
     readonly evidence: "triage-evidence.json";
     readonly failureScreenshot: "triage-failure-screenshot.png";
     readonly baselineScreenshot: "triage-baseline-screenshot.png";
+    /**
+     * Live screenshot of a flow's final visual state, captured at teardown while
+     * the page is still open. Persisted on successful runs so that a *later*
+     * failing run can use it as a true final-state baseline — symmetric with the
+     * failure screenshot, which is also a live end-of-test capture. Keyed per
+     * flow, like browser state.
+     */
+    readonly finalStateScreenshot: "triage-final-state-screenshot.png";
 };
 /**
  * Compresses a set of historical flow runs into an aggregate summary compact
@@ -420,6 +429,19 @@ declare function summarizeFlowHistory(flowName: string, flows: FlowMetadata[]):
  * success, and whether the page.ai cache was recently validated.
  */
 declare function deriveHistoricalSignals(history: FlowHistorySummary): HistoricalSignals;
+/**
+ * Captures a fresh screenshot of the page's current visual state. Called at
+ * teardown (failure triage and successful-run baseline capture) while the
+ * page/context is still open, so it reflects the true *end state* of the test.
+ *
+ * This is deliberately preferred over the last Donobu tool-call screenshot:
+ * Playwright `expect`/`waitFor` are not tool calls, so the last tool-call image
+ * can predate the failing assertion and capture a transient state (e.g. a
+ * loading spinner that has since resolved), which misleads the vision model.
+ * Fails open — returns null if the page is gone or unresponsive (crash, closed
+ * context, hang), in which case the caller proceeds without a screenshot.
+ */
+declare function captureLivePageScreenshot(page: DonobuExtendedPage): Promise<Buffer | null>;
 /**
  * Builds the heuristic triage assessment by combining rule-based inference,
  * contextual flags, and derived remediation guidance ahead of GPT enrichment.
@@ -432,5 +454,5 @@ declare function deriveHeuristicAssessment(testInfo: TestInfo, errorSummaries: E
 declare function reconcileTreatmentPlan(plan: z.infer<typeof TreatmentPlan>, heuristics: HeuristicAssessment): z.infer<typeof TreatmentPlan>;
 declare function gatherTestFailureEvidence(testInfo: TestInfo, page: DonobuExtendedPage, options?: GatherTestFailureEvidenceOptions): Promise<GatherTestFailureEvidenceResult | null>;
 declare function generateTreatmentPlanFromEvidence(gptClient: GptClient, evidence: FailureEvidenceRecord): Promise<z.infer<typeof TreatmentPlan>>;
-export { type AdditionalDataRequest, AdditionalDataRequestSchema, type AutomationDirectives, deriveHeuristicAssessment, deriveHistoricalSignals, type ErrorSummary, type FailureEvidenceRecord, type FailureReason, FailureReasonSchema, type FlowHistorySummary, gatherTestFailureEvidence, type GatherTestFailureEvidenceOptions, type GatherTestFailureEvidenceResult, generateTreatmentPlanFromEvidence, type HeuristicAssessment, type HistoricalFlowRun, type HistoricalSignals, reconcileTreatmentPlan, type RemediationCategory, type RemediationStep, RemediationStepSchema, type SanitizedFlowMetadata, type SummarizedToolCall, summarizeFlowHistory, TreatmentPlan, TRIAGE_PERSISTENCE_FILE_IDS, };
+export { type AdditionalDataRequest, AdditionalDataRequestSchema, type AutomationDirectives, captureLivePageScreenshot, deriveHeuristicAssessment, deriveHistoricalSignals, type ErrorSummary, type FailureEvidenceRecord, type FailureReason, FailureReasonSchema, type FlowHistorySummary, gatherTestFailureEvidence, type GatherTestFailureEvidenceOptions, type GatherTestFailureEvidenceResult, generateTreatmentPlanFromEvidence, type HeuristicAssessment, type HistoricalFlowRun, type HistoricalSignals, reconcileTreatmentPlan, type RemediationCategory, type RemediationStep, RemediationStepSchema, type SanitizedFlowMetadata, type SummarizedToolCall, summarizeFlowHistory, TreatmentPlan, TRIAGE_PERSISTENCE_FILE_IDS, };
 //# sourceMappingURL=triageTestFailure.d.ts.map

package/dist/esm/lib/test/utils/triageTestFailure.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TRIAGE_PERSISTENCE_FILE_IDS = exports.TreatmentPlan = exports.RemediationStepSchema = exports.FailureReasonSchema = exports.AdditionalDataRequestSchema = void 0;
+exports.captureLivePageScreenshot = captureLivePageScreenshot;
 exports.deriveHeuristicAssessment = deriveHeuristicAssessment;
 exports.deriveHistoricalSignals = deriveHistoricalSignals;
 exports.gatherTestFailureEvidence = gatherTestFailureEvidence;
@@ -79,9 +80,10 @@ const cacheLocator_1 = require("../../ai/cache/cacheLocator");
  *      history from the persistence layer.
  *   3. Fetches **historical runs** of the same flow (by name) from the flows manager to
  *      detect flakiness, regression patterns, and prior self-heal success.
- *   4. Captures the **failure screenshot** (last tool call screenshot from the current
- *      run) and the **baseline screenshot** (last tool call screenshot from the most
- *      recent successful historical run) for visual comparison.
+ *   4. Captures the **failure screenshot** (a live screenshot taken at triage time, while
+ *      the page is still open during teardown, so it reflects the true final state) and the
+ *      **baseline screenshot** (last tool call screenshot from the most recent successful
+ *      historical run) for visual comparison.
  *   5. Reads the source of the failing test case for contextual grounding.
  *   6. Runs the **heuristic classifier** (`deriveHeuristicAssessment`) which uses
  *      rule-based pattern matching over errors, tool calls, stale-cache indicators,
@@ -121,7 +123,7 @@ const cacheLocator_1 = require("../../ai/cache/cacheLocator");
  * | Flow metadata           | `DonobuExtendedPage._dnb`     | Run mode, objective, allowed tools, timing         |
  * | Stale cache indicators  | Derived from above            | Whether page.ai cache staleness is the root cause  |
  * | Historical flow runs    | `DonobuFlowsManager.getFlows` | Flakiness, regression patterns, prior self-heal    |
- * | Failure screenshot      | Last tool call screenshot     | Visual state of the page when the failure occurred |
+ * | Failure screenshot      | Live capture at triage time   | True final visual state of the page when it failed |
  * | Baseline screenshot     | Last successful run's screenshot | Visual reference for what the page *should* look like |
  * | Test source snippet     | TypeScript AST parsing        | The test's expectations and structure               |
  *
@@ -331,6 +333,14 @@ const TRIAGE_PERSISTENCE_FILE_IDS = {
     evidence: 'triage-evidence.json',
     failureScreenshot: 'triage-failure-screenshot.png',
     baselineScreenshot: 'triage-baseline-screenshot.png',
+    /**
+     * Live screenshot of a flow's final visual state, captured at teardown while
+     * the page is still open. Persisted on successful runs so that a *later*
+     * failing run can use it as a true final-state baseline — symmetric with the
+     * failure screenshot, which is also a live end-of-test capture. Keyed per
+     * flow, like browser state.
+     */
+    finalStateScreenshot: 'triage-final-state-screenshot.png',
 };
 exports.TRIAGE_PERSISTENCE_FILE_IDS = TRIAGE_PERSISTENCE_FILE_IDS;
 /**
@@ -554,41 +564,59 @@ async function fetchFlowHistory(page) {
     }
 }
 /**
- * Retrieves the screenshot from the last completed tool call in the current flow.
- * Returns the raw PNG/JPEG buffer if available, or null. Fails open so triage
- * proceeds even if the screenshot cannot be loaded.
+ * Captures a fresh screenshot of the page's current visual state. Called at
+ * teardown (failure triage and successful-run baseline capture) while the
+ * page/context is still open, so it reflects the true *end state* of the test.
+ *
+ * This is deliberately preferred over the last Donobu tool-call screenshot:
+ * Playwright `expect`/`waitFor` are not tool calls, so the last tool-call image
+ * can predate the failing assertion and capture a transient state (e.g. a
+ * loading spinner that has since resolved), which misleads the vision model.
+ * Fails open — returns null if the page is gone or unresponsive (crash, closed
+ * context, hang), in which case the caller proceeds without a screenshot.
  */
-async function fetchLastToolCallScreenshot(page) {
-    const flowId = page._dnb?.donobuFlowMetadata?.id;
-    const persistence = page._dnb?.persistence;
-    if (!flowId || !persistence) {
-        return null;
-    }
+async function captureLivePageScreenshot(page) {
     try {
-        const toolCalls = await persistence.getToolCalls(flowId);
-        if (toolCalls.length === 0) {
-            return null;
-        }
-        // Walk backwards to find the last tool call with a screenshot
-        for (let i = toolCalls.length - 1; i >= 0; i--) {
-            const screenshotId = toolCalls[i].postCallImageId;
-            if (screenshotId) {
-                return await persistence.getScreenShot(flowId, screenshotId);
-            }
-        }
-        return null;
+        return await page.screenshot({ animations: 'disabled', timeout: 10000 });
     }
     catch (error) {
-        Logger_1.appLogger.debug(`Failed to fetch last tool call screenshot for flow ${flowId}.`, error);
+        Logger_1.appLogger.debug('Failed to capture live page screenshot; proceeding without it.', error);
         return null;
     }
 }
 /**
- * Loads the final screenshot from a historical successful run to serve as a
- * visual baseline for comparison with the current failure state. This enables
- * the GPT triage agent to detect page redesigns and stale cache scenarios by
- * comparing "what the page looked like when it last worked" vs "what it looks
- * like now." Fails open — returns null if the screenshot cannot be retrieved.
+ * The failure screenshot for the current run. Prefers the final-state
+ * screenshot persisted at teardown (the single source of truth shared with
+ * baselines), and falls back to a live capture when it is missing — e.g. triage
+ * invoked outside the standard teardown, or the teardown capture failed.
+ */
+async function fetchCurrentRunFinalStateScreenshot(page) {
+    const flowId = page._dnb?.donobuFlowMetadata?.id;
+    const persistence = page._dnb?.persistence;
+    if (flowId && persistence) {
+        try {
+            const persisted = await persistence.getFlowFile(flowId, TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot);
+            if (persisted) {
+                return persisted;
+            }
+        }
+        catch (error) {
+            Logger_1.appLogger.debug(`Failed to read persisted final-state screenshot for flow ${flowId}; falling back to a live capture.`, error);
+        }
+    }
+    return captureLivePageScreenshot(page);
+}
+/**
+ * Loads a baseline screenshot from a historical successful run so the GPT
+ * triage agent can compare "what the page looked like when it last worked" vs
+ * "what it looks like now" to detect redesigns and stale-cache scenarios.
+ *
+ * Prefers the persisted final-state screenshot (a live end-of-test capture
+ * written on successful runs) so the baseline is symmetric with the live
+ * failure screenshot — both true end states. Falls back to the last tool-call
+ * image for runs that predate final-state capture; that image can be a
+ * mid-flow frame, so callers should treat such baselines as approximate.
+ * Fails open — returns null if no screenshot can be retrieved.
  */
 async function fetchBaselineScreenshot(page, historicalFlowId) {
     const persistence = page._dnb?.persistence;
@@ -596,10 +624,12 @@ async function fetchBaselineScreenshot(page, historicalFlowId) {
         return null;
     }
     try {
-        const toolCalls = await persistence.getToolCalls(historicalFlowId);
-        if (toolCalls.length === 0) {
-            return null;
+        const finalState = await persistence.getFlowFile(historicalFlowId, TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot);
+        if (finalState) {
+            return finalState;
         }
+        // Fallback for runs predating final-state capture: last tool-call image.
+        const toolCalls = await persistence.getToolCalls(historicalFlowId);
         for (let i = toolCalls.length - 1; i >= 0; i--) {
             const screenshotId = toolCalls[i].postCallImageId;
             if (screenshotId) {
@@ -1601,7 +1631,7 @@ async function gatherTestFailureEvidence(testInfo, page, options = {}) {
     // Capture screenshots for visual triage: current failure + baseline from last success
     const lastSuccessfulRunId = failureContext.flowHistory?.lastSuccessfulRunId ?? null;
     const [screenshotBuffer, baselineBuffer] = await Promise.all([
-        fetchLastToolCallScreenshot(page),
+        fetchCurrentRunFinalStateScreenshot(page),
         lastSuccessfulRunId
             ? fetchBaselineScreenshot(page, lastSuccessfulRunId)
             : Promise.resolve(null),
@@ -1805,10 +1835,20 @@ passed to each tool invocation. Use these to improve diagnosis:
 
 SCREENSHOT EVIDENCE:
 You may receive one or two screenshots:
-1. "FAILURE SCREENSHOT" — the state of the page at or near the point of failure in the current run.
+1. "FAILURE SCREENSHOT" — a live screenshot captured at triage time, immediately after the test
+   failed and while the page was still open. It reflects the true FINAL visual state of the page.
 2. "BASELINE SCREENSHOT" — the state of the page at the end of the most recent successful run of
    this same flow. This serves as a visual reference for what the page *should* look like.
 
+IMPORTANT — a screenshot is a single moment in time, not a recording:
+- Describe only what the frame shows. Do NOT assert that a state persisted for a duration — e.g.
+  "stuck on a loading spinner THROUGHOUT the test", "the page never loaded", "remained on X the
+  whole time". A single frame cannot establish how long anything lasted.
+- Only claim a persistent or temporal condition when it is corroborated by NON-visual evidence:
+  tool-call outcomes/durations, error messages, or timeouts in failureContext. Absent that, state
+  the end condition factually (e.g. "the final screenshot shows a loading spinner") and let the
+  other evidence determine duration and cause.
+
 When both screenshots are provided, compare them to:
 - Detect UI changes (redesigns, layout shifts, new modals) that would explain selector or cache failures.
 - Identify whether the failure screenshot shows a fundamentally different page state (error page, login wall)
@@ -1837,7 +1877,10 @@ When only the failure screenshot is provided (no baseline available), use it to:
     if (evidence.failureScreenshotPath) {
         try {
             const failureBytes = await fs.readFile(evidence.failureScreenshotPath);
-            userItems.push({ type: 'text', text: 'FAILURE SCREENSHOT (current run):' }, { type: 'png', bytes: new Uint8Array(failureBytes) });
+            userItems.push({
+                type: 'text',
+                text: 'FAILURE SCREENSHOT (live capture at triage time — true final state of the page):',
+            }, { type: 'png', bytes: new Uint8Array(failureBytes) });
         }
         catch (screenshotError) {
             Logger_1.appLogger.debug('Failed to load failure screenshot for GPT triage, proceeding with text only.', screenshotError);

package/dist/lib/test/testExtension.js

@@ -843,6 +843,40 @@ async function attachStepScreenshots(sharedState, testInfo) {
         contentType: 'application/json',
     });
 }
+/**
+ * Capture a live screenshot of the flow's final visual state at teardown (page
+ * still open) and persist it as a per-flow file — the single source of truth
+ * for "what the page looked like when this run ended." It is read both as the
+ * current run's failure screenshot (when this run failed) and as the baseline
+ * for a later failing run (when this run succeeded), keeping the two symmetric.
+ * See `fetchBaselineScreenshot` / `gatherTestFailureEvidence` in
+ * triageTestFailure.ts.
+ *
+ * Runs for any meaningful end state; skipped only for `skipped` tests (no real
+ * page state), when triage is disabled, or for V1 (legacy self-heal) tests.
+ * Best-effort and fails open.
+ */
+async function captureAndPersistFinalState(page, testInfo) {
+    if (testInfo.status === 'skipped' ||
+        process.env.DONOBU_TRIAGE_DISABLED === '1' ||
+        isV1Test(testInfo)) {
+        return;
+    }
+    const flowId = page._dnb?.donobuFlowMetadata?.id;
+    const persistence = page._dnb?.persistence;
+    if (!flowId || !persistence) {
+        return;
+    }
+    try {
+        const screenshot = await (0, triageTestFailure_1.captureLivePageScreenshot)(page);
+        if (screenshot) {
+            await persistence.setFlowFile(flowId, triageTestFailure_1.TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot, screenshot);
+        }
+    }
+    catch (error) {
+        Logger_1.appLogger.error(`Failed to persist final-state screenshot for flow ${flowId}.`, error);
+    }
+}
 async function finalizeTest(page, testInfo, logBuffer, videoOption) {
     const sharedState = page._dnb;
     // Kick off video persistence early in teardown. The actual file copy is
@@ -919,6 +953,10 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
     catch (error) {
         Logger_1.appLogger.error(`Error during cleanup for test ${testInfo.title}:`, error);
     }
+    // Capture the flow's final visual state before the status-specific handling
+    // below: triage (failed branch) reads it as the failure screenshot, and a
+    // future failing run reads a successful run's copy as its baseline.
+    await captureAndPersistFinalState(page, testInfo);
     if (testInfo.status === 'failed') {
         if (isV1Test(testInfo)) {
             if (isV1SelfHealingEnabled(testInfo) &&

package/dist/lib/test/utils/triageTestFailure.d.ts

@@ -28,9 +28,10 @@ import type { DonobuExtendedPage } from '../../page/DonobuExtendedPage';
  *      history from the persistence layer.
  *   3. Fetches **historical runs** of the same flow (by name) from the flows manager to
  *      detect flakiness, regression patterns, and prior self-heal success.
- *   4. Captures the **failure screenshot** (last tool call screenshot from the current
- *      run) and the **baseline screenshot** (last tool call screenshot from the most
- *      recent successful historical run) for visual comparison.
+ *   4. Captures the **failure screenshot** (a live screenshot taken at triage time, while
+ *      the page is still open during teardown, so it reflects the true final state) and the
+ *      **baseline screenshot** (last tool call screenshot from the most recent successful
+ *      historical run) for visual comparison.
  *   5. Reads the source of the failing test case for contextual grounding.
  *   6. Runs the **heuristic classifier** (`deriveHeuristicAssessment`) which uses
  *      rule-based pattern matching over errors, tool calls, stale-cache indicators,
@@ -70,7 +71,7 @@ import type { DonobuExtendedPage } from '../../page/DonobuExtendedPage';
  * | Flow metadata           | `DonobuExtendedPage._dnb`     | Run mode, objective, allowed tools, timing         |
  * | Stale cache indicators  | Derived from above            | Whether page.ai cache staleness is the root cause  |
  * | Historical flow runs    | `DonobuFlowsManager.getFlows` | Flakiness, regression patterns, prior self-heal    |
- * | Failure screenshot      | Last tool call screenshot     | Visual state of the page when the failure occurred |
+ * | Failure screenshot      | Live capture at triage time   | True final visual state of the page when it failed |
  * | Baseline screenshot     | Last successful run's screenshot | Visual reference for what the page *should* look like |
  * | Test source snippet     | TypeScript AST parsing        | The test's expectations and structure               |
  *
@@ -408,6 +409,14 @@ declare const TRIAGE_PERSISTENCE_FILE_IDS: {
     readonly evidence: "triage-evidence.json";
     readonly failureScreenshot: "triage-failure-screenshot.png";
     readonly baselineScreenshot: "triage-baseline-screenshot.png";
+    /**
+     * Live screenshot of a flow's final visual state, captured at teardown while
+     * the page is still open. Persisted on successful runs so that a *later*
+     * failing run can use it as a true final-state baseline — symmetric with the
+     * failure screenshot, which is also a live end-of-test capture. Keyed per
+     * flow, like browser state.
+     */
+    readonly finalStateScreenshot: "triage-final-state-screenshot.png";
 };
 /**
  * Compresses a set of historical flow runs into an aggregate summary compact
@@ -420,6 +429,19 @@ declare function summarizeFlowHistory(flowName: string, flows: FlowMetadata[]):
  * success, and whether the page.ai cache was recently validated.
  */
 declare function deriveHistoricalSignals(history: FlowHistorySummary): HistoricalSignals;
+/**
+ * Captures a fresh screenshot of the page's current visual state. Called at
+ * teardown (failure triage and successful-run baseline capture) while the
+ * page/context is still open, so it reflects the true *end state* of the test.
+ *
+ * This is deliberately preferred over the last Donobu tool-call screenshot:
+ * Playwright `expect`/`waitFor` are not tool calls, so the last tool-call image
+ * can predate the failing assertion and capture a transient state (e.g. a
+ * loading spinner that has since resolved), which misleads the vision model.
+ * Fails open — returns null if the page is gone or unresponsive (crash, closed
+ * context, hang), in which case the caller proceeds without a screenshot.
+ */
+declare function captureLivePageScreenshot(page: DonobuExtendedPage): Promise<Buffer | null>;
 /**
  * Builds the heuristic triage assessment by combining rule-based inference,
  * contextual flags, and derived remediation guidance ahead of GPT enrichment.
@@ -432,5 +454,5 @@ declare function deriveHeuristicAssessment(testInfo: TestInfo, errorSummaries: E
 declare function reconcileTreatmentPlan(plan: z.infer<typeof TreatmentPlan>, heuristics: HeuristicAssessment): z.infer<typeof TreatmentPlan>;
 declare function gatherTestFailureEvidence(testInfo: TestInfo, page: DonobuExtendedPage, options?: GatherTestFailureEvidenceOptions): Promise<GatherTestFailureEvidenceResult | null>;
 declare function generateTreatmentPlanFromEvidence(gptClient: GptClient, evidence: FailureEvidenceRecord): Promise<z.infer<typeof TreatmentPlan>>;
-export { type AdditionalDataRequest, AdditionalDataRequestSchema, type AutomationDirectives, deriveHeuristicAssessment, deriveHistoricalSignals, type ErrorSummary, type FailureEvidenceRecord, type FailureReason, FailureReasonSchema, type FlowHistorySummary, gatherTestFailureEvidence, type GatherTestFailureEvidenceOptions, type GatherTestFailureEvidenceResult, generateTreatmentPlanFromEvidence, type HeuristicAssessment, type HistoricalFlowRun, type HistoricalSignals, reconcileTreatmentPlan, type RemediationCategory, type RemediationStep, RemediationStepSchema, type SanitizedFlowMetadata, type SummarizedToolCall, summarizeFlowHistory, TreatmentPlan, TRIAGE_PERSISTENCE_FILE_IDS, };
+export { type AdditionalDataRequest, AdditionalDataRequestSchema, type AutomationDirectives, captureLivePageScreenshot, deriveHeuristicAssessment, deriveHistoricalSignals, type ErrorSummary, type FailureEvidenceRecord, type FailureReason, FailureReasonSchema, type FlowHistorySummary, gatherTestFailureEvidence, type GatherTestFailureEvidenceOptions, type GatherTestFailureEvidenceResult, generateTreatmentPlanFromEvidence, type HeuristicAssessment, type HistoricalFlowRun, type HistoricalSignals, reconcileTreatmentPlan, type RemediationCategory, type RemediationStep, RemediationStepSchema, type SanitizedFlowMetadata, type SummarizedToolCall, summarizeFlowHistory, TreatmentPlan, TRIAGE_PERSISTENCE_FILE_IDS, };
 //# sourceMappingURL=triageTestFailure.d.ts.map

package/dist/lib/test/utils/triageTestFailure.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TRIAGE_PERSISTENCE_FILE_IDS = exports.TreatmentPlan = exports.RemediationStepSchema = exports.FailureReasonSchema = exports.AdditionalDataRequestSchema = void 0;
+exports.captureLivePageScreenshot = captureLivePageScreenshot;
 exports.deriveHeuristicAssessment = deriveHeuristicAssessment;
 exports.deriveHistoricalSignals = deriveHistoricalSignals;
 exports.gatherTestFailureEvidence = gatherTestFailureEvidence;
@@ -79,9 +80,10 @@ const cacheLocator_1 = require("../../ai/cache/cacheLocator");
  *      history from the persistence layer.
  *   3. Fetches **historical runs** of the same flow (by name) from the flows manager to
  *      detect flakiness, regression patterns, and prior self-heal success.
- *   4. Captures the **failure screenshot** (last tool call screenshot from the current
- *      run) and the **baseline screenshot** (last tool call screenshot from the most
- *      recent successful historical run) for visual comparison.
+ *   4. Captures the **failure screenshot** (a live screenshot taken at triage time, while
+ *      the page is still open during teardown, so it reflects the true final state) and the
+ *      **baseline screenshot** (last tool call screenshot from the most recent successful
+ *      historical run) for visual comparison.
  *   5. Reads the source of the failing test case for contextual grounding.
  *   6. Runs the **heuristic classifier** (`deriveHeuristicAssessment`) which uses
  *      rule-based pattern matching over errors, tool calls, stale-cache indicators,
@@ -121,7 +123,7 @@ const cacheLocator_1 = require("../../ai/cache/cacheLocator");
  * | Flow metadata           | `DonobuExtendedPage._dnb`     | Run mode, objective, allowed tools, timing         |
  * | Stale cache indicators  | Derived from above            | Whether page.ai cache staleness is the root cause  |
  * | Historical flow runs    | `DonobuFlowsManager.getFlows` | Flakiness, regression patterns, prior self-heal    |
- * | Failure screenshot      | Last tool call screenshot     | Visual state of the page when the failure occurred |
+ * | Failure screenshot      | Live capture at triage time   | True final visual state of the page when it failed |
  * | Baseline screenshot     | Last successful run's screenshot | Visual reference for what the page *should* look like |
  * | Test source snippet     | TypeScript AST parsing        | The test's expectations and structure               |
  *
@@ -331,6 +333,14 @@ const TRIAGE_PERSISTENCE_FILE_IDS = {
     evidence: 'triage-evidence.json',
     failureScreenshot: 'triage-failure-screenshot.png',
     baselineScreenshot: 'triage-baseline-screenshot.png',
+    /**
+     * Live screenshot of a flow's final visual state, captured at teardown while
+     * the page is still open. Persisted on successful runs so that a *later*
+     * failing run can use it as a true final-state baseline — symmetric with the
+     * failure screenshot, which is also a live end-of-test capture. Keyed per
+     * flow, like browser state.
+     */
+    finalStateScreenshot: 'triage-final-state-screenshot.png',
 };
 exports.TRIAGE_PERSISTENCE_FILE_IDS = TRIAGE_PERSISTENCE_FILE_IDS;
 /**
@@ -554,41 +564,59 @@ async function fetchFlowHistory(page) {
     }
 }
 /**
- * Retrieves the screenshot from the last completed tool call in the current flow.
- * Returns the raw PNG/JPEG buffer if available, or null. Fails open so triage
- * proceeds even if the screenshot cannot be loaded.
+ * Captures a fresh screenshot of the page's current visual state. Called at
+ * teardown (failure triage and successful-run baseline capture) while the
+ * page/context is still open, so it reflects the true *end state* of the test.
+ *
+ * This is deliberately preferred over the last Donobu tool-call screenshot:
+ * Playwright `expect`/`waitFor` are not tool calls, so the last tool-call image
+ * can predate the failing assertion and capture a transient state (e.g. a
+ * loading spinner that has since resolved), which misleads the vision model.
+ * Fails open — returns null if the page is gone or unresponsive (crash, closed
+ * context, hang), in which case the caller proceeds without a screenshot.
  */
-async function fetchLastToolCallScreenshot(page) {
-    const flowId = page._dnb?.donobuFlowMetadata?.id;
-    const persistence = page._dnb?.persistence;
-    if (!flowId || !persistence) {
-        return null;
-    }
+async function captureLivePageScreenshot(page) {
     try {
-        const toolCalls = await persistence.getToolCalls(flowId);
-        if (toolCalls.length === 0) {
-            return null;
-        }
-        // Walk backwards to find the last tool call with a screenshot
-        for (let i = toolCalls.length - 1; i >= 0; i--) {
-            const screenshotId = toolCalls[i].postCallImageId;
-            if (screenshotId) {
-                return await persistence.getScreenShot(flowId, screenshotId);
-            }
-        }
-        return null;
+        return await page.screenshot({ animations: 'disabled', timeout: 10000 });
     }
     catch (error) {
-        Logger_1.appLogger.debug(`Failed to fetch last tool call screenshot for flow ${flowId}.`, error);
+        Logger_1.appLogger.debug('Failed to capture live page screenshot; proceeding without it.', error);
         return null;
     }
 }
 /**
- * Loads the final screenshot from a historical successful run to serve as a
- * visual baseline for comparison with the current failure state. This enables
- * the GPT triage agent to detect page redesigns and stale cache scenarios by
- * comparing "what the page looked like when it last worked" vs "what it looks
- * like now." Fails open — returns null if the screenshot cannot be retrieved.
+ * The failure screenshot for the current run. Prefers the final-state
+ * screenshot persisted at teardown (the single source of truth shared with
+ * baselines), and falls back to a live capture when it is missing — e.g. triage
+ * invoked outside the standard teardown, or the teardown capture failed.
+ */
+async function fetchCurrentRunFinalStateScreenshot(page) {
+    const flowId = page._dnb?.donobuFlowMetadata?.id;
+    const persistence = page._dnb?.persistence;
+    if (flowId && persistence) {
+        try {
+            const persisted = await persistence.getFlowFile(flowId, TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot);
+            if (persisted) {
+                return persisted;
+            }
+        }
+        catch (error) {
+            Logger_1.appLogger.debug(`Failed to read persisted final-state screenshot for flow ${flowId}; falling back to a live capture.`, error);
+        }
+    }
+    return captureLivePageScreenshot(page);
+}
+/**
+ * Loads a baseline screenshot from a historical successful run so the GPT
+ * triage agent can compare "what the page looked like when it last worked" vs
+ * "what it looks like now" to detect redesigns and stale-cache scenarios.
+ *
+ * Prefers the persisted final-state screenshot (a live end-of-test capture
+ * written on successful runs) so the baseline is symmetric with the live
+ * failure screenshot — both true end states. Falls back to the last tool-call
+ * image for runs that predate final-state capture; that image can be a
+ * mid-flow frame, so callers should treat such baselines as approximate.
+ * Fails open — returns null if no screenshot can be retrieved.
  */
 async function fetchBaselineScreenshot(page, historicalFlowId) {
     const persistence = page._dnb?.persistence;
@@ -596,10 +624,12 @@ async function fetchBaselineScreenshot(page, historicalFlowId) {
         return null;
     }
     try {
-        const toolCalls = await persistence.getToolCalls(historicalFlowId);
-        if (toolCalls.length === 0) {
-            return null;
+        const finalState = await persistence.getFlowFile(historicalFlowId, TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot);
+        if (finalState) {
+            return finalState;
         }
+        // Fallback for runs predating final-state capture: last tool-call image.
+        const toolCalls = await persistence.getToolCalls(historicalFlowId);
         for (let i = toolCalls.length - 1; i >= 0; i--) {
             const screenshotId = toolCalls[i].postCallImageId;
             if (screenshotId) {
@@ -1601,7 +1631,7 @@ async function gatherTestFailureEvidence(testInfo, page, options = {}) {
     // Capture screenshots for visual triage: current failure + baseline from last success
     const lastSuccessfulRunId = failureContext.flowHistory?.lastSuccessfulRunId ?? null;
     const [screenshotBuffer, baselineBuffer] = await Promise.all([
-        fetchLastToolCallScreenshot(page),
+        fetchCurrentRunFinalStateScreenshot(page),
         lastSuccessfulRunId
             ? fetchBaselineScreenshot(page, lastSuccessfulRunId)
             : Promise.resolve(null),
@@ -1805,10 +1835,20 @@ passed to each tool invocation. Use these to improve diagnosis:
 
 SCREENSHOT EVIDENCE:
 You may receive one or two screenshots:
-1. "FAILURE SCREENSHOT" — the state of the page at or near the point of failure in the current run.
+1. "FAILURE SCREENSHOT" — a live screenshot captured at triage time, immediately after the test
+   failed and while the page was still open. It reflects the true FINAL visual state of the page.
 2. "BASELINE SCREENSHOT" — the state of the page at the end of the most recent successful run of
    this same flow. This serves as a visual reference for what the page *should* look like.
 
+IMPORTANT — a screenshot is a single moment in time, not a recording:
+- Describe only what the frame shows. Do NOT assert that a state persisted for a duration — e.g.
+  "stuck on a loading spinner THROUGHOUT the test", "the page never loaded", "remained on X the
+  whole time". A single frame cannot establish how long anything lasted.
+- Only claim a persistent or temporal condition when it is corroborated by NON-visual evidence:
+  tool-call outcomes/durations, error messages, or timeouts in failureContext. Absent that, state
+  the end condition factually (e.g. "the final screenshot shows a loading spinner") and let the
+  other evidence determine duration and cause.
+
 When both screenshots are provided, compare them to:
 - Detect UI changes (redesigns, layout shifts, new modals) that would explain selector or cache failures.
 - Identify whether the failure screenshot shows a fundamentally different page state (error page, login wall)
@@ -1837,7 +1877,10 @@ When only the failure screenshot is provided (no baseline available), use it to:
     if (evidence.failureScreenshotPath) {
         try {
             const failureBytes = await fs.readFile(evidence.failureScreenshotPath);
-            userItems.push({ type: 'text', text: 'FAILURE SCREENSHOT (current run):' }, { type: 'png', bytes: new Uint8Array(failureBytes) });
+            userItems.push({
+                type: 'text',
+                text: 'FAILURE SCREENSHOT (live capture at triage time — true final state of the page):',
+            }, { type: 'png', bytes: new Uint8Array(failureBytes) });
         }
         catch (screenshotError) {
             Logger_1.appLogger.debug('Failed to load failure screenshot for GPT triage, proceeding with text only.', screenshotError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.46.0",
+  "version": "5.47.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",