sela-core 1.0.6 → 1.0.8

package/dist/engine/SelaEngine.js

@@ -36,15 +36,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SelaEngine = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 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
@@ -53,10 +59,25 @@ const PRAutomationService_1 = require("../services/PRAutomationService");
 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();
@@ -66,9 +87,17 @@ 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)
+    // healArgument - repairs a wrong action argument (e.g. selectOption)
     // ─────────────────────────────────────────────────────────────
     async healArgument(page, selector, action, oldArgument, stableId, filePath, line) {
         console.log(`[Sela] 🔧 HEALING ARGUMENT for action '${action}': "${oldArgument}"`);
@@ -76,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({
@@ -101,13 +130,44 @@ CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only
         return null;
     }
     // ─────────────────────────────────────────────────────────────
-    // heal — repairs a broken selector
+    // heal - repairs a broken selector
     // ─────────────────────────────────────────────────────────────
     async heal(page, fullSelector, elementSelectorOnly, stableId, filePath, line, healMode = "action") {
         console.log(`\n[Sela] 🛠️  HEALING START for: ${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) {
+                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;
@@ -134,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
@@ -158,10 +218,10 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     return "";
                 const lines = [];
                 if (anchors.closestLabel) {
-                    lines.push(`- Label: "${anchors.closestLabel}" — the UI label or heading associated with this element.`);
+                    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.`);
+                    lines.push(`- Row key: "${anchors.rowAnchor}" - unique cell text identifying the table row this element belonged to.`);
                 }
                 if (lines.length === 0)
                     return "";
@@ -171,16 +231,57 @@ 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 ✅`);
@@ -208,7 +309,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     console.log(`[Sela] 🔍 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,
+                // 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);
@@ -221,7 +322,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                         : "";
                     const occFlag = liveVisibility?.isOccluded ? " 🫥 OCCLUDED" : "";
                     console.log(`[Sela] 🔍 Step 3.6: Live v2 capture complete` +
-                        `${ghostFlag}${occFlag} — ancestry depth: ${liveAncestry?.length ?? 0}`);
+                        `${ghostFlag}${occFlag} - ancestry depth: ${liveAncestry?.length ?? 0}`);
                 }
                 else {
                     console.log(`[Sela] 🔍 Step 3.6: Live v2 capture skipped`);
@@ -255,7 +356,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     }
                     // ── Report: PROTECTED (or BLOCKED non-INCONSISTENT) ─────────
                     // The auto-fix was blocked. If the auditor verdict is INCONSISTENT
-                    // this is a "Security Win" — a masked regression was caught.
+                    // this is a "Security Win" - a masked regression was caught.
                     const protectedEvent = {
                         kind: "PROTECTED",
                         stableId,
@@ -278,7 +379,24 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                         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
@@ -290,7 +408,7 @@ 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: ${fmtPctEngine(aiFix.confidence)} | ` +
+                    console.log(`[Sela] 📊 Score - AI: ${fmtPctEngine(aiFix.confidence)} | ` +
                         `Auditor: ${fmtPctEngine(breakdown.adjustedConfidence)} ` +
                         `(raw ${fmtPctEngine(breakdown.rawConfidence)}, ${parts.join(", ")})`);
                 }
@@ -300,7 +418,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                 //   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)
+                //   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;
@@ -312,23 +430,26 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     (sameFileDef ? defSite?.line : undefined) ??
                     line;
                 const mutatedFilePath = !sameFileDef && defSite ? defSite.file : filePath;
-                // Capture the native unified diff straight from git. This runs AFTER
-                // SourceUpdater flushed the file to disk and BEFORE any `git add` —
-                // so `git diff HEAD` reports the exact pending change at the real
-                // mutated line. No in-process line-index math, no off-by-one when
-                // JumpToDef lands above the failure site, and cross-file healing
-                // falls out for free.
-                const gitUnifiedDiff = this._captureGitDiff(mutatedFilePath);
+                // 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);
+                // 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.
+                // 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);
@@ -368,6 +489,7 @@ 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,
@@ -396,9 +518,28 @@ 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.
+            // AI did not return FIXED - record as FAILED.
             const failedEvent = {
                 kind: "FAILED",
                 stableId,
@@ -421,8 +562,15 @@ 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]");
-            const isNotFoundAlreadyRecorded = typeof error?.message === "string" && error.message === "AI could not provide a fix";
+            // 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",
@@ -452,14 +600,20 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         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);
+        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);
+            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/);
@@ -471,36 +625,37 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         }
     }
     /**
-     * Capture the native `git diff --unified=1 HEAD -- <file>` for the file the
-     * AST mutation just wrote to. Returns an empty string when git is not
-     * available, the file is not tracked, or any other failure — callers must
-     * treat empty output as "no diff captured" and fall back to a direct disk
-     * read of the mutated line.
+     * 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.
      *
-     * Path safety: the absolute path is always wrapped in double quotes after
-     * escaping any embedded double quotes, which makes the call safe on Windows
-     * paths containing spaces or backslashes as well as POSIX paths.
+     * 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.
      */
-    _captureGitDiff(filePath) {
+    _captureIsolatedDiff(filePath) {
         try {
             const cleaned = this._toReportFile(filePath);
             const abs = path.isAbsolute(cleaned)
                 ? cleaned
                 : path.resolve(process.cwd(), cleaned);
-            if (!abs || !fs.existsSync(abs))
+            if (!abs)
                 return "";
-            const quoted = `"${abs.replace(/"/g, '\\"')}"`;
-            const out = (0, child_process_1.execSync)(`git diff --unified=1 HEAD -- ${quoted}`, {
-                cwd: process.cwd(),
-                encoding: "utf-8",
-                stdio: ["pipe", "pipe", "pipe"],
-                windowsHide: true,
+            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,
             });
-            return out.toString();
         }
         catch (err) {
-            // git missing / not a repo / file untracked vs HEAD → log & fall back.
-            console.debug?.(`[Sela] git diff capture skipped: ${err?.message ?? err}`);
+            console.debug?.(`[Sela] isolated diff capture skipped: ${err?.message ?? err}`);
             return "";
         }
     }
@@ -511,7 +666,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
      * `gitUnifiedDiff` payload yet.
      *
      * Carefully skips the diff preamble (--- a/file, +++ b/file, "diff ",
-     * "index ", rename headers) — those lines would otherwise be mistaken for
+     * "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.
@@ -551,7 +706,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         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%.
+        // 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
@@ -623,15 +778,16 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
     _buildReasoningSteps(ctx) {
         const steps = [];
         if (ctx.dnaTag || ctx.dnaText) {
-            steps.push(`Recovered DNA baseline — previously a <${ctx.dnaTag ?? "?"}>` +
-                (ctx.dnaText ? ` with text "${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.`);
+            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}`);
@@ -640,7 +796,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         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(`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.`);
@@ -665,7 +821,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
             this.testTitleBuffer.clear();
             SourceUpdater_1.SourceUpdater.flushAdvisories();
         }
-        // ── Sela Insights — render the transparent healing report ───────
+        // ── Sela Insights - render the transparent healing report ───────
         let reportHtmlPath = null;
         const healedEvents = HealReportService_1.sharedHealReport.getHealedEvents();
         const protectedEvents = HealReportService_1.sharedHealReport.getProtectedEvents();
@@ -681,26 +837,55 @@ 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: ${fmtPctEngine(decision.minAiConfidence)}, ` +
-                        `minAuditor: ${fmtPctEngine(decision.minAuditorConfidence)})`);
+        // ── 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) {
+                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: 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) {
-                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
@@ -708,14 +893,20 @@ 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)
+    // 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
+    // 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) {
@@ -746,7 +937,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
             p === "frame" ||
             p.includes("frame-"));
         if (aiHasFrameSegments) {
-            console.log(`[Sela] 🔗 AI returned full frame path — using directly: ${aiNewSelector}`);
+            console.log(`[Sela] 🔗 AI returned full frame path - using directly: ${aiNewSelector}`);
             return aiNewSelector;
         }
         return [...frameParts, ...aiParts].join(" >> ");
@@ -774,7 +965,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         return arrayOfFiles;
     }
     // ─────────────────────────────────────────────────────────────
-    // captureSuccessfulElement — capture and buffer a v2 DNA snapshot.
+    // 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.