iterate-plugin 3.5.6 → 3.6.0

package/dist/tools/fix.js

@@ -18,9 +18,10 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import { writeJsonAtomic, writeTextAtomic } from "../atomic-fs.js";
-import { dirname, join, sep } from 'node:path';
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { withProjectLock } from "../file-lock.js";
 import { runWithJob } from "../jobs.js";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
@@ -47,11 +48,27 @@ export function fixId(finding) {
     const key = `${finding.file}|${finding.dimension}|${finding.line ?? 0}|${finding.summary}`;
     return `fix-${hashString(key)}`;
 }
+/**
+ * Exact-alignment budget for the changed middle block: a dynamic-programming
+ * LCS pass over `m × n` cells. Beyond these bounds diffLines falls back to the
+ * legacy single-hunk report (coarser counts, but never a hang), so a
+ * pathological multi-thousand-line input cannot stall the tool loop.
+ */
+export const DIFF_MAX_REGION_CELLS = 20_000;
+export const DIFF_MAX_REGION_LINES = 5_000;
 /**
  * Compute a minimal line diff between two texts.
- * Returns an array of hunks (empty when unchanged). Uses common-prefix/suffix
- * trimming then reports the changed middle block — sufficient and deterministic
- * for the small atomic edits this toolchain produces.
+ * Returns an array of hunks (empty when unchanged).
+ *
+ * Common prefix/suffix are trimmed first, then the changed middle block is
+ * aligned EXACTLY (suffix-LCS dynamic programming, bounded by
+ * DIFF_MAX_REGION_CELLS / DIFF_MAX_REGION_LINES) and split into one hunk per
+ * run of changed lines separated by unchanged lines. This keeps counts honest:
+ * changing line 1 AND line 100 of a 200-line file reports {added:2, removed:2}
+ * across two hunks, not {100,100} for the whole span — the atomic `max_lines`
+ * gate and the persisted FixRecord line counts are derived from these numbers.
+ * When the region exceeds the budget, the old single-hunk behavior is kept so
+ * huge inputs degrade to coarse-but-correct counts instead of hanging.
  */
 export function diffLines(before, after) {
     const a = before.split('\n');
@@ -69,6 +86,13 @@ export function diffLines(before, after) {
     const added = b.slice(start, endB);
     if (removed.length === 0 && added.length === 0)
         return [];
+    return alignRegion(removed, added, start) ?? singleRegionHunk(removed, added, start);
+}
+/**
+ * Legacy single-hunk report for the trimmed changed block (also the bounded
+ * fallback when `alignRegion` refuses an over-budget region).
+ */
+function singleRegionHunk(removed, added, start) {
     const contentLines = [];
     for (const line of removed)
         contentLines.push(`- ${line}`);
@@ -84,6 +108,81 @@ export function diffLines(before, after) {
         },
     ];
 }
+/**
+ * Exactly align the trimmed changed block and split it into per-spot hunks
+ * (each maximal run of changed lines, separated by at least one unchanged
+ * line). Returns `null` when the region exceeds the DP budget so the caller
+ * can fall back to {@link singleRegionHunk}.
+ *
+ * Hunk coordinates follow GNU `diff -U0` conventions: for a pure insertion
+ * `oldStart` is the line BEFORE the insertion point (oldLines = 0), for a pure
+ * deletion `newStart` is the line before the deletion point (newLines = 0),
+ * and for a replacement both point at the replaced line.
+ */
+function alignRegion(removed, added, start) {
+    const m = removed.length;
+    const n = added.length;
+    if (m > DIFF_MAX_REGION_LINES || n > DIFF_MAX_REGION_LINES || m * n > DIFF_MAX_REGION_CELLS)
+        return null;
+    // dp[i][j] = LCS length of removed[i..] / added[j..] (suffix table).
+    const stride = n + 1;
+    const dp = new Int32Array((m + 1) * stride);
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            dp[i * stride + j] = removed[i] === added[j]
+                ? dp[(i + 1) * stride + j + 1] + 1
+                : Math.max(dp[(i + 1) * stride + j], dp[i * stride + j + 1]);
+        }
+    }
+    const hunks = [];
+    let open = null;
+    const closeHunk = () => {
+        if (!open)
+            return;
+        hunks.push({
+            // oldLines > 0 → first removed line (1-based); pure insertion → the
+            // line before the insertion point (= its 0-based index).
+            oldStart: start + open.iOpen + (open.oldLines > 0 ? 1 : 0),
+            oldLines: open.oldLines,
+            newStart: start + open.jOpen + (open.newLines > 0 ? 1 : 0),
+            newLines: open.newLines,
+            content: open.content.join('\n'),
+        });
+        open = null;
+    };
+    let i = 0; // region index into removed
+    let j = 0; // region index into added
+    while (i < m || j < n) {
+        // A matching pair always belongs to SOME optimal alignment (CLRS
+        // x_i = y_j ⇒ LCS(i,j) = 1 + LCS(i+1,j+1)), so greedily closing the
+        // current hunk here is exact, not heuristic.
+        if (i < m && j < n && removed[i] === added[j]) {
+            closeHunk();
+            i++;
+            j++;
+            continue;
+        }
+        // Diverged: consume whichever side the suffix table says costs less.
+        // Ties prefer removal so a plain replacement reads `- old / + new`.
+        const takeRemoved = i >= m ? false : j >= n ? true : dp[(i + 1) * stride + j] >= dp[i * stride + j + 1];
+        if (takeRemoved) {
+            if (!open)
+                open = { iOpen: i, jOpen: j, oldLines: 0, newLines: 0, content: [] };
+            open.oldLines++;
+            open.content.push(`- ${removed[i]}`);
+            i++;
+        }
+        else {
+            if (!open)
+                open = { iOpen: i, jOpen: j, oldLines: 0, newLines: 0, content: [] };
+            open.newLines++;
+            open.content.push(`+ ${added[j]}`);
+            j++;
+        }
+    }
+    closeHunk();
+    return hunks;
+}
 /** Added/removed line counts for a change (derived from diffLines). */
 export function countChangedLines(before, after) {
     const hunks = diffLines(before, after);
@@ -124,11 +223,17 @@ export function readRegistry(projectRoot) {
         // contain a round without a `records` array, or records that are missing
         // their id / finding object — all of which would make readers
         // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+        // Numeric counters are also floored to non-negative integers: the status
+        // output schema declares them `type: 'integer'`, so a `fixedCount: 1.5`
+        // must never reach iterate_status.
+        const intCount = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
         parsed.rounds = parsed.rounds
             .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
             .map((r) => ({
             ...r,
             round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+            fixedCount: intCount(r.fixedCount),
+            failedCount: intCount(r.failedCount),
             records: r.records.filter((rec) => !!rec &&
                 typeof rec === 'object' &&
                 typeof rec.id === 'string' &&
@@ -151,12 +256,18 @@ export function findFixRecord(registry, id) {
     }
     return undefined;
 }
-/** All fix records for a file, in chronological order. */
+/**
+ * All fix records for a file, in chronological order.
+ * Both sides are canonicalized with {@link normalizeProjectPath} so a record
+ * persisted as `./README.md` (pre-normalization builds) still matches a
+ * query for `README.md` and vice versa.
+ */
 export function recordsForFile(registry, file) {
+    const want = normalizeProjectPath(file);
     const out = [];
     for (const round of registry.rounds) {
         for (const r of round.records) {
-            if (r.finding.file === file && r.success)
+            if (normalizeProjectPath(r.finding.file) === want && r.success)
                 out.push(r);
         }
     }
@@ -242,6 +353,63 @@ export function resolveProjectFile(projectRoot, file) {
     }
     return { ok: true, resolved };
 }
+/**
+ * Canonicalize a model-supplied relative path ONCE at argument intake.
+ *
+ * Strips a leading `./`, collapses duplicate separators, and resolves `.` /
+ * `..` segments lexically so the containment check, the protected-path glob,
+ * the persisted FixRecord, and every later diff/rollback lookup all compare
+ * the SAME string — a raw `./README.md` must not dodge a `README.md` veto
+ * glob, and `src/../README.md` must record as `README.md`.
+ * Absolute paths and `..` escapes survive normalization and are rejected by
+ * {@link resolveProjectFile} afterwards. Pure, exported for unit tests.
+ */
+export function normalizeProjectPath(file) {
+    // An empty intake must stay empty (node's normalize('') === '.') so
+    // resolveProjectFile still rejects it instead of resolving to the root.
+    if (typeof file !== 'string' || file === '')
+        return '';
+    return normalize(file);
+}
+/**
+ * Validate a registry-recorded backup path before it is read (iterate_diff)
+ * or used to overwrite a project file (iterate_rollback).
+ *
+ * The registry is a plain JSON file on disk: a hand-edited/corrupt record can
+ * point `backupPath` anywhere, turning diff into an arbitrary-file read and
+ * rollback into arbitrary-content injection. A backup must stay inside the
+ * project's fixes directory — lexically AND via realpath when it exists (so a
+ * symlink planted inside `.iterate/fixes` cannot smuggle content either).
+ */
+export function resolveBackupPath(projectRoot, backupPath) {
+    if (typeof backupPath !== 'string' || backupPath.trim().length === 0) {
+        return { ok: false, reason: 'backup path is missing from the fix record' };
+    }
+    const fixes = fixesDir(projectRoot);
+    // Relative entries are anchored at the project root (never the process cwd)
+    // so `../../etc/passwd` fails the containment check below.
+    const resolved = isAbsolute(backupPath) ? normalize(backupPath) : join(projectRoot, backupPath);
+    const prefix = fixes.endsWith(sep) ? fixes : fixes + sep;
+    if (resolved !== fixes && !resolved.startsWith(prefix)) {
+        return { ok: false, reason: `backup path escapes the fixes directory: ${backupPath}` };
+    }
+    if (existsSync(resolved)) {
+        let realFixes;
+        let real;
+        try {
+            realFixes = realpathSync(fixes);
+            real = realpathSync(resolved);
+        }
+        catch {
+            return { ok: false, reason: `failed to resolve real path for backup containment check: ${backupPath}` };
+        }
+        const realPrefix = realFixes.endsWith(sep) ? realFixes : realFixes + sep;
+        if (real !== realFixes && !real.startsWith(realPrefix)) {
+            return { ok: false, reason: `backup path escapes the fixes directory (symlink): ${backupPath}` };
+        }
+    }
+    return { ok: true, resolved };
+}
 // ─── Shared execute helpers ──────────────────────────────────────────────────
 /**
  * Minimal glob matcher for personalization.protected_paths.
@@ -381,9 +549,15 @@ export function registerFixTool(ctx) {
                 const { config } = loadEffectiveConfig(projectRoot);
                 const maxLines = config.atomic?.max_lines ?? 20;
                 const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
-                const file = typeof args.file === 'string' ? args.file : '';
-                if (!file)
+                // Canonicalize ONCE at intake: `./README.md` and `src/../README.md`
+                // must behave exactly like `README.md` downstream — the protected-path
+                // glob, the fix id, the persisted FixRecord, and later diff/rollback
+                // lookups all compare this normalized form (escapes/absolute paths
+                // survive normalization and are rejected by resolveProjectFile).
+                const rawFile = typeof args.file === 'string' ? args.file : '';
+                if (!rawFile)
                     return { ok: false, error: 'file is required' };
+                const file = normalizeProjectPath(rawFile);
                 if (typeof args.content !== 'string')
                     return { ok: false, error: 'content must be a string' };
                 if (args.content.length > MAX_FIX_CONTENT_CHARS) {
@@ -395,21 +569,23 @@ export function registerFixTool(ctx) {
                 if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
                     return { ok: false, error: 'round must be a positive integer' };
                 }
-                const finding = args.finding;
-                if (!finding || typeof finding !== 'object') {
+                const rawFinding = args.finding;
+                if (!rawFinding || typeof rawFinding !== 'object') {
                     return { ok: false, error: 'finding must be an object' };
                 }
-                if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
+                if (typeof rawFinding.file !== 'string' || rawFinding.file.trim().length === 0) {
                     return { ok: false, error: 'finding.file must be a non-empty string' };
                 }
-                if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
+                if (typeof rawFinding.dimension !== 'string' || rawFinding.dimension.trim().length === 0) {
                     return { ok: false, error: 'finding.dimension must be a non-empty string' };
                 }
                 // The finding must reference the file being fixed — the fix id and the
                 // rollback/diff target are derived from finding.file, so a mismatch
-                // would back up/restore the WRONG file.
+                // would back up/restore the WRONG file. Both sides are compared in
+                // their NORMALIZED form (`./src/a.ts` and `src/a.ts` are the same fix).
+                const finding = { ...rawFinding, file: normalizeProjectPath(rawFinding.file) };
                 if (finding.file !== file) {
-                    return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
+                    return { ok: false, error: `finding.file ("${rawFinding.file}") must match the file being fixed ("${rawFile}")` };
                 }
                 // Full finding validation, mirroring the review schema: malformed
                 // findings would produce lossy registry/log entries and a degraded id.
@@ -448,90 +624,102 @@ export function registerFixTool(ctx) {
                     };
                 }
                 const id = fixId(finding);
-                const registry = readRegistry(projectRoot);
-                if (findFixRecord(registry, id)) {
-                    return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
-                }
-                // No-op guard: content-identical "fixes" (e.g. a fixer that re-sent the
-                // file unchanged) must never burn a backup, a write, or a registry/success
-                // record. Placed after the registry check so a re-sent fix of an id that
-                // was ALREADY fixed is still reported as "already fixed this run".
-                if (added === 0 && removed === 0) {
-                    return {
-                        ok: false,
-                        error: `no changes: the supplied content for ${file} is identical to the current content — apply a real edit`,
-                    };
-                }
-                const target = resolveProjectFile(projectRoot, file);
-                if (!target.ok)
-                    return { ok: false, error: target.reason };
-                // Personalization guards (SKILL.md Phase 2): protected_paths veto the
-                // fix outright; forbidden_fixes veto fix approaches appearing in the
-                // new content. Both are security-relevant, so they are enforced here
-                // in the tool, not left to the model.
-                const pers = config.personalization;
-                const protectedPaths = Array.isArray(pers?.protected_paths)
-                    ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
-                    : [];
-                for (const pattern of protectedPaths) {
-                    if (globMatch(file, pattern)) {
-                        return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
-                    }
-                }
-                const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
-                    ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
-                    : [];
-                for (const forbidden of forbiddenFixes) {
-                    if (args.content.includes(forbidden)) {
-                        return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
-                    }
-                }
                 const timestamp = new Date().toISOString();
-                const backupPath = fixBackupPath(projectRoot, id, timestamp);
-                try {
-                    mkdirSync(fixesDir(projectRoot), { recursive: true });
-                    copyFileSync(target.resolved, backupPath);
-                }
-                catch (err) {
-                    return { ok: false, error: `failed to create backup: ${String(err)}` };
-                }
-                try {
-                    writeTextAtomic(target.resolved, args.content);
-                }
-                catch (err) {
-                    return { ok: false, error: `failed to write file: ${String(err)}` };
-                }
-                const record = {
-                    id,
-                    timestamp,
-                    round: args.round,
-                    finding,
-                    backupPath,
-                    diffSummary: buildDiffSummary(hunks),
-                    linesAdded: added,
-                    linesRemoved: removed,
-                    success: true,
-                };
-                const nextRegistry = upsertRecord(registry, record);
-                try {
-                    writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
-                }
-                catch (err) {
-                    // Registry write failed → the file was already modified but no record
-                    // exists, so a later rollback/diff could never see it and a retry would
-                    // back up the already-fixed content as "original". Restore the file
-                    // from the backup atomically to leave the tree exactly as it was.
-                    try {
-                        writeTextAtomic(target.resolved, readFileSync(backupPath, 'utf-8'));
+                // Cross-process read-modify-write guard: the registry read (dup check)
+                // and the record write form ONE window — two plugin processes racing
+                // here could each read the old registry and silently drop the other's
+                // update. The shared advisory lock (src/file-lock.ts) serializes the
+                // window; the decision-log append runs after it is released.
+                const applied = withProjectLock(projectRoot, 'fix-registry', () => {
+                    const registry = readRegistry(projectRoot);
+                    if (findFixRecord(registry, id)) {
+                        return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
                     }
-                    catch (restoreErr) {
+                    // No-op guard: content-identical "fixes" (e.g. a fixer that re-sent the
+                    // file unchanged) must never burn a backup, a write, or a registry/success
+                    // record. Placed after the registry check so a re-sent fix of an id that
+                    // was ALREADY fixed is still reported as "already fixed this run".
+                    if (added === 0 && removed === 0) {
                         return {
                             ok: false,
-                            error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                            error: `no changes: the supplied content for ${file} is identical to the current content — apply a real edit`,
                         };
                     }
-                    return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
-                }
+                    const target = resolveProjectFile(projectRoot, file);
+                    if (!target.ok)
+                        return { ok: false, error: target.reason };
+                    // Personalization guards (SKILL.md Phase 2): protected_paths veto the
+                    // fix outright; forbidden_fixes veto fix approaches appearing in the
+                    // new content. Both are security-relevant, so they are enforced here
+                    // in the tool, not left to the model. The glob runs against the
+                    // NORMALIZED `file`, so `./README.md` cannot dodge a `README.md` veto.
+                    const pers = config.personalization;
+                    const protectedPaths = Array.isArray(pers?.protected_paths)
+                        ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
+                        : [];
+                    for (const pattern of protectedPaths) {
+                        if (globMatch(file, pattern)) {
+                            return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+                        }
+                    }
+                    const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
+                        ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
+                        : [];
+                    for (const forbidden of forbiddenFixes) {
+                        if (args.content.includes(forbidden)) {
+                            return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                        }
+                    }
+                    const backupPath = fixBackupPath(projectRoot, id, timestamp);
+                    try {
+                        mkdirSync(fixesDir(projectRoot), { recursive: true });
+                        copyFileSync(target.resolved, backupPath);
+                    }
+                    catch (err) {
+                        return { ok: false, error: `failed to create backup: ${String(err)}` };
+                    }
+                    try {
+                        writeTextAtomic(target.resolved, args.content);
+                    }
+                    catch (err) {
+                        return { ok: false, error: `failed to write file: ${String(err)}` };
+                    }
+                    const record = {
+                        id,
+                        timestamp,
+                        round: args.round,
+                        finding,
+                        backupPath,
+                        diffSummary: buildDiffSummary(hunks),
+                        linesAdded: added,
+                        linesRemoved: removed,
+                        success: true,
+                    };
+                    const nextRegistry = upsertRecord(registry, record);
+                    try {
+                        writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
+                    }
+                    catch (err) {
+                        // Registry write failed → the file was already modified but no record
+                        // exists, so a later rollback/diff could never see it and a retry would
+                        // back up the already-fixed content as "original". Restore the file
+                        // from the backup atomically to leave the tree exactly as it was.
+                        try {
+                            writeTextAtomic(target.resolved, readFileSync(backupPath, 'utf-8'));
+                        }
+                        catch (restoreErr) {
+                            return {
+                                ok: false,
+                                error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                            };
+                        }
+                        return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
+                    }
+                    return { ok: true, record, backupPath };
+                });
+                if (!applied.ok)
+                    return applied;
+                const { record, backupPath } = applied;
                 const logRes = appendDecisionEntry(projectRoot, {
                     timestamp,
                     round: args.round,
@@ -615,18 +803,26 @@ export function registerDiffTool(ctx) {
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;
             const registry = readRegistry(projectRoot);
-            const file = typeof args.file === 'string' && args.file.trim() ? args.file : undefined;
+            const file = typeof args.file === 'string' && args.file.trim()
+                ? normalizeProjectPath(args.file)
+                : undefined;
             if (file) {
                 const records = recordsForFile(registry, file);
                 const first = records[0];
                 if (!first)
                     return { ok: false, error: `no fixes recorded for ${file}` };
+                // Containment: the registry is on-disk JSON that a hand edit can
+                // point anywhere — a tampered backupPath must never turn this
+                // read-only diff into an arbitrary-file read.
+                const backup = resolveBackupPath(projectRoot, first.backupPath);
+                if (!backup.ok)
+                    return { ok: false, error: `invalid backup for ${file}: ${backup.reason}` };
                 const current = readProjectFile(projectRoot, file);
                 if (!current.ok)
                     return { ok: false, error: current.reason };
                 let original = '';
                 try {
-                    original = readFileSync(first.backupPath, 'utf-8');
+                    original = readFileSync(backup.resolved, 'utf-8');
                 }
                 catch (err) {
                     return { ok: false, error: `backup missing for ${file}: ${String(err)}` };
@@ -727,31 +923,63 @@ export function registerRollbackTool(ctx) {
             const id = typeof args.id === 'string' ? args.id : '';
             if (!id)
                 return { ok: false, error: 'id is required' };
-            const registry = readRegistry(projectRoot);
-            const record = findFixRecord(registry, id);
-            if (!record)
-                return { ok: false, error: `fix not found: ${id}` };
-            if (!existsSync(record.backupPath)) {
-                return { ok: false, error: `backup missing for fix ${id}` };
-            }
-            const target = resolveProjectFile(projectRoot, record.finding.file);
-            if (!target.ok)
-                return { ok: false, error: target.reason };
-            try {
-                // Atomic restore: never leave a truncated source file if we crash
-                // mid-restore (matches the writeTextAtomic guarantee used by apply).
-                writeTextAtomic(target.resolved, readFileSync(record.backupPath, 'utf-8'));
-            }
-            catch (err) {
-                return { ok: false, error: `failed to restore backup: ${String(err)}` };
-            }
-            const nextRegistry = removeRecord(registry, id);
-            try {
-                writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
-            }
-            catch (err) {
-                return { ok: false, error: `failed to update fix registry: ${String(err)}` };
-            }
+            // One locked read-modify-write window (see src/file-lock.ts): the
+            // registry read, the file restore, and the record removal must not
+            // interleave with another process's fix/rollback or the update is lost.
+            const restored = withProjectLock(projectRoot, 'fix-registry', () => {
+                const registry = readRegistry(projectRoot);
+                const record = findFixRecord(registry, id);
+                if (!record)
+                    return { ok: false, error: `fix not found: ${id}` };
+                // LIFO safety: restoring an OLDER backup would silently destroy every
+                // NEWER successful fix to the same file — their records would stay
+                // success:true while the bytes they wrote are gone. Refuse and name
+                // the clobbered ids so the caller can roll back in reverse order first.
+                const fileRecords = recordsForFile(registry, record.finding.file);
+                const targetIdx = fileRecords.findIndex((r) => r.id === id);
+                const newer = targetIdx >= 0
+                    ? fileRecords.slice(targetIdx + 1)
+                    : fileRecords.filter((r) => r.id !== id && r.timestamp > record.timestamp);
+                if (newer.length > 0) {
+                    const clobbered = newer.map((r) => r.id).join(', ');
+                    return {
+                        ok: false,
+                        error: `rollback refused: fix ${id} is older than fix(es) ${clobbered} on ${record.finding.file} — ` +
+                            'restoring its backup would destroy them. Roll back the later fix(es) first (LIFO order).',
+                    };
+                }
+                // Containment: the registry is on-disk JSON that a hand edit can
+                // point anywhere — a tampered backupPath must never inject arbitrary
+                // content into the project file.
+                const backup = resolveBackupPath(projectRoot, record.backupPath);
+                if (!backup.ok)
+                    return { ok: false, error: `invalid backup for fix ${id}: ${backup.reason}` };
+                if (!existsSync(backup.resolved)) {
+                    return { ok: false, error: `backup missing for fix ${id}` };
+                }
+                const target = resolveProjectFile(projectRoot, record.finding.file);
+                if (!target.ok)
+                    return { ok: false, error: target.reason };
+                try {
+                    // Atomic restore: never leave a truncated source file if we crash
+                    // mid-restore (matches the writeTextAtomic guarantee used by apply).
+                    writeTextAtomic(target.resolved, readFileSync(backup.resolved, 'utf-8'));
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to restore backup: ${String(err)}` };
+                }
+                const nextRegistry = removeRecord(registry, id);
+                try {
+                    writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to update fix registry: ${String(err)}` };
+                }
+                return { ok: true, record };
+            });
+            if (!restored.ok)
+                return restored;
+            const record = restored.record;
             const logRes = appendDecisionEntry(projectRoot, {
                 timestamp: new Date().toISOString(),
                 round: record.round,