forgedock 1.2.0 → 1.4.0

package/bin/hooks/interactive-engine.mjs

@@ -36,10 +36,10 @@
  * The hook looks for FORGE annotation markers in the transcript's tool
  * results (gh issue comment / gh api calls):
  *
- *   INVESTIGATION:COMPLETE  → phase "investigate" committed
- *   FORGE:CONTEXT           → phase "context" committed
- *   FORGE:ARCHITECT         → phase "architect" committed
- *   FORGE:BUILDER:COMPLETE  → phase "build" committed
+ *   INVESTIGATION:COMPLETE     → phase "investigate" committed
+ *   FORGE:CONTEXT:COMPLETE     → phase "context" committed
+ *   FORGE:ARCHITECT:COMPLETE   → phase "architect" committed
+ *   FORGE:BUILDER:COMPLETE     → phase "build" committed
  *   FORGE:REVIEWER          → phase "review" committed
  *   workflow:merged label   → phase "close" committed (terminal)
  *
@@ -60,6 +60,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 import { dirname, join, resolve } from "path";
 import { existsSync, readFileSync } from "fs";
 import { execFileSync } from "child_process";
+import { PHASE_MARKERS as PHASE_MARKER_REGISTRY } from "../../packages/protocol/src/phases.js";
 
 // ---------------------------------------------------------------------------
 // Bootstrap
@@ -75,18 +76,31 @@ const FORGE_HOME = resolve(__dirname, "..", "..");
 // Maps FORGE annotation markers (found in transcript tool results) to phase IDs.
 // ---------------------------------------------------------------------------
 
+// forge#2378: marker strings are single-sourced from packages/protocol's phase
+// registry (bin/engine/phases.mjs imports the identical registry) — do NOT
+// reintroduce inline "FORGE:..."/"INVESTIGATION:..."/"workflow:merged" literals
+// here. This table previously hand-duplicated those strings and drifted out of
+// sync with the engine's stricter :COMPLETE gate (forge#2375/PR#2395) — sourcing
+// both consumers from one registry makes that class of drift structurally
+// impossible going forward.
+//
+// Require the :COMPLETE suffix — a bare "FORGE:CONTEXT"/"FORGE:ARCHITECT"
+// substring also matches a partial/interrupted annotation (e.g.
+// FORGE:CONTEXT:PARTIAL), which is not actually committed. bin/engine/phases.mjs's
+// architect detectOutcome() requires the identical :COMPLETE marker to consider
+// the phase committed.
 /** @type {Array<{marker: string, phase: string, terminal?: boolean, terminalReason?: string}>} */
 const PHASE_MARKERS = [
-  { marker: "INVESTIGATION:COMPLETE",  phase: "investigate" },
-  { marker: "INVESTIGATION:INVALID",   phase: "investigate", terminal: true, terminalReason: "invalid" },
-  { marker: "DECOMPOSE:YES",           phase: "investigate", terminal: true, terminalReason: "decomposed" },
-  { marker: "FORGE:CONTEXT",           phase: "context" },
-  { marker: "FORGE:ARCHITECT",         phase: "architect" },
-  { marker: "FORGE:BUILDER:COMPLETE",  phase: "build" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.completionMarker, phase: "investigate" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.invalidMarker,    phase: "investigate", terminal: true, terminalReason: "invalid" },
+  { marker: PHASE_MARKER_REGISTRY.investigate.decomposedMarker, phase: "investigate", terminal: true, terminalReason: "decomposed" },
+  { marker: PHASE_MARKER_REGISTRY.context.completionMarker,     phase: "context" },
+  { marker: PHASE_MARKER_REGISTRY.architect.completionMarker,   phase: "architect" },
+  { marker: PHASE_MARKER_REGISTRY.build.completionMarker,       phase: "build" },
   // review phase: PR merged is detected from gh label/state
-  { marker: "FORGE:REVIEWER:MERGED",   phase: "review" },
+  { marker: PHASE_MARKER_REGISTRY.review.completionMarker,      phase: "review" },
   // close phase: issue closed with workflow:merged
-  { marker: "workflow:merged",         phase: "close", terminal: true, terminalReason: "merged" },
+  { marker: PHASE_MARKER_REGISTRY.close.completionLabel,        phase: "close", terminal: true, terminalReason: "merged" },
 ];
 
 /**
@@ -164,13 +178,15 @@ async function main() {
   // missing, block the subagent from completing silently and inject
   // corrective context so the agent knows what to do.
   if (skillInvoked && annotationMissing && phaseId) {
+    // forge#2378: sourced from the same registry as PHASE_MARKERS above — no
+    // second hand-written copy of these marker strings.
     const PHASE_ANNOTATION_MAP = {
-      investigate: "INVESTIGATION:COMPLETE (or INVESTIGATION:INVALID / DECOMPOSE:YES)",
-      context:     "FORGE:CONTEXT",
-      architect:   "FORGE:ARCHITECT",
-      build:       "FORGE:BUILDER:COMPLETE",
-      review:      "FORGE:REVIEWER:MERGED",
-      close:       "workflow:merged label",
+      investigate: `${PHASE_MARKER_REGISTRY.investigate.completionMarker} (or ${PHASE_MARKER_REGISTRY.investigate.invalidMarker} / ${PHASE_MARKER_REGISTRY.investigate.decomposedMarker})`,
+      context:     PHASE_MARKER_REGISTRY.context.completionMarker,
+      architect:   PHASE_MARKER_REGISTRY.architect.completionMarker,
+      build:       PHASE_MARKER_REGISTRY.build.completionMarker,
+      review:      PHASE_MARKER_REGISTRY.review.completionMarker,
+      close:       `${PHASE_MARKER_REGISTRY.close.completionLabel} label`,
     };
     const expected = PHASE_ANNOTATION_MAP[phaseId] || `the ${phaseId} phase annotation`;
     // Output additionalContext JSON (v2.1.163+ SubagentStop format).
@@ -308,6 +324,20 @@ export function parseTranscript(transcriptPath) {
  *   - Scan tool_result entries for gh CLI output containing FORGE annotation markers
  *   - Extract issue number from Skill args or from the skill name context
  *
+ * `outputs` is intentionally always `{}` from this function (forge#2375): earlier
+ * versions matched a bare `"number"` field and a bare `branch[:space]` token against
+ * the full text of every tool_result block, with no scoping to a FORGE-authoritative
+ * source. That regularly matched unrelated JSON (e.g. `gh issue view`'s own `"number"`
+ * field, matching the issue's own number as if it were a PR) or unrelated prose
+ * containing the word "branch", producing corrupt PHASE_COMMIT run-log entries
+ * (observed: `branch:"diff"`, `branch:"writer"`, `branch:"refs"`, `pr:<issue#>`).
+ * Those values were also consumed as a state fallback by
+ * bin/engine/runlog.mjs:deriveState() → bin/engine/phases.mjs:resolveBranch(), so a
+ * corrupt hook-derived value could leak into the engine's own resolution path. The
+ * engine already resolves branch/PR from GitHub ground truth
+ * (bin/engine/phases.mjs:parseBranchFromMarkers(), scoped to the FORGE:BUILDER:COMPLETE
+ * comment — forge#2184) on next pickup, so no replacement extraction is needed here.
+ *
  * @param {object[]} entries
  * @returns {{ issueNumber: number|null, phaseId: string|null, terminalReason: string|null, outputs: object, skillInvoked: boolean, annotationMissing: boolean }}
  */
@@ -352,12 +382,8 @@ export function detectPhase(entries) {
         for (const { marker } of PHASE_MARKERS) {
           if (content.includes(marker)) foundMarkers.add(marker);
         }
-        // Extract PR number if present.
-        const prM = content.match(/"number"\s*:\s*(\d+)/);
-        if (prM) outputs.pr = parseInt(prM[1], 10);
-        // Extract branch from git push output.
-        const branchM = content.match(/(?:refs\/heads\/|branch[:\s]+)([\w\-./]+)/i);
-        if (branchM) outputs.branch = branchM[1];
+        // No PR/branch extraction here (forge#2375) — see the JSDoc above
+        // detectPhase() for why. `outputs` stays empty from this scan.
       }
 
       // Also scan assistant message text blocks for FORGE markers.

package/bin/hooks/pre-tool-use.mjs

@@ -151,17 +151,104 @@ async function getInvariants() {
 /**
  * Allowed label transitions: from → [to, ...]
  * A label not in this map can be added freely (not a workflow: label).
+ *
+ * `workflow:invalid` is reachable from `ready-to-build`, `building`, and
+ * `in-review` (issue #2326) — not just from `investigating` — because
+ * invalidity is not always discovered where the pipeline first labels the
+ * issue "ready to build". A cheap false positive is usually caught during
+ * investigation; a subtler one is only disproved once the architect/build
+ * phase reads the actual code and tests (see #2312: the premise wasn't
+ * disproved until Phase 3C.6 read `bin/tests/engine-crash.test.mjs`).
+ *
+ * These three post-investigation successors are NOT unconditional, though —
+ * see EVIDENCE_REQUIRED_TARGETS below and its enforcement in
+ * checkLabelTransition(). Reaching `workflow:invalid` from any of these
+ * three states requires a posted reversal comment (a second
+ * `FORGE:INVESTIGATOR` comment carrying `**Verdict**: INVALID`) already on
+ * the issue — the state machine still refuses a bare relabel with no
+ * evidence trail. This preserves the original protection (see history below)
+ * while making the terminal state reachable where it is actually discovered.
+ *
+ * History: this map was introduced by #1250/#1513 to stop arbitrary/skipped
+ * label jumps (e.g. investigating → merged in one hop) — it enforces that
+ * every workflow label transition follows the pipeline's real phase order,
+ * with corrective error messages naming the legal next states. Widening a
+ * terminal-reachability edge is safe as long as an equivalent guard (the
+ * evidence precondition) replaces the blanket "not reachable at all" rule
+ * for the specific case this hook was never asked to consider: legitimate,
+ * evidenced invalidation discovered after ready-to-build.
  */
 const LABEL_TRANSITIONS = {
   "workflow:investigating": ["workflow:ready-to-build", "workflow:invalid", "workflow:decomposed"],
-  "workflow:ready-to-build": ["workflow:building"],
-  "workflow:building": ["workflow:in-review", "workflow:ready-to-build"], // retry allowed
-  "workflow:in-review": ["workflow:merged", "workflow:building"],         // review → re-build allowed
+  "workflow:ready-to-build": ["workflow:building", "workflow:invalid"],
+  "workflow:building": ["workflow:in-review", "workflow:ready-to-build", "workflow:invalid"], // retry allowed; evidenced reversal allowed (#2326)
+  "workflow:in-review": ["workflow:merged", "workflow:building", "workflow:invalid"],         // review → re-build allowed; evidenced reversal allowed (#2326)
   "workflow:merged": [],     // terminal — no successors
   "workflow:invalid": [],    // terminal
   "workflow:decomposed": [], // terminal
 };
 
+/**
+ * States from which a transition to `workflow:invalid` requires posted
+ * evidence (a reversal comment), rather than being freely allowed.
+ * `workflow:investigating` is deliberately excluded — invalidation
+ * discovered during initial investigation is the pipeline's normal,
+ * unguarded path (Phase 1D) and needs no additional precondition.
+ */
+const EVIDENCE_REQUIRED_FOR_INVALID_FROM = new Set([
+  "workflow:ready-to-build",
+  "workflow:building",
+  "workflow:in-review",
+]);
+
+/**
+ * `authorAssociation` values (as returned by `gh issue view --json comments`,
+ * which GitHub computes server-side from the commenter's actual repo/org
+ * relationship) that are trusted to post reversal evidence. Deliberately
+ * NOT a hardcoded bot login: the pipeline's own `gh` identity legitimately
+ * rotates (issue #1722 — the primary automation account's token went invalid
+ * mid-batch and a session switched to a maintainer's personal account to keep
+ * working), and a literal-login allowlist would fail closed the next time
+ * identity rotates. Checking the GitHub-computed relationship instead of a
+ * specific account name survives that rotation: whichever account is
+ * authenticated, as long as it is an org member / repo owner / granted
+ * collaborator access, reports one of these three values regardless of which
+ * account it is. Everything else — `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`,
+ * `NONE`, or a missing/malformed field — is untrusted and must NOT satisfy
+ * the evidence check (issue #2332: this repo is public with no interaction
+ * restrictions, so any free GitHub account can otherwise post a comment
+ * matching the marker + verdict text below).
+ */
+const TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+
+/**
+ * A reversal comment is a `FORGE:INVESTIGATOR` annotation whose verdict is
+ * INVALID — i.e. a second investigation report that supersedes the
+ * original CONFIRMED/PARTIAL verdict with citable evidence (see #2312's
+ * "Investigation Report — CORRECTED" comment for the live example this
+ * pattern is modeled on). Matching on the marker + verdict line only (not
+ * on incident-specific text like issue numbers or the word "CORRECTED")
+ * keeps this a general-purpose evidence check, not a one-off special case.
+ *
+ * In addition to the marker + verdict text, the comment's author must carry
+ * a trusted `authorAssociation` (see TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS
+ * above, issue #2332) — otherwise any commenter, with no write access to the
+ * repository, could forge the marker text and unlock this transition.
+ *
+ * @param {Array<{body?: string, authorAssociation?: string}>} comments
+ * @returns {boolean}
+ */
+function hasInvalidReversalEvidence(comments) {
+  if (!Array.isArray(comments)) return false;
+  return comments.some((c) => {
+    const body = String((c && c.body) || "");
+    if (!body.includes("FORGE:INVESTIGATOR")) return false;
+    if (!/\*\*Verdict\*\*:\s*INVALID/i.test(body)) return false;
+    const association = String((c && c.authorAssociation) || "").toUpperCase();
+    return TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS.has(association);
+  });
+}
+
 /** Labels that are never allowed as a PR --base target. */
 const FORBIDDEN_PR_BASES = ["main", "master"];
 
@@ -180,13 +267,29 @@ const WORKFLOW_LABEL_PREFIX = "workflow:";
 // ---------------------------------------------------------------------------
 
 /**
- * Match a `find` search-root token that is exactly the filesystem root (`/`)
- * or a bare Git-Bash drive mount (`/c`, `/d`, `/C`, ... — a single letter,
- * case-insensitive, optionally followed by nothing else). Deliberately does
- * NOT match `/c/Users/...` or any other scoped absolute path — only the bare
- * root/drive-mount token itself.
+ * Match a `find` search-root token that reaches the exact same whole-drive,
+ * non-terminating scan on Git Bash as the bare filesystem root (`/`) or a
+ * bare drive mount (`/c`, `/d`, ...). This includes trailing-slash drive
+ * mounts (`/c/`) — a natural way to write the same root, since `/c` and
+ * `/c/` are the identical directory — and the dot/double-slash root
+ * variants `/.`, `/..`, `//`, which likewise resolve to (or immediately
+ * above, which Git Bash still normalizes to) the same whole-drive tree
+ * (issue #2113 — PR #2112 review finding SEC-1: `find /c/` was silently
+ * ALLOWED because the prior regex had no trailing-slash/dot alternative).
+ * This also includes the trailing-slash dot forms `/./` and `/../` — the
+ * dot alternative did not originally carry the same optional trailing
+ * slash the drive-letter alternative got in #2113, so those two bare
+ * tokens reached the identical whole-drive scan but were wrongly ALLOWED
+ * (issue #2213).
+ *
+ * Deliberately does NOT match `/c/Users/...`, `/./foo`, `/../foo` (with
+ * anything beyond the trailing slash), or any other scoped absolute path —
+ * only the bare root/drive-mount token itself, optionally followed by
+ * exactly one trailing slash (drive-letter and dot/double-slash cases) or
+ * standing alone. Case-insensitive on the drive letter only (POSIX paths
+ * are otherwise case-sensitive).
  */
-const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z])?$/;
+const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z]\/?|\.{1,2}\/?|\/)?$/;
 
 /**
  * Shell metacharacters that can glue a command name to an adjacent token
@@ -493,7 +596,13 @@ function checkPrTarget(command) {
  *
  * Reads the current workflow labels from GitHub via `gh issue view` and
  * validates that the new label is a legal successor in the state machine.
- * Falls back to allow (exit 0) on any gh CLI error so the hook is fail-open.
+ * Falls back to allow (exit 0) on a `gh` CLI error for ordinary transitions,
+ * so the hook stays resilient to transient `gh`/network failures. The one
+ * exception (#2347): when the attempted transition is to `workflow:invalid`
+ * (`mayNeedEvidence`), the same lookup also fetches the reversal-evidence
+ * comments required by the evidence gate below — a `gh` error there fails
+ * *closed* instead, so a transient CLI error can never silently bypass the
+ * evidence gate the way a blanket fail-open would.
  *
  * @param {string} command
  * @returns {string|null} Error message to show, or null if allowed.
@@ -522,11 +631,18 @@ function checkLabelTransition(command) {
   // Extract repo (-R flag) if present.
   const repoFlag = extractFlag(command, "-R") || extractFlag(command, "--repo");
 
-  // Read current labels from GitHub synchronously.
+  // Read current labels from GitHub synchronously. Also fetch comments when
+  // the requested transition is one that requires reversal evidence (see
+  // EVIDENCE_REQUIRED_FOR_INVALID_FROM) — deferred to a single conditional
+  // extra field so the common case (any other transition) stays a
+  // labels-only fetch, unchanged from before #2326.
   let currentWorkflowLabel = null;
+  let comments = null;
+  const mayNeedEvidence = newLabel === "workflow:invalid";
   try {
     const { execFileSync: exec } = _require("child_process");
-    const args = ["issue", "view", issueNum, "--json", "labels"];
+    const fields = mayNeedEvidence ? "labels,comments" : "labels";
+    const args = ["issue", "view", issueNum, "--json", fields];
     if (repoFlag) { args.push("-R", repoFlag); }
     const out = exec("gh", args, {
       encoding: "utf-8",
@@ -543,8 +659,29 @@ function checkLabelTransition(command) {
         currentWorkflowLabel = lbl;
       }
     }
+    if (mayNeedEvidence) {
+      comments = Array.isArray(parsed.comments) ? parsed.comments : [];
+    }
   } catch {
-    return null; // gh CLI error — fail-open
+    if (mayNeedEvidence) {
+      // #2347: the lookup that failed is the same one that would have
+      // fetched the reversal-evidence comments for the workflow:invalid
+      // evidence gate (#2326/#2332). Fail closed here instead of silently
+      // allowing an unverified workflow:invalid transition through.
+      return [
+        `[ForgeDock] BLOCKED: Unable to verify workflow:invalid evidence (gh CLI error).`,
+        ``,
+        `Attempted transition: → "workflow:invalid"`,
+        ``,
+        `This transition requires verifying a posted reversal comment, but the`,
+        `"gh issue view" lookup used to fetch that evidence failed. Failing`,
+        `closed rather than silently bypassing the evidence gate.`,
+        ``,
+        `This is transient, not permanent: retry once "gh issue view ${issueNum}"`,
+        `succeeds again (e.g. after a network blip or rate-limit reset).`,
+      ].join("\n");
+    }
+    return null; // gh CLI error on an ordinary transition — fail-open
   }
 
   if (!currentWorkflowLabel) {
@@ -581,6 +718,35 @@ function checkLabelTransition(command) {
     ].join("\n");
   }
 
+  // Evidence precondition (#2326): reaching workflow:invalid from
+  // ready-to-build/building/in-review is structurally allowed above, but
+  // still gated against *casual* invalidation — a bare relabel with no
+  // paper trail is blocked. Require a posted reversal comment (a second
+  // FORGE:INVESTIGATOR annotation carrying "**Verdict**: INVALID") already
+  // on the issue before allowing the transition through, from a trusted
+  // author (issue #2332 — marker text alone is forgeable by anyone who can
+  // comment on a public issue; see TRUSTED_REVERSAL_AUTHOR_ASSOCIATIONS).
+  if (newLabel === "workflow:invalid" && EVIDENCE_REQUIRED_FOR_INVALID_FROM.has(currentWorkflowLabel)) {
+    if (!hasInvalidReversalEvidence(comments)) {
+      return [
+        `[ForgeDock] BLOCKED: workflow:invalid requires reversal evidence.`,
+        ``,
+        `Current workflow state: "${currentWorkflowLabel}"`,
+        `Attempted transition: → "workflow:invalid"`,
+        ``,
+        `This transition is allowed only when the issue carries a posted reversal:`,
+        `a FORGE:INVESTIGATOR comment with "**Verdict**: INVALID" documenting the`,
+        `evidence that disproved the original premise (see #2312 for the pattern),`,
+        `posted by an author with a trusted authorAssociation (OWNER, MEMBER, or`,
+        `COLLABORATOR — see #2332). A comment matching the marker text from any`,
+        `other commenter does not satisfy this gate.`,
+        ``,
+        `Fix: post the corrected investigation report first (verdict INVALID, with`,
+        `evidence, from a trusted account), then retry this label transition.`,
+      ].join("\n");
+    }
+  }
+
   return null; // valid transition — allow
 }
 
@@ -682,12 +848,16 @@ function extractLogicalTokens(command) {
 
 /**
  * Check whether a Bash command contains a `find` invocation whose search
- * root is the filesystem root (`/`) or a bare Git-Bash drive mount (`/c`,
- * `/d`, ...). On Windows Git Bash, `/` spans every mounted drive, so a
- * root-anchored `find` never terminates and accumulates as an orphaned,
- * CPU-exhausting process (issue #2034 — #1984 was a narrow precursor fix
- * that only patched a single call site + added a prose guardrail; this is
- * the systemic, deterministic follow-up).
+ * root is the filesystem root (`/`), a bare Git-Bash drive mount (`/c`,
+ * `/d`, ...), a trailing-slash drive mount (`/c/`), or a dot/double-slash
+ * root variant (`/.`, `/..`, `//`). On Windows Git Bash, `/` spans every
+ * mounted drive, so a root-anchored `find` never terminates and accumulates
+ * as an orphaned, CPU-exhausting process (issue #2034 — #1984 was a narrow
+ * precursor fix that only patched a single call site + added a prose
+ * guardrail; this is the systemic, deterministic follow-up. Issue #2113
+ * widened the root-token match to also cover the trailing-slash/dot
+ * variants, which reach the identical whole-drive scan but were not
+ * originally matched by `FIND_ROOT_TOKEN_RE`).
  *
  * Scans ALL logical tokens for a `find` occurrence (not just the first word
  * of the command), so it catches `find` appearing after `&&`, `;`, `|`, a

package/bin/journey.mjs

@@ -747,7 +747,8 @@ 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 } from "fs/promises";
+import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink, rm } from "fs/promises";
+import { compareVersions } from "./registry.mjs";
 import { relative, dirname as pathDirname } from "path";
 import {
   installSessionStartHook,
@@ -1073,6 +1074,60 @@ async function copyDirIfChanged(srcDir, destDir) {
   return { copied, unchanged };
 }
 
+/**
+ * Recursively delete entries in `destDir` that no longer exist in `srcDir`.
+ * The mirror-image of copyDirIfChanged(): that function is additive-only (it
+ * copies new/changed files but never removes anything), so a file dropped or
+ * renamed upstream would otherwise linger in the persisted `~/.forge/` copy
+ * forever (forge#2133). A missing `srcDir` or `destDir` is treated as
+ * "nothing to reconcile" rather than an error — mirrors copyDirIfChanged()'s
+ * own ENOENT handling.
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @returns {Promise<{ removed: number }>}
+ */
+async function removeOrphans(srcDir, destDir) {
+  let destEntries;
+  try {
+    destEntries = await readdir(destDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return { removed: 0 };
+    throw err;
+  }
+
+  let srcNames = null;
+  try {
+    const srcEntries = await readdir(srcDir, { withFileTypes: true });
+    srcNames = new Set(srcEntries.map((e) => e.name));
+  } catch (err) {
+    if (err.code !== "ENOENT" && err.code !== "ENOTDIR") throw err;
+    // srcDir missing entirely (ENOENT), or the corresponding source path changed
+    // type and is no longer a directory — e.g. a symlink-to-file replacing what
+    // used to be a real directory (ENOTDIR) — every dest entry is an orphan.
+    // Treating both the same way keeps this a per-path fail-open instead of
+    // letting an uncaught ENOTDIR escape to persistHome()'s single outer catch,
+    // which would otherwise silently skip the *entire* persist for one bad path
+    // (forge#2227).
+    srcNames = new Set();
+  }
+
+  let removed = 0;
+  for (const entry of destEntries) {
+    const destPath = join(destDir, entry.name);
+    if (!srcNames.has(entry.name)) {
+      await rm(destPath, { recursive: true, force: true });
+      removed++;
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const sub = await removeOrphans(join(srcDir, entry.name), destPath);
+      removed += sub.removed;
+    }
+  }
+  return { removed };
+}
+
 /**
  * Copy ForgeDock's own installable payload (bin/, commands/, scripts/,
  * templates/) from wherever the package currently resolved — npm global
@@ -1115,6 +1170,7 @@ async function copyDirIfChanged(srcDir, destDir) {
  *   version: string,
  *   filesCopied?: number,
  *   filesUnchanged?: number,
+ *   filesRemoved?: number,
  * }>}
  */
 export async function persistHome(ctx) {
@@ -1142,15 +1198,55 @@ export async function persistHome(ctx) {
     // proceed with version === ""
   }
 
+  // Downgrade guard (forge#2133): if a newer version is already persisted at
+  // ~/.forge/version than the source package we're about to copy from, skip
+  // the copy entirely rather than silently overwriting newer files with
+  // older ones. This happens when a stale resolved package (e.g. a plain
+  // `npx forgedock update` that resolved an old global install) runs after
+  // ~/.forge/ was already refreshed to a newer version by some other path
+  // (e.g. `npx forgedock@latest`). Both `version` and the persisted value
+  // must be non-empty for the guard to apply — an unreadable/missing
+  // ~/.forge/version is treated as "no guard needed" so first-run persist
+  // is never blocked.
+  const persistedVersionPath = join(persistedHome, "version");
+  let existingPersistedVersion = "";
+  let persistedVersionFileExists = true;
+  try {
+    existingPersistedVersion = readFileSync(persistedVersionPath, "utf-8").trim();
+  } catch {
+    // missing/unreadable — proceed, nothing to guard against. Tracked
+    // separately from existingPersistedVersion's "" default so the
+    // versionChanged check below (a fresh persist with no prior version
+    // file) is still correctly treated as "changed" even when the source
+    // package's own version also resolves to "" (e.g. missing package.json).
+    persistedVersionFileExists = false;
+  }
+  if (
+    version &&
+    existingPersistedVersion &&
+    compareVersions(version, existingPersistedVersion) < 0
+  ) {
+    return {
+      forgeHome: persistedHome,
+      migrated: false,
+      skipped: true,
+      reason: `refusing to downgrade ~/.forge/ from v${existingPersistedVersion} to v${version} — source package is older than what's already persisted`,
+      version: existingPersistedVersion,
+    };
+  }
+
   try {
     await mkdir(persistedHome, { recursive: true });
 
     let filesCopied = 0;
     let filesUnchanged = 0;
+    let filesRemoved = 0;
     for (const name of PERSIST_HOME_DIRS) {
       const res = await copyDirIfChanged(join(source, name), join(persistedHome, name));
       filesCopied += res.copied;
       filesUnchanged += res.unchanged;
+      const pruned = await removeOrphans(join(source, name), join(persistedHome, name));
+      filesRemoved += pruned.removed;
     }
 
     // Also persist package.json itself (not just PERSIST_HOME_DIRS) — several
@@ -1181,18 +1277,19 @@ export async function persistHome(ctx) {
 
     // Write ~/.forge/version — content-compared like everything else here so
     // an unchanged version doesn't touch the file's mtime on every re-run.
-    const versionPath = join(persistedHome, "version");
-    let versionChanged = true;
-    try {
-      versionChanged = readFileSync(versionPath, "utf-8").trim() !== version;
-    } catch {
-      // missing/unreadable — treat as changed
-    }
+    // Reuses persistedVersionPath/existingPersistedVersion read above for the
+    // downgrade guard rather than re-reading the same file a second time. A
+    // version file that didn't exist yet (persistedVersionFileExists: false)
+    // always counts as "changed", regardless of whether the source's own
+    // version happens to also be "" (e.g. missing package.json) — otherwise
+    // "" !== "" would wrongly read as unchanged on a fresh, never-persisted
+    // ~/.forge/.
+    let versionChanged = !persistedVersionFileExists || existingPersistedVersion !== version;
     if (versionChanged) {
-      const tmpVersionPath = versionPath + ".tmp";
+      const tmpVersionPath = persistedVersionPath + ".tmp";
       try {
         writeFileSync(tmpVersionPath, version + "\n", "utf-8");
-        renameSync(tmpVersionPath, versionPath);
+        renameSync(tmpVersionPath, persistedVersionPath);
       } catch (err) {
         try { unlinkSync(tmpVersionPath); } catch { /* best-effort cleanup */ }
         throw err;
@@ -1201,11 +1298,12 @@ export async function persistHome(ctx) {
 
     return {
       forgeHome: persistedHome,
-      migrated: filesCopied > 0 || versionChanged,
+      migrated: filesCopied > 0 || filesRemoved > 0 || versionChanged,
       skipped: false,
       version,
       filesCopied,
       filesUnchanged,
+      filesRemoved,
     };
   } catch (err) {
     // Fail-open (forge#383): a permission error, disk-full, etc. must never

package/bin/labels.json

@@ -64,6 +64,11 @@
     "color": "E4E669",
     "description": "Pipeline stalled — requires human intervention. Managed by ForgeDock."
   },
+  {
+    "name": "workflow:engine-error",
+    "color": "B60205",
+    "description": "Pipeline stalled — engine/tool failure (not a genuine human-judgment block). Managed by ForgeDock."
+  },
   {
     "name": "blocked-on-human-merge",
     "color": "006B75",