forgedock 1.5.1 → 1.6.0

package/bin/forgedock.mjs

@@ -59,8 +59,8 @@ import {
   detectClaudeVersion,
   loadBreakpoints,
   hasFeature,
-  getPersistedHomeState,
   setPersistedHomeState,
+  getInstalledCommandsDriftStatus,
 } from "./registry.mjs";
 import { renderMark, ember } from "./cinema.mjs";
 import {
@@ -2740,27 +2740,16 @@ async function doctor(fix = false) {
             `incomplete (missing: ${missingDirs.join(", ")}). Run: npx forgedock install`,
           );
         } else {
-          // Prefer the version registry.mjs last recorded for this exact
-          // write (getPersistedHomeState()) — the single source of truth
-          // update()/install also write through — falling back to reading
-          // ~/.forge/version directly on disk when the registry has no entry
-          // (e.g. an older ForgeDock version wrote ~/.forge/ before #1943
-          // added registry tracking). Reading both keeps doctor() honest
-          // even if the registry ever drifts from what's actually on disk.
-          const recorded = getPersistedHomeState();
-          let persistedVersion = recorded?.version || "";
-          if (!persistedVersion) {
-            try {
-              persistedVersion = readFileSync(versionPath, "utf-8").trim();
-            } catch {
-              // version file missing/unreadable — reported below as "unknown"
-            }
-          }
-          const sourceVersion = getVersion();
-          if (persistedVersion && sourceVersion && compareVersions(persistedVersion, sourceVersion) < 0) {
+          // Package-vs-installed-commands drift comparison is factored into
+          // a single shared helper (bin/registry.mjs's
+          // getInstalledCommandsDriftStatus, forge#2719) so doctor, the
+          // `version` command, and the SessionStart hook all agree on one
+          // source of truth instead of re-deriving this logic independently.
+          const { persistedVersion, isStale, unknown } = getInstalledCommandsDriftStatus(FORGE_HOME);
+          if (!unknown && isStale) {
             warn(
               "Persisted toolset home (~/.forge)",
-              `v${persistedVersion} — source is v${sourceVersion}. Run: npx forgedock update`,
+              `v${persistedVersion} — source is v${getVersion()}. Run: npx forgedock update`,
             );
           } else {
             pass("Persisted toolset home (~/.forge)", `v${persistedVersion || "unknown"} at ${persistedHome}`);
@@ -3959,6 +3948,18 @@ switch (command) {
           `Run ${CYAN}npx forgedock update${RESET} to fetch it.`,
       );
     }
+
+    // forge#2719 — surface package-vs-installed-commands drift (previously
+    // only visible via `doctor` Check 5d). Uses the same shared helper doctor
+    // calls, so both surfaces agree. Silent when versions match or when
+    // either version is unknown (e.g. a git-clone dev install, which never
+    // persists to ~/.forge — see registry.mjs's getInstalledCommandsDriftStatus).
+    const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+    if (!driftStatus.unknown && driftStatus.isStale) {
+      console.log(
+        `  ${YELLOW}Installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion}${RESET} — run: ${CYAN}npx forgedock update${RESET}`,
+      );
+    }
     break;
   }
   case "help":

package/bin/hooks/session-start.mjs

@@ -51,6 +51,8 @@ const FORGE_HOME = resolve(__dirname, "..", "..");
 let resolveState;
 let nudgeSeen;
 let markNudgeSeen;
+// Assigned alongside the other registry.mjs helpers below — see forge#2719.
+let getInstalledCommandsDriftStatus;
 
 // ---------------------------------------------------------------------------
 // forge-utils helpers — populated inside the try block to honour fail-open
@@ -88,7 +90,7 @@ try {
   // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
   /** @type {import('../registry.mjs')} */
   (
-    { resolveState, nudgeSeen, markNudgeSeen } = await import(
+    { resolveState, nudgeSeen, markNudgeSeen, getInstalledCommandsDriftStatus } = await import(
       pathToFileURL(join(FORGE_HOME, "bin", "registry.mjs")).href
     )
   );
@@ -126,6 +128,25 @@ try {
   const cwd = process.cwd();
   const state = resolveState(cwd);
 
+  // Surface package-vs-installed-commands drift as a single non-fatal
+  // advisory line (forge#2719). Uses the same shared helper doctor's
+  // Check 5d and the `version` command call, so all three surfaces agree.
+  // Best-effort: any failure here must never block the session, and
+  // managed-optedout directories stay completely silent per this hook's
+  // existing contract for that state (see the switch below).
+  if (state !== "managed-optedout") {
+    try {
+      const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+      if (!driftStatus.unknown && driftStatus.isStale) {
+        console.log(
+          `ForgeDock: installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion} — run: npx forgedock update`,
+        );
+      }
+    } catch {
+      // Fail open — never let a drift-check error affect session start.
+    }
+  }
+
   switch (state) {
     case "managed-active":
       await handleManagedActive(cwd);

package/bin/registry.mjs

@@ -465,6 +465,92 @@ export async function setPersistedHomeState({ path, version, updatedAt } = {}) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Package-vs-installed-commands drift detection (issue #2719)
+// ---------------------------------------------------------------------------
+//
+// Single shared source of truth for "is the persisted ~/.forge/ toolset
+// (commands/skills the SessionStart hook and ~/.claude/commands actually
+// load) older than the forgedock package currently running?" — previously
+// this comparison existed only inline inside doctor's Check 5d
+// (bin/forgedock.mjs), so a user who bumped the npm package but never ran
+// `forgedock update` had no way to learn about the drift outside of
+// proactively running `doctor`. This helper is now the one place the
+// comparison lives; doctor, the `version` command, and the SessionStart hook
+// all call it instead of re-deriving the logic (forge#1589 split-brain
+// precedent — see the persistHome() comment above for why that matters).
+
+/**
+ * Compare the running forgedock package's version against the version last
+ * persisted to `~/.forge/` (the copy the SessionStart hook and
+ * `~/.claude/commands` actually load from — see persistHome() in
+ * bin/journey.mjs).
+ *
+ * Fail-open: never throws. Any failure to read either version (missing/
+ * corrupt package.json, missing/corrupt registry, missing/unreadable
+ * `~/.forge/version` file) resolves to `unknown: true` with empty version
+ * strings, rather than propagating an error to the caller. This mirrors the
+ * fail-open contract required of both doctor (best-effort diagnostics) and
+ * the SessionStart hook (must never block a Claude Code session — see
+ * forge#383/forge#489).
+ *
+ * Version comparison delegates to the already-fixed compareVersions() above
+ * (forge#1932 — do not reimplement comparison logic here).
+ *
+ * @param {string} forgeHome - Absolute path to the ForgeDock installation
+ *   root whose package.json holds the "source" version (the package
+ *   currently running). Callers pass their own FORGE_HOME.
+ * @returns {{
+ *   persistedVersion: string,
+ *   sourceVersion: string,
+ *   isStale: boolean,
+ *   unknown: boolean
+ * }}
+ */
+export function getInstalledCommandsDriftStatus(forgeHome) {
+  const notFound = { persistedVersion: "", sourceVersion: "", isStale: false, unknown: true };
+
+  let sourceVersion = "";
+  try {
+    const pkg = JSON.parse(readFileSync(join(forgeHome, "package.json"), "utf-8"));
+    sourceVersion = pkg.version || "";
+  } catch {
+    // Missing/unreadable/corrupt package.json — cannot determine the source
+    // version at all; degrade to unknown rather than guessing.
+    return notFound;
+  }
+
+  // Prefer the version registry.mjs last recorded for persistHome()'s write
+  // (the single source of truth update()/install also write through),
+  // falling back to reading ~/.forge/version directly on disk when the
+  // registry has no entry (e.g. an older ForgeDock version wrote ~/.forge/
+  // before forge#1943 added registry tracking). Mirrors doctor's Check 5d.
+  let persistedVersion = "";
+  try {
+    const recorded = getPersistedHomeState();
+    persistedVersion = recorded?.version || "";
+  } catch {
+    // getPersistedHomeState() already fails open to null — this catch is
+    // defensive only.
+  }
+  if (!persistedVersion) {
+    try {
+      const versionPath = join(HOME, ".forge", "version");
+      persistedVersion = readFileSync(versionPath, "utf-8").trim();
+    } catch {
+      // version file missing/unreadable — no persisted-home version is
+      // knowable; degrade to unknown.
+    }
+  }
+
+  if (!persistedVersion) {
+    return notFound;
+  }
+
+  const isStale = compareVersions(persistedVersion, sourceVersion) < 0;
+  return { persistedVersion, sourceVersion, isStale, unknown: false };
+}
+
 // ---------------------------------------------------------------------------
 // Claude Code version detection and breakpoints resolution (issue #1252)
 // ---------------------------------------------------------------------------

package/bin/runner.mjs

@@ -47,7 +47,7 @@ import {
   rmSync,
   realpathSync,
 } from "fs";
-import { join, dirname, basename, relative, isAbsolute } from "path";
+import { join, dirname, basename, relative, isAbsolute, extname } from "path";
 import os from "os";
 import { execSync, spawnSync } from "child_process";
 import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
@@ -143,11 +143,23 @@ export const VALID_BACKENDS = readOnlySet(["cli", "api", "auto"]);
 //      evict the oldest (insertion-order, via `Map`'s iteration order and a
 //      delete+re-set on refresh) so a process that probes an unbounded
 //      number of distinct `cwd` values cannot grow this cache without limit.
-// Each entry stores `{ available, cachedAt }` instead of a bare boolean so
-// `isClaudeCliAvailable()` can evaluate the TTL.
+// Each entry stores `{ available, cliPath, cachedAt }` instead of a bare
+// boolean so `isClaudeCliAvailable()` can evaluate the TTL, and so the
+// *same* resolved absolute executable path the probe validated can be
+// reused by `runCliBackend()`'s production invocation (issue #2741) — see
+// `resolveClaudeCliBinary()` below. `cliPath` is `null` when unavailable or
+// when the probe succeeded but no path-like line could be parsed out of it
+// (e.g. an injected test `execImpl` that returns a bare version string).
 const CLI_AVAILABILITY_CACHE_TTL_MS = 60_000;
 const CLI_AVAILABILITY_CACHE_MAX_SIZE = 100;
 const cliAvailabilityCache = new Map();
+// Windows file extensions `spawnSync(shell:false)` can actually launch:
+// native executables (`.exe`, `.com`) directly, and `.cmd`/`.bat` via Node's
+// own built-in special-cased re-exec through cmd.exe (see the comment on
+// `runCliBackend()` below). An extensionless file — e.g. the POSIX shell
+// shim `npm`/`npx` also drop alongside these on Windows — cannot be
+// launched by `CreateProcess` at all, with or without a full absolute path.
+const WINDOWS_SPAWNABLE_EXTENSIONS = new Set([".exe", ".cmd", ".bat", ".com"]);
 // Cap tool-result payloads so a large file read or verbose command does not
 // blow the context window in a single turn.
 const MAX_TOOL_RESULT_CHARS = 100_000;
@@ -203,21 +215,110 @@ export function resolveConfiguredDefaultModel(cwd) {
 // Backend selection (issue #2003) — CLI vs API execution backend
 // ---------------------------------------------------------------------------
 
+/**
+ * Split the combined probe command's stdout (issue #2741 — see
+ * `isClaudeCliAvailable()`) into the leading "path-like" lines (from the
+ * `where`/`command -v` half of the command) versus everything after them
+ * (the `claude --version` output). A path-like line is one containing a
+ * path separator (`/` or `\`); `claude --version` output (e.g.
+ * `"1.2.3 (Claude Code)"`) never does, so the first non-path-like line
+ * marks the boundary.
+ *
+ * Pure/side-effect-free so it can be unit tested directly against
+ * synthetic multi-line `where` output without spawning anything.
+ *
+ * @param {string} raw
+ * @returns {string[]} Leading path-like lines, in original order.
+ */
+function parseProbeOutput(raw) {
+  const lines = String(raw ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const pathLines = [];
+  for (const line of lines) {
+    if (line.includes("/") || line.includes("\\")) {
+      pathLines.push(line);
+    } else {
+      break;
+    }
+  }
+  return pathLines;
+}
+
+/**
+ * Pick the best resolved `claude` executable path out of the candidate
+ * path-like lines produced by `parseProbeOutput()` (issue #2741).
+ *
+ * On Windows, prefers a candidate with a recognized spawnable extension
+ * (`WINDOWS_SPAWNABLE_EXTENSIONS`) over an extensionless one — `where`
+ * matches bare filenames as well as PATHEXT-suffixed ones, and an
+ * npx-transient shim directory can contain both an extensionless POSIX
+ * shell script and a `.cmd`/`.ps1` sibling generated by npm's cross-platform
+ * shim generator. If every candidate is extensionless, checks the same
+ * directory for a `.cmd`/`.exe`/`.bat`/`.com` sibling with the same base
+ * name before giving up and returning the bare match as-is.
+ *
+ * On POSIX, `command -v` returns a single resolvable path directly usable
+ * by `spawnSync(shell:false)` (POSIX `execve` honors the shebang line), so
+ * no extension preference is needed.
+ *
+ * @param {string[]} pathLines
+ * @returns {string|null}
+ */
+function selectResolvedCliPath(pathLines) {
+  if (pathLines.length === 0) return null;
+  if (process.platform !== "win32") return pathLines[0];
+
+  const withExt = pathLines.find((line) =>
+    WINDOWS_SPAWNABLE_EXTENSIONS.has(extname(line).toLowerCase()),
+  );
+  if (withExt) return withExt;
+
+  const bare = pathLines[0];
+  const dir = dirname(bare);
+  const base = basename(bare);
+  for (const ext of [".cmd", ".exe", ".bat", ".com"]) {
+    const candidate = join(dir, `${base}${ext}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return bare;
+}
+
 /**
  * Probe whether the Claude Code CLI (`claude`) is present and responds on
  * this machine, so `forgedock run` can drive it directly instead of
  * requiring a separate, billable ANTHROPIC_API_KEY.
  *
- * Deliberately uses `execSync("claude --version", ...)` — a single command
- * *string* executed through a shell — rather than
- * `execFileSync("claude", [...])`. On Windows, `claude` is installed as a
- * `claude.cmd` shim; `execFileSync` does not resolve `.cmd` shims and throws
- * ENOENT even though the CLI is genuinely installed and on PATH (this exact
- * regression previously made an unrelated skill-based enrichment backend
- * silently dead on Windows — see issue #382). `execSync` always runs its
- * command through a shell, which resolves PATHEXT-registered `.cmd`/`.bat`
- * shims correctly on Windows and behaves identically on POSIX. This mirrors
- * the pre-existing `claude --version` doctor check in bin/forgedock.mjs.
+ * Deliberately runs a single command *string* through a shell (via
+ * `execSync`) rather than `execFileSync("claude", [...])` or a no-shell
+ * `spawnSync`. On Windows, `claude` may be installed as a `claude.cmd`
+ * shim, or present only as an npx-transient shim (an extensionless script
+ * in a `_npx` cache directory, reachable only via the shell-augmented
+ * PATH); `execFileSync`/no-shell `spawnSync` do not resolve either case the
+ * same way a shell does and throw ENOENT even though the CLI is genuinely
+ * runnable (see issue #382 for the `.cmd`-shim regression this originally
+ * guarded against, and issue #2741 for the npx-shim case). `execSync`
+ * always runs its command through a shell, which resolves both cases
+ * correctly on Windows and behaves identically on POSIX.
+ *
+ * issue #2741 — probe/invocation asymmetry fix: this probe now does double
+ * duty. In a single `execImpl` call (so per-cwd caching below still pays
+ * the probe cost exactly once — existing tests assert this), it both
+ * verifies `claude --version` responds AND captures the shell-resolved
+ * absolute path (`where claude` on Windows / `command -v claude` on POSIX)
+ * that made that resolution possible. That resolved path is cached
+ * alongside `available` and exposed via `resolveClaudeCliBinary()` below,
+ * so `runCliBackend()`'s production call site can spawn the *exact* binary
+ * this probe validated — with `shell:false` — instead of a bare `"claude"`
+ * name that the no-shell OS exec-path search may fail to resolve the same
+ * way. The two commands are chained with `&&` (path-resolution failure
+ * short-circuits the whole probe as "unavailable") rather than run
+ * independently: an environment where `claude` only resolves as an
+ * unlocatable shell alias/function (no path lookup, `--version` succeeds
+ * anyway) was never actually spawnable via `spawnSync` in the first place,
+ * so treating that as "unavailable" here is consistent with what
+ * `runCliBackend()` can actually do with it.
  *
  * Bounded by CLI_PROBE_TIMEOUT_MS so a hung or misbehaving `claude` binary
  * can never make backend resolution (and therefore --dry-run, or the start
@@ -249,15 +350,18 @@ export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync
   if (cached && Date.now() - cached.cachedAt < CLI_AVAILABILITY_CACHE_TTL_MS) {
     return cached.available;
   }
+  const resolveCmd = process.platform === "win32" ? "where claude" : "command -v claude";
   let available;
+  let cliPath = null;
   try {
-    execImpl("claude --version", {
+    const raw = execImpl(`${resolveCmd} && claude --version`, {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf-8",
       timeout: CLI_PROBE_TIMEOUT_MS,
     });
     available = true;
+    cliPath = selectResolvedCliPath(parseProbeOutput(raw));
   } catch {
     available = false;
   }
@@ -266,7 +370,7 @@ export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync
   // entry — whether "oldest" means "never refreshed" or "not refreshed in
   // the longest time."
   cliAvailabilityCache.delete(cwd);
-  cliAvailabilityCache.set(cwd, { available, cachedAt: Date.now() });
+  cliAvailabilityCache.set(cwd, { available, cliPath, cachedAt: Date.now() });
   if (cliAvailabilityCache.size > CLI_AVAILABILITY_CACHE_MAX_SIZE) {
     const oldestKey = cliAvailabilityCache.keys().next().value;
     cliAvailabilityCache.delete(oldestKey);
@@ -274,6 +378,28 @@ export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync
   return available;
 }
 
+/**
+ * Return the exact absolute `claude` executable path that
+ * `isClaudeCliAvailable()` validated for `cwd` (issue #2741), ensuring the
+ * probe/cache is populated or refreshed first. This is what closes the
+ * probe/invocation asymmetry: `runCommand()`'s production call site passes
+ * this resolved path as `runCliBackend()`'s `bin` argument instead of the
+ * bare `"claude"` default, so the invocation spawns the identical binary
+ * the probe already confirmed responds — with `shell:false` preserved
+ * throughout (see the SECURITY note on `runCliBackend()` below).
+ *
+ * @param {string} [cwd] - Working directory for the probe (default cwd).
+ * @param {object} [opts] - Forwarded to `isClaudeCliAvailable()` (e.g.
+ *   `execImpl` test seam).
+ * @returns {string|null} Absolute resolved path, or `null` when the CLI is
+ *   unavailable or no path-like line could be parsed from the probe output
+ *   (falls back to the bare `"claude"` name at the call site in that case).
+ */
+export function resolveClaudeCliBinary(cwd = process.cwd(), opts = {}) {
+  isClaudeCliAvailable(cwd, opts);
+  return cliAvailabilityCache.get(cwd)?.cliPath ?? null;
+}
+
 /**
  * Shared backend-resolution primitive (issue #2026) used by both
  * `resolveBackend()` (below, `forgedock run`'s engine ladder — issue #2003)
@@ -386,19 +512,32 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {})
  * arbitrary shell commands with this process's privileges). Do not
  * reintroduce `shell: true` or string-command interpolation here.
  *
- * Windows `.cmd` shim resolution works WITHOUT `shell: true`: Node's
- * spawn/spawnSync resolve a bare `"claude"` command via PATH+PATHEXT and
- * safely re-invoke through cmd.exe internally when the resolved target is a
+ * Windows `.cmd`/`.bat` shim resolution works WITHOUT `shell: true` — BUT
+ * only when `bin` is already a resolvable target: Node's spawn/spawnSync
+ * safely re-invoke through cmd.exe internally when the *given* target is a
  * `.cmd`/`.bat` file, using a properly escaped mechanism, and argv elements
  * are never parsed as shell syntax (verified empirically on Windows: a
  * malicious-looking argv element is delivered to the child process
  * byte-for-byte, not executed). This is the correct fix for the
  * `execFileSync("claude", [...])` ENOENT-on-Windows regression from issue
- * #382 — that regression was about USING execFileSync with an unresolved
- * bare command name in an older/incompatible way, not about needing
- * `shell: true`; spawnSync's own PATH/PATHEXT resolution (unlike
- * execFileSync's, in the failure mode #382 hit) handles the `.cmd` shim
- * transparently here.
+ * #382 for a `claude.cmd` sitting directly on a real PATH entry.
+ *
+ * CORRECTED (issue #2741): the claim that a bare `"claude"` name resolves
+ * via "spawnSync's own PATH/PATHEXT resolution" was overconfident and
+ * false for an npx-transient shim (an extensionless script living in a
+ * `_npx` cache directory rather than a stable PATH entry with a registered
+ * PATHEXT extension) — `spawnSync(shell:false)` resolves a bare command
+ * name via the OS's own exec-path search, which does not carry the same
+ * shell/PATHEXT semantics `isClaudeCliAvailable()`'s shell-based probe
+ * uses, and ENOENTs on that shim even though the probe reports the CLI
+ * available. The fix is NOT `shell: true` (would reopen the injection hole
+ * above); it is resolving the *exact* absolute path the probe validated
+ * once, via `resolveClaudeCliBinary()`, and passing that resolved path as
+ * `bin` — `spawnSync(shell:false)` launches an already-fully-resolved
+ * absolute path (native `.exe`, or `.cmd`/`.bat` via the special-cased
+ * re-exec described above) without needing any further PATH/PATHEXT
+ * resolution of its own. See `isClaudeCliAvailable()`/
+ * `resolveClaudeCliBinary()` above for how that resolution happens.
  *
  * `--dangerously-skip-permissions` mirrors the established headless-CI
  * invocation pattern already documented in docs/CI.md and
@@ -454,14 +593,19 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {})
  * @param {string[]} [opts.args]
  * @param {string} opts.cwd
  * @param {{log: Function, error?: Function}} [opts.logger]
- * @param {string} [opts.bin] - Executable to invoke (default "claude"). Test
- *   seam only — production callers must never override this; it exists so
- *   tests can point at a controlled fake binary instead of either invoking
- *   the real `claude` CLI (slow, non-deterministic, real side effects) or
- *   fighting platform-specific PATH-resolution semantics to shim "claude"
- *   itself (Windows resolves a bare executable name via the *calling*
- *   process's search path at the OS level, which is not reliably
- *   overridable per-call from within the same process).
+ * @param {string} [opts.bin] - Executable to invoke (default "claude").
+ *   UPDATED (issue #2741): the real production caller (`runCommand()`
+ *   below) now deliberately passes `resolveClaudeCliBinary(cwd) ?? "claude"`
+ *   here — a pre-resolved absolute path, not the bare default — to close
+ *   the probe/invocation asymmetry described on `isClaudeCliAvailable()`
+ *   above. The bare `"claude"` default remains purely a fallback for that
+ *   production call site (when resolution genuinely finds nothing) and a
+ *   test seam: tests still point this at a controlled fake binary instead
+ *   of either invoking the real `claude` CLI (slow, non-deterministic, real
+ *   side effects) or fighting platform-specific PATH-resolution semantics
+ *   to shim "claude" itself (Windows resolves a bare executable name via
+ *   the *calling* process's search path at the OS level, which is not
+ *   reliably overridable per-call from within the same process).
  * @param {Function} [opts.spawnFn] - Injectable replacement for
  *   `child_process.spawnSync` (default `spawnSync`). Test seam only —
  *   production callers must never override this. Mirrors the identical
@@ -825,8 +969,12 @@ export function runCliBackend({
     delete childEnv.ANTHROPIC_API_KEY;
 
     // No `shell` option (defaults to false): argv is passed as discrete,
-    // unparsed elements — see the SECURITY note above. This also correctly
-    // resolves the Windows `.cmd` shim without needing shell:true.
+    // unparsed elements — see the SECURITY note above. `bin` is expected to
+    // already be a fully-resolved absolute path (see `resolveClaudeCliBinary()`
+    // and the `opts.bin` doc comment above, issue #2741) — spawnSync launches
+    // an already-resolved `.exe`/`.cmd`/`.bat` path directly (with Node's
+    // built-in special-cased `.cmd`/`.bat` re-exec) without needing any
+    // further shell/PATHEXT resolution of its own.
     const result = spawnFn(bin, cliArgs, {
       cwd,
       encoding: "utf-8",
@@ -1896,7 +2044,22 @@ export async function runCommand(opts = {}) {
           }.`,
       );
     }
-    return runCliBackend({ spec, userMessage, systemPrompt: cliSystemPrompt, args, cwd, logger });
+    // Pass the exact absolute path isClaudeCliAvailable() already validated
+    // for this cwd (issue #2741) — resolveClaudeCliBinary() reuses that same
+    // per-cwd cache, so this does not trigger a second probe. Falls back to
+    // the bare "claude" name only if resolution genuinely found nothing
+    // (e.g. an injected-execImpl test scenario with no path-like output),
+    // preserving prior behavior in that edge case.
+    const resolvedBin = resolveClaudeCliBinary(cwd) ?? "claude";
+    return runCliBackend({
+      spec,
+      userMessage,
+      systemPrompt: cliSystemPrompt,
+      args,
+      cwd,
+      logger,
+      bin: resolvedBin,
+    });
   }
 
   if (!apiKey) {

package/commands/orchestrate/phase-3-dependency.md

@@ -1061,7 +1061,12 @@ The engine drives every phase transition deterministically, mirrors state to the
 
 **Why engine-first**: The engine's phase table enforces gate semantics in code — not via LLM interpretation of markdown specs. This eliminates the class of bug where the LLM assumes a review approved when the FORGE:REVIEW comment is absent or unreadable (issue #1714). Interactive sessions that run `/work-on` via Skill invocations additionally bridge to the engine run-log via the SubagentStop hook (`bin/hooks/interactive-engine.mjs`) — state is durable across compaction and context resets.
 
-**Fallback (no forgedock CLI)**: If `forgedock` is not in PATH, fall back to spawning Agent sub-agents that run `Skill("work-on", ...)` per issue. The SubagentStop hook still bridges these runs to the engine run-log for state persistence.
+**Fallback — best-effort, not all-or-nothing (fixed forge#2743)**: Engine-first is guaranteed to have an Agent-spawn fallback under two distinct trigger conditions, not just CLI absence:
+
+1. **CLI absent at dispatch time**: If `forgedock` is not in PATH, `phase-4-execution.md` Step 4A falls back to spawning Agent sub-agents that run `Skill("work-on", ...)` per issue for the whole batch, before any dispatch happens.
+2. **Backend unavailable despite CLI presence, or a runtime engine-error with empty committed state**: `command -v forgedock` only proves the orchestrator CLI is installed — it says nothing about whether the engine's execution backend (the `claude` CLI spawn) can actually run a phase (forge#2741 is a concrete case: `spawnSync claude` ENOENTs even though a shell `command -v` probe reports the binary present). Step 4A now runs a cheap backend preflight canary before committing the whole ready set to engine-first, downgrading the entire run to Agent-spawn on failure. And per-issue, Step 4B's completion handler auto-falls-back any individual engine-dispatched issue that completes at `workflow:engine-error` with an empty committed state (`committed=[] branch=null pr=null` — see `bin/engine-cli.mjs`'s `formatTerminalDiagnostics()`) to the same Agent-spawn template, rather than leaving it stuck waiting on a resume mechanism that only exists for Agent-spawn-dispatched issues. An engine-error with partial committed state (branch/PR non-null) is NOT auto-fallen-back, to avoid double-work — it surfaces via the existing stall-detection alert instead.
+
+In both cases the SubagentStop hook still bridges the fallback Agent-spawn runs to the engine run-log for state persistence. Engine-first is therefore best-effort: it is always backed by a working Agent-spawn path, whether the gap is discovered before dispatch (canary) or after (per-issue fallback) — a whole ready set is never permanently lost to an environmental engine failure.
 
 ### Concurrency model: in-process worker pool + worktree-per-issue
 

package/commands/orchestrate/phase-4-execution.md

@@ -528,6 +528,32 @@ Use `${ISSUE_LANE[$NUM]}` and `${ISSUE_PR_BASE[$NUM]}` to populate `{LANE}` and
 # Uses SORTED_READY_SET[] from Step 3E.5 (descending value/cost) and budget gate from Step 4A-pre.0
 FORGEDOCK_AVAILABLE=$(command -v forgedock >/dev/null 2>&1 && echo "true" || echo "false")
 
+# Backend preflight canary (forge#2743): `command -v forgedock` only proves the orchestrator CLI
+# binary is on PATH — it says nothing about whether the engine's execution backend (the `claude`
+# CLI spawn, or a working `ANTHROPIC_API_KEY`) can actually run a phase. Without this probe, an
+# environmental failure (e.g. forge#2741 — `spawnSync claude` ENOENT despite a shell `command -v`
+# probe reporting the binary present) commits the ENTIRE ready set to engine-first dispatch, every
+# `forgedock run-issue` call fails within seconds, and nothing re-routes the batch — a human has
+# to notice and manually re-dispatch via the Agent-spawn path below.
+#
+# CRITICAL — do NOT use a shell-resolved probe here (`command -v claude`, `claude --version` run
+# directly by bash, `which claude`, etc.). forge#2741's entire root cause is that a shell-resolved
+# probe and the engine's actual invocation resolve the `claude` binary differently: bash's builtin
+# PATH lookup (and `execSync("claude --version", ...)`, used deliberately by
+# `bin/runner.mjs`'s `isClaudeCliAvailable()` for this exact reason) can find and run an
+# npx-transient/extensionless shim that `bin/runner.mjs`'s actual backend call —
+# `runCliBackend()`'s `spawnFn(bin, cliArgs, { shell: false, ... })` with bare `bin = "claude"`
+# (no shell resolution) — cannot. A canary that shell-resolves `claude` reproduces the exact
+# blind spot it exists to catch and reports the backend healthy in precisely forge#2741's failure
+# scenario. The canary MUST reproduce `runCliBackend()`'s exact invocation shape — bare binary
+# name, `shell: false` — via a one-off Node `spawnSync` call, not a bash-native probe:
+if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+  if ! node -e "const r = require('node:child_process').spawnSync('claude', ['--version'], { shell: false }); process.exit(r.error ? 1 : 0);" 2>/dev/null; then
+    echo "WARNING: forgedock CLI is on PATH, but its execution backend is not invocable via the engine's own spawn shape (bare 'claude', shell:false) in this environment. Downgrading to the Agent-spawn fallback path for this entire run — see forge#2743. (If forge#2741's ENOENT root cause is fixed, this canary will pass again on the next /orchestrate invocation.)"
+    FORGEDOCK_AVAILABLE="false"
+  fi
+fi
+
 if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
   # Build the budget-gated dispatch queue first (forge#1743's should_dispatch() still applies
   # per-issue, independent of the concurrency cap below).
@@ -849,7 +875,7 @@ If `DISPATCH_NOW` is empty (headroom is 0), do not spawn any agents this cycle
 
 You will be automatically notified when each background agent completes — or, for an engine-first dispatch (Step 4A, `FORGEDOCK_AVAILABLE=true`), when a backgrounded `Bash(run_in_background=true, command="forgedock run-issue ...")` call completes. Both are the same underlying "background task finished" notification the harness delivers; treat them identically for the purposes of this step. **Do NOT use `sleep` loops to poll for completion.** Instead, wait for the automatic notification. When one arrives, look up which issue it belongs to — `AGENT_ISSUE_MAP` for an `agent_completed` notification, `ENGINE_DISPATCH_MAP` (fixed forge#2466) for a background-Bash notification from the engine-first path — and immediately process it exactly the same way regardless of which map resolved it; every check below (`classify_predecessor_state()`, dependent dispatch, stall/staging checks) keys off GitHub labels/state, not which dispatch mechanism produced them. **Fallback**: if a runtime ever fails to deliver a background-Bash completion notification, poll `gh issue view --json labels` for the in-flight engine-dispatched issue's workflow label instead of blocking — the same degrade-gracefully behavior already used when `BACKGROUND_DISPATCH_ENABLED=false` for the Agent-spawn path (see `phase-3-dependency.md` → Background Dispatch Mode).
 
-**Concurrency slot release (MANDATORY — first action on every completion)** <!-- Added: forge#1912 -->: The instant a completion notification arrives — `agent_completed`, or a background-Bash completion for an engine-dispatched issue — decrement `ACTIVE_DISPATCH_COUNT` by 1 — a worker slot has just freed, regardless of what terminal state the issue ended up in. Do this before any stall-recovery/resume logic below. If that agent is then resumed (item 2 below, or Step 4B.5's stall recovery) because it stalled mid-pipeline rather than truly finishing, re-increment `ACTIVE_DISPATCH_COUNT` when the `Agent(resume=...)` call is issued — a resume re-occupies a worker slot exactly like a fresh dispatch does. (Step 4B.5's stall-resume mechanism is `Agent(resume=...)`-specific and is unchanged by this fix — an engine-dispatched issue that stalls is not currently auto-resumed by Step 4B.5; it surfaces the same way any other stalled issue does, via the standard stall-detection alert, and `forgedock resume-stalled` remains available as a separate manual/scripted recovery path outside this file's scope.)
+**Concurrency slot release (MANDATORY — first action on every completion)** <!-- Added: forge#1912 -->: The instant a completion notification arrives — `agent_completed`, or a background-Bash completion for an engine-dispatched issue — decrement `ACTIVE_DISPATCH_COUNT` by 1 — a worker slot has just freed, regardless of what terminal state the issue ended up in. Do this before any stall-recovery/resume logic below. If that agent is then resumed or fallback-dispatched (item 2 below, or Step 4B.5's stall recovery) because it stalled mid-pipeline rather than truly finishing, re-increment `ACTIVE_DISPATCH_COUNT` when the `Agent(resume=...)` (or, per item 2b below, the fresh `Agent(...)` fallback dispatch) call is issued — either re-occupies a worker slot exactly like a fresh dispatch does. (Step 4B.5's TIME-BASED hang detector — an agent that never completes at all, as opposed to one that completes at `workflow:engine-error` — remains `Agent(resume=...)`-specific and out of scope for this fix: an engine-dispatched issue that silently hangs still surfaces only via the standard stall-detection alert, and `forgedock resume-stalled` remains available as a separate manual/scripted recovery path for that case. The completion-triggered case — an engine-dispatched issue that DOES complete, at `workflow:engine-error` with empty committed state — is now auto-fallen-back to Agent-spawn by item 2b below, fixed forge#2743.)
 
 **Ordering requirement (MANDATORY — prevents transient over-cap)**: For every agent that completed in this notification batch, finish its terminal-state check and, if applicable, its resume re-increment (items 1-2 below) BEFORE computing `dispatch_headroom` for item 5's newly-ready-issue dispatch. Computing headroom before a to-be-resumed agent's re-increment would let a genuinely-still-running agent's freed slot be double-booked — once by a fresh dispatch, once by the resume itself — transiently exceeding `MAX_CONCURRENT`. Process every completed agent's items 1-2 to a decision (terminal vs. resumed) first; only then compute headroom once for the batch's item 5 dispatch.
 
@@ -888,6 +914,10 @@ classify_predecessor_state() {
     # predecessor were still mid-pipeline — which is accurate, since the
     # stall-detection step below (item 2) auto-resumes/retries a completed
     # agent run that ends in workflow:engine-error, same as any other stall.
+    # Fixed forge#2743: item 2's sub-case 2b is what actually fulfills this for
+    # ENGINE_DISPATCH_MAP-tracked issues (fresh Agent-spawn fallback on empty
+    # committed state) — 2a's Agent(resume=...) alone cannot reach them, since
+    # they were never in AGENT_ISSUE_MAP.
     echo "IN_PROGRESS"
   elif [ "$PRED_STATE" = "CLOSED" ]; then
     # Closed with no workflow:invalid/merged label (e.g. closed-not-planned) — treat as DONE,
@@ -1086,7 +1116,11 @@ done
    echo "#{NUM}: $FINAL_STATE"
    ```
 
-2. **If the issue is NOT in a terminal-for-this-agent state** (`workflow:merged`, `workflow:invalid`, `needs-human`, or `workflow:awaiting-merge`), the agent stalled mid-pipeline. **Resume it immediately**. `workflow:engine-error` (forge#2261 — `bin/engine.mjs`'s headless engine terminating on an engine/tool-level failure rather than a genuine human-judgment block) is deliberately excluded from the terminal-for-this-agent set: a completed agent run ending there is treated exactly like any other stall and auto-resumed/retried here, up to the resume-cap in item 3 below — no human decision is pending, so there is nothing to gate on:
+2. **If the issue is NOT in a terminal-for-this-agent state** (`workflow:merged`, `workflow:invalid`, `needs-human`, or `workflow:awaiting-merge`), the agent stalled mid-pipeline. **Resume it immediately**. `workflow:engine-error` (forge#2261 — `bin/engine.mjs`'s headless engine terminating on an engine/tool-level failure rather than a genuine human-judgment block) is deliberately excluded from the terminal-for-this-agent set: a completed agent run ending there is treated exactly like any other stall and auto-resumed/retried here, up to the resume-cap in item 3 below — no human decision is pending, so there is nothing to gate on.
+
+   **Two distinct resume mechanisms, dispatched by which map resolved the completion (fixed forge#2743)** — `AGENT_ISSUE_MAP`-resolved completions (Agent-spawn path) and `ENGINE_DISPATCH_MAP`-resolved completions (engine-first path) hit `workflow:engine-error` for structurally different reasons and need different recovery:
+
+   **2a. Agent-spawn-dispatched issue (`AGENT_ISSUE_MAP[{NUMBER}]` set)** — unchanged from prior behavior. Resume the same agent in place:
    ```
    Agent(
      resume=AGENT_ISSUE_MAP[{NUMBER}],
@@ -1095,7 +1129,83 @@ done
      prompt="The previous /work-on invocation stopped before completing the full pipeline. The issue is currently at {CURRENT_WORKFLOW_STATE}. Continue — invoke Skill(skill='work-on', args='{NUMBER} --under-orchestration') to resume the routing loop from the current state. /work-on will re-read GitHub state and pick up where it left off."
    )
    ```
-   **Resume ALL stalled agents in a single message** (parallel resume). Do not wait between resumes. Each resume re-occupies a worker slot — increment `ACTIVE_DISPATCH_COUNT` by 1 per agent resumed here (it was already decremented by the "Concurrency slot release" rule above when the stall was first observed as a completion). <!-- Added: forge#1912 -->
+
+   **2b. Engine-first-dispatched issue (`ENGINE_DISPATCH_MAP[{NUMBER}]` set, no `AGENT_ISSUE_MAP` entry)** — `Agent(resume=...)` has nothing to resume here; the completed task was a backgrounded `Bash(command="forgedock run-issue ...")` call, not an `Agent()`. Re-issuing the identical `forgedock run-issue` command would just reproduce the same environmental failure. Instead, fall back to the Agent-spawn path for this ONE issue — but only when it is safe to do so:
+   ```bash
+   # Idempotency guard: only fall back once per issue per engine-error occurrence.
+   ALREADY_FALLEN_BACK=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+     --jq '[.[] | select(.body | contains("FORGE:ENGINE_FALLBACK"))] | length' 2>/dev/null || echo "0")
+
+   # Safety gate: only fall back when the engine run committed NOTHING — no branch, no PR, no
+   # committed phases. Primary source: the `FORGE:STATE` HTML-comment block the engine already
+   # mirrors onto the issue BODY on every phase transition (`bin/engine/state.mjs`/`projector.mjs`
+   # — see phase-3-dependency.md "Engine mode (default)"), which carries `committed`/`branch`/`pr`
+   # as real JSON — read it directly rather than screen-scraping terminal text:
+   # NOTE (forge#2750 review fix): `bin/engine/state.mjs`'s `serializeState()` writes the block
+   # as THREE separate lines — `<!-- FORGE:STATE`, the JSON payload, and `-->` — never all on one
+   # line. A single-line `grep -oP '(?<=<!-- FORGE:STATE)[\s\S]*?(?=-->)'` NEVER matches this <!-- allowlist:portability — cited non-portable anti-pattern being replaced, not a command this spec runs -->
+   # (GNU `grep -P` without `-z` operates per-line, not across newlines, regardless of `[\s\S]`)
+   # — it always returns empty. Extract the block with a `sed` line-range instead, which handles
+   # the real multi-line shape correctly:
+   STATE_BLOCK=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body' \
+     | sed -n '/<!-- FORGE:STATE/,/-->/p')
+   STATE_JSON=$(echo "$STATE_BLOCK" | sed '1d;$d')
+   if [ -n "$STATE_JSON" ]; then
+     COMMITTED_COUNT=$(echo "$STATE_JSON" | jq -r '.committed | length' 2>/dev/null)
+     STATE_BRANCH=$(echo "$STATE_JSON" | jq -r '.branch' 2>/dev/null)
+     STATE_PR=$(echo "$STATE_JSON" | jq -r '.pr' 2>/dev/null)
+     [ "$COMMITTED_COUNT" = "0" ] && [ "$STATE_BRANCH" = "null" ] && [ "$STATE_PR" = "null" ] \
+       && EMPTY_COMMITTED_STATE="true" || EMPTY_COMMITTED_STATE="false"
+   else
+     # No FORGE:STATE block was ever written to the issue body (e.g. the run failed before
+     # phase 1 committed anything). There is no reliable structured signal available in this
+     # case — fail SAFE: do NOT auto-fallback on an unverifiable state. This surfaces via the
+     # existing stall-detection alert / needs-human path instead, exactly as before this fix.
+     # (An earlier draft of this fix attempted a second fallback source — a
+     # `committed=[] branch=null pr=null` diagnostic line assumed to be present in the
+     # completed background Bash call's captured stdout — but no code in this file or
+     # phase-3-dependency.md actually captures/populates that stdout into a named variable,
+     # so that fallback was dead code reading an unset variable. Removed rather than wired up:
+     # the FORGE:STATE block above is the engine's own durable, already-documented mirror of
+     # this exact data and should always be present by the time a phase transition occurs;
+     # treating its absence as "cannot verify, don't risk it" is the correct fail-safe.)
+     EMPTY_COMMITTED_STATE="false"
+   fi
+   # A non-empty committed/branch/pr means real per-issue work exists that a fresh Agent-spawn
+   # dispatch could collide with or duplicate — that case is NOT auto-fallen-back; it surfaces
+   # via the existing stall-detection alert / needs-human path instead, exactly as before this fix.
+
+   if [ "$ALREADY_FALLEN_BACK" -eq 0 ] && [ "$EMPTY_COMMITTED_STATE" = "true" ]; then
+     ENGINE_FALLBACK_BODY="<!-- FORGE:ENGINE_FALLBACK -->
+   ## Engine-First Dispatch Failed — Falling Back to Agent-Spawn
+
+   \`forgedock run-issue\` ended at \`workflow:engine-error\` with no committed phases, branch, or PR
+   (\`committed=[] branch=null pr=null\`) — this is an environmental/tool failure (forge#2261), not a
+   per-issue content failure, and nothing was committed that a fresh dispatch could collide with.
+   Auto-falling back to the Agent-spawn \`/work-on\` path for this issue. See forge#2743."
+     gh issue comment {NUMBER} {GH_FLAG} --body "$ENGINE_FALLBACK_BODY" # <!-- allowlist:check-command-side-effects — intentional pipeline status annotation, mirrors work-on/build/architect.md:700 -->
+
+     # Reuse the SAME Agent-spawn template as Step 4A's "Agent-spawn path (fallback when forgedock
+     # CLI unavailable)" section above (the `Agent(subagent_type="general-purpose", ...)` block
+     # under "Copy this template. Fill in variables. Do not modify the structure:") verbatim —
+     # HARD RULE 1 preserved. This is a fresh dispatch, not a resume: capture its returned agent
+     # ID into AGENT_ISSUE_MAP so subsequent completions for this issue route through 2a above.
+     Agent(
+       subagent_type="general-purpose",
+       model="{SUBAGENT_MODEL}",
+       description="Work on {PROJECT_PREFIX}#{NUMBER} (engine-error fallback)",
+       run_in_background=true,
+       prompt="<same template body as Step 4A's Agent-spawn path — see the 'Agent-spawn path (fallback when forgedock CLI unavailable)' section above; fill {NUMBER}/{GH_REPO}/{REPO_PATH}/{LANE}/{PR_BASE}/{ISSUE_TITLE} exactly as that template does>"
+     )
+     AGENT_ISSUE_MAP[{NUMBER}] = <agent_id returned by the Agent() call above>
+     # Re-occupies the worker slot this completion just freed (see "Concurrency slot release" above).
+     ACTIVE_DISPATCH_COUNT=$((ACTIVE_DISPATCH_COUNT + 1))
+   elif [ "$ALREADY_FALLEN_BACK" -eq 0 ]; then
+     echo "#{NUMBER}: engine-error with non-empty committed state (partial work exists) — NOT auto-falling back. Surfaces via standard stall-detection alert; forgedock resume-stalled remains available for manual/scripted recovery."
+   fi
+   ```
+
+   **Resume ALL stalled agents in a single message** (parallel resume/fallback across 2a and 2b together). Do not wait between resumes. Each resume or fallback dispatch re-occupies a worker slot — increment `ACTIVE_DISPATCH_COUNT` by 1 per agent resumed/dispatched here (it was already decremented by the "Concurrency slot release" rule above when the stall was first observed as a completion). <!-- Added: forge#1912 -->
 
 3. **Track resume cycles per agent.** If an agent has been resumed 2+ times and still hasn't reached a terminal state, report it as a failure — do not resume again.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/check-spec-markers.sh

@@ -102,6 +102,7 @@ MARKER_REGISTRY="
   DESIGN
   DISPATCHER
   DOSSIER_UPDATED
+  ENGINE_FALLBACK
   FAST_PATH
   FINDING_SOURCE
   FIX_CI