forgedock 1.4.0 → 1.5.1

package/bin/journey.mjs

@@ -747,9 +747,9 @@ export async function preflight(ctx) {
 // Act II — Forging: command symlinks + SessionStart hook (Task 6)
 // ---------------------------------------------------------------------------
 
-import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink, rm } from "fs/promises";
+import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink, rm, open } from "fs/promises";
 import { compareVersions } from "./registry.mjs";
-import { relative, dirname as pathDirname } from "path";
+import { relative, dirname as pathDirname, isAbsolute } from "path";
 import {
   installSessionStartHook,
   installSubagentStopHook,
@@ -855,12 +855,278 @@ async function loadCopiedManifest(manifestPath) {
 /** Save the manifest atomically (mkdir recursive + .tmp+rename). */
 async function saveCopiedManifest(manifestPath, manifest) {
   await mkdir(pathDirname(manifestPath), { recursive: true });
-  await writeFile(manifestPath + ".tmp", JSON.stringify(manifest, null, 2) + "\n", "utf-8");
-  await rename(manifestPath + ".tmp", manifestPath);
+  // Suffix the tmp sibling with this process's PID so concurrent forge()
+  // invocations never share the same tmp path — mirrors the fix already
+  // applied to the copy-file branch in this same function (forge#2542).
+  const tmpPath = manifestPath + "." + process.pid + ".tmp";
+  try {
+    await writeFile(tmpPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+  } catch (writeErr) {
+    await unlink(tmpPath).catch(() => {});
+    throw writeErr;
+  }
+  try {
+    await rename(tmpPath, manifestPath);
+  } catch (renameErr) {
+    await unlink(tmpPath).catch(() => {});
+    throw renameErr;
+  }
+}
+
+// Age (ms) below which a pid-suffixed manifest tmp sibling is assumed to be a
+// concurrent forge()'s in-flight write and left untouched. Anything older is a
+// crash-orphan (SIGKILL/OOM/power loss between writeFile and rename) that no
+// future pid-matched run and no other cleanup path will ever reclaim
+// (forge#2612). Generous relative to real write→rename latency.
+const STALE_MANIFEST_TMP_AGE_MS = 60_000;
+
+// Age (ms) above which a held manifest lock file is assumed to be a
+// crash-orphan (the holder died between acquiring the lock and releasing it)
+// rather than a live concurrent holder, and is safe to reclaim. Deliberately
+// shorter than STALE_MANIFEST_TMP_AGE_MS (60s, forge#2612) rather than
+// matching it: the lock's critical section (one readFile+JSON.parse, an
+// in-memory loop, one writeFile+rename) is far lighter than the write this
+// process guards against staleness in the tmp-sweep case, so a live holder
+// should never legitimately hold this lock anywhere near that long. Not set
+// as low as the original 10s either — that left too little headroom under
+// slow I/O (AV scanning, network home dirs, loaded CI), which could plausibly
+// exceed 10s and trigger premature reclaim of a still-live lock (review
+// finding on PR #2654, forge#2655). 30s is a documented middle ground: 3x the
+// original headroom, still 2x shorter than the tmp precedent.
+const STALE_MANIFEST_LOCK_AGE_MS = 30_000;
+
+// Bounded retry/backoff for acquireManifestLock (forge#2637). Total worst-case
+// wait is small (a few hundred ms) — long enough to let a concurrent holder's
+// short critical section finish, short enough that a stuck/foreign lock never
+// meaningfully delays a forge() run before falling back to unlocked behavior.
+const MANIFEST_LOCK_RETRY_DELAYS_MS = [10, 20, 40, 80, 150];
+
+/**
+ * Acquire an exclusive lock guarding the manifest's final read→merge→write
+ * critical section (forge#2637). Uses `fs.open(lockPath, 'wx')` — O_EXCL
+ * create — as a zero-dependency mutual-exclusion primitive: the call fails
+ * with EEXIST if another process already holds the lock, and succeeds
+ * atomically otherwise (no separate exists-check + create races).
+ *
+ * On contention, retries with the bounded backoff schedule above. Each retry
+ * also opportunistically busts a stale lock (older than
+ * STALE_MANIFEST_LOCK_AGE_MS — a crash-orphan from a holder that died before
+ * releasing) so a hard-killed process can never permanently deadlock future
+ * runs.
+ *
+ * Never throws. Returns the open file handle on success, or `null` if the
+ * lock could not be acquired after all retries — callers MUST treat `null`
+ * as "proceed without the lock" (this file's manifest-save path is
+ * best-effort/never-abort by design; the lock narrows the race window, it is
+ * not a hard correctness requirement).
+ */
+async function acquireManifestLock(manifestPath) {
+  const lockPath = manifestPath + ".lock";
+  for (let attempt = 0; attempt <= MANIFEST_LOCK_RETRY_DELAYS_MS.length; attempt++) {
+    try {
+      return await open(lockPath, "wx");
+    } catch (err) {
+      if (err?.code !== "EEXIST") return null; // unexpected error (e.g. EACCES) — proceed unlocked
+      // Contended — opportunistically reclaim a stale (crash-orphaned) lock.
+      let reclaimed = false;
+      try {
+        const st = await lstat(lockPath);
+        if (Date.now() - st.mtimeMs >= STALE_MANIFEST_LOCK_AGE_MS) {
+          // Re-stat immediately before deleting and only unlink if it's
+          // provably the SAME file we just judged stale (matching inode +
+          // mtime) — a plain lstat-then-unlink-by-path has a window where
+          // the original holder releases and a brand-new live holder
+          // acquires a fresh lock at this same path in between; unlinking
+          // by path alone would then delete that new holder's live lock,
+          // reproducing the exact race this lock exists to prevent, one
+          // layer down (review finding on PR #2654). If the file changed
+          // (or vanished) between the two stats, leave it alone — some
+          // other process has since claimed or released the path — and let
+          // the next retry iteration re-evaluate from scratch.
+          try {
+            const st2 = await lstat(lockPath);
+            if (st2.ino === st.ino && st2.mtimeMs === st.mtimeMs) {
+              await unlink(lockPath).catch(() => {});
+              reclaimed = true;
+            }
+          } catch {
+            // vanished between the two stats — already released, nothing to reclaim
+          }
+        }
+      } catch {
+        // lock file vanished between the failed open and this stat (the
+        // holder released it) — fall through to the next attempt/retry.
+      }
+      // A successful reclaim just proved the path is free — retry open()
+      // immediately instead of waiting out the full backoff delay for this
+      // iteration (review finding on PR #2654, forge#2656). Still counts as
+      // a used attempt (loop counter still advances), it just skips the
+      // sleep.
+      if (reclaimed) continue;
+      if (attempt === MANIFEST_LOCK_RETRY_DELAYS_MS.length) return null; // retries exhausted
+      await new Promise((resolve) => setTimeout(resolve, MANIFEST_LOCK_RETRY_DELAYS_MS[attempt]));
+    }
+  }
+  return null;
+}
+
+/**
+ * Release a lock acquired by acquireManifestLock() (forge#2637). Closes the
+ * handle and removes the lock file. Never throws — same best-effort contract
+ * as the rest of the manifest-save path; a failure to release cleanly is
+ * recovered by the next contender's stale-lock reclaim in
+ * acquireManifestLock() rather than by this function succeeding.
+ */
+async function releaseManifestLock(manifestPath, handle) {
+  if (!handle) return;
+  await handle.close().catch(() => {});
+  await unlink(manifestPath + ".lock").catch(() => {});
+}
+
+/**
+ * Best-effort sweep of crash-orphaned pid-suffixed manifest tmp siblings
+ * (forge#2612). saveCopiedManifest() writes to `manifestPath.<pid>.tmp` then
+ * renames it into place; if the process is hard-killed in that window the
+ * pid-suffixed tmp is orphaned permanently — no future run reuses that exact
+ * pid (unlike the old shared literal `.tmp` name any run would overwrite) and
+ * no other cleanup path scans this directory. Removes siblings matching
+ * `<manifest-basename>.<digits>.tmp` that are older than
+ * STALE_MANIFEST_TMP_AGE_MS (so a concurrent forge()'s in-flight tmp is never
+ * deleted) and are not this process's own live tmp. Never throws —
+ * housekeeping only, same never-abort contract as the manifest-save guard.
+ */
+async function sweepStaleManifestTmps(manifestPath) {
+  const dir = pathDirname(manifestPath);
+  const base = basename(manifestPath);
+  const liveTmp = base + "." + process.pid + ".tmp";
+  // Match only `<base>.<digits>.tmp` — the exact pid-suffixed shape. The legacy
+  // plain `<base>.tmp` (no digit segment) is intentionally excluded so a
+  // foreign/legacy sibling is never reclaimed here.
+  const stalePattern = new RegExp(
+    "^" + base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\.\\d+\\.tmp$",
+  );
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return; // dir missing/unreadable — nothing to reclaim
+  }
+  const now = Date.now();
+  await Promise.all(
+    entries.map(async (name) => {
+      if (name === liveTmp || !stalePattern.test(name)) return;
+      const full = join(dir, name);
+      try {
+        const st = await lstat(full);
+        if (now - st.mtimeMs < STALE_MANIFEST_TMP_AGE_MS) return; // maybe in-flight
+        await unlink(full);
+      } catch {
+        // best-effort — ignore races / permission errors
+      }
+    }),
+  );
 }
 
 const isLinkPermissionError = (err) => err.code === "EPERM" || err.code === "EACCES";
 
+/**
+ * Verify a freshly created symlink is actually readable by *this* process
+ * before trusting it. `fs.symlink()` can return successfully (no EPERM/
+ * EACCES — so `isLinkPermissionError()` never fires) while still producing a
+ * link the OS refuses to resolve for this security/runtime context. The
+ * concrete case this guards against (forge#2620): installing under Git Bash
+ * (MSYS2) on Windows creates an MSYS-style symlink; the reparse point itself
+ * is written successfully, but a native Windows process (the Node binary
+ * behind Claude Code) later hits `"The path cannot be traversed because it
+ * contains an untrusted mount point"` when it tries to read through it. That
+ * failure surfaces at *read* time, not at *creation* time, and with an error
+ * code (`UNKNOWN`/`EIO`, not `EPERM`/`EACCES`) that the existing permission
+ * gate doesn't recognize — so the copy-fallback path never engaged and a
+ * dead, unreadable link was left in place.
+ *
+ * Reading the link back immediately after creating it catches this (and any
+ * other silently-broken-symlink case) regardless of the specific error code
+ * involved, without needing to enumerate every possible OS/runtime error.
+ *
+ * @param {string} target - Path to the symlink just created.
+ * @returns {Promise<boolean>} true if the symlink resolves and is readable.
+ */
+export async function isSymlinkTraversable(target) {
+  try {
+    await readFile(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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
@@ -941,6 +1207,108 @@ async function pruneOrphanedSymlinks(targetDir, commandsDir) {
   return pruned;
 }
 
+/**
+ * Remove leftover extensionless entries at the top level of targetDir left
+ * behind by prior `npx forgedock <command>` runs (forge#2620). Those older
+ * ephemeral invocations created extensionless symlinks/directories (e.g.
+ * `orchestrate`, `pipeline-health`) pointing into the npx download cache
+ * (`%LocalAppData%\npm-cache\_npx\...` / `~/.npm/_npx/...`). Those cache
+ * targets are routinely evicted by npx/npm cache cleanup or OS temp
+ * cleanup, leaving dead entries that collide on the base command name with
+ * the real `{name}.md` file this installer is about to create —
+ * `mkdir(..., {recursive:true})` throws when a same-named non-directory
+ * file already occupies that path segment.
+ *
+ * Conservative by design — must run BEFORE the main install loop so stale
+ * entries are cleared before any mkdir/symlink attempt can collide with
+ * them this run (pruneOrphanedSymlinks above only catches entries that
+ * point *into commandsDir*, and runs after the loop; this catches the
+ * separate npx-cache-origin case pre-emptively). Only removes a top-level
+ * entry when its basename has no file extension (`.md` files and dotfiles
+ * are never touched) AND it is a symlink whose target either no longer
+ * exists or resolves into a known ephemeral cache path
+ * (`isEphemeralCachePath`). Real command directories (e.g. `work-on/`)
+ * created by this installer are plain directories containing `.md` files,
+ * never symlinks — untouched by either condition.
+ *
+ * @param {string} targetDir - ~/.claude/commands
+ * @returns {Promise<number>} Number of stale entries removed.
+ */
+// Matches a Windows drive-relative path like "C:foo" (drive letter + colon,
+// NOT followed by a path separator) — as opposed to a drive-absolute path
+// like "C:\foo" or "C:/foo", which path.isAbsolute() already recognizes
+// correctly. A drive-relative target resolves relative to that drive's own
+// current working directory, which Node has no API to query — there is no
+// way to compute the correct absolute path here (review finding on PR #2658,
+// forge#2659). Deliberately narrow: only fires when isAbsolute() has already
+// said "no" and the string still starts with `<letter>:` immediately
+// followed by a non-separator character. Platform-gated (review finding
+// forge#2663): on POSIX, `:` has no special meaning in filenames, so a
+// literal relative target like `C:foo` is a perfectly valid path component
+// and must NOT be misclassified as an unresolvable Windows drive-relative
+// path — only apply this heuristic on win32.
+const WINDOWS_DRIVE_RELATIVE_RE = /^[A-Za-z]:(?![\\/])/;
+
+export async function pruneStaleExtensionlessEntries(targetDir) {
+  let pruned = 0;
+  let entries;
+  try {
+    entries = await readdir(targetDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return pruned;
+    throw err;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    if (name.includes(".")) continue; // has an extension (or is a dotfile) — never touch
+    if (!entry.isSymbolicLink()) continue; // only manage symlinks here — real dirs/files are left alone
+    const full = join(targetDir, name);
+    let linkTarget;
+    try {
+      linkTarget = await readlink(full);
+    } catch {
+      continue; // unreadable link metadata — skip rather than guess
+    }
+    // readlink() returns whatever string was stored at symlink-creation time.
+    // A relative target is defined (POSIX) relative to the symlink's own
+    // containing directory (targetDir, since full = join(targetDir, name)) —
+    // not the process cwd, which is what a raw lstat(linkTarget) would use.
+    //
+    // Two shapes isAbsolute() alone misclassifies as "relative" and would
+    // otherwise be wrongly joined onto targetDir:
+    //   - Windows drive-relative ("C:foo") — see WINDOWS_DRIVE_RELATIVE_RE
+    //     above; unresolvable here, so the entry is left untouched. Only
+    //     meaningful on win32 (review finding forge#2663) — on POSIX, `:` is
+    //     just an ordinary filename character, so this check is skipped
+    //     there and the target falls through to normal relative resolution.
+    //   - Shell-style tilde ("~/foo", "~\foo", or bare "~") — expand against
+    //     os.homedir() first, matching shell semantics (review finding on
+    //     PR #2658, forge#2660).
+    if (process.platform === "win32" && WINDOWS_DRIVE_RELATIVE_RE.test(linkTarget)) continue; // can't resolve without the drive's own cwd — leave alone
+    let effectiveTarget = linkTarget;
+    if (effectiveTarget === "~" || effectiveTarget.startsWith("~/") || effectiveTarget.startsWith("~\\")) {
+      effectiveTarget = join(os.homedir(), effectiveTarget.slice(1));
+    }
+    const resolvedTarget = isAbsolute(effectiveTarget) ? effectiveTarget : join(targetDir, effectiveTarget);
+    let targetMissing = false;
+    try {
+      await lstat(resolvedTarget);
+    } catch (err) {
+      if (err.code !== "ENOENT") continue; // unexpected error — skip to be safe
+      targetMissing = true;
+    }
+    if (targetMissing || isEphemeralCachePath(linkTarget)) {
+      try {
+        await unlink(full);
+        pruned++;
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+    }
+  }
+  return pruned;
+}
+
 /**
  * Detect whether `p` sits inside a known ephemeral npm/npx/pnpm/yarn cache
  * directory rather than a durable install location (global npm install,
@@ -1378,12 +1746,7 @@ async function linkPipelineScripts(ctx) {
 
     let linked = false;
     if (wantSymlink) {
-      try {
-        await symlink(file, target);
-        linked = true;
-      } catch (linkErr) {
-        if (!isLinkPermissionError(linkErr)) throw linkErr;
-      }
+      linked = (await atomicSymlinkInstall(file, target)) === "linked";
     }
     if (!linked) {
       await copyFile(file, target);
@@ -1520,208 +1883,272 @@ export function detectCrossEnvInstall(ctx, envInfo, deps = {}) {
 }
 
 /**
- * Act II: link commands into ~/.claude/commands with a molten progress line,
- * then register the SessionStart hook.
- * Symlink semantics preserved verbatim from the original install():
- * regular files are skipped with a warning; changed links updated atomically.
- * On Windows without Developer Mode (symlink → EPERM/EACCES) each command is
- * copied instead, and recorded in a manifest so re-runs can tell ForgeDock's
- * own copies apart from user-owned files. ctx.linkStrategy ("symlink" default)
- * can be set to "copy" to skip all symlink attempts (deterministic tests).
+ * 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.
  */
-export async function forge(ctx) {
-  const { stdout: w } = ctx;
-  const commandsDir = join(ctx.forgeHome, "commands");
-  const targetDir = join(ctx.home, ".claude", "commands");
-  const manifestPath = join(ctx.home, ".claude", "forgedock", "copied-commands.json");
-  const wantSymlink = ctx.linkStrategy !== "copy";
-
-  w.write("\n  " + ember("Forging commands", ctx.mode) + " " + dimLine(ctx, `into ${targetDir}`) + "\n\n");
-  await mkdir(targetDir, { recursive: true });
-
-  const manifest = await loadCopiedManifest(manifestPath);
-  let manifestChanged = false;
-
-  const files = await findMarkdownFiles(commandsDir, { includeExtras: !!ctx.includeExtras });
-  let installed = 0, updated = 0, skipped = 0, copied = 0;
-  const barWidth = 24;
-  let barShown = false;
-
-  const recordCopy = (rel) => {
-    if (!manifest.files[rel]) {
-      manifest.files[rel] = true;
-      manifestChanged = true;
-    }
-  };
-
-  for (let i = 0; i < files.length; i++) {
-    const file = files[i];
-    const rel = relative(commandsDir, file);
-    const target = join(targetDir, rel);
-    await mkdir(pathDirname(target), { recursive: true });
-
+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 stats = await lstat(target);
-      if (stats.isSymbolicLink()) {
-        const current = await readlink(target);
-        if (current === file) {
-          skipped++;
+      const mergedManifest = await loadCopiedManifest(manifestPath);
+      for (const { rel, op } of manifestOps) {
+        if (op === "add") {
+          mergedManifest.files[rel] = true;
         } else {
-          let relinked = false;
-          if (wantSymlink) {
-            try {
-              await symlink(file, target + ".tmp");
-              try {
-                await rename(target + ".tmp", target);
-              } catch (renameErr) {
-                await unlink(target + ".tmp").catch(() => {});
-                throw renameErr;
-              }
-              updated++;
-              relinked = true;
-            } catch (linkErr) {
-              if (!isLinkPermissionError(linkErr)) throw linkErr;
-            }
-          }
-          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.
-            await unlink(target);
-            await copyFile(file, target);
-            updated++; // replaces an existing managed entry
-            recordCopy(rel);
-          }
-        }
-      } 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;
-        if (wantSymlink) {
-          try {
-            await symlink(file, target + ".tmp");
-            try {
-              await rename(target + ".tmp", target); // rename replaces existing files on Windows
-            } catch (renameErr) {
-              await unlink(target + ".tmp").catch(() => {});
-              throw renameErr;
-            }
-            updated++;
-            delete manifest.files[rel];
-            manifestChanged = true;
-            upgraded = true;
-          } catch (linkErr) {
-            if (!isLinkPermissionError(linkErr)) throw linkErr;
-          }
-        }
-        if (!upgraded) {
-          const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
-          if (src.equals(dst)) {
-            skipped++;
-          } else {
-            await copyFile(file, target);
-            updated++;
-          }
-        }
-      } else {
-        // Regular file not in manifest — could be a copy from a pre-manifest
-        // ForgeDock version, or a user-owned file. Content-compare: if it
-        // matches source exactly, adopt it into the manifest silently (it was
-        // ours). If it differs, leave it untouched — it may be user-customized.
-        let adopted = false;
-        try {
-          const [src, dst] = await Promise.all([readFile(file), readFile(target)]);
-          if (src.equals(dst)) {
-            recordCopy(rel);
-            skipped++;
-            adopted = true;
-          }
-        } catch { /* readFile failure — fall through to warning */ }
-        if (!adopted) {
-          if (barShown) { w.write("\x1b[1A\x1b[2K"); barShown = false; }
-          w.write(`  WARNING: ${rel} is a regular file — skipping (remove it manually to let ForgeDock manage it)\n`);
-          skipped++;
-        }
-      }
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-      let linked = false;
-      if (wantSymlink) {
-        try {
-          await symlink(file, target);
-          installed++;
-          linked = true;
-          if (manifest.files[rel]) {
-            // Symlinks work now and the old copy is gone — drop the stale record.
-            delete manifest.files[rel];
-            manifestChanged = true;
-          }
-        } catch (linkErr) {
-          if (!isLinkPermissionError(linkErr)) throw linkErr;
+          delete mergedManifest.files[rel];
         }
       }
-      if (!linked) {
-        // Windows without Developer Mode/admin — fall back to a copy.
-        await copyFile(file, target);
-        copied++;
-        recordCopy(rel);
-      }
+      await saveCopiedManifest(manifestPath, mergedManifest);
+    } finally {
+      await releaseManifestLock(manifestPath, lockHandle);
     }
+    return true;
+  } catch {
+    return false;
+  }
+}
 
-    if (ctx.motion) {
-      if (barShown) w.write("\x1b[1A\x1b[2K");
-      w.write(`  ${moltenBar(i + 1, files.length, { width: barWidth, mode: ctx.mode })}  ${i + 1}/${files.length}  ${dimLine(ctx, "/" + rel.replace(/\.md$/, ""))}\n`);
-      barShown = true;
+/**
+ * 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 (barShown) w.write("\x1b[1A\x1b[2K");
-
-  // Prune orphaned symlinks: links that point into commandsDir but whose
-  // target file no longer exists (e.g. after a command is renamed or deleted).
-  const pruned = await pruneOrphanedSymlinks(targetDir, commandsDir);
-
-  // Link the small set of universal pipeline-agent scripts (forge#1885).
-  const scriptsResult = await linkPipelineScripts(ctx);
-
-  const hookScript = join(ctx.forgeHome, "bin", "hooks", "session-start.mjs");
-  const settingsPath = join(ctx.home, ".claude", "settings.json");
-  const { status: hookStatus } = installSessionStartHook(settingsPath, hookScript);
-
-  // Install enforcement hooks (#1250): PreToolUse (branch/label validation)
-  // and SubagentStop interactive engine adapter. Both are idempotent and
-  // always installed (fail-open if settings.json is malformed, same
-  // contract as SessionStart hook).
-  const preToolUseScript = join(ctx.forgeHome, "bin", "hooks", "pre-tool-use.mjs");
-  const subagentStopScript = join(ctx.forgeHome, "bin", "hooks", "interactive-engine.mjs");
-  const { status: preToolUseStatus } = installPreToolUseHook(settingsPath, preToolUseScript);
-  installSubagentStopHook(settingsPath, subagentStopScript);
+  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 };
+}
 
-  // SubagentStop annotation-verifier hook (#1250) is NOT installed: its
-  // trigger condition (a `FORGE:PHASE_START` marker in the transcript) is
-  // never emitted anywhere in the pipeline, so it always exits 0 with zero
-  // enforcement effect while still spawning a process + reading the
-  // transcript on every SubagentStop (forge#1527). Actively clean up any
-  // prior installation instead of installing it.
-  const { status: subagentStopEnforceStatus } = removeSubagentStopEnforceHook(settingsPath);
+/**
+ * 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;
+}
 
-  // Housekeeping — must never abort the receipt or the hook.
-  let manifestSaveFailed = false;
-  if (manifestChanged) {
-    try {
-      await saveCopiedManifest(manifestPath, manifest);
-    } catch {
-      manifestSaveFailed = true;
+/**
+ * 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}, unchanged ${skipped})`
-    : `(new ${installed}, updated ${updated}, unchanged ${skipped})`;
-  w.write(`  ${glyph(true)} ${files.length} slash commands ${headlineVerb} ${dimLine(ctx, headlineDetail)}\n`);
+    ? `(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`);
   }
@@ -1811,8 +2238,178 @@ export async function forge(ctx) {
   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.
+ * Symlink semantics preserved verbatim from the original install():
+ * regular files are skipped with a warning; changed links updated atomically.
+ * On Windows without Developer Mode (symlink → EPERM/EACCES) each command is
+ * copied instead, and recorded in a manifest so re-runs can tell ForgeDock's
+ * own copies apart from user-owned files. ctx.linkStrategy ("symlink" default)
+ * can be set to "copy" to skip all symlink attempts (deterministic tests).
+ */
+export async function forge(ctx) {
+  const { stdout: w } = ctx;
+  const commandsDir = join(ctx.forgeHome, "commands");
+  const targetDir = join(ctx.home, ".claude", "commands");
+  const manifestPath = join(ctx.home, ".claude", "forgedock", "copied-commands.json");
+  const wantSymlink = ctx.linkStrategy !== "copy";
+
+  w.write("\n  " + ember("Forging commands", ctx.mode) + " " + dimLine(ctx, `into ${targetDir}`) + "\n\n");
+  await mkdir(targetDir, { recursive: true });
+
+  // Clear stale extensionless entries from prior `npx forgedock` runs before
+  // the install loop below can collide with them (forge#2620).
+  const staleExtensionlessPruned = await pruneStaleExtensionlessEntries(targetDir);
+
+  const manifest = await loadCopiedManifest(manifestPath);
+  // Reclaim crash-orphaned pid-suffixed tmp siblings left by prior hard-killed
+  // runs (forge#2612). Best-effort — must never abort the forge receipt/hook.
+  await sweepStaleManifestTmps(manifestPath).catch(() => {});
+  let manifestChanged = false;
+  // This run's own manifest mutations, tracked as a replayable diff
+  // (forge#2614). #2599/#2609 fixed the tmp-file *write-path* race (two
+  // concurrent forge() runs no longer collide on the same tmp filename) but
+  // left the manifest's logical *content* racy: each run loads the manifest
+  // into memory once, mutates its own copy across the whole run, then writes
+  // the entire in-memory object back at the end — a classic last-writer-wins
+  // race on manifest.files. Recording this run's own adds/deletes here (instead
+  // of relying on the run-start in-memory snapshot) lets the final save re-read
+  // the on-disk manifest and replay only these ops onto it, so a concurrent
+  // run's own adds/deletes made after this run's initial load are preserved
+  // rather than silently overwritten.
+  const manifestOps = [];
+
+  const files = await findMarkdownFiles(commandsDir, { includeExtras: !!ctx.includeExtras });
+  let installed = 0, updated = 0, skipped = 0, copied = 0, backedUp = 0;
+  const barWidth = 24;
+  let barShown = false;
+
+  const recordCopy = (rel) => {
+    if (!manifest.files[rel]) {
+      manifest.files[rel] = true;
+      manifestChanged = true;
+    }
+    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];
+    const rel = relative(commandsDir, file);
+    const target = join(targetDir, rel);
+    await mkdir(pathDirname(target), { recursive: true });
+
+    try {
+      const stats = await lstat(target);
+      if (stats.isSymbolicLink()) {
+        const current = await readlink(target);
+        if (current === file) {
+          skipped++;
+        } else {
+          let relinked = false;
+          if (wantSymlink) {
+            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.
+            // (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;
+            });
+            await copyFile(file, target);
+            updated++; // replaces an existing managed entry
+            recordCopy(rel);
+          }
+        }
+      } else if (manifest.files[rel]) {
+        const eff = await upgradeManagedCopy(file, target, rel, { wantSymlink, recordDelete });
+        updated += eff.updatedDelta;
+        skipped += eff.skippedDelta;
+      } else {
+        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++;
+        }
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      const eff = await installFreshCommandFile(file, target, rel, { wantSymlink, manifest, recordCopy, recordDelete });
+      installed += eff.installedDelta;
+      copied += eff.copiedDelta;
+    }
+
+    if (ctx.motion) {
+      if (barShown) w.write("\x1b[1A\x1b[2K");
+      w.write(`  ${moltenBar(i + 1, files.length, { width: barWidth, mode: ctx.mode })}  ${i + 1}/${files.length}  ${dimLine(ctx, "/" + rel.replace(/\.md$/, ""))}\n`);
+      barShown = true;
+    }
+  }
+  if (barShown) w.write("\x1b[1A\x1b[2K");
+
+  // Prune orphaned symlinks: links that point into commandsDir but whose
+  // target file no longer exists (e.g. after a command is renamed or deleted).
+  const pruned = await pruneOrphanedSymlinks(targetDir, commandsDir);
+
+  // Link the small set of universal pipeline-agent scripts (forge#1885).
+  const scriptsResult = await linkPipelineScripts(ctx);
+
+  const hookScript = join(ctx.forgeHome, "bin", "hooks", "session-start.mjs");
+  const settingsPath = join(ctx.home, ".claude", "settings.json");
+  const { status: hookStatus } = installSessionStartHook(settingsPath, hookScript);
+
+  // Install enforcement hooks (#1250): PreToolUse (branch/label validation)
+  // and SubagentStop interactive engine adapter. Both are idempotent and
+  // always installed (fail-open if settings.json is malformed, same
+  // contract as SessionStart hook).
+  const preToolUseScript = join(ctx.forgeHome, "bin", "hooks", "pre-tool-use.mjs");
+  const subagentStopScript = join(ctx.forgeHome, "bin", "hooks", "interactive-engine.mjs");
+  const { status: preToolUseStatus } = installPreToolUseHook(settingsPath, preToolUseScript);
+  installSubagentStopHook(settingsPath, subagentStopScript);
+
+  // SubagentStop annotation-verifier hook (#1250) is NOT installed: its
+  // trigger condition (a `FORGE:PHASE_START` marker in the transcript) is
+  // never emitted anywhere in the pipeline, so it always exits 0 with zero
+  // enforcement effect while still spawning a process + reading the
+  // transcript on every SubagentStop (forge#1527). Actively clean up any
+  // prior installation instead of installing it.
+  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) {
+    manifestSaveFailed = !(await saveManifestWithMerge(manifestPath, manifestOps));
+  }
+
+  renderForgeReceipt(ctx, {
+    installed, updated, skipped, copied, backedUp, pruned, total: files.length,
+    staleExtensionlessPruned, scriptsResult, manifestSaveFailed,
+    hookStatus, settingsPath, preToolUseStatus, subagentStopEnforceStatus,
+  });
 
-  return { installed, updated, skipped, copied, pruned, total: files.length, hookStatus, preToolUseStatus, subagentStopEnforceStatus, scriptsResult };
+  return { installed, updated, skipped, copied, backedUp, pruned, total: files.length, hookStatus, preToolUseStatus, subagentStopEnforceStatus, scriptsResult };
 }
 
 // ---------------------------------------------------------------------------