sela-core 1.0.5 → 1.0.7

package/dist/engine/SelaEngine.js

@@ -37,17 +37,47 @@ 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 SnapshotService_1 = require("../services/SnapshotService");
 const DOMUtils_1 = require("../utils/DOMUtils");
 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 HealReportService_1 = require("../services/HealReportService");
 const PRAutomationService_1 = require("../services/PRAutomationService");
+const PendingPromptLedger_1 = require("../services/PendingPromptLedger");
+const SelaError_1 = require("../errors/SelaError");
+/**
+ * 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";
+}
+/**
+ * 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();
@@ -57,6 +87,14 @@ class SelaEngine {
         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)
@@ -67,10 +105,10 @@ class SelaEngine {
             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".
+                ? `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.`;
             const aiFix = await this.llmService.getFix({
@@ -99,6 +137,37 @@ CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only
         // 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) {
+                console.warn(`[Sela] 🛑 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;
@@ -125,19 +194,19 @@ CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only
             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.
+            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
@@ -162,16 +231,56 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     "\n" +
                     "Prioritize selectors that preserve these relationships (e.g. filter by row key, then target by label).");
             })();
-            console.log(`[Sela] 🔍 Step 3: Requesting AI fix from LLM...`);
-            const aiFix = await this.llmService.getFix({
-                targetIntent: intentDescription,
-                failedSelector: fullSelector,
-                previousState: lastKnownState || {},
-                currentDom: neighborhoodDom +
-                    contextHint +
-                    anchorContextHint +
-                    contentChangeInstructions,
-            });
+            // ── 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) {
+                    console.log(`[Sela] 🧊 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) {
+                console.log(`[Sela] 🔍 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") {
                 console.log(`[Sela] 🔍 Step 3: AI responded ✅`);
@@ -262,14 +371,31 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                         reason: safetyDecision.reason,
                         safetyLevel: safetyDecision.level,
                         auditor: this._auditorBlockFromDecision(safetyDecision.meta),
-                        aiConfidence: typeof aiFix.confidence === "number" ? aiFix.confidence : 0,
+                        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);
-                    throw new Error(`[SafetyGuard] ${safetyDecision.level}: ${safetyDecision.reason}`);
+                    throw new SelaError_1.SelaError({
+                        subsystem: "SafetyGuard",
+                        code: safetyDecision.code ?? SelaError_1.SAFETY_GUARD_CODES.GENERIC_REJECTION,
+                        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
@@ -281,16 +407,11 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                         parts.push(`${breakdown.penalty} ancestry drift`);
                     if (breakdown.bonus !== 0)
                         parts.push(`+${breakdown.bonus} anchor match`);
-                    console.log(`[Sela] 📊 Score — AI: ${aiFix.confidence}% | ` +
-                        `Auditor: ${breakdown.adjustedConfidence}% ` +
-                        `(raw ${breakdown.rawConfidence}%, ${parts.join(", ")})`);
+                    console.log(`[Sela] 📊 Score — AI: ${fmtPctEngine(aiFix.confidence)} | ` +
+                        `Auditor: ${fmtPctEngine(breakdown.adjustedConfidence)} ` +
+                        `(raw ${fmtPctEngine(breakdown.rawConfidence)}, ${parts.join(", ")})`);
                 }
                 console.log(`[Sela] 🚀 Rebuilt Full Runtime Selector (Clean): ${newFullSelector}`);
-                // Snapshot the ENTIRE source file BEFORE the AST mutation.
-                // We don't know which line will actually be mutated until update()
-                // returns (JumpToDef may land on the const-decl line, not the failure
-                // line) — so we keep the pre-image around and slice into it after.
-                const preMutationLines = this._safeReadAllLines(filePath);
                 const 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)
@@ -308,15 +429,21 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     (sameFileDef ? defSite?.line : undefined) ??
                     line;
                 const mutatedFilePath = !sameFileDef && defSite ? defSite.file : filePath;
-                // Old line: PRE-mutation content at the line that ended up being mutated.
-                // If the mutation was cross-file, read the pre-image of THAT file by
-                // recovering it from disk minus our own change (we don't track that —
-                // fall back to current pre-image if same file, else empty string).
-                const oldCodeLine = sameFileDef && preMutationLines.length > 0
-                    ? (preMutationLines[writtenLine - 1] ?? "")
-                    : this._safeReadLine(mutatedFilePath, writtenLine);
-                // New line: POST-mutation content at the same line in the mutated file.
-                const newCodeLine = this._safeReadLine(mutatedFilePath, writtenLine);
+                // 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;
                 console.log(`[Sela] ✅ Canonical selector (disk == runtime): "${canonicalSelector}"`);
                 // Buffer CLI-ready metadata — merged into DNA at commitUpdates() time.
@@ -359,12 +486,14 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     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,
-                    aiConfidence: typeof aiFix.confidence === "number" ? aiFix.confidence : 0,
+                    gitUnifiedDiff: gitUnifiedDiff || undefined,
+                    aiConfidence: aiFix.confidence,
                     aiExplanation: aiFix.explanation ?? "",
                     aiAlternatives: this._buildAlternatives(aiFix.chainSegments, aiFix.segments),
                     reasoningSteps: this._buildReasoningSteps({
@@ -386,6 +515,25 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     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) => console.warn(`[HealingCache] ⚠️  set() failed: ${err?.message ?? err}`));
+                }
                 return canonicalSelector;
             }
             // AI did not return FIXED — record as FAILED.
@@ -411,7 +559,11 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         catch (error) {
             console.error(`[Sela] ❌ Healing Failure:`, error.message);
             // Avoid double-recording when a SafetyGuard PROTECTED event was already pushed.
-            const isSafetyBlock = typeof error?.message === "string" && error.message.includes("[SafetyGuard]");
+            // 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 = {
@@ -461,30 +613,95 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         }
     }
     /**
-     * Snapshot the entire file as a string[] of lines.  Returns an empty array
-     * if the file is missing or unreadable.  Used to preserve the PRE-mutation
-     * source so the diff in HealedEvent reflects the line that was actually
-     * mutated (which may differ from the failure line when JumpToDef lands on
-     * a const declaration above).
+     * 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.
      */
-    _safeReadAllLines(filePath) {
+    _captureIsolatedDiff(filePath) {
         try {
             const cleaned = this._toReportFile(filePath);
-            const abs = path.isAbsolute(cleaned) ? cleaned : path.resolve(process.cwd(), cleaned);
-            if (!fs.existsSync(abs))
-                return [];
-            return fs.readFileSync(abs, "utf8").split(/\r?\n/);
+            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 {
-            return [];
+        catch (err) {
+            console.debug?.(`[Sela] 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: meta.auditorConfidence ?? 0,
+            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.",
@@ -562,7 +779,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         if (ctx.aiFix.explanation) {
             steps.push(`AI reasoning: ${ctx.aiFix.explanation}`);
         }
-        steps.push(`Confidence: ${ctx.aiFix.confidence}%.`);
+        steps.push(`Confidence: ${fmtPctEngine(ctx.aiFix.confidence)}.`);
         if (ctx.aiFix.contentChange) {
             steps.push(`Detected content drift: "${ctx.aiFix.contentChange.oldText}" → "${ctx.aiFix.contentChange.newText}".`);
         }
@@ -607,25 +824,54 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                 console.warn(`[Sela] ⚠️  Failed to write insights report: ${err.message}`);
             }
         }
-        // ── PR Automation — batched git-flow at session end ─────────────
-        if (this.config.prAutomation.enabled) {
-            try {
-                const branchInfo = (0, PRAutomationService_1.detectBranch)(process.cwd());
-                const decision = (0, PRAutomationService_1.decideEffectiveStrategy)(this.config.prAutomation, branchInfo.branch, healedEvents);
-                if (decision.downgradeReason) {
-                    console.warn(`[Sela PR] ⚠️  Strategy downgraded: '${decision.configured}' → '${decision.effective}' ` +
-                        `(reason: ${decision.downgradeReason}, ` +
-                        `minAI: ${decision.minAiConfidence}%, minAuditor: ${decision.minAuditorConfidence}%)`);
+        // ── Dual-Mode post-run lifecycle ─────────────────────────────────
+        //
+        // CI (process.env.CI truthy) → Clean-Room PR automation (existing flow).
+        // Local DX (CI falsy)        → Interactive CLI review of each mutated
+        //                              file; Apply keeps the on-disk fix, Reject
+        //                              rewinds via WorkspaceSnapshotService.
+        //
+        // The interactive 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) {
+                try {
+                    const branchInfo = (0, PRAutomationService_1.detectBranch)(process.cwd());
+                    const decision = (0, PRAutomationService_1.decideEffectiveStrategy)(this.config.prAutomation, branchInfo.branch, healedEvents);
+                    if (decision.downgradeReason) {
+                        console.warn(`[Sela PR] ⚠️  Strategy downgraded: '${decision.configured}' → '${decision.effective}' ` +
+                            `(reason: ${decision.downgradeReason}, ` +
+                            `minAI: ${fmtPctEngine(decision.minAiConfidence)}, ` +
+                            `minAuditor: ${fmtPctEngine(decision.minAuditorConfidence)})`);
+                    }
+                    else {
+                        console.log(`[Sela 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);
                 }
-                else {
-                    console.log(`[Sela PR] 🎯 Effective strategy: '${decision.effective}' on branch '${branchInfo.branch ?? "unknown"}'`);
+                catch (err) {
+                    console.warn(`[Sela PR] ⚠️  PR automation step failed: ${err.message}`);
                 }
-                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);
+            }
+        }
+        else if (healedEvents.length > 0) {
+            // Local DX: do NOT block this process on stdin — workers have no
+            // TTY and would deadlock until Playwright's per-test timeout fires.
+            // Serialise the mutated snapshots to a cross-process ledger; the
+            // SelaReporter drains it from `onEnd()` in the main process where
+            // an interactive `readline` is safe.
+            try {
+                (0, PendingPromptLedger_1.writePendingPromptsLedger)({
+                    cwd: process.cwd(),
+                    workspace: WorkspaceSnapshotService_1.sharedWorkspaceSnapshot,
+                    healedEvents,
+                });
             }
             catch (err) {
-                console.warn(`[Sela PR] ⚠️  PR automation step failed: ${err.message}`);
+                console.warn(`[Sela] ⚠️  Pending-prompts ledger write failed: ${err.message}`);
             }
         }
         // Clear the report buffer last so any downstream consumers (e.g. test
@@ -633,6 +879,12 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         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)