sela-core 0.1.0-alpha.1

package/dist/engine/SelaEngine.js

@@ -0,0 +1,1146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SelaEngine = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const LLMService_1 = require("../services/LLMService");
+const WorkspaceSnapshotService_1 = require("../services/WorkspaceSnapshotService");
+const IsolatedDiff_1 = require("../utils/IsolatedDiff");
+const logger_1 = require("../utils/logger");
+const SnapshotService_1 = require("../services/SnapshotService");
+const DOMUtils_1 = require("../utils/DOMUtils");
+const FileLock_1 = require("../utils/FileLock");
+const SourceUpdater_1 = require("../services/SourceUpdater");
+const ASTSourceUpdater_1 = require("../services/ASTSourceUpdater");
+const SafetyGuard_1 = require("../services/SafetyGuard");
+const HealingCacheService_1 = require("../services/HealingCacheService");
+const ConfigLoader_1 = require("../config/ConfigLoader");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const HealBudget_1 = require("../services/HealBudget");
+const HealReportService_1 = require("../services/HealReportService");
+const PRAutomationService_1 = require("../services/PRAutomationService");
+const PendingPromptLedger_1 = require("../services/PendingPromptLedger");
+const SelaError_1 = require("../errors/SelaError");
+const SelectorSanitizer_1 = require("../services/SelectorSanitizer");
+/**
+ * Graceful percentage formatter for engine-side log lines. Mirrors the helper
+ * in PRAutomationService / HealReportService so a missing AI/auditor
+ * confidence reads as "n/a" instead of "undefined%" or "0%".
+ */
+function fmtPctEngine(v) {
+    return typeof v === "number" && Number.isFinite(v) ? `${v}%` : "n/a";
+}
+/** Convert an `internal:*` selector to idiomatic Playwright API notation for terminal display. */
+function fmtSelector(sel) {
+    return (0, SelectorSanitizer_1.internalToMethodExpression)(sel, "page") ?? sel;
+}
+const EMPTY_DNA_SUMMARY = {
+    tagName: "unknown",
+    text: null,
+    role: null,
+    classes: [],
+    attributes: {},
+    ancestry: [],
+    closestLabel: null,
+    rowAnchor: null,
+    isGhost: false,
+    ghostReason: null,
+    isOccluded: false,
+    isInShadowDom: false,
+};
+/**
+ * Truthy when the current process is a CI runner. We accept the standard
+ * `CI=1`/`CI=true` convention used by GitHub Actions, GitLab, CircleCI,
+ * Buildkite, etc. Anything else (empty string, undefined, `0`, `false`)
+ * is treated as Local DX mode.
+ */
+function isCiEnvironment() {
+    const raw = process.env.CI;
+    if (raw === undefined || raw === null)
+        return false;
+    const v = String(raw).trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+class SelaEngine {
+    llmService;
+    snapshotService;
+    safetyGuard;
+    astDirectiveScanner;
+    healingCache;
+    config;
+    dnaBuffer = new Map();
+    healMetaBuffer = new Map();
+    testTitleBuffer = new Map();
+    constructor() {
+        this.config = ConfigLoader_1.ConfigLoader.getInstance();
+        // Seed the per-run heal budget (T2). null => unlimited.
+        HealBudget_1.sharedHealBudget.configure(this.config.maxHealsPerRun);
+        this.llmService = new LLMService_1.LLMService();
+        this.snapshotService = new SnapshotService_1.SnapshotService();
+        this.safetyGuard = new SafetyGuard_1.SafetyGuard(this.config.thresholds);
+        // Dedicated lightweight ts-morph project used only for the leading-comment
+        // pre-scan. Keeping it separate from the SourceUpdater's project avoids
+        // polluting that cache with files we may never actually mutate.
+        this.astDirectiveScanner = new ASTSourceUpdater_1.ASTSourceUpdater();
+        // Local healing cache - short-circuits the LLM call when an identical
+        // (filePath, oldSelector) pair was healed safely in a prior session.
+        // Disabled when SELA_NO_CACHE=1; reads/writes skipped during dry runs.
+        this.healingCache = HealingCacheService_1.sharedHealingCache;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // healArgument - repairs a wrong action argument (e.g. selectOption)
+    // ─────────────────────────────────────────────────────────────
+    async healArgument(page, selector, action, oldArgument, stableId, filePath, line) {
+        logger_1.logger.stage("HEALING", `argument for '${action}': "${oldArgument}"`);
+        try {
+            const { dom } = await DOMUtils_1.DOMUtils.getNeighborhoodDom(page, selector);
+            const neighborhoodDom = dom;
+            const targetIntent = action === "selectOption"
+                ? `ARGUMENT_HEALING: The selectOption argument "${oldArgument}" does not exist.
+Look at the <select> element in the DOM and find all <option> elements inside it.
+Return in 'new_selector' ONLY the TEXT CONTENT of the closest matching <option>.
+For example: if the options are "Male" and "Female" and the old argument was "Man", return "Male".
+CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only, exactly as it appears in the option.`
+                : `Fix the broken argument "${oldArgument}" for action "${action}". Return the correct value.`;
+            // Max-heals budget gate (T2): argument heals are LLM-backed too.
+            if (!HealBudget_1.sharedHealBudget.tryConsume()) {
+                if (HealBudget_1.sharedHealBudget.shouldWarnOnce()) {
+                    logger_1.logger.warn(`maxHealsPerRun limit (${HealBudget_1.sharedHealBudget.limit()}) reached — ` +
+                        `halting new LLM heals. Already-applied fixes are preserved.`);
+                }
+                return null;
+            }
+            const aiFix = await this.llmService.getFix({
+                targetIntent,
+                failedSelector: `${selector}::${action}("${oldArgument}")`,
+                previousState: {},
+                currentDom: neighborhoodDom,
+            });
+            if (aiFix?.status === "FIXED" && aiFix.new_selector) {
+                const newArgument = aiFix.new_selector;
+                logger_1.logger.debug(`New argument: "${newArgument}"`);
+                SourceUpdater_1.SourceUpdater.updateArgument({ filePath, line }, action, oldArgument, newArgument);
+                return newArgument;
+            }
+        }
+        catch (error) {
+            logger_1.logger.error("Argument healing failed", error?.message);
+        }
+        return null;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // heal - repairs a broken selector
+    // ─────────────────────────────────────────────────────────────
+    async heal(page, fullSelector, elementSelectorOnly, stableId, filePath, line, healMode = "action") {
+        logger_1.logger.stage("HEALING", stableId);
+        // Resolve file path for report purposes (project-relative when possible).
+        const reportFile = this._toReportFile(filePath);
+        const testTitle = this.testTitleBuffer.get(stableId);
+        // ── Developer fail-fast directive pre-gate ──────────────────────
+        // Scan the failing statement's leading comments for `// sela-fail-fast`
+        // BEFORE the expensive LLM round-trip. When present, record a
+        // "Skipped by Developer" FailedEvent and propagate the canonical
+        // SelaError(AST_HEAL_DISABLED_BY_DIRECTIVE) so retries are skipped too.
+        try {
+            this.astDirectiveScanner.enforceFailFastDirective({ filePath, line });
+        }
+        catch (directiveErr) {
+            if ((0, SelaError_1.isSelaErrorFrom)(directiveErr, "ASTUpdater") &&
+                directiveErr.code === SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE) {
+                logger_1.logger.warn(`Skipped by Developer - ${directiveErr.reason}`);
+                const skipEvent = {
+                    kind: "FAILED",
+                    stableId,
+                    sourceFile: reportFile,
+                    sourceLine: line,
+                    testTitle,
+                    timestamp: new Date().toISOString(),
+                    framePath: [],
+                    inIframe: false,
+                    inShadowDom: false,
+                    oldSelector: elementSelectorOnly,
+                    reason: "Skipped by Developer (sela-fail-fast directive)",
+                    dnaBefore: null,
+                };
+                HealReportService_1.sharedHealReport.record(skipEvent);
+                throw directiveErr;
+            }
+            throw directiveErr;
+        }
+        // Snapshot for report event context (loaded once below, used at all exit paths).
+        let lastKnownStateForReport = null;
+        let aiFixForReport = null;
+        try {
+            // load() now always returns ElementSnapshotV2 (v1 snapshots are
+            // migrated transparently; v2 fields default to safe values).
+            const lastKnownState = await this.snapshotService.load(stableId);
+            lastKnownStateForReport = lastKnownState;
+            // ── Extract v2 DNA context ────────────────────────────────
+            const dnaAncestry = lastKnownState?.ancestry ?? [];
+            const dnaAnchors = lastKnownState?.anchors;
+            logger_1.logger.debug("Step 2: extracting neighborhood DOM...");
+            const { dom: neighborhoodDom, successfulPath } = await DOMUtils_1.DOMUtils.getNeighborhoodDom(page, fullSelector);
+            if (!neighborhoodDom || neighborhoodDom.length === 0) {
+                throw new Error("Failed to extract any DOM context for AI");
+            }
+            logger_1.logger.debug(`Step 2: DOM extracted (${neighborhoodDom.length} chars)`);
+            const contextHint = successfulPath.length > 0
+                ? `\n\n[CONTEXT HINT]: The provided DOM is extracted from INSIDE this frame path: "${successfulPath.join(" >> ")}". ` +
+                    `If you find the element, your suggested selector should be relative to THIS context.`
+                : "";
+            const oldText = lastKnownState?.text ?? null;
+            const dnaRole = lastKnownState?.role ?? undefined;
+            const intentDescription = lastKnownState
+                ? `The element that was a ${lastKnownState.tagName} with text "${lastKnownState.text}"`
+                : `Element identified by ${stableId}`;
+            const contentChangeInstructions = `
+
+[CONTENT CHANGE DETECTION]:
+If the element's VISIBLE TEXT has changed compared to its previous value${oldText ? ` ("${oldText}")` : ""}, you MUST include a "contentChange" field.
+NOTE: This change will NOT be applied automatically to the source code to prevent masking potential bugs.
+It will only be presented as a suggested fix in the terminal.
+{
+  "contentChange": {
+    "oldText": "<the previous visible text>",
+    "newText": "<the new visible text as it appears in the current DOM>"
+  }
+}
+This is required so that any expect(...).toHaveText("${oldText ?? "..."}") assertions in the test file can be automatically updated to match the new text.
+If the text has NOT changed, omit the "contentChange" field entirely.`;
+            // ── Semantic anchor context hint for the LLM ─────────────────────
+            // When DNA v2 anchor data exists, tell the AI which label and row
+            // key the element was associated with so it can use semantic landmarks
+            // to disambiguate identical controls (e.g. multiple "Edit" buttons).
+            const anchorContextHint = (() => {
+                const anchors = lastKnownState?.anchors;
+                if (!anchors)
+                    return "";
+                const lines = [];
+                if (anchors.closestLabel) {
+                    lines.push(`- Label: "${anchors.closestLabel}" - the UI label or heading associated with this element.`);
+                }
+                if (anchors.rowAnchor) {
+                    lines.push(`- Row key: "${anchors.rowAnchor}" - unique cell text identifying the table row this element belonged to.`);
+                }
+                if (lines.length === 0)
+                    return "";
+                return ("\n\n[ELEMENT SEMANTIC CONTEXT]:\n" +
+                    "The DNA snapshot recorded these semantic landmarks for the element you must find:\n" +
+                    lines.join("\n") +
+                    "\n" +
+                    "Prioritize selectors that preserve these relationships (e.g. filter by row key, then target by label).");
+            })();
+            // ── Cache pre-check ────────────────────────────────────────────
+            // When a prior session healed this exact (filePath, oldSelector)
+            // pair AND SafetyGuard cleared it, replay the cached fix instead
+            // of paying the LLM round-trip. Disabled when SELA_NO_CACHE=1.
+            // The synthetic aiFix is fed through SafetyGuard exactly like a
+            // fresh LLM response - cache is a latency optimisation, never a
+            // safety bypass.
+            let aiFix = null;
+            let cacheHit = false;
+            // Fingerprint inputs the cache key depends on. Recomputed every
+            // heal so a DNA rewrite - which changes `dnaContentHash` -
+            // automatically invalidates every prior entry without an explicit
+            // purge.
+            const dnaContentHash = (0, HealingCacheService_1.hashDnaContent)(lastKnownState ?? null);
+            const cacheKeyInput = {
+                filePath,
+                line,
+                dnaContentHash,
+                brokenSelector: fullSelector,
+                mode: healMode,
+            };
+            if (!this.config.noCache) {
+                const cached = this.healingCache.get(cacheKeyInput);
+                if (cached) {
+                    logger_1.logger.debug(`Cache hit (0ms LLM) - replaying healed selector "${cached.healedSelector}"`);
+                    aiFix = {
+                        status: "FIXED",
+                        new_selector: cached.healedSelector,
+                        chainSegments: cached.chainSegments,
+                        segments: cached.segments ?? [
+                            { type: "element", selector: cached.healedSelector },
+                        ],
+                        confidence: cached.confidence,
+                        contentChange: cached.contentChange,
+                        explanation: cached.explanation ?? "Replayed from local healing cache",
+                    };
+                    cacheHit = true;
+                }
+            }
+            if (!cacheHit) {
+                // ── Max-heals budget gate (T2) ───────────────────────────────
+                // Reserve a slot BEFORE the await (synchronous check-and-reserve).
+                // Cache hits skip this branch entirely, so replays never count.
+                if (!HealBudget_1.sharedHealBudget.tryConsume()) {
+                    if (HealBudget_1.sharedHealBudget.shouldWarnOnce()) {
+                        logger_1.logger.warn(`maxHealsPerRun limit (${HealBudget_1.sharedHealBudget.limit()}) reached — ` +
+                            `halting new LLM heals. Already-applied fixes are preserved.`);
+                    }
+                    // Surfaced as a FAILED event by the catch block below.
+                    throw new Error("maxHealsPerRun reached");
+                }
+                logger_1.logger.debug("Step 3: requesting AI fix from LLM...");
+                aiFix = await this.llmService.getFix({
+                    targetIntent: intentDescription,
+                    failedSelector: fullSelector,
+                    previousState: lastKnownState || {},
+                    currentDom: neighborhoodDom +
+                        contextHint +
+                        anchorContextHint +
+                        contentChangeInstructions,
+                });
+            }
+            aiFixForReport = aiFix;
+            if (aiFix && aiFix.status === "FIXED") {
+                logger_1.logger.debug("Step 3: AI responded");
+                // ── Build new selector ────────────────────────────────────
+                const aiSegments = aiFix.segments || [];
+                const newSegmentsFromAI = aiSegments.filter((aiSeg) => !successfulPath.includes(aiSeg.selector));
+                const newFullSelector = [
+                    ...successfulPath,
+                    ...newSegmentsFromAI.map((s) => s.selector),
+                ].join(" >> ");
+                const rawElementSelector = newSegmentsFromAI.map((s) => s.selector).join(" >> ") ||
+                    newFullSelector;
+                const framePrefix = successfulPath.join(" >> ");
+                const elementOnlySelector = framePrefix && rawElementSelector.startsWith(framePrefix + " >> ")
+                    ? rawElementSelector.slice(framePrefix.length + 4)
+                    : rawElementSelector;
+                // ── Step 3.5: Fetch live text (lightweight zero-trust probe) ─
+                const liveText = await this.fetchLiveText(page, elementOnlySelector, successfulPath);
+                const dnaBaselineText = oldText ?? undefined;
+                if (liveText !== null) {
+                    logger_1.logger.debug(`Step 3.5: live text fetched: "${liveText}"` +
+                        (dnaBaselineText ? ` (DNA baseline: "${dnaBaselineText}")` : ""));
+                }
+                else {
+                    logger_1.logger.debug("Step 3.5: live text fetch skipped (element not yet rendered or non-text)");
+                }
+                // ── Step 3.6: Atomic v2 capture of the candidate element ──
+                // Single page.evaluate() call - collects visibility, ancestry,
+                // and anchors of the healed element for SafetyGuard use.
+                // Returns null on any failure; never blocks the heal.
+                const liveSnapshot = await this.snapshotService.captureElement(page, elementOnlySelector, successfulPath);
+                const liveVisibility = liveSnapshot?.visibility;
+                const liveAncestry = liveSnapshot?.ancestry;
+                const liveAnchors = liveSnapshot?.anchors;
+                if (liveSnapshot) {
+                    const ghostFlag = liveVisibility?.isGhost
+                        ? ` 👻 GHOST(${liveVisibility.ghostReason})`
+                        : "";
+                    const occFlag = liveVisibility?.isOccluded ? " 🫥 OCCLUDED" : "";
+                    logger_1.logger.debug(`Step 3.6: live v2 capture complete` +
+                        `${ghostFlag}${occFlag} - ancestry depth: ${liveAncestry?.length ?? 0}`);
+                }
+                else {
+                    logger_1.logger.debug("Step 3.6: live v2 capture skipped");
+                }
+                // ── Safety: delegate all go/no-go decisions to SafetyGuard ─
+                const branch = ConfigLoader_1.ConfigLoader.getBranch() ?? undefined;
+                const safetyDecision = await this.safetyGuard.evaluate({ mode: healMode, branch }, {
+                    confidence: aiFix.confidence,
+                    contentChange: aiFix.contentChange,
+                    explanation: aiFix.explanation,
+                    liveText: liveText ?? undefined,
+                    dnaBaselineText,
+                    dnaRole,
+                    // v2 structural context
+                    liveVisibility,
+                    liveAncestry,
+                    liveAnchors,
+                    dnaAncestry,
+                    dnaAnchors,
+                });
+                // Three-way action (decision #1, quarantine):
+                //   APPLY  → write + use the heal (fall through to the write path)
+                //   HOLD   → propose but DO NOT write or execute this run
+                //   REJECT → refuse outright
+                const disposition = safetyDecision.disposition ?? (0, SafetyGuard_1.dispositionFor)(safetyDecision.level);
+                logger_1.logger.debug(`SafetyGuard [${safetyDecision.level}] (${disposition}) ${safetyDecision.reason}`);
+                if (disposition !== "APPLY") {
+                    if (safetyDecision.level === "BLOCKED" &&
+                        safetyDecision.meta?.auditorVerdict === "SUSPICIOUS") {
+                        const strictness = this.config.thresholds.auditorStrictness;
+                        const conf = safetyDecision.meta.auditorConfidence ?? "?";
+                        const suggestion = strictness === "strict" ? "Balanced" : "Loose";
+                        logger_1.logger.warn(`Auditor status: SUSPICIOUS (Confidence: ${conf}%)`);
+                        logger_1.logger.warn(`Policy: '${strictness}' (Branch: ${branch ?? "unknown"}). Auto-fix blocked.`);
+                        logger_1.logger.info(`To allow this, change 'auditorStrictness' to '${suggestion}' in sela.config.ts.`);
+                    }
+                    if (disposition === "HOLD") {
+                        logger_1.logger.warn(`Heal QUARANTINED (${safetyDecision.level}) - proposed but NOT ` +
+                            `written to source and NOT executed this run. Approve to apply. ` +
+                            `Candidate: ${fmtSelector(newFullSelector)}`);
+                    }
+                    // ── Report: PROTECTED ───────────────────────────────────────
+                    // REJECT → the auto-fix was blocked (FAIL_HARD / BLOCKED). If the
+                    //   auditor verdict is INCONSISTENT this is a "Security Win" - a
+                    //   masked regression was caught.
+                    // HOLD   → the heal is quarantined for review; recorded with
+                    //   safetyLevel REQUIRES_REVIEW so the report can render it as an
+                    //   amber proposal, distinct from a red block.
+                    // In neither case is source written or the candidate executed.
+                    const protectedEvent = {
+                        kind: "PROTECTED",
+                        stableId,
+                        sourceFile: reportFile,
+                        sourceLine: line,
+                        testTitle,
+                        timestamp: new Date().toISOString(),
+                        framePath: successfulPath,
+                        inIframe: successfulPath.length > 0,
+                        inShadowDom: liveSnapshot?.isInShadowDom ?? false,
+                        oldSelector: elementSelectorOnly,
+                        candidateNewSelector: newFullSelector,
+                        reason: safetyDecision.reason,
+                        safetyLevel: safetyDecision.level,
+                        auditor: this._auditorBlockFromDecision(safetyDecision.meta),
+                        aiConfidence: aiFix.confidence,
+                        aiExplanation: aiFix.explanation ?? "",
+                        dnaBefore: (0, HealReportService_1.summariseSnapshot)(lastKnownState),
+                        dnaAfter: (0, HealReportService_1.summariseSnapshot)(liveSnapshot ?? null),
+                        contentChange: aiFix.contentChange,
+                    };
+                    HealReportService_1.sharedHealReport.record(protectedEvent);
+                    const rejectionCode = disposition === "HOLD"
+                        ? (safetyDecision.code ?? SelaError_1.SAFETY_GUARD_CODES.HELD_FOR_REVIEW)
+                        : (safetyDecision.code ?? SelaError_1.SAFETY_GUARD_CODES.GENERIC_REJECTION);
+                    throw new SelaError_1.SelaError({
+                        subsystem: "SafetyGuard",
+                        code: rejectionCode,
+                        reason: safetyDecision.reason,
+                        context: {
+                            filePath: reportFile,
+                            line,
+                            selector: elementSelectorOnly,
+                            healedSelector: newFullSelector,
+                            stableId,
+                            testTitle,
+                            branch,
+                            safetyLevel: safetyDecision.level,
+                            auditorVerdict: safetyDecision.meta?.auditorVerdict,
+                            auditorConfidence: safetyDecision.meta?.auditorConfidence,
+                            aiConfidence: aiFix.confidence,
+                        },
+                    });
+                }
+                // ── Heal-completion score summary ─────────────────────────────────
+                // Emits a single consolidated line showing AI confidence plus the
+                // auditor's structural adjustments (ancestry drift / anchor bonus).
+                const breakdown = safetyDecision.meta?.auditScoreBreakdown;
+                if (breakdown && (breakdown.penalty !== 0 || breakdown.bonus !== 0)) {
+                    const parts = [];
+                    if (breakdown.penalty !== 0)
+                        parts.push(`${breakdown.penalty} ancestry drift`);
+                    if (breakdown.bonus !== 0)
+                        parts.push(`+${breakdown.bonus} anchor match`);
+                    logger_1.logger.debug(`Score - AI: ${fmtPctEngine(aiFix.confidence)} | ` +
+                        `Auditor: ${fmtPctEngine(breakdown.adjustedConfidence)} ` +
+                        `(raw ${fmtPctEngine(breakdown.rawConfidence)}, ${parts.join(", ")})`);
+                }
+                logger_1.logger.debug(`Rebuilt full runtime selector: ${newFullSelector}`);
+                // ── PRIMARY: composeHeal trace-back pipeline (Stages 1-4) ──────────
+                // Trace the failing call-site to its source declaration and apply a
+                // write-disciplined Method-Shift / in-place mutation through the
+                // type-safety gate. Restricted to plain in-place writes (commentOnly /
+                // branch / autoCommit / dry-run keep the legacy git-aware path).
+                // Falls back to the legacy regex/semantic engine on ABORT / PROMPT.
+                let updateResult;
+                const plainInPlace = (!this.config.updateStrategy ||
+                    this.config.updateStrategy === "inPlace") &&
+                    !this.config.autoCommit;
+                const resolvedForCompose = SourceUpdater_1.SourceUpdater.resolveFilePath(filePath);
+                if (plainInPlace && !DryRunGuard_1.DryRunGuard.active() && resolvedForCompose) {
+                    try {
+                        WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(resolvedForCompose);
+                        const composed = ASTSourceUpdater_1.ASTSourceUpdater.composeHeal({
+                            filePath: resolvedForCompose,
+                            line,
+                            newSelector: newFullSelector,
+                            apply: true,
+                            applyOptions: { respectDryRun: true },
+                        });
+                        const strat = composed.decision?.strategy;
+                        if (composed.kind === "decision" &&
+                            composed.outcome?.status === "applied" &&
+                            (strat === "MUTATE_IN_PLACE" || strat === "FORK_AT_TEST")) {
+                            WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(resolvedForCompose);
+                            const wl = composed.writtenLine ?? line;
+                            logger_1.logger.stage("ANALYZING AST", `composeHeal primary path (${strat})`);
+                            updateResult = {
+                                success: true,
+                                reason: `composeHeal[${strat}]: ${composed.decision.reason}`,
+                                lineUpdated: wl - 1,
+                                healedLocatorString: newFullSelector,
+                                definitionSite: { file: resolvedForCompose, line: wl - 1 },
+                                blastRadius: composed.decision.blastRadius,
+                            };
+                        }
+                        else {
+                            const why = composed.kind === "abort"
+                                ? `abort:${composed.trace.code ?? composed.trace.status}`
+                                : `${strat ?? "no-decision"}/${composed.outcome?.status ?? "not-applied"}`;
+                            logger_1.logger.debug(`composeHeal declined (${why}) - falling back to legacy heal`);
+                        }
+                    }
+                    catch (e) {
+                        logger_1.logger.debug(`composeHeal primary failed (${e?.message}) - falling back to legacy heal`);
+                    }
+                }
+                // ── FALLBACK: legacy regex/semantic heal (also handles dry-run /
+                //    commentOnly / branch / autoCommit / cross-file). ──────────────
+                if (!updateResult) {
+                    updateResult = SourceUpdater_1.SourceUpdater.update({ filePath, line }, elementSelectorOnly, newFullSelector, neighborhoodDom, undefined, fullSelector, aiFix.segments, aiFix.contentChange, aiFix.chainSegments, aiFix.originalChainHint, this.config.updateStrategy, this.config.autoCommit);
+                }
+                // Resolve the line that was actually mutated. Order of precedence:
+                //   1. updateResult.lineUpdated  (the strategy's literal write location)
+                //   2. updateResult.definitionSite.line  (semantic JumpToDef target,
+                //      used when the mutation crossed into a const/variable declaration)
+                //   3. line  (the original failure line - last-resort fallback)
+                // For cross-file definitionSite.file, we still read the new line from
+                // the SAME file that was mutated.
+                const defSite = updateResult.definitionSite;
+                const sameFileDef = defSite && defSite.file
+                    ? path.resolve(defSite.file) ===
+                        (SourceUpdater_1.SourceUpdater.resolveFilePath(filePath) ?? "")
+                    : true;
+                const writtenLine = updateResult.lineUpdated ??
+                    (sameFileDef ? defSite?.line : undefined) ??
+                    line;
+                const mutatedFilePath = !sameFileDef && defSite ? defSite.file : filePath;
+                // Clean-Room isolated diff. We diff the in-memory snapshot recorded
+                // by WorkspaceSnapshotService (contentBefore - disk state right
+                // before Sela's first write to this file) against the post-write
+                // disk state. The result contains EXCLUSIVELY Sela's selector swap;
+                // any developer dirty edits sit identically in both buffers and
+                // therefore cancel out. Falls back to "" when the snapshot is
+                // missing (cross-file healing into an untracked path, etc.).
+                const gitUnifiedDiff = this._captureIsolatedDiff(mutatedFilePath);
+                const firstChange = this._extractFirstChangeFromDiff(gitUnifiedDiff);
+                // Backward-compat: keep oldCodeLine/newCodeLine populated from the
+                // first -/+ pair inside the diff. When git produced no diff (file
+                // untracked, git unavailable, …) fall back to a direct disk read of
+                // the mutated line - strictly inferior but preserves old reports.
+                const oldCodeLine = firstChange.oldLine ??
+                    this._safeReadLine(mutatedFilePath, writtenLine);
+                const newCodeLine = firstChange.newLine ??
+                    this._safeReadLine(mutatedFilePath, writtenLine);
+                const canonicalSelector = updateResult.healedLocatorString ?? newFullSelector;
+                logger_1.logger.debug(`Canonical selector (disk == runtime): "${canonicalSelector}"`);
+                // Buffer CLI-ready metadata - merged into DNA at commitUpdates() time.
+                // Sanitize filePath: strip any residual "at " stack-trace prefix + whitespace,
+                // then resolve to an absolute path before converting to project-relative form.
+                const match = filePath.match(/at\s+(.*)/i);
+                // 2. אם מצאנו התאמה ניקח אותה, אחרת ניקח את המחרוזת המקורית.
+                // בנוסף, ננקה רווחים וסוגריים (לפעמים נתיבים ב-Stack trace מוקפים בסוגריים).
+                const cleanFilePath = (match ? match[1] : filePath)
+                    .replace(/^\(|\)$/g, "") // מסיר סוגריים אם קיימים ( )
+                    .trim();
+                // 3. הפיכה לנתיב אבסולוטי ואז ליחסי (כמו שעשית, שזה מעולה)
+                const absFilePath = cleanFilePath && path.isAbsolute(cleanFilePath)
+                    ? cleanFilePath
+                    : cleanFilePath
+                        ? path.resolve(process.cwd(), cleanFilePath)
+                        : "";
+                const relativeSourceFile = absFilePath
+                    ? path.relative(process.cwd(), absFilePath)
+                    : "";
+                this.healMetaBuffer.set(stableId, {
+                    selector: canonicalSelector,
+                    sourceFile: relativeSourceFile,
+                    sourceLine: line,
+                    originalSelector: elementSelectorOnly,
+                    healedSelector: canonicalSelector,
+                    lastHealed: new Date().toISOString(),
+                    status: "healed",
+                    definitionSite: updateResult.definitionSite,
+                    blastRadius: updateResult.blastRadius,
+                });
+                // ── Report: HEALED event ───────────────────────────────────────
+                const healedEvent = {
+                    kind: "HEALED",
+                    stableId,
+                    sourceFile: relativeSourceFile || reportFile,
+                    sourceLine: line,
+                    testTitle,
+                    timestamp: new Date().toISOString(),
+                    framePath: successfulPath,
+                    inIframe: successfulPath.length > 0,
+                    inShadowDom: liveSnapshot?.isInShadowDom ?? false,
+                    dryRun: DryRunGuard_1.DryRunGuard.active() ? true : undefined,
+                    oldSelector: elementSelectorOnly,
+                    newSelector: canonicalSelector,
+                    oldCodeLine,
+                    newCodeLine,
+                    newLineNumber: writtenLine,
+                    gitUnifiedDiff: gitUnifiedDiff || undefined,
+                    aiConfidence: aiFix.confidence,
+                    aiExplanation: aiFix.explanation ?? "",
+                    aiAlternatives: this._buildAlternatives(aiFix.chainSegments, aiFix.segments),
+                    reasoningSteps: this._buildReasoningSteps({
+                        aiFix,
+                        dnaText: lastKnownState?.text ?? null,
+                        dnaTag: lastKnownState?.tagName ?? null,
+                        safetyLevel: safetyDecision.level,
+                        strategy: updateResult.reason || "ast-update",
+                        writtenLine,
+                        blastRadius: updateResult.blastRadius,
+                        successfulPath,
+                    }),
+                    auditor: this._auditorBlockFromDecision(safetyDecision.meta),
+                    dnaBefore: (0, HealReportService_1.summariseSnapshot)(lastKnownState) ?? EMPTY_DNA_SUMMARY,
+                    dnaAfter: (0, HealReportService_1.summariseSnapshot)(liveSnapshot ?? null),
+                    diffStrategy: updateResult.reason || "ast-update",
+                    blastRadius: updateResult.blastRadius,
+                    definitionSite: updateResult.definitionSite,
+                    contentChange: aiFix.contentChange,
+                };
+                HealReportService_1.sharedHealReport.record(healedEvent);
+                // ── Cache write - persist this safe heal for future sessions ──
+                // Best-effort: failures are logged inside the service and never
+                // block the heal return. Skipped automatically during dry runs
+                // and when SELA_NO_CACHE=1.
+                if (!this.config.noCache && !cacheHit) {
+                    this.healingCache
+                        .set({
+                        ...cacheKeyInput,
+                        healedSelector: canonicalSelector,
+                        chainSegments: aiFix.chainSegments,
+                        segments: aiFix.segments,
+                        confidence: aiFix.confidence,
+                        contentChange: aiFix.contentChange,
+                        explanation: aiFix.explanation,
+                        alternatives: this._buildAlternatives(aiFix.chainSegments, aiFix.segments),
+                        safe: true,
+                    })
+                        .catch((err) => logger_1.logger.debug(`HealingCache set() failed: ${err?.message ?? err}`));
+                }
+                logger_1.logger.success(`Healed ${fmtSelector(elementSelectorOnly)} → ${fmtSelector(canonicalSelector)}` +
+                    (DryRunGuard_1.DryRunGuard.active() ? " (dry-run)" : ""));
+                return canonicalSelector;
+            }
+            // AI did not return FIXED - record as FAILED.
+            const failedEvent = {
+                kind: "FAILED",
+                stableId,
+                sourceFile: reportFile,
+                sourceLine: line,
+                testTitle,
+                timestamp: new Date().toISOString(),
+                framePath: [],
+                inIframe: false,
+                inShadowDom: lastKnownStateForReport?.isInShadowDom ?? false,
+                oldSelector: elementSelectorOnly,
+                reason: "AI could not provide a fix (NOT_FOUND)",
+                aiConfidence: aiFix?.confidence,
+                aiExplanation: aiFix?.explanation,
+                dnaBefore: (0, HealReportService_1.summariseSnapshot)(lastKnownStateForReport),
+            };
+            HealReportService_1.sharedHealReport.record(failedEvent);
+            throw new Error("AI could not provide a fix");
+        }
+        catch (error) {
+            logger_1.logger.error(`Healing failed for ${stableId}`, error?.message);
+            // Avoid double-recording when a SafetyGuard PROTECTED event was already pushed.
+            // Prefer the structured instanceof check; fall back to message-substring
+            // detection for any legacy throw sites that have not yet been migrated.
+            const isSafetyBlock = (0, SelaError_1.isSelaErrorFrom)(error, "SafetyGuard") ||
+                (typeof error?.message === "string" &&
+                    error.message.includes("[Sela-SafetyGuard]")) ||
+                (typeof error?.message === "string" &&
+                    error.message.includes("[SafetyGuard]"));
+            const isNotFoundAlreadyRecorded = typeof error?.message === "string" &&
+                error.message === "AI could not provide a fix";
+            if (!isSafetyBlock && !isNotFoundAlreadyRecorded) {
+                const failedEvent = {
+                    kind: "FAILED",
+                    stableId,
+                    sourceFile: reportFile,
+                    sourceLine: line,
+                    testTitle,
+                    timestamp: new Date().toISOString(),
+                    framePath: [],
+                    inIframe: false,
+                    inShadowDom: lastKnownStateForReport?.isInShadowDom ?? false,
+                    oldSelector: elementSelectorOnly,
+                    reason: error?.message ?? "Unknown heal failure",
+                    aiConfidence: aiFixForReport?.confidence,
+                    aiExplanation: aiFixForReport?.explanation,
+                    dnaBefore: (0, HealReportService_1.summariseSnapshot)(lastKnownStateForReport),
+                };
+                HealReportService_1.sharedHealReport.record(failedEvent);
+            }
+            throw error;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Report helpers
+    // ─────────────────────────────────────────────────────────────
+    _toReportFile(filePath) {
+        if (!filePath)
+            return "";
+        const match = filePath.match(/at\s+(.*)/i);
+        const cleaned = (match ? match[1] : filePath)
+            .replace(/^\(|\)$/g, "")
+            .trim();
+        const abs = path.isAbsolute(cleaned)
+            ? cleaned
+            : path.resolve(process.cwd(), cleaned);
+        return path.relative(process.cwd(), abs) || abs;
+    }
+    _safeReadLine(filePath, lineNumber) {
+        try {
+            const cleaned = this._toReportFile(filePath);
+            const abs = path.isAbsolute(cleaned)
+                ? cleaned
+                : path.resolve(process.cwd(), cleaned);
+            if (!fs.existsSync(abs))
+                return "";
+            const lines = fs.readFileSync(abs, "utf8").split(/\r?\n/);
+            const idx = Math.max(0, Math.min(lines.length - 1, lineNumber - 1));
+            return lines[idx] ?? "";
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * Clean-Room isolated diff: render a unified diff between the file's
+     * pre-Sela disk snapshot (`contentBefore`) and the post-write disk state
+     * (`contentAfter`) captured by `WorkspaceSnapshotService`. Returns "" when
+     * the file was never tracked (no snapshot) or the AST mutation produced
+     * no net change.
+     *
+     * This is what makes the HTML report immune to developer dirty edits: any
+     * pre-existing uncommitted changes live in BOTH buffers identically and
+     * are therefore filtered out by the diff. The output contains only Sela's
+     * selector swap.
+     */
+    _captureIsolatedDiff(filePath) {
+        try {
+            const cleaned = this._toReportFile(filePath);
+            const abs = path.isAbsolute(cleaned)
+                ? cleaned
+                : path.resolve(process.cwd(), cleaned);
+            if (!abs)
+                return "";
+            const snap = WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.getSnapshot(abs);
+            if (!snap || snap.contentAfter === null)
+                return "";
+            if (snap.contentBefore === snap.contentAfter)
+                return "";
+            return (0, IsolatedDiff_1.generateUnifiedDiff)(snap.contentBefore, snap.contentAfter, {
+                filePath: snap.relativePath,
+                context: 1,
+            });
+        }
+        catch (err) {
+            logger_1.logger.debug(`isolated diff capture skipped: ${err?.message ?? err}`);
+            return "";
+        }
+    }
+    /**
+     * Walk a unified diff and pull out the first removed line and the first
+     * added line so the legacy report fields (`oldCodeLine`, `newCodeLine`)
+     * stay populated for callers that haven't migrated to the full
+     * `gitUnifiedDiff` payload yet.
+     *
+     * Carefully skips the diff preamble (--- a/file, +++ b/file, "diff ",
+     * "index ", rename headers) - those lines would otherwise be mistaken for
+     * a -/+ change pair and produce nonsense like the original "line replaced
+     * by itself" output. Real change lines only count once the parser has seen
+     * a "@@" hunk header.
+     */
+    _extractFirstChangeFromDiff(diff) {
+        if (!diff)
+            return {};
+        let inHunk = false;
+        let oldLine;
+        let newLine;
+        for (const row of diff.split(/\r?\n/)) {
+            if (!inHunk) {
+                if (row.startsWith("@@"))
+                    inHunk = true;
+                continue;
+            }
+            // Defensive: a fresh @@ header starts a new hunk but does not reset
+            // the values we've already captured.
+            if (row.startsWith("@@"))
+                continue;
+            if (row.startsWith("---") || row.startsWith("+++"))
+                continue;
+            if (row.startsWith("\\"))
+                continue;
+            if (row.startsWith("-") && oldLine === undefined) {
+                oldLine = row.slice(1);
+            }
+            else if (row.startsWith("+") && newLine === undefined) {
+                newLine = row.slice(1);
+            }
+            if (oldLine !== undefined && newLine !== undefined)
+                break;
+        }
+        return { oldLine, newLine };
+    }
+    _auditorBlockFromDecision(meta) {
+        if (!meta || !meta.auditorVerdict)
+            return null;
+        // Keep auditor confidence as `undefined` when SafetyGuard did not produce
+        // one - the renderer fmtPct helper turns it into "n/a" rather than 0%.
+        const conf = typeof meta.auditorConfidence === "number" &&
+            Number.isFinite(meta.auditorConfidence)
+            ? meta.auditorConfidence
+            : undefined;
+        return {
+            verdict: meta.auditorVerdict,
+            confidence: conf,
+            reason: meta.auditScoreBreakdown
+                ? `Adjusted ${meta.auditScoreBreakdown.rawConfidence}% → ${meta.auditScoreBreakdown.adjustedConfidence}% (penalty ${meta.auditScoreBreakdown.penalty}, bonus +${meta.auditScoreBreakdown.bonus}).`
+                : "Auditor verdict recorded by SafetyGuard.",
+            inversionType: null,
+            rawConfidence: meta.auditScoreBreakdown?.rawConfidence,
+            penalty: meta.auditScoreBreakdown?.penalty,
+            bonus: meta.auditScoreBreakdown?.bonus,
+        };
+    }
+    _buildAlternatives(chainSegments, segments) {
+        const out = [];
+        if (chainSegments && chainSegments.length) {
+            for (const seg of chainSegments) {
+                switch (seg.type) {
+                    case "locator":
+                        out.push(`locator(${JSON.stringify(seg.selector)})`);
+                        break;
+                    case "frameLocator":
+                        out.push(`frameLocator(${JSON.stringify(seg.selector)})`);
+                        break;
+                    case "getByRole":
+                        out.push(`getByRole(${JSON.stringify(seg.role)}${seg.name ? ", { name: " + JSON.stringify(seg.name) + (seg.exact ? ", exact: true" : "") + " }" : ""})`);
+                        break;
+                    case "getByLabel":
+                        out.push(`getByLabel(${JSON.stringify(seg.text)}${seg.exact ? ", { exact: true }" : ""})`);
+                        break;
+                    case "getByText":
+                        out.push(`getByText(${JSON.stringify(seg.text)}${seg.exact ? ", { exact: true }" : ""})`);
+                        break;
+                    case "getByPlaceholder":
+                        out.push(`getByPlaceholder(${JSON.stringify(seg.text)})`);
+                        break;
+                    case "getByTestId":
+                        out.push(`getByTestId(${JSON.stringify(seg.testId)})`);
+                        break;
+                    case "getByAltText":
+                        out.push(`getByAltText(${JSON.stringify(seg.text)})`);
+                        break;
+                    case "getByTitle":
+                        out.push(`getByTitle(${JSON.stringify(seg.text)})`);
+                        break;
+                    case "filter":
+                        out.push(`filter(${JSON.stringify(seg)})`);
+                        break;
+                    case "first":
+                        out.push("first()");
+                        break;
+                    case "last":
+                        out.push("last()");
+                        break;
+                    case "nth":
+                        out.push(`nth(${seg.index})`);
+                        break;
+                }
+            }
+        }
+        if (segments && segments.length) {
+            out.push(segments.map((s) => s.selector).join(" >> "));
+        }
+        return Array.from(new Set(out)).slice(0, 8);
+    }
+    _buildReasoningSteps(ctx) {
+        const steps = [];
+        if (ctx.dnaTag || ctx.dnaText) {
+            steps.push(`Recovered DNA baseline - previously a <${ctx.dnaTag ?? "?"}>` +
+                (ctx.dnaText ? ` with text "${ctx.dnaText}"` : "") +
+                ".");
+        }
+        if (ctx.successfulPath.length > 0) {
+            steps.push(`Resolved DOM context inside ${ctx.successfulPath.length} nested frame(s): ${ctx.successfulPath.join(" >> ")}.`);
+        }
+        const firstSeg = ctx.aiFix.chainSegments?.[0];
+        if (firstSeg) {
+            steps.push(`AI preserved the ${firstSeg.type} pattern - semantic locator over raw CSS path.`);
+        }
+        if (ctx.aiFix.explanation) {
+            steps.push(`AI reasoning: ${ctx.aiFix.explanation}`);
+        }
+        steps.push(`Confidence: ${fmtPctEngine(ctx.aiFix.confidence)}.`);
+        if (ctx.aiFix.contentChange) {
+            steps.push(`Detected content drift: "${ctx.aiFix.contentChange.oldText}" → "${ctx.aiFix.contentChange.newText}".`);
+        }
+        steps.push(`SafetyGuard verdict: ${ctx.safetyLevel} - change cleared for write.`);
+        steps.push(`Source updated via ${ctx.strategy} at line ${ctx.writtenLine}.`);
+        if (ctx.blastRadius != null && ctx.blastRadius > 0) {
+            steps.push(`Blast radius: ${ctx.blastRadius} dependent test reference(s) inherited the fix.`);
+        }
+        return steps;
+    }
+    preloadTestTitle(stableId, testTitle) {
+        this.testTitleBuffer.set(stableId, testTitle);
+    }
+    async saveSnapshot(stableId, data) {
+        this.dnaBuffer.set(stableId, data);
+    }
+    async commitUpdates() {
+        if (this.dnaBuffer.size > 0) {
+            for (const [key, dna] of this.dnaBuffer.entries()) {
+                const meta = this.healMetaBuffer.get(key);
+                const toSave = meta ? { ...dna, ...meta } : dna;
+                await this.snapshotService.save(key, toSave);
+            }
+            this.dnaBuffer.clear();
+            this.healMetaBuffer.clear();
+            this.testTitleBuffer.clear();
+            SourceUpdater_1.SourceUpdater.flushAdvisories();
+        }
+        // ── Sela Insights - render the transparent healing report ───────
+        let reportHtmlPath = null;
+        const healedEvents = HealReportService_1.sharedHealReport.getHealedEvents();
+        const protectedEvents = HealReportService_1.sharedHealReport.getProtectedEvents();
+        if (HealReportService_1.sharedHealReport.hasContent()) {
+            // SELA-5: in a LOCAL multi-worker run every worker shares one cwd, so a
+            // direct flushToDisk is a last-writer-wins race on sela-report.json.
+            // Each worker instead writes a private shard; the single main-process
+            // reporter fans them in at onEnd. CI keeps the direct flush — it runs
+            // one worker per sharded machine and merges across machines separately.
+            const inLocalWorker = !isCiEnvironment() && process.env["TEST_WORKER_INDEX"] !== undefined;
+            if (inLocalWorker) {
+                try {
+                    const shard = HealReportService_1.sharedHealReport.flushShard(process.cwd());
+                    if (shard) {
+                        logger_1.logger.debug(`Heal shard written: ${path.relative(process.cwd(), shard)}`);
+                    }
+                }
+                catch (err) {
+                    logger_1.logger.warn(`Failed to write heal shard: ${err.message}`);
+                }
+            }
+            else {
+                try {
+                    logger_1.logger.stage("GENERATING REPORT");
+                    reportHtmlPath = HealReportService_1.sharedHealReport.flushToDisk(process.cwd());
+                    if (reportHtmlPath) {
+                        logger_1.logger.success(`Insights report written: ${path.relative(process.cwd(), reportHtmlPath)}`);
+                        logger_1.logger.info("   Open with:  npx sela show-report");
+                    }
+                }
+                catch (err) {
+                    logger_1.logger.warn(`Failed to write insights report: ${err.message}`);
+                }
+            }
+        }
+        // ── Dual-Mode post-run lifecycle ─────────────────────────────────
+        //
+        // CI (process.env.CI truthy) → Clean-Room PR automation (existing flow).
+        // Local DX (CI falsy)        → Write-and-notify: AST mutations are
+        //                              already on disk; the reporter prints a
+        //                              diff + vscode:// deeplink + report link
+        //                              via printHealReview() (no Y/N prompt).
+        //
+        // The local branch deliberately bypasses PR automation because:
+        //   • AST fixes are ALREADY persisted to disk (the test passed on them).
+        //   • Local devs want to inspect + cherry-pick, not auto-commit.
+        if (isCiEnvironment()) {
+            if (this.config.prAutomation.enabled) {
+                // SELA-5: serialise PR automation (git stash / checkout / commit /
+                // push) behind a repo-root lock. CI normally runs one worker per
+                // sharded machine, so the lock is uncontended; if a machine is
+                // misconfigured with workers>1 it prevents concurrent git operations
+                // from corrupting the index / worktree. NOTE: this guards against git
+                // corruption only — aggregating heals from multiple workers into a
+                // single PR is intentionally out of scope (run one worker per shard).
+                const prLock = new FileLock_1.FileLock((0, FileLock_1.lockDirFor)(path.join(process.cwd(), ".sela-pr")), { staleMs: 120_000 });
+                try {
+                    const ran = await prLock.withLock(async () => {
+                        const workerIdx = process.env["TEST_WORKER_INDEX"];
+                        if (workerIdx !== undefined && workerIdx !== "0") {
+                            logger_1.logger.warn("[PR] PR automation under workers>1 is unsupported — " +
+                                "run one worker per CI shard. Serialising to protect the git " +
+                                "index; heals from other workers may land in separate commits.");
+                        }
+                        const branchInfo = (0, PRAutomationService_1.detectBranch)(process.cwd());
+                        const decision = (0, PRAutomationService_1.decideEffectiveStrategy)(this.config.prAutomation, branchInfo.branch, healedEvents);
+                        if (decision.downgradeReason) {
+                            logger_1.logger.warn(`[PR] Strategy downgraded: '${decision.configured}' → '${decision.effective}' ` +
+                                `(reason: ${decision.downgradeReason}, ` +
+                                `minAI: ${fmtPctEngine(decision.minAiConfidence)}, ` +
+                                `minAuditor: ${fmtPctEngine(decision.minAuditorConfidence)})`);
+                        }
+                        else {
+                            logger_1.logger.debug(`[PR] Effective strategy: '${decision.effective}' on branch '${branchInfo.branch ?? "unknown"}'`);
+                        }
+                        const ctx = { cwd: process.cwd(), reportHtmlPath };
+                        await (0, PRAutomationService_1.execute)(this.config.prAutomation, decision, healedEvents, branchInfo, ctx);
+                        await (0, PRAutomationService_1.handleBugDetected)(this.config.prAutomation.onBugDetected, protectedEvents, branchInfo, ctx);
+                    });
+                    if (ran === undefined) {
+                        logger_1.logger.warn("[PR] Skipped PR automation — another worker holds the PR lock.");
+                    }
+                }
+                catch (err) {
+                    logger_1.logger.warn(`[PR] PR automation step failed: ${err.message}`);
+                }
+            }
+        }
+        else if (healedEvents.length > 0) {
+            // Local DX: serialise the mutated snapshots to a cross-process
+            // ledger. The SelaReporter drains it from `onEnd()` in the main
+            // process and prints a non-blocking summary (diff + vscode://
+            // deeplink). Mutations are already on disk - the ledger only
+            // exists so the reporter knows what to narrate.
+            try {
+                (0, PendingPromptLedger_1.writePendingPromptsLedger)({
+                    cwd: process.cwd(),
+                    workspace: WorkspaceSnapshotService_1.sharedWorkspaceSnapshot,
+                    healedEvents,
+                });
+            }
+            catch (err) {
+                logger_1.logger.warn(`Pending-prompts ledger write failed: ${err.message}`);
+            }
+        }
+        // Clear the report buffer last so any downstream consumers (e.g. test
+        // re-runs in the same process) start fresh on the next session.
+        if (HealReportService_1.sharedHealReport.hasContent()) {
+            HealReportService_1.sharedHealReport.clear();
+        }
+        // Drop the Clean-Room workspace snapshot ledger so the next session
+        // starts with an empty `contentBefore` map. Without this, a long-lived
+        // Node process (`vitest --watch`, IDE test runner) would carry stale
+        // pre-Sela snapshots from one session into the next, causing the
+        // isolated-diff layer to compare against the wrong baseline.
+        WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.clear();
+    }
+    // ─────────────────────────────────────────────────────────────
+    // fetchLiveText - frame-aware innerText fetch (zero-trust probe)
+    //
+    // Navigates the frame chain encoded in successfulPath, then calls
+    // .first().innerText() on the element-only selector.  Uses a short
+    // 1.5 s timeout so it never adds meaningful latency.  Returns null
+    // on ANY failure - the caller must treat null as "no data" and skip
+    // live verification rather than blocking the heal.
+    // ─────────────────────────────────────────────────────────────
+    async fetchLiveText(page, elementOnlySelector, framePath) {
+        try {
+            let ctx = page;
+            for (const frameSel of framePath) {
+                ctx = ctx.frameLocator(frameSel);
+            }
+            const text = await ctx
+                .locator(elementOnlySelector)
+                .first()
+                .innerText({ timeout: 1500 });
+            return text.trim().length > 0 ? text.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    _rebuildSelectorWithFrames(fullSelector, elementSelectorOnly, aiNewSelector) {
+        const fullParts = fullSelector.split(" >> ").map((s) => s.trim());
+        const elementParts = elementSelectorOnly.split(" >> ").map((s) => s.trim());
+        const aiParts = aiNewSelector.split(" >> ").map((s) => s.trim());
+        const frameParts = fullParts.slice(0, fullParts.length - elementParts.length);
+        if (frameParts.length === 0)
+            return aiNewSelector;
+        const aiHasFrameSegments = aiParts.some((p) => p.includes("-frame") ||
+            p === "iframe" ||
+            p === "frame" ||
+            p.includes("frame-"));
+        if (aiHasFrameSegments) {
+            logger_1.logger.debug(`AI returned full frame path - using directly: ${aiNewSelector}`);
+            return aiNewSelector;
+        }
+        return [...frameParts, ...aiParts].join(" >> ");
+    }
+    getAllFiles(dirPath, arrayOfFiles = []) {
+        const files = fs.readdirSync(dirPath);
+        const ignoreList = [
+            "node_modules",
+            ".git",
+            "sela-snapshots",
+            "dist",
+            "test-results",
+            "tests/reset-demo.ts",
+        ];
+        files.forEach((file) => {
+            const fullPath = path.join(dirPath, file);
+            if (fs.statSync(fullPath).isDirectory()) {
+                if (!ignoreList.includes(file))
+                    this.getAllFiles(fullPath, arrayOfFiles);
+            }
+            else if (file.endsWith(".ts") || file.endsWith(".js")) {
+                arrayOfFiles.push(fullPath);
+            }
+        });
+        return arrayOfFiles;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // captureSuccessfulElement - capture and buffer a v2 DNA snapshot.
+    //
+    // Replaces the previous DOMUtils.getElementDNA() path with a single
+    // captureElement() call that collects all v2 metrics atomically.
+    // ─────────────────────────────────────────────────────────────
+    async captureSuccessfulElement(page, selector, stableId) {
+        try {
+            const snapshot = await this.snapshotService.captureElement(page, selector);
+            if (snapshot) {
+                const testTitle = this.testTitleBuffer.get(stableId);
+                const enriched = {
+                    ...snapshot,
+                    selector,
+                    ...(testTitle ? { testTitle } : {}),
+                };
+                this.dnaBuffer.set(stableId, enriched);
+                logger_1.logger.debug(`DNA v2 captured for: ${stableId}`);
+            }
+        }
+        catch (error) {
+            logger_1.logger.debug(`DNA capture skipped: ${error.message}`);
+        }
+    }
+}
+exports.SelaEngine = SelaEngine;