sela-core 1.0.6 → 1.0.7

package/dist/services/PRAutomationService.js

@@ -54,6 +54,8 @@ exports.handleBugDetected = handleBugDetected;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
+const IsolatedDiff_1 = require("../utils/IsolatedDiff");
 // ═══════════════════════════════════════════════════════════════════
 // SHELL HELPERS
 // ═══════════════════════════════════════════════════════════════════
@@ -327,7 +329,19 @@ function buildDefaultBody(heals, branchInfo, reportLink, decision) {
     lines.push(`Generated automatically by \`sela-core\`.`);
     return lines.join("\n");
 }
-async function execute(cfg, decision, heals, branchInfo, ctx) {
+/**
+ * Clean-Room execution lifecycle.
+ *
+ * The legacy flow committed the developer's whole dirty working tree onto
+ * the PR branch — polluting reviewers with `test.only`, commented debug
+ * blocks, etc. This refactor isolates Sela's specific AST changes onto an
+ * ephemeral branch, leaves the developer's local workspace byte-identical
+ * to its pre-Sela state, and is wrapped in a try/finally that restores
+ * the workspace even on mid-flight crashes.
+ */
+async function execute(cfg, decision, heals, branchInfo, ctx, 
+/** Injectable for tests — defaults to the module singleton. */
+workspace = WorkspaceSnapshotService_1.sharedWorkspaceSnapshot) {
     const result = {
         effective: decision.effective,
         prUrl: null,
@@ -355,14 +369,13 @@ async function execute(cfg, decision, heals, branchInfo, ctx) {
         console.warn(`[Sela PR] ⚠️  Detached HEAD — skipping git operations.`);
         return result;
     }
-    // ── Stage all healed files (relative paths from event records) ────
-    const filesToStage = Array.from(new Set(heals.map((h) => h.sourceFile).filter((f) => f && f.length > 0)));
-    if (filesToStage.length === 0) {
-        result.errors.push("no files to stage");
-        console.warn(`[Sela PR] ⚠️  No file paths in HEALED events — skipping.`);
+    const mutatedSnaps = workspace.getMutatedSnapshots();
+    if (mutatedSnaps.length === 0) {
+        result.errors.push("no mutated files tracked");
+        console.warn(`[Sela PR] ⚠️  WorkspaceSnapshotService reports no mutated files — skipping.`);
         return result;
     }
-    // Render title — use first heal as representative
+    // Render title / body up front — needed by all branches below.
     const first = heals[0];
     const titleVars = {
         testName: first.testTitle ?? "automation",
@@ -381,90 +394,268 @@ async function execute(cfg, decision, heals, branchInfo, ctx) {
             reasoning: heals.map((h) => h.aiExplanation).join("\n\n"),
         })
         : buildDefaultBody(heals, branchInfo, reportLink, decision);
-    // ── directCommit ────────────────────────────────────────────────
     if (decision.effective === "directCommit") {
-        for (const f of filesToStage) {
-            const add = sh(`git add "${f}"`, ctx.cwd);
-            if (!add.ok)
-                result.errors.push(`git add ${f}: ${add.stderr}`);
-        }
-        const commit = sh(`git commit -m ${shellQuote(title)}`, ctx.cwd);
-        if (!commit.ok) {
-            result.errors.push(`git commit: ${commit.stderr}`);
-            console.warn(`[Sela PR] ⚠️  git commit failed: ${commit.stderr}`);
-            return result;
-        }
-        console.log(`[Sela PR] ✅ Direct commit on '${branchInfo.branch}': ${title}`);
-        const push = sh(`git push`, ctx.cwd);
-        if (!push.ok) {
-            result.errors.push(`git push: ${push.stderr}`);
-            console.warn(`[Sela PR] ⚠️  git push failed: ${push.stderr}`);
-            return result;
-        }
-        console.log(`[Sela PR] 🚀 Pushed to '${branchInfo.branch}'`);
-        return result;
+        return runCleanRoom({
+            mode: "directCommit",
+            cfg,
+            ctx,
+            mutatedSnaps,
+            title,
+            body,
+            branchInfo,
+            decision,
+            result,
+        });
     }
-    // ── pr / draftPR ────────────────────────────────────────────────
     if (decision.effective === "pr" || decision.effective === "draftPR") {
         if (!ghAvailable(ctx.cwd)) {
             result.errors.push("gh CLI not available");
             console.warn(`[Sela PR] ⚠️  gh CLI not installed — cannot open PR. Run \`gh auth login\` after install.`);
             return result;
         }
-        const id = String(Date.now());
-        const branchName = render(cfg.branchNameTemplate, { id, timestamp: id });
-        const checkout = sh(`git checkout -b ${branchName}`, ctx.cwd);
-        if (!checkout.ok) {
-            result.errors.push(`git checkout: ${checkout.stderr}`);
-            console.warn(`[Sela PR] ⚠️  Could not create branch '${branchName}': ${checkout.stderr}`);
-            return result;
+        return runCleanRoom({
+            mode: decision.effective,
+            cfg,
+            ctx,
+            mutatedSnaps,
+            title,
+            body,
+            branchInfo,
+            decision,
+            result,
+        });
+    }
+    return result;
+}
+async function runCleanRoom(args) {
+    const { mode, cfg, ctx, mutatedSnaps, title, body, branchInfo, decision, result } = args;
+    const id = String(Date.now());
+    const stashLabel = `sela:clean-room-${id}`;
+    const originalBranch = currentBranch(ctx.cwd);
+    const targetBranch = mode === "directCommit"
+        ? originalBranch
+        : render(cfg.branchNameTemplate, { id, timestamp: id });
+    // Lifecycle state — used by the finally{} restoration block.
+    let didRestoreOriginal = false;
+    let didStash = false;
+    let didSwitchToTarget = false;
+    let didCommit = false;
+    try {
+        // 1. State Checkpoint — rewind developer's mutated files to pre-Sela
+        //    state on disk. Other dirty files (unrelated to Sela) stay where
+        //    they are; the subsequent stash will sweep them up.
+        workspaceRestoreOriginal(mutatedSnaps);
+        didRestoreOriginal = true;
+        // 2. Branch Isolation — stash everything (tracked + untracked) so the
+        //    worktree mirrors HEAD when we switch / branch off.
+        const stash = sh(`git stash push -u -m ${shellQuote(stashLabel)}`, ctx.cwd);
+        if (stash.ok) {
+            didStash = !/No local changes to save/i.test(stash.stdout);
+        }
+        else {
+            // Stash failures are non-fatal when the worktree was already clean.
+            console.debug?.(`[Sela PR] stash skipped: ${stash.stderr}`);
+        }
+        if (mode !== "directCommit") {
+            const checkout = sh(`git checkout -b ${targetBranch}`, ctx.cwd);
+            if (!checkout.ok) {
+                throw new Error(`git checkout -b ${targetBranch}: ${checkout.stderr}`);
+            }
+            didSwitchToTarget = true;
         }
-        for (const f of filesToStage) {
-            const add = sh(`git add "${f}"`, ctx.cwd);
+        // 3. Targeted Hunk Patching — apply ONLY Sela's blocks to each file's
+        //    clean HEAD content. Refuses to write if dirty edits collide with
+        //    Sela's mutation site (block not found / not unique).
+        for (const snap of mutatedSnaps) {
+            const applied = applyMutationToClean(snap);
+            if (!applied.ok) {
+                throw new Error(`cannot apply Sela mutation to clean base of ${snap.relativePath}: ${applied.reason}`);
+            }
+            fs.writeFileSync(snap.absolutePath, applied.result, "utf8");
+        }
+        // 4. Stage, commit, push.
+        for (const snap of mutatedSnaps) {
+            const add = sh(`git add ${shellQuote(snap.relativePath)}`, ctx.cwd);
             if (!add.ok)
-                result.errors.push(`git add ${f}: ${add.stderr}`);
+                result.errors.push(`git add ${snap.relativePath}: ${add.stderr}`);
         }
+        configureGitIdentityForCI(ctx.cwd);
         const commit = sh(`git commit -m ${shellQuote(title)}`, ctx.cwd);
         if (!commit.ok) {
-            result.errors.push(`git commit: ${commit.stderr}`);
-            console.warn(`[Sela PR] ⚠️  git commit failed: ${commit.stderr}`);
-            return result;
+            throw new Error(`git commit: ${commit.stderr}`);
         }
-        const push = sh(`git push -u origin ${branchName}`, ctx.cwd);
+        didCommit = true;
+        console.log(`[Sela PR] ✅ Clean commit on '${targetBranch ?? "(unknown)"}': ${title}`);
+        const pushCmd = mode === "directCommit"
+            ? `git push`
+            : `git push -u origin ${shellQuote(targetBranch)}`;
+        const push = sh(pushCmd, ctx.cwd);
         if (!push.ok) {
-            result.errors.push(`git push: ${push.stderr}`);
-            console.warn(`[Sela PR] ⚠️  git push failed: ${push.stderr}`);
-            return result;
+            throw new Error(`git push: ${push.stderr}`);
         }
-        result.branchPushed = branchName;
-        // Write body to a temp file to avoid shell-escaping headaches
-        const bodyFile = path.join(ctx.cwd, `.sela-pr-body-${id}.md`);
-        fs.writeFileSync(bodyFile, body, "utf8");
-        const labelFlag = cfg.labels.length > 0
-            ? cfg.labels.map((l) => `--label ${shellQuote(l)}`).join(" ")
-            : "";
-        const draftFlag = decision.effective === "draftPR" ? "--draft" : "";
-        const baseFlag = branchInfo.branch ? `--base ${shellQuote(branchInfo.branch)}` : "";
-        const prCmd = `gh pr create ${draftFlag} ${baseFlag} ` +
-            `--title ${shellQuote(title)} ` +
-            `--body-file ${shellQuote(bodyFile)} ` +
-            `${labelFlag}`;
-        const pr = sh(prCmd, ctx.cwd);
+        if (mode !== "directCommit") {
+            result.branchPushed = targetBranch;
+        }
+        // 5. (PR modes only) open the PR.
+        if (mode === "pr" || mode === "draftPR") {
+            const prUrl = openPullRequest({
+                cfg,
+                ctx,
+                mode,
+                title,
+                body,
+                branchInfo,
+                id,
+                result,
+            });
+            if (prUrl)
+                result.prUrl = prUrl;
+        }
+    }
+    catch (err) {
+        result.errors.push(err?.message ?? String(err));
+        console.warn(`[Sela PR] ⚠️  Clean-room flow failed: ${err?.message ?? err}`);
+    }
+    finally {
+        // 6. Workspace Restoration — ALWAYS attempt, even on mid-flight crash.
+        //    Order matters:
+        //      a) Switch back to the developer's original branch (if we left it).
+        //      b) Pop the stash to restore the dirty pre-Sela working tree.
+        //      c) Defensively re-write contentBefore for tracked files in case
+        //         the stash was lost.
         try {
-            fs.unlinkSync(bodyFile);
+            if (didSwitchToTarget && originalBranch) {
+                const back = sh(`git checkout ${shellQuote(originalBranch)}`, ctx.cwd);
+                if (!back.ok) {
+                    console.warn(`[Sela PR] ⚠️  Could not switch back to '${originalBranch}': ${back.stderr}`);
+                }
+            }
+            if (didStash) {
+                const pop = sh(`git stash pop`, ctx.cwd);
+                if (!pop.ok) {
+                    console.warn(`[Sela PR] ⚠️  git stash pop failed: ${pop.stderr}`);
+                }
+            }
+            if (didRestoreOriginal) {
+                // Belt-and-braces — every tracked snapshot back to its dirty
+                // pre-Sela state. No-op if stash pop already did the job.
+                workspaceRestoreOriginal(mutatedSnaps);
+            }
         }
-        catch { /* ignore */ }
-        if (!pr.ok) {
-            result.errors.push(`gh pr create: ${pr.stderr}`);
-            console.warn(`[Sela PR] ⚠️  gh pr create failed: ${pr.stderr}`);
-            return result;
+        catch (restoreErr) {
+            console.warn(`[Sela PR] ⚠️  Workspace restoration error: ${restoreErr?.message ?? restoreErr}`);
         }
-        result.prUrl = pr.stdout.trim();
-        console.log(`[Sela PR] ✅ ${decision.effective === "draftPR" ? "Draft PR" : "PR"} opened: ${result.prUrl}`);
-        return result;
+    }
+    if (!didCommit && result.errors.length === 0) {
+        result.errors.push("clean-room flow did not produce a commit");
     }
     return result;
 }
+function openPullRequest(args) {
+    const { cfg, ctx, mode, title, body, branchInfo, id, result } = args;
+    const bodyFile = path.join(ctx.cwd, `.sela-pr-body-${id}.md`);
+    try {
+        fs.writeFileSync(bodyFile, body, "utf8");
+    }
+    catch (err) {
+        result.errors.push(`pr body write: ${err?.message ?? err}`);
+        return null;
+    }
+    const labelFlag = cfg.labels.length > 0
+        ? cfg.labels.map((l) => `--label ${shellQuote(l)}`).join(" ")
+        : "";
+    const draftFlag = mode === "draftPR" ? "--draft" : "";
+    const baseFlag = branchInfo.branch ? `--base ${shellQuote(branchInfo.branch)}` : "";
+    const prCmd = `gh pr create ${draftFlag} ${baseFlag} ` +
+        `--title ${shellQuote(title)} ` +
+        `--body-file ${shellQuote(bodyFile)} ` +
+        `${labelFlag}`;
+    const pr = sh(prCmd, ctx.cwd);
+    try {
+        fs.unlinkSync(bodyFile);
+    }
+    catch {
+        /* ignore */
+    }
+    if (!pr.ok) {
+        result.errors.push(`gh pr create: ${pr.stderr}`);
+        console.warn(`[Sela PR] ⚠️  gh pr create failed: ${pr.stderr}`);
+        return null;
+    }
+    const url = pr.stdout.trim();
+    console.log(`[Sela PR] ✅ ${mode === "draftPR" ? "Draft PR" : "PR"} opened: ${url}`);
+    return url;
+}
+// ═══════════════════════════════════════════════════════════════════
+// CLEAN-ROOM HELPERS
+// ═══════════════════════════════════════════════════════════════════
+function currentBranch(cwd) {
+    const r = sh("git rev-parse --abbrev-ref HEAD", cwd);
+    if (!r.ok)
+        return null;
+    const b = r.stdout.trim();
+    return b && b !== "HEAD" ? b : null;
+}
+function workspaceRestoreOriginal(snaps) {
+    for (const snap of snaps) {
+        try {
+            if (snap.createdBySela) {
+                if (fs.existsSync(snap.absolutePath))
+                    fs.unlinkSync(snap.absolutePath);
+                continue;
+            }
+            fs.writeFileSync(snap.absolutePath, snap.contentBefore, "utf8");
+        }
+        catch (err) {
+            console.warn(`[Sela PR] ⚠️  Could not restore ${snap.relativePath}: ${err?.message ?? err}`);
+        }
+    }
+}
+function applyMutationToClean(snap) {
+    const after = snap.contentAfter ?? "";
+    // File didn't exist on HEAD (created by Sela or untracked). Write the
+    // post-mutation content directly — there's no clean base to merge into.
+    if (snap.headContent === null) {
+        return { ok: true, result: after };
+    }
+    // No dirty edits — `headContent === contentBefore`, so the mutation
+    // applies cleanly as a 1:1 string equivalence.
+    if (snap.headContent === snap.contentBefore) {
+        return { ok: true, result: after };
+    }
+    // Dirty edits present — extract Sela's specific change blocks and
+    // re-apply them against the clean HEAD content via unique substring
+    // replacement. Fails loudly when the dirty edits overlap Sela's site.
+    const blocks = (0, IsolatedDiff_1.extractChangeBlocks)(snap.contentBefore, after);
+    if (blocks.length === 0) {
+        return { ok: true, result: snap.headContent };
+    }
+    return (0, IsolatedDiff_1.applyChangeBlocks)(snap.headContent, blocks);
+}
+/**
+ * CI adapters (GitHub Actions, GitLab, Jenkins) often run with no global
+ * git identity. `git commit` then fails with `Please tell me who you are`,
+ * tanking the whole heal pipeline. Plant a sela bot identity for THIS
+ * commit only when no `user.email` / `user.name` is configured — never
+ * overwrite an existing identity.
+ */
+function configureGitIdentityForCI(cwd) {
+    const isCI = process.env.CI === "true" ||
+        process.env.CI === "1" ||
+        !!process.env.GITHUB_ACTIONS ||
+        !!process.env.GITLAB_CI ||
+        !!process.env.JENKINS_URL;
+    if (!isCI)
+        return;
+    const email = sh("git config user.email", cwd);
+    if (!email.ok || email.stdout.trim().length === 0) {
+        sh(`git config user.email "sela-bot@anthropic.local"`, cwd);
+    }
+    const name = sh("git config user.name", cwd);
+    if (!name.ok || name.stdout.trim().length === 0) {
+        sh(`git config user.name "Sela Bot"`, cwd);
+    }
+}
 // ═══════════════════════════════════════════════════════════════════
 // BUG-DETECTED HANDLING
 // ═══════════════════════════════════════════════════════════════════

package/dist/services/PendingPromptLedger.d.ts

@@ -0,0 +1,44 @@
+import type { WorkspaceSnapshotService } from "./WorkspaceSnapshotService";
+import type { HealedEvent } from "./HealReportService";
+export interface PendingPromptEntry {
+    absolutePath: string;
+    relativePath: string;
+    contentBefore: string;
+    contentAfter: string;
+    createdBySela: boolean;
+    /** 1-based line number for the vscode:// deeplink, or null when unknown. */
+    lineNumber: number | null;
+}
+/**
+ * Resolve the ledger directory for a given cwd. The directory is created
+ * lazily on the first write so we never clutter repos that aren't running
+ * Sela.
+ */
+export declare function ledgerDir(cwd: string): string;
+/**
+ * Persist this worker's mutated snapshots to a fresh JSON file under
+ * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker —
+ * subsequent calls in the same process append a NEW file (rare in
+ * practice but keeps the contract simple).
+ *
+ * Returns the absolute path of the written file, or `null` when there is
+ * nothing to persist (so callers can skip the prompt entirely in CI /
+ * empty-mutation runs).
+ */
+export declare function writePendingPromptsLedger(opts: {
+    cwd: string;
+    workspace: WorkspaceSnapshotService;
+    healedEvents: HealedEvent[];
+}): string | null;
+/**
+ * Drain every per-worker JSON file under the ledger directory and merge
+ * their entries into a single de-duplicated list (keyed by absolutePath).
+ * The most-recent contentAfter wins on collision — that's the disk truth.
+ *
+ * The directory is NOT deleted here so the reporter can inspect entries
+ * before calling `clearPendingPromptsLedger()`.
+ */
+export declare function readPendingPromptsLedger(cwd: string): PendingPromptEntry[];
+/** Remove the ledger directory and every file beneath it. Idempotent. */
+export declare function clearPendingPromptsLedger(cwd: string): void;
+//# sourceMappingURL=PendingPromptLedger.d.ts.map

package/dist/services/PendingPromptLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingPromptLedger.d.ts","sourceRoot":"","sources":["../../src/services/PendingPromptLedger.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,wBAAwB,CAAC;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,IAAI,CAehB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAyB1E;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3D"}

package/dist/services/PendingPromptLedger.js

@@ -0,0 +1,180 @@
+"use strict";
+// src/services/PendingPromptLedger.ts
+//
+// Cross-process ledger for the Local DX dual-mode lifecycle.
+//
+// Playwright workers run in separate Node processes from the reporter
+// (main process). The in-memory `WorkspaceSnapshotService` ledger is
+// per-process, so we can't drive an interactive prompt from the reporter
+// using only worker-side state.
+//
+// Solution: each worker SERIALISES its mutated FileSnapshots to a JSON
+// file under `<cwd>/.sela/pending-prompts/`, one file per worker process
+// (keyed by pid + monotonic timestamp). The reporter's onEnd hook reads
+// every file in that directory, drives `runInteractiveReview()` against
+// the merged list, then deletes the directory.
+//
+// CRITICAL: workers MUST NOT call `readline` / block on stdin — they have
+// no TTY attached. Blocking the event loop here causes the Playwright
+// test timeout to fire. This ledger is the boundary between silent
+// worker-side execution and TTY-bound reporter-side prompting.
+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.ledgerDir = ledgerDir;
+exports.writePendingPromptsLedger = writePendingPromptsLedger;
+exports.readPendingPromptsLedger = readPendingPromptsLedger;
+exports.clearPendingPromptsLedger = clearPendingPromptsLedger;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const LEDGER_SUBDIR = path.join(".sela", "pending-prompts");
+/**
+ * Resolve the ledger directory for a given cwd. The directory is created
+ * lazily on the first write so we never clutter repos that aren't running
+ * Sela.
+ */
+function ledgerDir(cwd) {
+    return path.join(cwd, LEDGER_SUBDIR);
+}
+/**
+ * Persist this worker's mutated snapshots to a fresh JSON file under
+ * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker —
+ * subsequent calls in the same process append a NEW file (rare in
+ * practice but keeps the contract simple).
+ *
+ * Returns the absolute path of the written file, or `null` when there is
+ * nothing to persist (so callers can skip the prompt entirely in CI /
+ * empty-mutation runs).
+ */
+function writePendingPromptsLedger(opts) {
+    const snaps = opts.workspace.getMutatedSnapshots();
+    if (snaps.length === 0)
+        return null;
+    const entries = snaps.map((s) => snapshotToEntry(s, opts.healedEvents, opts.cwd));
+    const dir = ledgerDir(opts.cwd);
+    fs.mkdirSync(dir, { recursive: true });
+    const fileName = `${process.pid}-${Date.now()}-${randomTag()}.json`;
+    const full = path.join(dir, fileName);
+    fs.writeFileSync(full, JSON.stringify(entries, null, 2), "utf8");
+    return full;
+}
+/**
+ * Drain every per-worker JSON file under the ledger directory and merge
+ * their entries into a single de-duplicated list (keyed by absolutePath).
+ * The most-recent contentAfter wins on collision — that's the disk truth.
+ *
+ * The directory is NOT deleted here so the reporter can inspect entries
+ * before calling `clearPendingPromptsLedger()`.
+ */
+function readPendingPromptsLedger(cwd) {
+    const dir = ledgerDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const merged = new Map();
+    const files = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .sort(); // pid-timestamp prefix gives a stable, time-ordered merge
+    for (const f of files) {
+        const full = path.join(dir, f);
+        try {
+            const raw = fs.readFileSync(full, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                continue;
+            for (const entry of parsed) {
+                if (!entry || typeof entry.absolutePath !== "string")
+                    continue;
+                merged.set(path.normalize(entry.absolutePath), entry);
+            }
+        }
+        catch {
+            // Corrupt ledger file — skip rather than crashing the whole review.
+        }
+    }
+    return Array.from(merged.values());
+}
+/** Remove the ledger directory and every file beneath it. Idempotent. */
+function clearPendingPromptsLedger(cwd) {
+    const dir = ledgerDir(cwd);
+    if (!fs.existsSync(dir))
+        return;
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+// ───────────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────────
+function snapshotToEntry(snap, heals, cwd) {
+    return {
+        absolutePath: snap.absolutePath,
+        relativePath: snap.relativePath,
+        contentBefore: snap.contentBefore,
+        contentAfter: snap.contentAfter ?? "",
+        createdBySela: snap.createdBySela,
+        lineNumber: findLineNumberForSnapshot(snap, heals, cwd),
+    };
+}
+/**
+ * Resolve a 1-based line number for the vscode:// deeplink. Priority:
+ *   1. `definitionSite.line` for a heal whose `definitionSite.file`
+ *      resolves to this snapshot.
+ *   2. `newLineNumber` reported on a heal whose `sourceFile` resolves to
+ *      this snapshot.
+ *   3. `null` (link emitted without a line suffix).
+ */
+function findLineNumberForSnapshot(snap, heals, cwd) {
+    const normSnap = path.normalize(snap.absolutePath);
+    for (const heal of heals) {
+        if (heal.definitionSite) {
+            const defAbs = path.isAbsolute(heal.definitionSite.file)
+                ? path.normalize(heal.definitionSite.file)
+                : path.normalize(path.resolve(cwd, heal.definitionSite.file));
+            if (defAbs === normSnap && heal.definitionSite.line > 0) {
+                return heal.definitionSite.line;
+            }
+        }
+    }
+    for (const heal of heals) {
+        const healAbs = path.isAbsolute(heal.sourceFile)
+            ? path.normalize(heal.sourceFile)
+            : path.normalize(path.resolve(cwd, heal.sourceFile));
+        if (healAbs === normSnap && heal.newLineNumber > 0) {
+            return heal.newLineNumber;
+        }
+    }
+    return null;
+}
+function randomTag() {
+    return Math.random().toString(36).slice(2, 8);
+}