@indigoai-us/hq-cloud 6.11.11 → 6.11.13

package/src/cli/rescue-core.ts

@@ -694,6 +694,7 @@ function doRescue(
     unchangedList,
     appendLog,
     out,
+    decisions: [],
     actions: [],
   };
 
@@ -728,16 +729,19 @@ function doRescue(
   }
 
   // --- 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");
@@ -813,7 +817,8 @@ function doRescue(
   // 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");
@@ -1076,7 +1081,7 @@ interface WalkCtx {
   historyFloor: string;
   baselineMode: "history_floor" | "head_compare";
   // Batched git results, precomputed once before the classify walk so
-  // processOne does map lookups instead of spawning git ~3x per file. On a
+  // classifyOne does map lookups instead of spawning git ~3x per file. On a
   // large wipe set, process-startup overhead dominates and this is the
   // difference between minutes and seconds. A rel absent from a map falls back
   // to a per-file spawn (safety for paths that can't be batched line-delimited,
@@ -1089,13 +1094,18 @@ interface WalkCtx {
   floorShas?: Map<string, string | null>;
   runTs: string;
   srcSha: string;
-  // Deferred destructive ops, collected during the (read-only) classification
-  // walk and executed only AFTER the entire wipe set has been classified
-  // without error (PHASE 2 in doRescue). This is what makes a classifier crash
-  // fail-safe — a throw mid-classify aborts before a single file is mutated, so
-  // the wipe is never left half-applied (DEV-1767). Dry-run never fills this (it
-  // returns after classification), so live + dry-run share one classify path.
-  actions: Array<() => void>;
+  // Read-only classifier output, collected in walk order. Dry-run rendering is
+  // emitted inline as each decision is recorded; live filesystem action
+  // construction is derived from this same list only after the full classify
+  // walk completes.
+  decisions: RescueDecision[];
+  // Deferred destructive ops, built from RescueDecision only AFTER the entire
+  // wipe set has been classified without error (PHASE 2 in doRescue). This is
+  // what makes a classifier crash fail-safe — a throw mid-classify aborts before
+  // a single file is mutated, so the wipe is never left half-applied
+  // (DEV-1767). Dry-run never fills this (it returns after classification), so
+  // live + dry-run share one classify path.
+  actions: RescueAction[];
   counts: {
     userOnly: number;
     unchanged: number;
@@ -1112,6 +1122,189 @@ interface WalkCtx {
   out: (s: string) => void;
 }
 
+interface RescueAction {
+  label: string;
+  affectedRels: string[];
+  run: () => void;
+}
+
+export type RescueDecision =
+  | { kind: "skip"; rel: string }
+  | { kind: "drop-conflict-artifact"; rel: string }
+  | { kind: "drop-script-managed"; rel: string }
+  | { kind: "drop-reindex-symlink"; rel: string; target: string }
+  | { kind: "user-only"; rel: string }
+  | { kind: "cloud-symlink-reconciled"; rel: string }
+  | { kind: "drift-reconciled"; rel: string }
+  | { kind: "user-edit-diff-append"; rel: string }
+  | { kind: "user-edit-overwrite-safe"; rel: string }
+  | { kind: "user-edit-conflict"; rel: string }
+  | { kind: "user-edit-rescue"; rel: string; target: string }
+  | { kind: "unchanged-preserve"; rel: string }
+  | { kind: "unchanged-delete"; rel: string }
+  | { kind: "wholesale-replace-template"; rel: "companies/_template" };
+
+function recordDecision(ctx: WalkCtx, decision: RescueDecision): void {
+  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: WalkCtx, backupDir: string): void {
+  const completed: RescueAction[] = [];
+  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: WalkCtx,
+  completed: RescueAction[],
+  backupDir: string,
+): string[] {
+  if (!backupDir || !isDir(backupDir)) return [];
+
+  const rels: string[] = [];
+  const seen = new Set<string>();
+  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: string[] = [];
+  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: WalkCtx,
+  backupDir: string,
+  failedAction: RescueAction,
+  completed: RescueAction[],
+  restored: string[],
+  err: unknown,
+): string | null {
+  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: string[] = [];
+  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: string): string {
   if (rel === ".claude/CLAUDE.md") return "personal/CLAUDE.md";
@@ -1143,16 +1336,16 @@ function isOverwriteSafe(rel: string): boolean {
   );
 }
 
-function isMasterSyncSymlink(localPath: string): boolean {
+function masterSyncSymlinkTarget(localPath: string): string | null {
   const st = lstatOrNull(localPath);
-  if (!st || !st.isSymbolicLink()) return false;
+  if (!st || !st.isSymbolicLink()) 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: Config, rel: string): boolean {
@@ -1405,14 +1598,13 @@ function conflictOne(ctx: WalkCtx, rel: string): void {
   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: WalkCtx, rel: string): void {
+// 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: WalkCtx, rel: string): RescueDecision {
   const { cfg } = ctx;
   const localPath = path.join(ctx.hqRoot, rel);
   const srcPath = path.join(ctx.srcDir, rel);
@@ -1423,50 +1615,27 @@ function processOne(ctx: WalkCtx, rel: string): void {
     throw new Error(`rescue classifier fault injected at ${rel} (HQ_RESCUE_FAULT_AT_REL)`);
   }
 
-  if (isUnderPreserve(cfg, rel)) return;
+  if (isUnderPreserve(cfg, rel)) 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?
@@ -1497,9 +1666,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
 
   // 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.
@@ -1524,95 +1691,186 @@ function processOne(ctx: WalkCtx, rel: string): void {
 
   // 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;
-      }
-    } else {
-      if (rel === ".claude/CLAUDE.md") {
-        ctx.actions.push(() => rescueOne(ctx, rel));
-      } else if (isOverwriteSafe(rel)) {
-        ctx.actions.push(() => {
+    if (rel === ".claude/CLAUDE.md") {
+      return { kind: "user-edit-diff-append", rel };
+    }
+    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: WalkCtx, decision: RescueDecision): void {
+  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: WalkCtx): RescueAction[] {
+  const actions: RescueAction[] = [];
+  const add = (label: string, affectedRels: string[], runAction: () => void) => {
+    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
@@ -1620,10 +1878,10 @@ function processOne(ctx: WalkCtx, rel: string): void {
 // 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: WalkCtx, wipeToplevel: string[]): void {
-  const allRels: string[] = []; // every rel that reaches processOne (files + symlinks)
+  const allRels: string[] = []; // every rel that reaches classifyOne (files + symlinks)
   const fileRels: string[] = []; // subset that are regular files (hashable)
   const fileAbs: string[] = []; // parallel to fileRels
 
@@ -1639,7 +1897,7 @@ function precomputeGitMaps(ctx: WalkCtx, wipeToplevel: string[]): void {
         : [];
     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);
       const st = lstatOrNull(path.join(ctx.hqRoot, rel));
@@ -1650,7 +1908,7 @@ function precomputeGitMaps(ctx: WalkCtx, wipeToplevel: string[]): void {
     }
   }
 
-  // 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();
@@ -1687,7 +1945,7 @@ function precomputeGitMaps(ctx: WalkCtx, wipeToplevel: string[]): void {
   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
@@ -1718,22 +1976,12 @@ function precomputeGitMaps(ctx: WalkCtx, wipeToplevel: string[]): void {
 }
 
 function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
-  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;
   }
 
@@ -1741,35 +1989,22 @@ function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
 
   // 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));
   }
 }