forgedock 1.5.0 → 1.6.0

package/bin/journey.mjs

@@ -1060,6 +1060,73 @@ export async function isSymlinkTraversable(target) {
   }
 }
 
+/**
+ * Atomically install `target` as a symlink to `file`, verifying the result is
+ * readable by *this* process. Single source of truth for the correctness
+ * invariants that previously lived as near-verbatim copies at every symlink
+ * call site (forge#2667):
+ *
+ * - The symlink is first created at a tmp sibling suffixed with this
+ *   process's PID, then rename()d onto target. symlink() is exclusive-create,
+ *   so two concurrent forge() invocations installing the same path would
+ *   collide with an uncaught EEXIST on a shared literal path — the PID
+ *   suffix guarantees they never share one (forge#2542, forge#2599,
+ *   forge#2600, forge#2631). rename() atomically replaces any existing
+ *   target, including on Windows.
+ * - The tmp sibling is unlinked on every failure path so a rename failure
+ *   (or any rethrow) never orphans it (forge#2612).
+ * - The link is read back via isSymlinkTraversable() on the PID-scoped tmp
+ *   path *before* the rename: fs.symlink() can succeed while producing a link
+ *   this runtime cannot resolve (MSYS symlink + native Windows "untrusted
+ *   mount point" — forge#2620). Verifying the tmp sibling — which no other
+ *   process ever touches — instead of the shared target *after* the rename
+ *   closes a TOCTOU window: a post-rename readback could describe (and the
+ *   old cleanup unlink could remove) a concurrent installer's freshly-renamed
+ *   link, not ours (forge#2679). An unreadable link is discarded as tmp and
+ *   never renamed onto target, so target is left untouched.
+ *
+ * Callers keep their own `wantSymlink` guard and site-specific bookkeeping
+ * (counters, manifest mutation, copy fall-through) around the result.
+ *
+ * @param {string} file   - Symlink target (the source file to link to).
+ * @param {string} target - Path where the symlink is installed.
+ * @returns {Promise<"linked"|"unreadable"|"denied">}
+ *   "linked"     — symlink atomically installed at target and traversable.
+ *   "unreadable" — symlink was created but not readable back (forge#2620);
+ *                  the dead link was discarded as tmp and the rename never
+ *                  happened, so any existing target is left intact (forge#2679).
+ *                  Caller should fall back to a copy.
+ *   "denied"     — EPERM/EACCES from symlink/rename (no symlink installed;
+ *                  e.g. Windows without Developer Mode). Caller should fall
+ *                  back to a copy.
+ *   Any other error (EEXIST on the tmp path, ENOSPC, rename failures, …) is
+ *   rethrown after tmp cleanup.
+ */
+export async function atomicSymlinkInstall(file, target) {
+  const tmpTarget = target + "." + process.pid + ".tmp";
+  try {
+    await symlink(file, tmpTarget);
+    // Read back the PID-scoped tmp sibling *before* renaming onto target. No
+    // other process touches tmpTarget, so the verdict cannot describe a
+    // concurrent installer's link, and an unreadable link is discarded here
+    // without ever unlinking target (forge#2679, forge#2620).
+    if (!(await isSymlinkTraversable(tmpTarget))) {
+      await unlink(tmpTarget).catch(() => {});
+      return "unreadable";
+    }
+    try {
+      await rename(tmpTarget, target);
+    } catch (renameErr) {
+      await unlink(tmpTarget).catch(() => {});
+      throw renameErr;
+    }
+    return "linked";
+  } catch (linkErr) {
+    if (!isLinkPermissionError(linkErr)) throw linkErr;
+    return "denied";
+  }
+}
+
 /**
  * Allowlist of universal pipeline-agent scripts installed to
  * ~/.claude/scripts/ by forge() (linkPipelineScripts()) and cleaned up by
@@ -1679,27 +1746,7 @@ async function linkPipelineScripts(ctx) {
 
     let linked = false;
     if (wantSymlink) {
-      // Suffix the tmp sibling with this process's PID so a losing
-      // concurrent forge() invocation linking the same brand-new pipeline
-      // script never collides on the same literal target path (which
-      // raises an uncaught EEXIST — isLinkPermissionError() only treats
-      // EPERM/EACCES as recoverable). Mirrors the fresh-install symlink
-      // branch in forge() (forge#2631) and the relink/upgrade branches
-      // (forge#2542, forge#2600, forge#2599).
-      const tmpTarget = target + "." + process.pid + ".tmp";
-      try {
-        await symlink(file, tmpTarget);
-        try {
-          await rename(tmpTarget, target);
-        } catch (renameErr) {
-          await unlink(tmpTarget).catch(() => {});
-          throw renameErr;
-        }
-        linked = await isSymlinkTraversable(target);
-        if (!linked) await unlink(target).catch(() => {});
-      } catch (linkErr) {
-        if (!isLinkPermissionError(linkErr)) throw linkErr;
-      }
+      linked = (await atomicSymlinkInstall(file, target)) === "linked";
     }
     if (!linked) {
       await copyFile(file, target);
@@ -1835,6 +1882,364 @@ export function detectCrossEnvInstall(ctx, envInfo, deps = {}) {
   }
 }
 
+/**
+ * Final manifest save for forge(): locked re-read → replay this run's
+ * `manifestOps` → write. Returns true on success, false on any failure —
+ * never throws, because manifest housekeeping must never abort the caller's
+ * receipt or the hook installation.
+ */
+async function saveManifestWithMerge(manifestPath, manifestOps) {
+  try {
+    // Re-read-and-merge (forge#2614): another concurrent forge() invocation
+    // may have saved its own manifest.files adds/deletes since this run's
+    // initial load above. Re-reading the on-disk manifest right before this
+    // run's own save and replaying only this run's own ops (manifestOps)
+    // onto that fresh copy — rather than blindly overwriting with the
+    // run-start in-memory snapshot — means this run's save can no longer
+    // silently drop the other run's changes. loadCopiedManifest() never
+    // throws (missing/corrupt on-disk manifest resolves to an empty one),
+    // so this stays within the surrounding never-abort contract.
+    //
+    // Lock the re-read→merge→write sequence itself (forge#2637): #2614
+    // narrowed the race from "whole run duration" to this critical section,
+    // but left it unprotected — a third concurrent forge() could still land
+    // its own save inside the gap between this run's re-read and its own
+    // write-rename completing. acquireManifestLock() is best-effort: on
+    // failure to acquire (contention exhausted retries, or an unexpected
+    // error) it returns null and this run proceeds unlocked, same as
+    // before — the lock narrows the window further, it does not change the
+    // never-abort contract.
+    const lockHandle = await acquireManifestLock(manifestPath);
+    try {
+      const mergedManifest = await loadCopiedManifest(manifestPath);
+      for (const { rel, op } of manifestOps) {
+        if (op === "add") {
+          mergedManifest.files[rel] = true;
+        } else {
+          delete mergedManifest.files[rel];
+        }
+      }
+      await saveCopiedManifest(manifestPath, mergedManifest);
+    } finally {
+      await releaseManifestLock(manifestPath, lockHandle);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Per-file branch for forge(): a manifest-tracked regular file — a copy we
+ * made on a previous run, ours to manage. First try upgrading it to a
+ * symlink (Developer Mode enabled since), preserving atomicSymlinkInstall()'s
+ * tri-state "linked"/"unreadable"/"denied" contract (forge#2620 / ADR #2667)
+ * exactly; on "denied", fall through to content-compare + copy.
+ * Returns counter deltas for forge() to fold in.
+ */
+async function upgradeManagedCopy(file, target, rel, { wantSymlink, recordDelete }) {
+  let upgraded = false;
+  let restoredAsCopy = false;
+  if (wantSymlink) {
+    const result = await atomicSymlinkInstall(file, target);
+    if (result === "linked") {
+      upgraded = true;
+      recordDelete(rel);
+    } else if (result === "unreadable") {
+      // Symlink was created but is not readable back (forge#2620) — the helper
+      // discarded it as tmp and left the existing copy at target untouched
+      // (forge#2679). Overwrite it with a fresh copy so the command stays
+      // readable. Keep the manifest entry (still copy-managed, not
+      // symlink-managed) and do NOT fall through to the generic
+      // copy-comparison below — the copy is already done.
+      await copyFile(file, target);
+      restoredAsCopy = true;
+    }
+    // "denied" — no symlink installed; fall through to content-compare.
+  }
+  if (upgraded || restoredAsCopy) {
+    return { updatedDelta: 1, skippedDelta: 0 };
+  }
+  const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
+  if (src.equals(dst)) {
+    return { updatedDelta: 0, skippedDelta: 1 };
+  }
+  await copyFile(file, target);
+  return { updatedDelta: 1, skippedDelta: 0 };
+}
+
+/**
+ * Per-file branch for forge(): a regular file not in the manifest — a copy
+ * from a pre-manifest ForgeDock version, or a stale copy that was never
+ * adopted. `rel` here is always enumerated from `files` (ForgeDock's own
+ * commandsDir listing) — every path this branch touches is a
+ * ForgeDock-managed command file, never an arbitrary user file, so there is
+ * no "user-customized" case to protect. Content-compare: if it matches
+ * source, adopt it into the manifest silently (it was ours all along). If it
+ * differs, it's stale — overwrite it and adopt it into the manifest too,
+ * mirroring the manifest-tracked branch, so future runs take the
+ * manifest-aware fast path.
+ *
+ * Never throws. Returns an effects object forge() folds into its counters:
+ * `handled: false` means every repair attempt failed and forge() should
+ * print the per-file WARNING (terminal/progress-bar state stays in forge()).
+ * `backedUpDelta` is mutated in place as backup/rollback progresses so a
+ * mid-sequence failure still reports any backup that remains on disk
+ * (forge#2559).
+ */
+async function adoptOrRepairUnmanagedCopy(file, target, rel, { recordCopy }) {
+  const effects = { handled: false, updatedDelta: 0, skippedDelta: 0, backedUpDelta: 0 };
+  try {
+    const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
+    if (src.equals(dst)) {
+      recordCopy(rel);
+      effects.skippedDelta++;
+      effects.handled = true;
+    } else {
+      // Write to a .tmp sibling and atomically rename onto target — never
+      // open target itself for a direct overwrite. copyFile() is not
+      // atomic: a mid-write failure (AV lock / ENOSPC / process kill)
+      // would otherwise leave target truncated/corrupted rather than
+      // simply stale, which the WARNING in forge() cannot distinguish. This
+      // mirrors the .tmp+rename swap already used for symlink installs
+      // (lines ~1573-1579, ~1601-1607).
+      //
+      // Unlike those symlink-based branches — where symlink() is itself
+      // exclusive-create and therefore naturally races out a concurrent
+      // writer — copyFile() has no such semantics: two concurrent
+      // forge() invocations (e.g. an overlapping `doctor --fix` run, or
+      // a file watcher) targeting the same file would both write
+      // through the same shared `target + ".tmp"` path and could
+      // interleave or clobber each other before either rename() runs.
+      // Suffix the tmp sibling with this process's PID so concurrent
+      // invocations never share a path (forge#2542).
+      const tmpTarget = target + "." + process.pid + ".tmp";
+      try {
+        await copyFile(file, tmpTarget);
+      } catch (copyErr) {
+        // A copyFile failure (disk full mid-copy, AV lock, permission
+        // error) can still leave a partially-written .tmp sibling on
+        // disk even though the write itself threw. The sibling
+        // rename() failure just below already cleans up tmpTarget
+        // on its own failure path (renameErr) — mirror that here so a
+        // copyFile failure doesn't orphan the .tmp file instead
+        // (forge#2540). Best-effort: never let the cleanup itself mask
+        // or replace the original copyErr being rethrown.
+        await unlink(tmpTarget).catch(() => {});
+        throw copyErr;
+      }
+      // Preserve the pre-existing content before it's replaced, mirroring
+      // half of the confirm+backup convention used by the forge.yaml
+      // overwrite path (bin/forgedock.mjs ~990-1021 / journey.mjs
+      // review(), both via backupExisting()). A confirmation prompt is
+      // deliberately NOT added: this branch also runs non-interactively
+      // inside `doctor --fix`'s automated repair (bin/forgedock.mjs
+      // runInstallRepairOnce() -> forge(ctx())), so pausing per-file for
+      // input would break that flow. Placed here — after the .tmp write
+      // has already succeeded, before the final rename — rather than
+      // before copyFile (as the forge.yaml path does), so a copyFile
+      // failure never backs up (and thereby displaces) a target that's
+      // about to remain untouched (see the .tmp-write-failure test,
+      // forge#2498). backupExisting()'s rename is itself atomic, so this
+      // ordering carries none of the non-atomic-write risk that forge#1396
+      // flagged for the old backup-then-writeFileSync forge.yaml path.
+      //
+      // Note: backupExisting() below is a *synchronous* rename
+      // (target -> target+".bak"); the tmpTarget -> target rename just
+      // after it is a separate, async filesystem operation. Between
+      // the two, target genuinely does not exist on disk for a
+      // sub-millisecond window. Only a hard process kill (not any
+      // catchable JS error) can land exactly there — any catchable
+      // failure of the second rename is already handled by the
+      // rollback block below — and recovery in that rare case is via
+      // the surviving target+".bak" on the next forge() run (forge#2558).
+      const backup = backupExisting(target);
+      if (backup) effects.backedUpDelta++;
+      try {
+        await rename(tmpTarget, target);
+      } catch (renameErr) {
+        await unlink(tmpTarget).catch(() => {});
+        if (backup) {
+          // The final rename failed AFTER backupExisting() already moved
+          // the original file to target+".bak" — target no longer exists
+          // on disk at this point. Without this rollback the user's file
+          // would simply vanish (present only as .bak) while the WARNING
+          // in forge() implies it merely "could not be repaired". Restore
+          // the prior content so a failed repair is a no-op, matching the
+          // pre-backup invariant that a rename failure never removes the
+          // existing file (see the .tmp-write-failure test, forge#2498).
+          // WIRE:PROVEN — manual: reasoned, not exercised by an automated
+          // test. This branch requires rename(tmp, target) to fail on the
+          // exact call immediately after backupExisting()'s own rename of
+          // the same target succeeded — an OS-level race with no portable
+          // way to force deterministically (the sibling renameErr catches
+          // for the symlink-relink paths above, lines ~1576/~1604, are the
+          // same kind of defensive OS-failure branch and are likewise
+          // untested for the same reason). Verified by code inspection:
+          // rename() is fs/promises' rename. The rollback rename's own
+          // outcome is captured explicitly rather than assumed — if it
+          // also fails (e.g. .bak itself is locked), target+".bak" is
+          // left in place as the only remaining copy of the prior
+          // content, so backedUpDelta must NOT be decremented in that
+          // case; it correctly reflects "a backup file still exists on
+          // disk" (forge#2559). Only on confirmed rollback success does
+          // the decrement keep the counter consistent with the restored
+          // on-disk state before renameErr is rethrown to the outer catch.
+          let rollbackOk = true;
+          await rename(target + ".bak", target).catch(() => { rollbackOk = false; });
+          if (rollbackOk) effects.backedUpDelta--;
+        }
+        throw renameErr;
+      }
+      recordCopy(rel);
+      effects.updatedDelta++;
+      effects.handled = true;
+    }
+  } catch { /* readFile/copyFile/rename failure — fall through to warning */ }
+  return effects;
+}
+
+/**
+ * Per-file branch for forge(): target does not exist yet (ENOENT from
+ * lstat) — fresh install. Symlink-first, copy-fallback; a successful link
+ * also drops any stale manifest record for the path.
+ * Returns counter deltas for forge() to fold in.
+ */
+async function installFreshCommandFile(file, target, rel, { wantSymlink, manifest, recordCopy, recordDelete }) {
+  let linked = false;
+  if (wantSymlink) {
+    linked = (await atomicSymlinkInstall(file, target)) === "linked";
+    if (linked && manifest.files[rel]) {
+      // Symlinks work now and the old copy is gone — drop the stale record.
+      recordDelete(rel);
+    }
+  }
+  if (!linked) {
+    // Windows without Developer Mode/admin, or symlink unreadable — copy.
+    await copyFile(file, target);
+    recordCopy(rel);
+    return { installedDelta: 0, copiedDelta: 1 };
+  }
+  return { installedDelta: 1, copiedDelta: 0 };
+}
+
+/**
+ * Act II receipt: render forge()'s summary lines, advisories, and hook
+ * statuses. Pure reporting — mechanical move of the forge() tail; reads
+ * `results` and writes to ctx.stdout, mutates nothing.
+ */
+function renderForgeReceipt(ctx, results) {
+  const { stdout: w } = ctx;
+  const {
+    installed, updated, skipped, copied, backedUp, pruned, total,
+    staleExtensionlessPruned, scriptsResult, manifestSaveFailed,
+    hookStatus, settingsPath, preToolUseStatus, subagentStopEnforceStatus,
+  } = results;
+
+  const glyph = (ok) => (ctx.mode === "none" ? (ok ? "✔" : "!") : `\x1b[38;2;255;179;71m${ok ? "✔" : "!"}\x1b[0m`);
+  const headlineVerb = copied > 0 ? "installed" : "linked";
+  const backupNote = backedUp > 0 ? `, ${backedUp} backed up` : "";
+  const headlineDetail = copied > 0
+    ? `(new ${installed}, copied ${copied}, updated ${updated}${backupNote}, unchanged ${skipped})`
+    : `(new ${installed}, updated ${updated}${backupNote}, unchanged ${skipped})`;
+  w.write(`  ${glyph(true)} ${total} slash commands ${headlineVerb} ${dimLine(ctx, headlineDetail)}\n`);
+  if (pruned > 0) {
+    w.write(`  ${glyph(true)} ${pruned} orphaned symlink${pruned === 1 ? "" : "s"} removed ${dimLine(ctx, "(commands deleted or renamed since last install)")}\n`);
+  }
+  if (staleExtensionlessPruned > 0) {
+    w.write(`  ${glyph(true)} ${staleExtensionlessPruned} stale extensionless entr${staleExtensionlessPruned === 1 ? "y" : "ies"} removed ${dimLine(ctx, "(leftover from prior npx forgedock runs)")}\n`);
+  }
+  if (copied > 0) {
+    w.write(`  ${glyph(false)} ${copied} copied (not linked) ${dimLine(ctx, "— enable Windows Developer Mode for live-updating links")}\n`);
+  }
+  if (scriptsResult.total > 0) {
+    const scriptsChanged = scriptsResult.installed + scriptsResult.updated + scriptsResult.copied;
+    const scriptsDetail = scriptsChanged > 0
+      ? `(new ${scriptsResult.installed}, updated ${scriptsResult.updated}, copied ${scriptsResult.copied}, unchanged ${scriptsResult.skipped})`
+      : `(unchanged ${scriptsResult.skipped})`;
+    w.write(`  ${glyph(true)} ${scriptsResult.total} pipeline scripts linked into ~/.claude/scripts ${dimLine(ctx, scriptsDetail)}\n`);
+  }
+  if (manifestSaveFailed) {
+    w.write("  " + dimLine(ctx, "manifest not saved — re-runs may warn about copied files") + "\n");
+  }
+  if (hookStatus === "skipped-malformed") {
+    w.write(`  ${glyph(false)} SessionStart hook NOT registered — ${settingsPath} is not valid JSON\n`);
+    w.write(fixCard([`Fix the JSON in ${settingsPath}, then re-run: npx forgedock install`], ctx.mode) + "\n");
+  } else {
+    w.write(`  ${glyph(true)} SessionStart hook ${hookStatus === "already" ? "active" : "registered"} ${dimLine(ctx, settingsPath)}\n`);
+  }
+
+  // Persisted-home / ephemeral-cache advisory (forge#1895, extended #1943):
+  // runJourney() calls persistHome(ctx) right before forge() and stashes its
+  // result on ctx.persistHomeResult; when persistHome() actually ran (i.e.
+  // wasn't skipped), ctx.forgeHome above has ALREADY been reassigned to the
+  // stable ~/.forge/ copy, so report that outcome instead of the raw
+  // ephemeral-cache warning. Direct forge() callers that never set
+  // ctx.persistHomeResult (e.g. relinkAndHint() in bin/forgedock.mjs) fall
+  // through to the original ephemeral-cache-only check unchanged.
+  const persistResult = ctx.persistHomeResult;
+  if (persistResult && !persistResult.skipped) {
+    if (persistResult.migrated) {
+      w.write(`  ${glyph(true)} toolset migrated to persisted home ${dimLine(ctx, persistResult.forgeHome)}\n`);
+    } else {
+      w.write(`  ${glyph(true)} persisted home already current ${dimLine(ctx, `v${persistResult.version || "unknown"} at ${persistResult.forgeHome}`)}\n`);
+    }
+  } else if (persistResult && persistResult.skipped && !isEphemeralCachePath(ctx.forgeHome)) {
+    // Skipped for a reason OTHER than "still ephemeral" — today that's always
+    // the git-working-tree exemption (Acceptance Criteria #5). Informational,
+    // not a warning: this is the expected, correct state for a git-clone install.
+    w.write(`  ${dimLine(ctx, `persisted home skipped — ${persistResult.reason || "not applicable"}`)}\n`);
+  } else if (hookStatus !== "skipped-malformed" && isEphemeralCachePath(ctx.forgeHome)) {
+    // Either persistHome() was never run (no ctx.persistHomeResult), or it
+    // ran but failed and left ctx.forgeHome pointing at the original
+    // ephemeral source (fail-open — see persistHome()'s error branch).
+    w.write(`  ${glyph(false)} FORGE_HOME resolves inside an ephemeral cache directory ${dimLine(ctx, ctx.forgeHome)}\n`);
+    w.write(fixCard([
+      "This path (npx/pnpm dlx/yarn dlx cache) can be pruned by npm/npx/pnpm/yarn",
+      "or OS temp cleanup. If that happens, the SessionStart hook silently stops",
+      "injecting ForgeDock context — no error is shown.",
+      "Mitigation: npm install -g forgedock  (or re-run npx forgedock periodically).",
+    ], ctx.mode, "warning") + "\n");
+  }
+
+  // Cross-environment install advisory (forge#1893): warn when this repo is
+  // reachable from both WSL and native Windows and BOTH sides already have a
+  // ForgeDock install. Each environment's install is fully independent (see
+  // #1589 — installs are always global, never per-repo), so running from
+  // both silently leaves forge.yaml/hook paths pointing at whichever side ran
+  // most recently, clobbering the other's config with no error surfaced.
+  // Advisory only — never fails the install.
+  const envInfo = detectEnvironment({ platform: ctx.platform, env: ctx.env, release: ctx.release });
+  const crossEnv = detectCrossEnvInstall(ctx, envInfo);
+  if (crossEnv.conflict) {
+    const otherLabel = crossEnv.direction === "windows" ? "a native Windows" : "a WSL";
+    w.write(`  ${glyph(false)} ${otherLabel} ForgeDock install detected for this repo ${dimLine(ctx, crossEnv.otherPath)}\n`);
+    w.write(fixCard([
+      `This repo is reachable from both WSL and native Windows, and ${otherLabel}`,
+      "install already exists. Each side's install is independent — running",
+      "forgedock from both can leave forge.yaml and hook paths pointing at",
+      "whichever environment ran last, silently overwriting the other's config.",
+      "Mitigation: pick one environment for this repo, or sync forge.yaml manually.",
+    ], ctx.mode, "warning") + "\n");
+  }
+
+  // Report enforcement hook status.
+  if (preToolUseStatus !== null) {
+    w.write(`  ${glyph(true)} PreToolUse enforcement hook ${preToolUseStatus === "already" ? "active" : "registered"} ${dimLine(ctx, "(branch/label enforcement)")}\n`);
+  } else {
+    w.write("  " + dimLine(ctx, "PreToolUse hook skipped — requires Claude Code v2.1.163+") + "\n");
+  }
+  // "skipped-malformed" and "absent" are intentionally silent here:
+  // - skipped-malformed: installSessionStartHook() above reads the same
+  //   settingsPath and already prints the malformed-JSON fix-card, so a
+  //   second message would just repeat the same signal.
+  // - absent: the expected steady state (nothing to remove) — this
+  //   function only reports state *changes*, not no-ops.
+  if (subagentStopEnforceStatus === "removed") {
+    w.write(`  ${glyph(true)} SubagentStop enforcement hook removed ${dimLine(ctx, "(non-functional — see forge#1527)")}\n`);
+  }
+}
+
 /**
  * Act II: link commands into ~/.claude/commands with a molten progress line,
  * then register the SessionStart hook.
@@ -1889,6 +2294,14 @@ export async function forge(ctx) {
     }
     manifestOps.push({ rel, op: "add" });
   };
+  // Mirror of recordCopy for removals — keeps manifest.files, manifestChanged,
+  // and the replayable manifestOps diff (forge#2614) mutating as one unit so
+  // the in-memory manifest and the final merge-save replay never diverge.
+  const recordDelete = (rel) => {
+    delete manifest.files[rel];
+    manifestChanged = true;
+    manifestOps.push({ rel, op: "delete" });
+  };
 
   for (let i = 0; i < files.length; i++) {
     const file = files[i];
@@ -1905,40 +2318,15 @@ export async function forge(ctx) {
         } else {
           let relinked = false;
           if (wantSymlink) {
-            // Suffix the tmp sibling with this process's PID so a losing
-            // concurrent forge() invocation's symlink() call never collides
-            // on the same literal path (which raises an uncaught EEXIST —
-            // isLinkPermissionError() only treats EPERM/EACCES as
-            // recoverable). Mirrors the copyFile branch and
-            // saveCopiedManifest fixes already applied in this file
-            // (forge#2542, forge#2599).
-            const tmpTarget = target + "." + process.pid + ".tmp";
-            try {
-              await symlink(file, tmpTarget);
-              try {
-                await rename(tmpTarget, target);
-              } catch (renameErr) {
-                await unlink(tmpTarget).catch(() => {});
-                throw renameErr;
-              }
-              relinked = await isSymlinkTraversable(target);
-              if (relinked) {
-                updated++;
-              } else {
-                // Symlink was created but is not readable back (e.g. MSYS
-                // symlink hit by native Windows "untrusted mount point" —
-                // forge#2620). Remove it and fall through to the copy branch.
-                await unlink(target).catch(() => {});
-              }
-            } catch (linkErr) {
-              if (!isLinkPermissionError(linkErr)) throw linkErr;
-            }
+            relinked = (await atomicSymlinkInstall(file, target)) === "linked";
+            if (relinked) updated++;
           }
           if (!relinked) {
             // Can't (or shouldn't) re-link — replace the managed link with a copy.
             // unlink first: copyFile onto a symlink writes THROUGH the link.
-            // (target may already be gone here if isSymlinkTraversable() failed
-            // and its own cleanup already removed it — tolerate ENOENT.)
+            // (On "unreadable" the rename never happened so the old link is
+            // still here; on "denied" likewise. ENOENT tolerated defensively
+            // in case the entry vanished out from under us — forge#2679.)
             await unlink(target).catch((err) => {
               if (err.code !== "ENOENT") throw err;
             });
@@ -1948,174 +2336,17 @@ export async function forge(ctx) {
           }
         }
       } else if (manifest.files[rel]) {
-        // A regular file we copied on a previous run — ours to manage.
-        // First try upgrading it to a symlink (Developer Mode enabled since).
-        let upgraded = false;
-        let restoredAsCopy = false;
-        if (wantSymlink) {
-          // Same per-process-unique tmp suffix as the relink branch above —
-          // sibling branch, identical shared-literal-path EEXIST risk
-          // (forge#2542, forge#2599).
-          const tmpTarget = target + "." + process.pid + ".tmp";
-          try {
-            await symlink(file, tmpTarget);
-            try {
-              await rename(tmpTarget, target); // rename replaces existing files on Windows
-            } catch (renameErr) {
-              await unlink(tmpTarget).catch(() => {});
-              throw renameErr;
-            }
-            upgraded = await isSymlinkTraversable(target);
-            if (upgraded) {
-              updated++;
-              delete manifest.files[rel];
-              manifestChanged = true;
-              manifestOps.push({ rel, op: "delete" });
-            } else {
-              // Symlink was created but is not readable back (e.g. MSYS
-              // symlink hit by native Windows "untrusted mount point" —
-              // forge#2620). Restore a real copy so the command stays
-              // readable. Keep the manifest entry (still copy-managed, not
-              // symlink-managed) and do NOT fall through to the generic
-              // copy-comparison below — the copy is already done.
-              await unlink(target).catch(() => {});
-              await copyFile(file, target);
-              updated++;
-              restoredAsCopy = true;
-            }
-          } catch (linkErr) {
-            if (!isLinkPermissionError(linkErr)) throw linkErr;
-          }
-        }
-        if (!upgraded && !restoredAsCopy) {
-          const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
-          if (src.equals(dst)) {
-            skipped++;
-          } else {
-            await copyFile(file, target);
-            updated++;
-          }
-        }
+        const eff = await upgradeManagedCopy(file, target, rel, { wantSymlink, recordDelete });
+        updated += eff.updatedDelta;
+        skipped += eff.skippedDelta;
       } else {
-        // Regular file not in manifest — a copy from a pre-manifest ForgeDock
-        // version, or a stale copy that was never adopted. `rel` here is
-        // always enumerated from `files` (ForgeDock's own commandsDir
-        // listing, see above) — every path this loop touches is a
-        // ForgeDock-managed command file, never an arbitrary user file, so
-        // there is no "user-customized" case to protect. Content-compare: if
-        // it matches source, adopt it into the manifest silently (it was
-        // ours all along). If it differs, it's stale — overwrite it and
-        // adopt it into the manifest too, mirroring the manifest-tracked
-        // branch above, so future runs take the manifest-aware fast path.
-        let handled = false;
-        try {
-          const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
-          if (src.equals(dst)) {
-            recordCopy(rel);
-            skipped++;
-            handled = true;
-          } else {
-            // Write to a .tmp sibling and atomically rename onto target — never
-            // open target itself for a direct overwrite. copyFile() is not
-            // atomic: a mid-write failure (AV lock / ENOSPC / process kill)
-            // would otherwise leave target truncated/corrupted rather than
-            // simply stale, which the WARNING below cannot distinguish. This
-            // mirrors the .tmp+rename swap already used for symlink installs
-            // above (lines ~1573-1579, ~1601-1607).
-            //
-            // Unlike those symlink-based branches — where symlink() is itself
-            // exclusive-create and therefore naturally races out a concurrent
-            // writer — copyFile() has no such semantics: two concurrent
-            // forge() invocations (e.g. an overlapping `doctor --fix` run, or
-            // a file watcher) targeting the same file would both write
-            // through the same shared `target + ".tmp"` path and could
-            // interleave or clobber each other before either rename() runs.
-            // Suffix the tmp sibling with this process's PID so concurrent
-            // invocations never share a path (forge#2542).
-            const tmpTarget = target + "." + process.pid + ".tmp";
-            try {
-              await copyFile(file, tmpTarget);
-            } catch (copyErr) {
-              // A copyFile failure (disk full mid-copy, AV lock, permission
-              // error) can still leave a partially-written .tmp sibling on
-              // disk even though the write itself threw. The sibling
-              // rename() failure just below already cleans up tmpTarget
-              // on its own failure path (renameErr) — mirror that here so a
-              // copyFile failure doesn't orphan the .tmp file instead
-              // (forge#2540). Best-effort: never let the cleanup itself mask
-              // or replace the original copyErr being rethrown.
-              await unlink(tmpTarget).catch(() => {});
-              throw copyErr;
-            }
-            // Preserve the pre-existing content before it's replaced, mirroring
-            // half of the confirm+backup convention used by the forge.yaml
-            // overwrite path (bin/forgedock.mjs ~990-1021 / journey.mjs
-            // review(), both via backupExisting()). A confirmation prompt is
-            // deliberately NOT added: this branch also runs non-interactively
-            // inside `doctor --fix`'s automated repair (bin/forgedock.mjs
-            // runInstallRepairOnce() -> forge(ctx())), so pausing per-file for
-            // input would break that flow. Placed here — after the .tmp write
-            // has already succeeded, before the final rename — rather than
-            // before copyFile (as the forge.yaml path does), so a copyFile
-            // failure never backs up (and thereby displaces) a target that's
-            // about to remain untouched (see the .tmp-write-failure test,
-            // forge#2498). backupExisting()'s rename is itself atomic, so this
-            // ordering carries none of the non-atomic-write risk that forge#1396
-            // flagged for the old backup-then-writeFileSync forge.yaml path.
-            //
-            // Note: backupExisting() below is a *synchronous* rename
-            // (target -> target+".bak"); the tmpTarget -> target rename just
-            // after it is a separate, async filesystem operation. Between
-            // the two, target genuinely does not exist on disk for a
-            // sub-millisecond window. Only a hard process kill (not any
-            // catchable JS error) can land exactly there — any catchable
-            // failure of the second rename is already handled by the
-            // rollback block below — and recovery in that rare case is via
-            // the surviving target+".bak" on the next forge() run (forge#2558).
-            const backup = backupExisting(target);
-            if (backup) backedUp++;
-            try {
-              await rename(tmpTarget, target);
-            } catch (renameErr) {
-              await unlink(tmpTarget).catch(() => {});
-              if (backup) {
-                // The final rename failed AFTER backupExisting() already moved
-                // the original file to target+".bak" — target no longer exists
-                // on disk at this point. Without this rollback the user's file
-                // would simply vanish (present only as .bak) while the WARNING
-                // below implies it merely "could not be repaired". Restore the
-                // prior content so a failed repair is a no-op, matching the
-                // pre-backup invariant that a rename failure never removes the
-                // existing file (see the .tmp-write-failure test, forge#2498).
-                // WIRE:PROVEN — manual: reasoned, not exercised by an automated
-                // test. This branch requires rename(tmp, target) to fail on the
-                // exact call immediately after backupExisting()'s own rename of
-                // the same target succeeded — an OS-level race with no portable
-                // way to force deterministically (the sibling renameErr catches
-                // for the symlink-relink paths above, lines ~1576/~1604, are the
-                // same kind of defensive OS-failure branch and are likewise
-                // untested for the same reason). Verified by code inspection:
-                // rename() is fs/promises' rename. The rollback rename's own
-                // outcome is captured explicitly rather than assumed — if it
-                // also fails (e.g. .bak itself is locked), target+".bak" is
-                // left in place as the only remaining copy of the prior
-                // content, so backedUp must NOT be decremented in that case;
-                // it correctly reflects "a backup file still exists on disk"
-                // (forge#2559). Only on confirmed rollback success does
-                // backedUp-- keep the counter consistent with the restored
-                // on-disk state before renameErr is rethrown to the outer catch.
-                let rollbackOk = true;
-                await rename(target + ".bak", target).catch(() => { rollbackOk = false; });
-                if (rollbackOk) backedUp--;
-              }
-              throw renameErr;
-            }
-            recordCopy(rel);
-            updated++;
-            handled = true;
-          }
-        } catch { /* readFile/copyFile/rename failure — fall through to warning */ }
-        if (!handled) {
+        const eff = await adoptOrRepairUnmanagedCopy(file, target, rel, { recordCopy });
+        updated += eff.updatedDelta;
+        skipped += eff.skippedDelta;
+        backedUp += eff.backedUpDelta;
+        if (!eff.handled) {
+          // Terminal/progress-bar state stays here — helpers never touch
+          // barShown or write to the stream.
           if (barShown) { w.write("\x1b[1A\x1b[2K"); barShown = false; }
           w.write(`  WARNING: ${rel} could not be repaired — remove it manually to let ForgeDock manage it\n`);
           skipped++;
@@ -2123,48 +2354,9 @@ export async function forge(ctx) {
       }
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
-      let linked = false;
-      if (wantSymlink) {
-        // Suffix the tmp sibling with this process's PID so a losing
-        // concurrent forge() invocation installing the same brand-new
-        // command never collides on the same literal target path (which
-        // raises an uncaught EEXIST — isLinkPermissionError() only treats
-        // EPERM/EACCES as recoverable). Mirrors the relink and copy-upgrade
-        // branches above (forge#2542, forge#2600, forge#2599).
-        const tmpTarget = target + "." + process.pid + ".tmp";
-        try {
-          await symlink(file, tmpTarget);
-          try {
-            await rename(tmpTarget, target);
-          } catch (renameErr) {
-            await unlink(tmpTarget).catch(() => {});
-            throw renameErr;
-          }
-          linked = await isSymlinkTraversable(target);
-          if (linked) {
-            installed++;
-            if (manifest.files[rel]) {
-              // Symlinks work now and the old copy is gone — drop the stale record.
-              delete manifest.files[rel];
-              manifestChanged = true;
-              manifestOps.push({ rel, op: "delete" });
-            }
-          } else {
-            // Symlink created but not readable back (e.g. MSYS symlink hit by
-            // native Windows "untrusted mount point" — forge#2620). Remove it
-            // and fall through to the copy path below.
-            await unlink(target).catch(() => {});
-          }
-        } catch (linkErr) {
-          if (!isLinkPermissionError(linkErr)) throw linkErr;
-        }
-      }
-      if (!linked) {
-        // Windows without Developer Mode/admin, or symlink unreadable — copy.
-        await copyFile(file, target);
-        copied++;
-        recordCopy(rel);
-      }
+      const eff = await installFreshCommandFile(file, target, rel, { wantSymlink, manifest, recordCopy, recordDelete });
+      installed += eff.installedDelta;
+      copied += eff.copiedDelta;
     }
 
     if (ctx.motion) {
@@ -2204,149 +2396,18 @@ export async function forge(ctx) {
   const { status: subagentStopEnforceStatus } = removeSubagentStopEnforceHook(settingsPath);
 
   // Housekeeping — must never abort the receipt or the hook.
+  // saveManifestWithMerge() owns the locked re-read → replay-manifestOps →
+  // save sequence (forge#2614/forge#2637) and never throws.
   let manifestSaveFailed = false;
   if (manifestChanged) {
-    try {
-      // Re-read-and-merge (forge#2614): another concurrent forge() invocation
-      // may have saved its own manifest.files adds/deletes since this run's
-      // initial load above. Re-reading the on-disk manifest right before this
-      // run's own save and replaying only this run's own ops (manifestOps)
-      // onto that fresh copy — rather than blindly overwriting with the
-      // run-start in-memory snapshot — means this run's save can no longer
-      // silently drop the other run's changes. loadCopiedManifest() never
-      // throws (missing/corrupt on-disk manifest resolves to an empty one),
-      // so this stays within the surrounding never-abort contract.
-      //
-      // Lock the re-read→merge→write sequence itself (forge#2637): #2614
-      // narrowed the race from "whole run duration" to this critical section,
-      // but left it unprotected — a third concurrent forge() could still land
-      // its own save inside the gap between this run's re-read and its own
-      // write-rename completing. acquireManifestLock() is best-effort: on
-      // failure to acquire (contention exhausted retries, or an unexpected
-      // error) it returns null and this run proceeds unlocked, same as
-      // before — the lock narrows the window further, it does not change the
-      // never-abort contract.
-      const lockHandle = await acquireManifestLock(manifestPath);
-      try {
-        const mergedManifest = await loadCopiedManifest(manifestPath);
-        for (const { rel, op } of manifestOps) {
-          if (op === "add") {
-            mergedManifest.files[rel] = true;
-          } else {
-            delete mergedManifest.files[rel];
-          }
-        }
-        await saveCopiedManifest(manifestPath, mergedManifest);
-      } finally {
-        await releaseManifestLock(manifestPath, lockHandle);
-      }
-    } catch {
-      manifestSaveFailed = true;
-    }
-  }
-
-  const glyph = (ok) => (ctx.mode === "none" ? (ok ? "✔" : "!") : `\x1b[38;2;255;179;71m${ok ? "✔" : "!"}\x1b[0m`);
-  const headlineVerb = copied > 0 ? "installed" : "linked";
-  const backupNote = backedUp > 0 ? `, ${backedUp} backed up` : "";
-  const headlineDetail = copied > 0
-    ? `(new ${installed}, copied ${copied}, updated ${updated}${backupNote}, unchanged ${skipped})`
-    : `(new ${installed}, updated ${updated}${backupNote}, unchanged ${skipped})`;
-  w.write(`  ${glyph(true)} ${files.length} slash commands ${headlineVerb} ${dimLine(ctx, headlineDetail)}\n`);
-  if (pruned > 0) {
-    w.write(`  ${glyph(true)} ${pruned} orphaned symlink${pruned === 1 ? "" : "s"} removed ${dimLine(ctx, "(commands deleted or renamed since last install)")}\n`);
-  }
-  if (staleExtensionlessPruned > 0) {
-    w.write(`  ${glyph(true)} ${staleExtensionlessPruned} stale extensionless entr${staleExtensionlessPruned === 1 ? "y" : "ies"} removed ${dimLine(ctx, "(leftover from prior npx forgedock runs)")}\n`);
-  }
-  if (copied > 0) {
-    w.write(`  ${glyph(false)} ${copied} copied (not linked) ${dimLine(ctx, "— enable Windows Developer Mode for live-updating links")}\n`);
-  }
-  if (scriptsResult.total > 0) {
-    const scriptsChanged = scriptsResult.installed + scriptsResult.updated + scriptsResult.copied;
-    const scriptsDetail = scriptsChanged > 0
-      ? `(new ${scriptsResult.installed}, updated ${scriptsResult.updated}, copied ${scriptsResult.copied}, unchanged ${scriptsResult.skipped})`
-      : `(unchanged ${scriptsResult.skipped})`;
-    w.write(`  ${glyph(true)} ${scriptsResult.total} pipeline scripts linked into ~/.claude/scripts ${dimLine(ctx, scriptsDetail)}\n`);
-  }
-  if (manifestSaveFailed) {
-    w.write("  " + dimLine(ctx, "manifest not saved — re-runs may warn about copied files") + "\n");
-  }
-  if (hookStatus === "skipped-malformed") {
-    w.write(`  ${glyph(false)} SessionStart hook NOT registered — ${settingsPath} is not valid JSON\n`);
-    w.write(fixCard([`Fix the JSON in ${settingsPath}, then re-run: npx forgedock install`], ctx.mode) + "\n");
-  } else {
-    w.write(`  ${glyph(true)} SessionStart hook ${hookStatus === "already" ? "active" : "registered"} ${dimLine(ctx, settingsPath)}\n`);
-  }
-
-  // Persisted-home / ephemeral-cache advisory (forge#1895, extended #1943):
-  // runJourney() calls persistHome(ctx) right before forge() and stashes its
-  // result on ctx.persistHomeResult; when persistHome() actually ran (i.e.
-  // wasn't skipped), ctx.forgeHome above has ALREADY been reassigned to the
-  // stable ~/.forge/ copy, so report that outcome instead of the raw
-  // ephemeral-cache warning. Direct forge() callers that never set
-  // ctx.persistHomeResult (e.g. relinkAndHint() in bin/forgedock.mjs) fall
-  // through to the original ephemeral-cache-only check unchanged.
-  const persistResult = ctx.persistHomeResult;
-  if (persistResult && !persistResult.skipped) {
-    if (persistResult.migrated) {
-      w.write(`  ${glyph(true)} toolset migrated to persisted home ${dimLine(ctx, persistResult.forgeHome)}\n`);
-    } else {
-      w.write(`  ${glyph(true)} persisted home already current ${dimLine(ctx, `v${persistResult.version || "unknown"} at ${persistResult.forgeHome}`)}\n`);
-    }
-  } else if (persistResult && persistResult.skipped && !isEphemeralCachePath(ctx.forgeHome)) {
-    // Skipped for a reason OTHER than "still ephemeral" — today that's always
-    // the git-working-tree exemption (Acceptance Criteria #5). Informational,
-    // not a warning: this is the expected, correct state for a git-clone install.
-    w.write(`  ${dimLine(ctx, `persisted home skipped — ${persistResult.reason || "not applicable"}`)}\n`);
-  } else if (hookStatus !== "skipped-malformed" && isEphemeralCachePath(ctx.forgeHome)) {
-    // Either persistHome() was never run (no ctx.persistHomeResult), or it
-    // ran but failed and left ctx.forgeHome pointing at the original
-    // ephemeral source (fail-open — see persistHome()'s error branch).
-    w.write(`  ${glyph(false)} FORGE_HOME resolves inside an ephemeral cache directory ${dimLine(ctx, ctx.forgeHome)}\n`);
-    w.write(fixCard([
-      "This path (npx/pnpm dlx/yarn dlx cache) can be pruned by npm/npx/pnpm/yarn",
-      "or OS temp cleanup. If that happens, the SessionStart hook silently stops",
-      "injecting ForgeDock context — no error is shown.",
-      "Mitigation: npm install -g forgedock  (or re-run npx forgedock periodically).",
-    ], ctx.mode, "warning") + "\n");
-  }
-
-  // Cross-environment install advisory (forge#1893): warn when this repo is
-  // reachable from both WSL and native Windows and BOTH sides already have a
-  // ForgeDock install. Each environment's install is fully independent (see
-  // #1589 — installs are always global, never per-repo), so running from
-  // both silently leaves forge.yaml/hook paths pointing at whichever side ran
-  // most recently, clobbering the other's config with no error surfaced.
-  // Advisory only — never fails the install.
-  const envInfo = detectEnvironment({ platform: ctx.platform, env: ctx.env, release: ctx.release });
-  const crossEnv = detectCrossEnvInstall(ctx, envInfo);
-  if (crossEnv.conflict) {
-    const otherLabel = crossEnv.direction === "windows" ? "a native Windows" : "a WSL";
-    w.write(`  ${glyph(false)} ${otherLabel} ForgeDock install detected for this repo ${dimLine(ctx, crossEnv.otherPath)}\n`);
-    w.write(fixCard([
-      `This repo is reachable from both WSL and native Windows, and ${otherLabel}`,
-      "install already exists. Each side's install is independent — running",
-      "forgedock from both can leave forge.yaml and hook paths pointing at",
-      "whichever environment ran last, silently overwriting the other's config.",
-      "Mitigation: pick one environment for this repo, or sync forge.yaml manually.",
-    ], ctx.mode, "warning") + "\n");
+    manifestSaveFailed = !(await saveManifestWithMerge(manifestPath, manifestOps));
   }
 
-  // Report enforcement hook status.
-  if (preToolUseStatus !== null) {
-    w.write(`  ${glyph(true)} PreToolUse enforcement hook ${preToolUseStatus === "already" ? "active" : "registered"} ${dimLine(ctx, "(branch/label enforcement)")}\n`);
-  } else {
-    w.write("  " + dimLine(ctx, "PreToolUse hook skipped — requires Claude Code v2.1.163+") + "\n");
-  }
-  // "skipped-malformed" and "absent" are intentionally silent here:
-  // - skipped-malformed: installSessionStartHook() above reads the same
-  //   settingsPath and already prints the malformed-JSON fix-card, so a
-  //   second message would just repeat the same signal.
-  // - absent: the expected steady state (nothing to remove) — this
-  //   function only reports state *changes*, not no-ops.
-  if (subagentStopEnforceStatus === "removed") {
-    w.write(`  ${glyph(true)} SubagentStop enforcement hook removed ${dimLine(ctx, "(non-functional — see forge#1527)")}\n`);
-  }
+  renderForgeReceipt(ctx, {
+    installed, updated, skipped, copied, backedUp, pruned, total: files.length,
+    staleExtensionlessPruned, scriptsResult, manifestSaveFailed,
+    hookStatus, settingsPath, preToolUseStatus, subagentStopEnforceStatus,
+  });
 
   return { installed, updated, skipped, copied, backedUp, pruned, total: files.length, hookStatus, preToolUseStatus, subagentStopEnforceStatus, scriptsResult };
 }