@indigoai-us/hq-cloud 6.11.11 → 6.11.13

package/dist/cli/rescue-core.js

@@ -616,6 +616,7 @@ function doRescue(cfg, env, out, err, setTmp) {
         unchangedList,
         appendLog,
         out,
+        decisions: [],
         actions: [],
     };
     // --- Pre-operation safety snapshot (BEFORE any destructive op) ---
@@ -645,16 +646,19 @@ function doRescue(cfg, env, out, err, setTmp) {
         out(`    snapshot complete (restore any file: cp "${backupDir}/<relpath>" "${hqRoot}/<relpath>")\n`);
     }
     // --- Walk + classify (PHASE 1: read-only) ---
-    // Classification mutates nothing on disk: every destructive op (delete,
-    // rescue-move, conflict-quarantine, symlink-drop) is recorded as a deferred
-    // closure in `ctx.actions` and executed later (PHASE 2). This is the
+    // Classification mutates nothing on disk: every outcome is recorded as a
+    // typed RescueDecision. Destructive ops (delete, rescue-move,
+    // conflict-quarantine, symlink-drop) are built from those decisions and
+    // executed later (PHASE 2). This is the
     // ordering-safety invariant: if classification throws partway through the
     // wipe set (e.g. an unreadable entry, a future unhandled file shape), it
-    // aborts HERE — before a single file has been touched — instead of leaving a
-    // half-applied wipe like the pre-port bash classifier did (DEV-1767:
+    // aborts HERE — before a single file has been touched or even queued as a
+    // filesystem closure — instead of leaving a half-applied wipe like the
+    // pre-port bash classifier did (DEV-1767:
     // `Error: Path is a directory` on a nested dir-symlink, thrown after ~10 core
-    // files were already deleted). Dry-run runs this exact same pass and then
-    // returns, so the `--check` plan can never miss a condition the live pass hits.
+    // files were already deleted). Dry-run renders each typed decision inline as
+    // the walk records it, preserving the legacy progress/fault timing while
+    // still sharing the same classify path as the live pass.
     out("\n");
     if (wipeToplevel.length === 0) {
         out("==> Wipe set is empty; nothing to process or overlay.\n");
@@ -734,8 +738,8 @@ function doRescue(cfg, env, out, err, setTmp) {
     // Actions run in classification (walk) order — the same order the old
     // interleaved walk mutated in — so per-file output and on-disk results are
     // unchanged versus before the two-phase split.
-    for (const act of ctx.actions)
-        act();
+    ctx.actions = buildRescueActions(ctx);
+    applyClassifiedActions(ctx, backupDir);
     // --- Back up preserve-subpaths to a mktemp shuttle ---
     const shuttle = path.join(tmpdir, "preserve");
     fs.mkdirSync(shuttle, { recursive: true });
@@ -966,6 +970,152 @@ function doRescue(cfg, env, out, err, setTmp) {
     }
     return { status: 0 };
 }
+function recordDecision(ctx, decision) {
+    ctx.decisions.push(decision);
+    if (ctx.cfg.dryRun)
+        renderDryRunDecision(ctx, decision);
+    switch (decision.kind) {
+        case "drop-reindex-symlink":
+            ctx.counts.symlinkDropped += 1;
+            return;
+        case "user-only":
+            ctx.counts.userOnly += 1;
+            return;
+        case "cloud-symlink-reconciled":
+            ctx.counts.cloudSymlinkReconciled += 1;
+            return;
+        case "drift-reconciled":
+            ctx.counts.driftReconciled += 1;
+            return;
+        case "unchanged-preserve":
+        case "unchanged-delete":
+            ctx.counts.unchanged += 1;
+            return;
+        default:
+            return;
+    }
+}
+function applyClassifiedActions(ctx, backupDir) {
+    const completed = [];
+    for (const action of ctx.actions) {
+        try {
+            action.run();
+            completed.push(action);
+        }
+        catch (err) {
+            const restored = rollbackCompletedActions(ctx, completed, backupDir);
+            const manifest = writeApplyFailureManifest(ctx, backupDir, action, completed, restored, err);
+            ctx.out("\n");
+            ctx.out(`error: rescue apply failed during '${action.label}'.\n`);
+            if (restored.length > 0) {
+                ctx.out(`==> Rolled back ${restored.length} prior action path(s) from the safety snapshot.\n`);
+            }
+            if (manifest) {
+                ctx.out(`==> Recovery manifest: ${manifest}\n`);
+            }
+            throw err;
+        }
+    }
+}
+function rollbackCompletedActions(ctx, completed, backupDir) {
+    if (!backupDir || !isDir(backupDir))
+        return [];
+    const rels = [];
+    const seen = new Set();
+    for (let i = completed.length - 1; i >= 0; i--) {
+        const action = completed[i];
+        for (let j = action.affectedRels.length - 1; j >= 0; j--) {
+            const rel = action.affectedRels[j];
+            if (rel && !seen.has(rel)) {
+                seen.add(rel);
+                rels.push(rel);
+            }
+        }
+    }
+    const restored = [];
+    for (const rel of rels) {
+        const snapshotPath = path.join(backupDir, rel);
+        if (!lexists(snapshotPath))
+            continue;
+        const dest = path.join(ctx.hqRoot, rel);
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.rmSync(dest, { recursive: true, force: true });
+            cpATo(snapshotPath, dest);
+            restored.push(rel);
+        }
+        catch {
+            // Recovery manifest below records any path that could not be restored.
+        }
+    }
+    return restored;
+}
+function writeApplyFailureManifest(ctx, backupDir, failedAction, completed, restored, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const completedLines = completed.length === 0
+        ? ["  (none)"]
+        : completed.map((action) => {
+            const paths = action.affectedRels.length > 0 ? action.affectedRels.join(", ") : "(no filesystem path)";
+            return `  - ${action.label}: ${paths}`;
+        });
+    const restoredSet = new Set(restored);
+    const unrestored = completed
+        .flatMap((action) => action.affectedRels)
+        .filter((rel, idx, arr) => rel && arr.indexOf(rel) === idx && !restoredSet.has(rel));
+    const lines = [];
+    lines.push("# HQ rescue apply recovery", "");
+    lines.push(`Created: ${ctx.runTs}`);
+    lines.push(`HQ root: ${ctx.hqRoot}`);
+    lines.push(`Source: ${ctx.cfg.sourceRepo}@${ctx.cfg.ref} (${ctx.srcSha})`);
+    lines.push(`Failed action: ${failedAction.label}`);
+    lines.push(`Error: ${message}`);
+    lines.push("");
+    lines.push("## Completed Before Failure");
+    lines.push(...completedLines);
+    lines.push("");
+    lines.push("## Failed Action Paths");
+    if (failedAction.affectedRels.length > 0) {
+        for (const rel of failedAction.affectedRels)
+            lines.push(`  - ${rel}`);
+    }
+    else {
+        lines.push("  (no filesystem path)");
+    }
+    lines.push("");
+    lines.push("## Rollback");
+    if (restored.length > 0) {
+        lines.push("Restored from the pre-op safety snapshot:");
+        for (const rel of restored)
+            lines.push(`  - ${rel}`);
+    }
+    else {
+        lines.push("No completed action paths were restored automatically.");
+    }
+    if (unrestored.length > 0) {
+        lines.push("", "Completed action paths still requiring review:");
+        for (const rel of unrestored)
+            lines.push(`  - ${rel}`);
+    }
+    if (backupDir && isDir(backupDir)) {
+        lines.push("");
+        lines.push("Manual restore examples:");
+        lines.push(`  cp "${backupDir}/<relpath>" "${ctx.hqRoot}/<relpath>"`);
+        lines.push(`  rsync -a "${backupDir}/" "${ctx.hqRoot}/"`);
+    }
+    else {
+        lines.push("", "No pre-op safety snapshot was available for automatic restore.");
+    }
+    const manifestDir = path.join(ctx.hqRoot, ".hq", "rescue-recovery");
+    const manifestPath = path.join(manifestDir, `rescue-apply-failure-${ctx.runTs}.md`);
+    try {
+        fs.mkdirSync(manifestDir, { recursive: true });
+        fs.writeFileSync(manifestPath, lines.join("\n") + "\n");
+        return manifestPath;
+    }
+    catch {
+        return null;
+    }
+}
 // --- Rescue-target mapping ---
 function mapRescueTarget(rel) {
     if (rel === ".claude/CLAUDE.md")
@@ -994,18 +1144,18 @@ function isOverwriteSafe(rel) {
         rel === "core/docs/hq/USER-GUIDE.md" ||
         rel === "core/policies/_digest.md");
 }
-function isMasterSyncSymlink(localPath) {
+function masterSyncSymlinkTarget(localPath) {
     const st = lstatOrNull(localPath);
     if (!st || !st.isSymbolicLink())
-        return false;
+        return null;
     let tgt = "";
     try {
         tgt = fs.readlinkSync(localPath);
     }
     catch {
-        return false;
+        return null;
     }
-    return tgt.includes("/personal/") || tgt.startsWith("personal/");
+    return tgt.includes("/personal/") || tgt.startsWith("personal/") ? tgt : null;
 }
 function isUnderPreserve(cfg, rel) {
     for (const sp of cfg.preserveSubpaths) {
@@ -1257,14 +1407,13 @@ function conflictOne(ctx, rel) {
     ctx.out(`    conflicted: ${rel}  ->  ${destRel}\n`);
     ctx.appendLog(`conflicted\t${rel}\t-> ${destRel}\n`);
 }
-// --- classify + act on one file (the per-file workhorse) ---
+// --- classify one file (the per-file workhorse) ---
 //
-// Read-only by contract: this records intent (counts + dry-run plan lines +
-// deferred `ctx.actions` closures) but never mutates the filesystem itself. The
-// closures are run later by the PHASE 2 apply loop, only once the whole wipe
-// set has classified without throwing. Keep it that way — a stray `fs.rmSync`
-// here re-opens the half-applied-wipe hole this split closed (DEV-1767).
-function processOne(ctx, rel) {
+// Read-only by contract: this returns a RescueDecision only. It does not render
+// dry-run text, update action queues, or mutate the filesystem. Dry-run text is
+// rendered by recordDecision, and PHASE 2 action building happens only once the
+// whole wipe set has classified without throwing. Keep it that way.
+function classifyOne(ctx, rel) {
     const { cfg } = ctx;
     const localPath = path.join(ctx.hqRoot, rel);
     const srcPath = path.join(ctx.srcDir, rel);
@@ -1274,51 +1423,24 @@ function processOne(ctx, rel) {
         throw new Error(`rescue classifier fault injected at ${rel} (HQ_RESCUE_FAULT_AT_REL)`);
     }
     if (isUnderPreserve(cfg, rel))
-        return;
+        return { kind: "skip", rel };
     // Conflict-resolution artifacts (`<name>.conflict-<ts>-<peer>.<ext>`).
     const base = rel.includes("/") ? rel.slice(rel.lastIndexOf("/") + 1) : rel;
     if (/\.conflict-/.test(base)) {
-        if (cfg.dryRun) {
-            ctx.out(`    drop conflict artifact: ${rel}\n`);
-        }
-        else {
-            ctx.actions.push(() => fs.rmSync(localPath, { force: true }));
-        }
-        return;
+        return { kind: "drop-conflict-artifact", rel };
     }
     // Script-managed files: core/core.yaml + legacy core.yaml.
     if (rel === "core/core.yaml" || rel === "core.yaml") {
-        if (cfg.dryRun) {
-            ctx.out(`    skip script-managed (rewrites at stamp step): ${rel}\n`);
-        }
-        else {
-            ctx.actions.push(() => fs.rmSync(localPath, { force: true }));
-        }
-        return;
+        return { kind: "drop-script-managed", rel };
     }
     // Symlinks (mid-tree).
     const lst = lstatOrNull(localPath);
     if (lst && lst.isSymbolicLink()) {
-        if (isMasterSyncSymlink(localPath)) {
-            ctx.counts.symlinkDropped += 1;
-            if (cfg.dryRun) {
-                let tgt = "";
-                try {
-                    tgt = fs.readlinkSync(localPath);
-                }
-                catch {
-                    /* ignore */
-                }
-                ctx.out(`    drop reindex symlink: ${rel}  ->  ${tgt}\n`);
-            }
-            else {
-                ctx.actions.push(() => {
-                    fs.rmSync(localPath, { force: true });
-                    ctx.appendLog(`symlink-dropped\t${rel}\t(reindex regenerable)\n`);
-                });
-            }
+        const target = masterSyncSymlinkTarget(localPath);
+        if (target !== null) {
+            return { kind: "drop-reindex-symlink", rel, target };
         }
-        return;
+        return { kind: "skip", rel };
     }
     // Is path in upstream HEAD?
     const inHead = existsFollow(srcPath) ? 1 : 0;
@@ -1345,10 +1467,7 @@ function processOne(ctx, rel) {
     }
     // USER-ONLY: unknown to upstream (HEAD AND floor both lack it).
     if (inHead === 0 && inFloor === 0) {
-        ctx.counts.userOnly += 1;
-        if (cfg.dryRun)
-            ctx.out(`    user-only (leave in place): ${rel}\n`);
-        return;
+        return { kind: "user-only", rel };
     }
     // Path is/was in upstream. Determine if user edited it.
     let userEdited = 0;
@@ -1373,99 +1492,154 @@ function processOne(ctx, rel) {
     }
     // Cloud-update reclassification.
     if (userEdited === 1 && isCloudFlattenedSymlinkEquiv(ctx, rel, localPath)) {
-        ctx.counts.cloudSymlinkReconciled += 1;
-        if (cfg.dryRun) {
-            ctx.out(`    cloud-symlink reconciled (unchanged): ${rel}  (hq-symlink: marker matches upstream target)\n`);
-        }
-        else {
-            ctx.actions.push(() => {
-                fs.rmSync(localPath, { force: true });
-                ctx.appendLog(`cloud-symlink-reconciled\t${rel}\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n`);
-            });
-        }
-        return;
+        return { kind: "cloud-symlink-reconciled", rel };
     }
     // Convergence guard: drifted from floor but identical to upstream HEAD.
     if (userEdited === 1 && inHead === 1 && bytesEqual(localPath, srcPath)) {
-        ctx.counts.driftReconciled += 1;
-        if (cfg.dryRun) {
-            ctx.out(`    drift reconciled (identical to upstream HEAD; no rescue): ${rel}\n`);
-        }
-        else {
-            ctx.actions.push(() => {
-                fs.rmSync(localPath, { force: true });
-                ctx.appendLog(`drift-reconciled\t${rel}\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\n`);
-            });
-        }
-        return;
+        return { kind: "drift-reconciled", rel };
     }
     if (userEdited === 1) {
-        if (cfg.dryRun) {
-            if (rel === ".claude/CLAUDE.md") {
-                ctx.out(`    user-edit (diff-append): ${rel}  ->  personal/CLAUDE.md\n`);
-                ctx.counts.userEdit += 1;
-            }
-            else if (isOverwriteSafe(rel)) {
-                ctx.out(`    user-edit (overwrite-safe): ${rel}  ->  upstream wins (no copy preserved)\n`);
-                ctx.counts.userOverwrite += 1;
-            }
-            else if (isConflictClass(rel)) {
-                ctx.out(`    user-edit (conflict): ${rel}  ->  .hq-conflicts/rescue-${ctx.runTs}/${rel}\n`);
-                ctx.counts.userConflict += 1;
-            }
-            else {
-                ctx.out(`    user-edit (rescue): ${rel}  ->  ${mapRescueTarget(rel)}\n`);
-                ctx.counts.userEdit += 1;
-            }
+        if (rel === ".claude/CLAUDE.md") {
+            return { kind: "user-edit-diff-append", rel };
         }
-        else {
-            if (rel === ".claude/CLAUDE.md") {
-                ctx.actions.push(() => rescueOne(ctx, rel));
-            }
-            else if (isOverwriteSafe(rel)) {
-                ctx.actions.push(() => {
+        if (isOverwriteSafe(rel)) {
+            return { kind: "user-edit-overwrite-safe", rel };
+        }
+        if (isConflictClass(rel)) {
+            return { kind: "user-edit-conflict", rel };
+        }
+        return { kind: "user-edit-rescue", rel, target: mapRescueTarget(rel) };
+    }
+    // user_edited=0: matches floor baseline. Split on byte-equality to HEAD.
+    if (bytesEqual(localPath, path.join(ctx.srcDir, rel))) {
+        return { kind: "unchanged-preserve", rel };
+    }
+    return { kind: "unchanged-delete", rel };
+}
+function renderDryRunDecision(ctx, decision) {
+    switch (decision.kind) {
+        case "skip":
+            break;
+        case "drop-conflict-artifact":
+            ctx.out(`    drop conflict artifact: ${decision.rel}\n`);
+            break;
+        case "drop-script-managed":
+            ctx.out(`    skip script-managed (rewrites at stamp step): ${decision.rel}\n`);
+            break;
+        case "drop-reindex-symlink":
+            ctx.out(`    drop reindex symlink: ${decision.rel}  ->  ${decision.target}\n`);
+            break;
+        case "user-only":
+            ctx.out(`    user-only (leave in place): ${decision.rel}\n`);
+            break;
+        case "cloud-symlink-reconciled":
+            ctx.out(`    cloud-symlink reconciled (unchanged): ${decision.rel}  (hq-symlink: marker matches upstream target)\n`);
+            break;
+        case "drift-reconciled":
+            ctx.out(`    drift reconciled (identical to upstream HEAD; no rescue): ${decision.rel}\n`);
+            break;
+        case "user-edit-diff-append":
+            ctx.out(`    user-edit (diff-append): ${decision.rel}  ->  personal/CLAUDE.md\n`);
+            ctx.counts.userEdit += 1;
+            break;
+        case "user-edit-overwrite-safe":
+            ctx.out(`    user-edit (overwrite-safe): ${decision.rel}  ->  upstream wins (no copy preserved)\n`);
+            ctx.counts.userOverwrite += 1;
+            break;
+        case "user-edit-conflict":
+            ctx.out(`    user-edit (conflict): ${decision.rel}  ->  .hq-conflicts/rescue-${ctx.runTs}/${decision.rel}\n`);
+            ctx.counts.userConflict += 1;
+            break;
+        case "user-edit-rescue":
+            ctx.out(`    user-edit (rescue): ${decision.rel}  ->  ${decision.target}\n`);
+            ctx.counts.userEdit += 1;
+            break;
+        case "unchanged-preserve":
+            ctx.out(`    unchanged (preserved in place): ${decision.rel}\n`);
+            break;
+        case "unchanged-delete":
+            ctx.out(`    unchanged (delete + replace): ${decision.rel}\n`);
+            break;
+        case "wholesale-replace-template":
+            ctx.out("    wholesale-replace: companies/_template (template carve-out)\n");
+            break;
+    }
+}
+function buildRescueActions(ctx) {
+    const actions = [];
+    const add = (label, affectedRels, runAction) => {
+        actions.push({ label, affectedRels, run: runAction });
+    };
+    for (const decision of ctx.decisions) {
+        const localPath = path.join(ctx.hqRoot, decision.rel);
+        switch (decision.kind) {
+            case "skip":
+            case "user-only":
+                break;
+            case "drop-conflict-artifact":
+                add(`drop conflict artifact: ${decision.rel}`, [decision.rel], () => fs.rmSync(localPath, { force: true }));
+                break;
+            case "drop-script-managed":
+                add(`drop script-managed: ${decision.rel}`, [decision.rel], () => fs.rmSync(localPath, { force: true }));
+                break;
+            case "drop-reindex-symlink":
+                add(`drop reindex symlink: ${decision.rel}`, [decision.rel], () => {
+                    fs.rmSync(localPath, { force: true });
+                    ctx.appendLog(`symlink-dropped\t${decision.rel}\t(reindex regenerable)\n`);
+                });
+                break;
+            case "cloud-symlink-reconciled":
+                add(`cloud-symlink reconciled: ${decision.rel}`, [decision.rel], () => {
+                    fs.rmSync(localPath, { force: true });
+                    ctx.appendLog(`cloud-symlink-reconciled\t${decision.rel}\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n`);
+                });
+                break;
+            case "drift-reconciled":
+                add(`drift reconciled: ${decision.rel}`, [decision.rel], () => {
+                    fs.rmSync(localPath, { force: true });
+                    ctx.appendLog(`drift-reconciled\t${decision.rel}\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\n`);
+                });
+                break;
+            case "user-edit-diff-append":
+                add(`rescue diff-append: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel));
+                break;
+            case "user-edit-overwrite-safe":
+                add(`overwrite-safe: ${decision.rel}`, [decision.rel], () => {
                     fs.rmSync(localPath, { force: true });
                     ctx.counts.userOverwrite += 1;
-                    ctx.appendLog(`overwritten\t${rel}\t(overwrite-safe; upstream wins, no copy preserved)\n`);
+                    ctx.appendLog(`overwritten\t${decision.rel}\t(overwrite-safe; upstream wins, no copy preserved)\n`);
                 });
-            }
-            else if (isConflictClass(rel)) {
-                ctx.actions.push(() => conflictOne(ctx, rel));
-            }
-            else {
-                ctx.actions.push(() => rescueOne(ctx, rel));
-            }
-        }
-    }
-    else {
-        // user_edited=0: matches floor baseline. Split on byte-equality to HEAD.
-        ctx.counts.unchanged += 1;
-        if (bytesEqual(localPath, path.join(ctx.srcDir, rel))) {
-            if (cfg.dryRun) {
-                ctx.out(`    unchanged (preserved in place): ${rel}\n`);
-            }
-            else {
-                ctx.actions.push(() => {
-                    fs.appendFileSync(ctx.unchangedList, `/${rel}\n`);
-                    ctx.appendLog(`unchanged\t${rel}\t(identical to upstream; left in place, mtime preserved)\n`);
+                break;
+            case "user-edit-conflict":
+                add(`conflict quarantine: ${decision.rel}`, [decision.rel], () => conflictOne(ctx, decision.rel));
+                break;
+            case "user-edit-rescue":
+                add(`rescue: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel));
+                break;
+            case "unchanged-preserve":
+                add(`preserve unchanged: ${decision.rel}`, [], () => {
+                    fs.appendFileSync(ctx.unchangedList, `/${decision.rel}\n`);
+                    ctx.appendLog(`unchanged\t${decision.rel}\t(identical to upstream; left in place, mtime preserved)\n`);
                 });
-            }
-        }
-        else {
-            if (cfg.dryRun) {
-                ctx.out(`    unchanged (delete + replace): ${rel}\n`);
-            }
-            else {
-                ctx.actions.push(() => {
+                break;
+            case "unchanged-delete":
+                add(`delete unchanged: ${decision.rel}`, [decision.rel], () => {
                     fs.rmSync(localPath, { force: true });
-                    ctx.appendLog(`deleted\t${rel}\t(unchanged vs baseline; re-laid by overlay if still upstream)\n`);
+                    ctx.appendLog(`deleted\t${decision.rel}\t(unchanged vs baseline; re-laid by overlay if still upstream)\n`);
                 });
-            }
+                break;
+            case "wholesale-replace-template":
+                add("wholesale-replace: companies/_template", [decision.rel], () => fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), {
+                    recursive: true,
+                    force: true,
+                }));
+                break;
         }
     }
+    return actions;
 }
 // --- walk a wipe-set root ---
-// Precompute the per-file git facts processOne needs, in two batched passes
+// Precompute the per-file git facts classifyOne needs, in two batched passes
 // instead of ~3 `git` spawns per file. Process-startup overhead (~15-20ms per
 // spawn) dominates the per-file path, so on a large wipe set this turns a
 // minutes-long classify into a seconds-long one. Behaviour is identical: the
@@ -1473,10 +1647,10 @@ function processOne(ctx, rel) {
 // rel not represented in a map falls back to its original per-file spawn.
 //
 // Mirrors walkAndProcess's enumeration so the batched set matches what actually
-// reaches processOne: it skips `companies/_template` (wholesale-replaced, never
+// reaches classifyOne: it skips `companies/_template` (wholesale-replaced, never
 // classified per-file) and top-level symlinks (dropped, never classified).
 function precomputeGitMaps(ctx, wipeToplevel) {
-    const allRels = []; // every rel that reaches processOne (files + symlinks)
+    const allRels = []; // every rel that reaches classifyOne (files + symlinks)
     const fileRels = []; // subset that are regular files (hashable)
     const fileAbs = []; // parallel to fileRels
     for (const rootRel of wipeToplevel) {
@@ -1493,7 +1667,7 @@ function precomputeGitMaps(ctx, wipeToplevel) {
                 : [];
         for (const rel of rels) {
             // A path containing a newline can't survive line-delimited batch stdin;
-            // leave it out of the maps and let processOne spawn per-file for it.
+            // leave it out of the maps and let classifyOne spawn per-file for it.
             if (rel.includes("\n"))
                 continue;
             allRels.push(rel);
@@ -1504,7 +1678,7 @@ function precomputeGitMaps(ctx, wipeToplevel) {
             }
         }
     }
-    // In head_compare mode processOne never consults these maps (it compares
+    // In head_compare mode classifyOne never consults these maps (it compares
     // bytes against the upstream working tree directly), so skip both git passes.
     if (ctx.baselineMode !== "history_floor") {
         ctx.floorShas = new Map();
@@ -1540,7 +1714,7 @@ function precomputeGitMaps(ctx, wipeToplevel) {
     }
     ctx.floorShas = floorShas;
     // Pass 2: local blob SHA, but ONLY for regular files that are in the floor.
-    // processOne reads localShas exclusively in the `inFloor === 1` branch, so a
+    // classifyOne reads localShas exclusively in the `inFloor === 1` branch, so a
     // file absent from the floor (e.g. the transient `.claude/worktrees/` trees,
     // which classify as user-only) never needs a hash — and hashing it would mean
     // reading its bytes for nothing. Restricting the hash set to floor members is
@@ -1571,55 +1745,31 @@ function precomputeGitMaps(ctx, wipeToplevel) {
     ctx.localShas = localShas;
 }
 function walkAndProcess(ctx, rootRel) {
-    const { cfg } = ctx;
     const rootAbs = path.join(ctx.hqRoot, rootRel);
     if (!lexists(rootAbs))
         return;
     // companies/_template — wholesale-replace.
     if (rootRel === "companies/_template") {
-        if (cfg.dryRun) {
-            ctx.out("    wholesale-replace: companies/_template (template carve-out)\n");
-        }
-        else {
-            ctx.actions.push(() => fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), {
-                recursive: true,
-                force: true,
-            }));
-        }
+        recordDecision(ctx, { kind: "wholesale-replace-template", rel: "companies/_template" });
         return;
     }
     const lst = lstatOrNull(rootAbs);
     // Top-level symlink.
     if (lst && lst.isSymbolicLink()) {
-        if (isMasterSyncSymlink(rootAbs)) {
-            ctx.counts.symlinkDropped += 1;
-            if (cfg.dryRun) {
-                let tgt = "";
-                try {
-                    tgt = fs.readlinkSync(rootAbs);
-                }
-                catch {
-                    /* ignore */
-                }
-                ctx.out(`    drop reindex symlink: ${rootRel}  ->  ${tgt}\n`);
-            }
-            else {
-                ctx.actions.push(() => {
-                    fs.rmSync(rootAbs, { force: true });
-                    ctx.appendLog(`symlink-dropped\t${rootRel}\t(reindex regenerable)\n`);
-                });
-            }
+        const target = masterSyncSymlinkTarget(rootAbs);
+        if (target !== null) {
+            recordDecision(ctx, { kind: "drop-reindex-symlink", rel: rootRel, target });
         }
         return;
     }
     // Top-level regular file.
     if (lst && lst.isFile()) {
-        processOne(ctx, rootRel);
+        recordDecision(ctx, classifyOne(ctx, rootRel));
         return;
     }
     // Top-level directory: recursive walk, pruning node_modules + nested .git.
     for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot)) {
-        processOne(ctx, rel);
+        recordDecision(ctx, classifyOne(ctx, rel));
     }
 }
 /**