donobu 5.60.0 → 5.60.2

package/dist/esm/utils/PlaywrightUtils.d.ts

@@ -1,9 +1,47 @@
 import type { BrowserContext, Locator, Page, PageScreenshotOptions } from 'playwright';
+/**
+ * Envelope resolved by expressions built with
+ * {@link PlaywrightUtils.asSizeGuardedJavaScriptExpression}. Small results
+ * come back inline in `value`; oversized (or non-JSON-serializable) results
+ * come back as a structural summary plus preview, with `stashedAt` naming the
+ * `window.__dnb_result_<n>` variable holding the full value when stashing was
+ * requested.
+ */
+export type SizeGuardedEvaluationResult = {
+    __dnbGuard: true;
+    oversized: false;
+    value: unknown;
+} | {
+    __dnbGuard: true;
+    oversized: true;
+    /** Serialized size in JSON characters, or null if not JSON-serializable. */
+    size: number | null;
+    summary: string;
+    preview: string;
+    stashedAt: string | null;
+};
 /**
  * Miscellaneous utility functions for working with the Playwright SDK. If you are looking to
  * instantiate a Playwright instance, see PlaywrightSetup instead.
  */
 export declare class PlaywrightUtils {
+    /**
+     * Maximum serialized size (in JSON characters) of an evaluation result that
+     * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+     * this go into the conversation history verbatim, so this bounds prompt
+     * growth per tool call.
+     */
+    static readonly MAX_INLINE_RESULT_JSON_CHARS = 32000;
+    /**
+     * Number of characters of the serialized result included as a preview when
+     * a result is too large to return inline.
+     */
+    static readonly OVERSIZED_RESULT_PREVIEW_CHARS = 2000;
+    /**
+     * Number of oversized results kept alive in the page via
+     * `window.__dnb_result_<n>` stash variables before the oldest is released.
+     */
+    static readonly MAX_STASHED_RESULTS = 3;
     private static _blankJpeg;
     private static _blankPng;
     private static readonly _browserInstallPromises;
@@ -49,6 +87,43 @@ export declare class PlaywrightUtils {
      * scripts.
      */
     static setupBasicBrowserContext(browserContext: BrowserContext): Promise<void>;
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code: string): string;
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code: string, options: {
+        stashOversizedResult: boolean;
+        maxInlineChars?: number;
+        previewChars?: number;
+    }): string;
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.

package/dist/esm/utils/PlaywrightUtils.js

@@ -133,6 +133,111 @@ class PlaywrightUtils {
         await browserContext.addInitScript(dialog_prompt_tracker_1.installDialogPromptTracker);
         await browserContext.addInitScript(smart_selector_generator_1.installSmartSelectorGenerator);
     }
+    /**
+     * Wraps arbitrary JavaScript code so that it can be passed as a string to
+     * Playwright's evaluate(). Playwright evaluates string arguments as bare
+     * expressions, so function-form code like `() => {...}` would evaluate to
+     * an (unserializable) function object that is never invoked, and the caller
+     * would get back undefined. The returned expression invokes function-form
+     * code and passes plain expressions through unchanged. Promise results
+     * (e.g. from async function-form code) are awaited by evaluate() itself.
+     *
+     * The wrapped code is placed on its own lines so that a trailing `//`
+     * comment cannot swallow the closing parenthesis.
+     */
+    static asInvokedJavaScriptExpression(code) {
+        return `(() => {
+  const __donobuEvalResult = (
+${code}
+  );
+  return typeof __donobuEvalResult === 'function'
+    ? __donobuEvalResult()
+    : __donobuEvalResult;
+})()`;
+    }
+    /**
+     * Like {@link asInvokedJavaScriptExpression}, but the result is measured
+     * page-side before it crosses the Playwright wire, so an enormous result
+     * never gets serialized over CDP into this process. The returned expression
+     * always resolves to a {@link SizeGuardedEvaluationResult} envelope.
+     *
+     * When the serialized result exceeds `maxInlineChars`, the envelope carries
+     * a structural summary and a short preview instead of the value. With
+     * `stashOversizedResult`, the value itself (a reference, not a copy) is
+     * additionally kept in the page as `window.__dnb_result_<n>` so follow-up
+     * evaluations can slice or aggregate it. The stash counter lives on
+     * `window`, so it resets with the page — names stay deterministic across
+     * cached replays because navigations replay too. Only the most recent
+     * {@link MAX_STASHED_RESULTS} stashes are kept alive.
+     *
+     * Results that fail JSON serialization (circular structures, BigInt, etc.)
+     * are treated as oversized with a `null` size, since they could not be
+     * returned through the tool result either.
+     */
+    static asSizeGuardedJavaScriptExpression(code, options) {
+        const maxInlineChars = options.maxInlineChars ?? PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS;
+        const previewChars = options.previewChars ?? PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS;
+        const stashSnippet = options.stashOversizedResult
+            ? `{
+      const __w = window;
+      __w.__dnb_stash_count = (__w.__dnb_stash_count || 0) + 1;
+      __stashedAt = '__dnb_result_' + __w.__dnb_stash_count;
+      __w[__stashedAt] = __value;
+      __w.__dnb_stash_names = __w.__dnb_stash_names || [];
+      __w.__dnb_stash_names.push(__stashedAt);
+      while (__w.__dnb_stash_names.length > ${PlaywrightUtils.MAX_STASHED_RESULTS}) {
+        delete __w[__w.__dnb_stash_names.shift()];
+      }
+    }`
+            : '';
+        return `(() => {
+  const __pending = Promise.resolve(
+${PlaywrightUtils.asInvokedJavaScriptExpression(code)}
+  );
+  return __pending.then((__value) => {
+    if (__value === undefined) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    let __json;
+    try {
+      __json = JSON.stringify(__value);
+    } catch {
+      __json = undefined;
+    }
+    if (__json !== undefined && __json.length <= ${maxInlineChars}) {
+      return { __dnbGuard: true, oversized: false, value: __value };
+    }
+    const __summary = (() => {
+      if (Array.isArray(__value)) {
+        const __first = __value.find((el) => el && typeof el === 'object');
+        const __keys = __first ? Object.keys(__first).slice(0, 12).join(', ') : null;
+        return 'an array of ' + __value.length + ' elements' +
+          (__keys ? ' (element keys: ' + __keys + ')' : '');
+      }
+      if (typeof __value === 'object' && __value !== null) {
+        return 'an object with keys: ' + Object.keys(__value).slice(0, 24).join(', ');
+      }
+      return 'a ' + typeof __value;
+    })();
+    let __preview = '';
+    try {
+      __preview = (__json !== undefined ? __json : String(__value)).slice(0, ${previewChars});
+    } catch {
+      // Leave the preview empty if the value cannot be stringified at all.
+    }
+    let __stashedAt = null;
+    ${stashSnippet}
+    return {
+      __dnbGuard: true,
+      oversized: true,
+      size: __json === undefined ? null : __json.length,
+      summary: __summary,
+      preview: __preview,
+      stashedAt: __stashedAt,
+    };
+  });
+})()`;
+    }
     /**
      * Returned true IFF the given error is a Playwright error regarding page closing,
      * of if the given error is an instance of {@link PageClosedException}.
@@ -297,6 +402,23 @@ class PlaywrightUtils {
     }
 }
 exports.PlaywrightUtils = PlaywrightUtils;
+/**
+ * Maximum serialized size (in JSON characters) of an evaluation result that
+ * {@link asSizeGuardedJavaScriptExpression} returns inline. Results above
+ * this go into the conversation history verbatim, so this bounds prompt
+ * growth per tool call.
+ */
+PlaywrightUtils.MAX_INLINE_RESULT_JSON_CHARS = 32_000;
+/**
+ * Number of characters of the serialized result included as a preview when
+ * a result is too large to return inline.
+ */
+PlaywrightUtils.OVERSIZED_RESULT_PREVIEW_CHARS = 2_000;
+/**
+ * Number of oversized results kept alive in the page via
+ * `window.__dnb_result_<n>` stash variables before the oldest is released.
+ */
+PlaywrightUtils.MAX_STASHED_RESULTS = 3;
 // Per-browser in-flight install promises — deduplicate concurrent requests.
 PlaywrightUtils._browserInstallPromises = new Map();
 //# sourceMappingURL=PlaywrightUtils.js.map

package/dist/lib/page/extendPage.d.ts

@@ -20,6 +20,12 @@ export declare function extendPage(page: Page, options?: {
     flowId?: string;
     visualCueDurationMs?: number;
     cacheFilepath?: string;
+    /**
+     * Spec file this page is serving. Used to decide whether the file-scoped
+     * Page.AI cache invalidation (`DONOBU_PAGE_AI_CLEAR_CACHE_FILES`) applies
+     * to this context.
+     */
+    specFilePath?: string;
     envVars?: string[];
     gptClient?: GptClient;
     headless?: boolean;

package/dist/lib/page/extendPage.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extendPage = extendPage;
 const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
 const v4_1 = require("zod/v4");
 const GptClient_1 = require("../../clients/GptClient");
 const VercelAiGptClient_1 = require("../../clients/VercelAiGptClient");
@@ -60,6 +64,25 @@ function resolveBaseUrl(page, url) {
 // Donobu page extension helpers: decorate Playwright pages with Donobu behaviors and keep one
 // coherent flow (and persistence record) per browser context so new tabs share state safely.
 const PLACEHOLDER_FLOW_URL = 'https://example.com';
+/**
+ * Whether Page.AI cache entries should be bypassed and invalidated for this
+ * context. Two knobs:
+ * - `DONOBU_PAGE_AI_CLEAR_CACHE` — run-wide, set by `--clear-ai-cache`.
+ * - `DONOBU_PAGE_AI_CLEAR_CACHE_FILES` — JSON array of spec paths, set by the
+ *   auto-heal rerun so only heal-target spec files regenerate selectors while
+ *   other re-running tests (serial prerequisites) keep their cache replay.
+ */
+function shouldClearPageAiCache(specFilePath) {
+    if (MiscUtils_1.MiscUtils.yn(envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE)) {
+        return true;
+    }
+    const files = envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE_FILES;
+    if (!files?.length || !specFilePath) {
+        return false;
+    }
+    const resolved = path_1.default.resolve(specFilePath);
+    return files.some((file) => path_1.default.resolve(file) === resolved);
+}
 // Cache the shared Donobu state per browser context so every tab in that context reuses the same
 // flow metadata, persistence, GPT client, and visualizer. WeakMap ensures cleanup when contexts die.
 const contextSharedState = new WeakMap();
@@ -137,7 +160,7 @@ async function extendPage(page, options) {
             gptClient: resolvedGptClient,
             controlPanelFactory: options?.controlPanelFactory,
             runtimeDirectives: {
-                clearPageAiCache: MiscUtils_1.MiscUtils.yn(envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE),
+                clearPageAiCache: shouldClearPageAiCache(options?.specFilePath),
             },
             tbdSessions: [],
             aiInvocations: [],

package/dist/lib/test/healRerunGate.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Runtime gate for auto-heal reruns.
+ *
+ * The auto-heal rerun is launched with the same project-level arguments as the
+ * initial run so Playwright's scheduling (declared project `dependencies`,
+ * workers, ordering) behaves with full fidelity. Within the targeted projects,
+ * however, only the tests the heal actually needs should execute. This module
+ * enforces that from an auto fixture that runs before any browser fixture:
+ * when `DONOBU_AUTO_HEAL_PLAN_PATH` is set, every test not in the rerun plan
+ * skips immediately — before a context or page is created — annotated with
+ * `donobu-heal-skip-replay` so the merge step drops the entry and leaves the
+ * initial run's result untouched.
+ *
+ * What runs during a heal rerun (the "declared signals only" policy):
+ *   - Heal targets (the failed tests with actionable treatment plans).
+ *   - For a target inside a `test.describe.serial` scope (or a file marked
+ *     serial via `test.describe.configure({ mode: 'serial' })`): the other
+ *     serial-scoped tests in that file. Serial mode is Playwright's declared
+ *     intra-file ordering contract — Playwright itself re-runs whole serial
+ *     groups on retry, and we mirror that. The orchestrator expands the plan
+ *     with these companions before the rerun (see
+ *     `expandTargetsWithSerialCompanions`) using the `serialScoped` flags the
+ *     Donobu reporter recorded during the initial run — the runner process
+ *     sees the suite tree; the worker (where this gate runs) does not.
+ *   - Declared dependency projects, which Playwright always runs in full.
+ *
+ * Implicit ordering (checkpoint files between plain tests, cross-file state
+ * with `workers: 1`) is deliberately NOT honored: tests relying on it will
+ * skip themselves during the rerun and surface as honest failures with
+ * guidance to declare the dependency.
+ *
+ * The gate runs at test runtime rather than collection time so Playwright's
+ * test-location attribution stays untouched (a collection-time wrapper would
+ * become every test's reported call site, breaking the merge's file-based
+ * matching) and so the plan can be matched against `testInfo.file`/`title`
+ * exactly instead of via stack inspection.
+ */
+import type { TestInfo } from '@playwright/test';
+/** Shape of the plan file the auto-heal orchestrator writes before the rerun. */
+export interface HealRerunPlan {
+    targets: Array<{
+        /** Spec file path; absolute, or relative to the rerun's CWD. */
+        file: string;
+        title: string;
+        projectName?: string;
+    }>;
+}
+/** Targets indexed by absolute spec path for O(1) per-test decisions. */
+export type HealRerunPlanIndex = Map<string, Set<string>>;
+export declare function buildPlanIndex(plan: HealRerunPlan): HealRerunPlanIndex;
+/**
+ * Pure decision: should the test in `file` with `title` actually execute
+ * during the heal rerun? The plan is fully explicit — serial companions were
+ * already expanded into it by the orchestrator.
+ */
+export declare function shouldRunDuringHealRerun(params: {
+    index: HealRerunPlanIndex;
+    file: string;
+    title: string;
+}): boolean;
+/**
+ * Expand heal targets with their `describe.serial` siblings, using the
+ * `serialScoped` flags the Donobu reporter recorded in the initial run's
+ * report. Companions live in the same file as their target by construction
+ * (serial scopes are intra-file), so they inherit the target's absolute file
+ * path; report file paths are rootDir-relative, hence the suffix match.
+ *
+ * Degrades to the unexpanded targets when the report (or the flags) are
+ * unavailable — serial chains then surface as honest not-reattempted
+ * failures instead of healing.
+ */
+export declare function expandTargetsWithSerialCompanions(targets: HealRerunPlan['targets'], initialReport: {
+    suites?: unknown;
+} | null): HealRerunPlan['targets'];
+/** Test-only: reset the memoized plan so each test can load its own. */
+export declare function resetHealRerunPlanCacheForTesting(): void;
+/**
+ * Called from the Donobu auto fixture before any browser fixture initializes.
+ * Outside heal reruns this is a no-op. During a rerun, tests outside the plan
+ * are annotated and skipped on the spot — no context, no page, no cost.
+ */
+export declare function maybeSkipForHealRerun(testInfo: TestInfo, options?: {
+    planPath?: string;
+}): void;
+//# sourceMappingURL=healRerunGate.d.ts.map

package/dist/lib/test/healRerunGate.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * @fileoverview Runtime gate for auto-heal reruns.
+ *
+ * The auto-heal rerun is launched with the same project-level arguments as the
+ * initial run so Playwright's scheduling (declared project `dependencies`,
+ * workers, ordering) behaves with full fidelity. Within the targeted projects,
+ * however, only the tests the heal actually needs should execute. This module
+ * enforces that from an auto fixture that runs before any browser fixture:
+ * when `DONOBU_AUTO_HEAL_PLAN_PATH` is set, every test not in the rerun plan
+ * skips immediately — before a context or page is created — annotated with
+ * `donobu-heal-skip-replay` so the merge step drops the entry and leaves the
+ * initial run's result untouched.
+ *
+ * What runs during a heal rerun (the "declared signals only" policy):
+ *   - Heal targets (the failed tests with actionable treatment plans).
+ *   - For a target inside a `test.describe.serial` scope (or a file marked
+ *     serial via `test.describe.configure({ mode: 'serial' })`): the other
+ *     serial-scoped tests in that file. Serial mode is Playwright's declared
+ *     intra-file ordering contract — Playwright itself re-runs whole serial
+ *     groups on retry, and we mirror that. The orchestrator expands the plan
+ *     with these companions before the rerun (see
+ *     `expandTargetsWithSerialCompanions`) using the `serialScoped` flags the
+ *     Donobu reporter recorded during the initial run — the runner process
+ *     sees the suite tree; the worker (where this gate runs) does not.
+ *   - Declared dependency projects, which Playwright always runs in full.
+ *
+ * Implicit ordering (checkpoint files between plain tests, cross-file state
+ * with `workers: 1`) is deliberately NOT honored: tests relying on it will
+ * skip themselves during the rerun and surface as honest failures with
+ * guidance to declare the dependency.
+ *
+ * The gate runs at test runtime rather than collection time so Playwright's
+ * test-location attribution stays untouched (a collection-time wrapper would
+ * become every test's reported call site, breaking the merge's file-based
+ * matching) and so the plan can be matched against `testInfo.file`/`title`
+ * exactly instead of via stack inspection.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlanIndex = buildPlanIndex;
+exports.shouldRunDuringHealRerun = shouldRunDuringHealRerun;
+exports.expandTargetsWithSerialCompanions = expandTargetsWithSerialCompanions;
+exports.resetHealRerunPlanCacheForTesting = resetHealRerunPlanCacheForTesting;
+exports.maybeSkipForHealRerun = maybeSkipForHealRerun;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const envVars_1 = require("../../envVars");
+const model_1 = require("../../reporter/model");
+const Logger_1 = require("../../utils/Logger");
+function buildPlanIndex(plan) {
+    const index = new Map();
+    for (const target of plan.targets ?? []) {
+        if (!target?.file || !target?.title) {
+            continue;
+        }
+        const file = path_1.default.resolve(target.file);
+        if (!index.has(file)) {
+            index.set(file, new Set());
+        }
+        index.get(file).add(target.title);
+    }
+    return index;
+}
+/**
+ * Pure decision: should the test in `file` with `title` actually execute
+ * during the heal rerun? The plan is fully explicit — serial companions were
+ * already expanded into it by the orchestrator.
+ */
+function shouldRunDuringHealRerun(params) {
+    const titles = params.index.get(path_1.default.resolve(params.file));
+    return titles?.has(params.title) ?? false;
+}
+/**
+ * Expand heal targets with their `describe.serial` siblings, using the
+ * `serialScoped` flags the Donobu reporter recorded in the initial run's
+ * report. Companions live in the same file as their target by construction
+ * (serial scopes are intra-file), so they inherit the target's absolute file
+ * path; report file paths are rootDir-relative, hence the suffix match.
+ *
+ * Degrades to the unexpanded targets when the report (or the flags) are
+ * unavailable — serial chains then surface as honest not-reattempted
+ * failures instead of healing.
+ */
+function expandTargetsWithSerialCompanions(targets, initialReport) {
+    const suites = (initialReport?.suites ?? []);
+    const expanded = [...targets];
+    const seen = new Set(targets.map((t) => `${path_1.default.resolve(t.file)}::${t.projectName}::${t.title}`));
+    for (const target of targets) {
+        if (!target.file || !target.title) {
+            continue;
+        }
+        const targetFile = path_1.default.resolve(target.file);
+        for (const suite of suites) {
+            const suiteFile = String(suite.file ?? '');
+            if (!targetFile.endsWith(path_1.default.normalize(suiteFile)) ||
+                suiteFile.length === 0) {
+                continue;
+            }
+            const specs = suite.specs ?? [];
+            const targetEntry = specs
+                .find((spec) => spec.title === target.title)
+                ?.tests?.find((test) => !target.projectName || test.projectName === target.projectName);
+            if (!targetEntry?.serialScoped) {
+                continue;
+            }
+            // The target is serial-scoped: every serial-scoped test in this file
+            // (same project) joins the plan. Bounded by the file, mirroring how
+            // Playwright re-runs whole serial groups on retry.
+            for (const spec of specs) {
+                for (const test of spec.tests ?? []) {
+                    if (!test.serialScoped) {
+                        continue;
+                    }
+                    if (target.projectName && test.projectName !== target.projectName) {
+                        continue;
+                    }
+                    const key = `${targetFile}::${test.projectName}::${spec.title}`;
+                    if (seen.has(key)) {
+                        continue;
+                    }
+                    seen.add(key);
+                    expanded.push({
+                        file: target.file,
+                        title: spec.title,
+                        projectName: test.projectName,
+                    });
+                }
+            }
+        }
+    }
+    return expanded;
+}
+let cachedPlanIndex;
+function getPlanIndex(planPathOverride) {
+    if (planPathOverride === undefined && cachedPlanIndex !== undefined) {
+        return cachedPlanIndex;
+    }
+    const planPath = planPathOverride ?? envVars_1.env.data.DONOBU_AUTO_HEAL_PLAN_PATH;
+    let index = null;
+    if (planPath) {
+        try {
+            const raw = fs_1.default.readFileSync(planPath, 'utf8');
+            index = buildPlanIndex(JSON.parse(raw));
+        }
+        catch (error) {
+            Logger_1.appLogger.warn(`Auto-heal rerun plan at ${planPath} could not be read; running all collected tests.`, error);
+            index = null;
+        }
+    }
+    if (planPathOverride === undefined) {
+        cachedPlanIndex = index;
+    }
+    return index;
+}
+/** Test-only: reset the memoized plan so each test can load its own. */
+function resetHealRerunPlanCacheForTesting() {
+    cachedPlanIndex = undefined;
+}
+/**
+ * Called from the Donobu auto fixture before any browser fixture initializes.
+ * Outside heal reruns this is a no-op. During a rerun, tests outside the plan
+ * are annotated and skipped on the spot — no context, no page, no cost.
+ */
+function maybeSkipForHealRerun(testInfo, options) {
+    const index = getPlanIndex(options?.planPath);
+    if (!index) {
+        return;
+    }
+    const shouldRun = shouldRunDuringHealRerun({
+        index,
+        file: testInfo.file,
+        title: testInfo.title,
+    });
+    if (shouldRun) {
+        return;
+    }
+    testInfo.annotations.push({
+        type: model_1.HEAL_SKIP_REPLAY_ANNOTATION_TYPE,
+        description: 'Not part of the auto-heal rerun plan; the initial run result stands.',
+    });
+    testInfo.skip(true, 'Not part of the auto-heal rerun plan; the initial run result stands.');
+}
+//# sourceMappingURL=healRerunGate.js.map

package/dist/lib/test/testExtension.d.ts

@@ -5,6 +5,7 @@ import { FlowLogBuffer } from '../../utils/FlowLogBuffer';
 import type { DonobuExtendedPage } from '../page/DonobuExtendedPage';
 export * from '@playwright/test';
 export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    healRerunGate: void;
     flowLoggingContext: {
         flowId: string;
         logBuffer: FlowLogBuffer;

package/dist/lib/test/testExtension.js

@@ -41,6 +41,7 @@ const PageLogListeners_1 = require("../../utils/PageLogListeners");
 const cacheLocator_1 = require("../ai/cache/cacheLocator");
 const extendPage_1 = require("../page/extendPage");
 const tbd_1 = require("../page/tbd");
+const healRerunGate_1 = require("./healRerunGate");
 const selfHealing_1 = require("./utils/selfHealing");
 const triageTestFailure_1 = require("./utils/triageTestFailure");
 __exportStar(require("@playwright/test"), exports);
@@ -220,6 +221,20 @@ function persistVideoIfApplicable(page, testInfo, videoOption) {
  */
 const UPLOAD_DRAIN_TIMEOUT_MS = 30_000;
 exports.test = test_1.test.extend({
+    /**
+     * Auto-heal rerun gate. First in registration order so it runs before every
+     * other test-scoped fixture: during a heal rerun, tests outside the rerun
+     * plan skip here — before a browser context or page is ever created — with
+     * the `donobu-heal-skip-replay` annotation the merge step uses to drop
+     * their entries. A no-op outside heal reruns.
+     */
+    healRerunGate: [
+        async ({}, use, testInfo) => {
+            (0, healRerunGate_1.maybeSkipForHealRerun)(testInfo);
+            await use();
+        },
+        { scope: 'test', auto: true },
+    ],
     /**
      * Establish a logging scope for the entire Playwright test *before* any other
      * fixtures run. Playwright builds the fixture dependency graph eagerly, so
@@ -400,6 +415,7 @@ exports.test = test_1.test.extend({
             flowId: flowId,
             visualCueDurationMs: visualCueDurationMs,
             cacheFilepath: (0, cacheLocator_1.buildPageAiCachePath)(testInfo.file),
+            specFilePath: testInfo.file,
             envVars: (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(overallObjective, testInfo.annotations
                 .filter((a) => a.type === 'ENV' && a.description)
                 .map((a) => a.description)),
@@ -1051,16 +1067,10 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
             }
         }
     }
-    else if (testInfo.status === 'passed' &&
-        MiscUtils_1.MiscUtils.yn(envVars_1.env.data.DONOBU_AUTO_HEAL_ACTIVE)) {
-        const hasSelfHealedAnnotation = testInfo.annotations.some((annotation) => annotation.type === 'self-healed');
-        if (!hasSelfHealedAnnotation) {
-            testInfo.annotations.push({
-                type: 'self-healed',
-                description: 'Automatically healed by Donobu auto-heal rerun.',
-            });
-        }
-    }
+    // Note: passing tests in an auto-heal rerun are NOT annotated here. Whether
+    // a test was actually healed (failed initially, passed on the rerun) is
+    // decided by the merge step, which sees both runs — annotating every rerun
+    // pass would mislabel dependency tests that never failed.
     // Flush any page.tbd() sessions: replace the tbd() call sites in the
     // source files with the generated Playwright code for the recorded
     // user interactions.

package/dist/reporter/buildReport.js

@@ -58,6 +58,14 @@ function buildDonobuReport(resultsByTest, rootDir) {
                     // Signal "skipped" tests to the renderers the same way the JSON
                     // reporter does.
                     status: test.expectedStatus === 'skipped' ? 'skipped' : undefined,
+                    // Consumed by `reportWalk.statusOf` to classify `test.fail()`
+                    // specs as expected failures rather than real ones; absent from
+                    // the legacy state-file shape.
+                    expectedStatus: test.expectedStatus,
+                    // Whether the test sits inside a `describe.serial` scope — declared
+                    // intra-file ordering. The auto-heal orchestrator uses this to
+                    // include a heal target's serial siblings in the rerun plan.
+                    serialScoped: isSerialScoped(test),
                     results: results.map((r) => ({
                         status: r.status,
                         duration: r.duration,
@@ -110,6 +118,30 @@ function buildDonobuReport(resultsByTest, rootDir) {
     }
     return { suites, metadata: {} };
 }
+/**
+ * Whether any enclosing suite is in serial mode (`test.describe.serial` or
+ * `test.describe.configure({ mode: 'serial' })`).
+ *
+ * Reads the runner-side suite internals (`_parallelMode`) — reporters receive
+ * the runner's own Suite instances, which carry it. Verified against
+ * @playwright/test 1.58; guarded so shape drift degrades to `false` (serial
+ * chains then lose heal eligibility, but reporting stays honest).
+ */
+function isSerialScoped(test) {
+    try {
+        let suite = test.parent;
+        while (suite) {
+            if (suite._parallelMode === 'serial') {
+                return true;
+            }
+            suite = suite.parent;
+        }
+    }
+    catch {
+        // Internal shape drifted — treat as non-serial.
+    }
+    return false;
+}
 /** Walk up the suite chain to find the enclosing project suite's title. */
 function getProjectName(test) {
     let suite = test.parent;