forgedock 1.5.1 → 1.7.0

package/bin/runner.mjs

@@ -47,9 +47,10 @@ import {
   rmSync,
   realpathSync,
 } from "fs";
-import { join, dirname, basename, relative, isAbsolute } from "path";
+import { join, dirname, basename, relative, isAbsolute, extname, win32 as win32Path } from "path";
 import os from "os";
 import { execSync, spawnSync } from "child_process";
+import { createRequire } from "module";
 import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
 import { DEFAULT_SPAWN_MAX_BUFFER_BYTES } from "./cli-spawn-shared.mjs";
 
@@ -70,6 +71,7 @@ const DEFAULT_CLI_TIMEOUT_MS = 15 * 60 * 1000;
 // it is far shorter than DEFAULT_CLI_TIMEOUT_MS. Mirrors the timeout already
 // used by the `claude --version` doctor check in bin/forgedock.mjs.
 const CLI_PROBE_TIMEOUT_MS = 5000;
+export const CLI_PROBE_OUTPUT_SENTINEL = "__FORGEDOCK_CLI_PATHS_END__";
 /**
  * Wraps a Set in a Proxy that blocks add()/delete()/clear(), so the
  * returned collection is genuinely read-only — not just Object.frozen.
@@ -143,11 +145,20 @@ 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 path types emitted by npm's shim generator. Native executables are
+// directly spawnable; .cmd/.bat files must be resolved to their trusted native
+// target before spawning because Node cannot exec them with shell:false.
+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 +214,144 @@ export function resolveConfiguredDefaultModel(cwd) {
 // Backend selection (issue #2003) — CLI vs API execution backend
 // ---------------------------------------------------------------------------
 
+/**
+ * Read path candidates from the explicitly delimited resolver section of the
+ * combined CLI probe. Version output is untrusted for parsing purposes: update
+ * notices can contain path-like URLs or filenames, so shape-based inference
+ * must never allow lines after the sentinel to become executable candidates.
+ *
+ * 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.
+ */
+export function parseProbeOutput(raw) {
+  const lines = String(raw ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const boundary = lines.indexOf(CLI_PROBE_OUTPUT_SENTINEL);
+  if (boundary < 0) return [];
+  return lines
+    .slice(0, boundary)
+    .filter((line) => line.includes("/") || line.includes("\\"));
+}
+
+/**
+ * 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}
+ */
+export function selectResolvedCliPath(
+  pathLines,
+  { platform = process.platform, existsImpl = existsSync } = {},
+) {
+  if (pathLines.length === 0) return null;
+  if (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 (existsImpl(candidate)) return candidate;
+  }
+  return bare;
+}
+
+/**
+ * Resolve an npm-generated Windows command shim to the native executable it
+ * delegates to. This keeps shell:false and argv-array isolation intact instead
+ * of interpolating untrusted command arguments into cmd.exe.
+ */
+export function resolveDirectCliExecutable(
+  cliPath,
+  {
+    platform = process.platform,
+    existsImpl = existsSync,
+    readImpl = readFileSync,
+  } = {},
+) {
+  if (!cliPath || platform !== "win32") return cliPath || null;
+  const extension = extname(cliPath).toLowerCase();
+  if (extension === ".exe" || extension === ".com") return cliPath;
+  if (extension !== ".cmd" && extension !== ".bat") return null;
+
+  try {
+    const shim = readImpl(cliPath, "utf-8");
+    // npm emits several equivalent native-target wrappers. Only accept a
+    // bounded %dp0%-relative .exe/.com target; never evaluate batch syntax.
+    const directMatch = shim.match(
+      /(?:^|\r?\n)\s*"%(?:~)?dp0%?[\\/]([^"\r\n]+\.(?:exe|com))"\s+%\*\s*(?:\r?\n|$)/im,
+    );
+    const variableMatch = shim.match(
+      /(?:^|\r?\n)\s*set\s+"[^"=]+=%(?:~)?dp0%?[\\/]([^"\r\n]+\.(?:exe|com))"[\s\S]*?\r?\n\s*"%[^"\r\n]+%"\s+%\*\s*(?:\r?\n|$)/im,
+    );
+    const match = directMatch || variableMatch;
+    if (!match) return null;
+    const pathApi = platform === "win32" ? win32Path : { join, dirname };
+    const target = pathApi.join(pathApi.dirname(cliPath), ...match[1].split(/[\\/]+/));
+    return existsImpl(target) ? target : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 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
@@ -244,20 +378,29 @@ export function resolveConfiguredDefaultModel(cwd) {
  *   `runCliBackend()`.
  * @returns {boolean}
  */
-export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync } = {}) {
+export function isClaudeCliAvailable(
+  cwd = process.cwd(),
+  { execImpl = execSync, platform = process.platform, existsImpl = existsSync } = {},
+) {
   const cached = cliAvailabilityCache.get(cwd);
   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} && echo ${CLI_PROBE_OUTPUT_SENTINEL} && claude --version`,
+      {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf-8",
       timeout: CLI_PROBE_TIMEOUT_MS,
-    });
+      },
+    );
     available = true;
+    cliPath = selectResolvedCliPath(parseProbeOutput(raw), { platform, existsImpl });
   } catch {
     available = false;
   }
@@ -266,7 +409,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 +417,123 @@ 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);
+  let cliPath = cliAvailabilityCache.get(cwd)?.cliPath ?? null;
+  if (!cliPath) return null;
+
+  const existsImpl = opts.existsImpl ?? existsSync;
+  try {
+    if (existsImpl(cliPath)) {
+      const executable = resolveDirectCliExecutable(cliPath, { ...opts, existsImpl });
+      if (executable) return executable;
+    }
+  } catch {
+    // Treat an unverifiable cached path as stale and make one bounded refresh.
+  }
+
+  cliAvailabilityCache.delete(cwd);
+  isClaudeCliAvailable(cwd, opts);
+  cliPath = cliAvailabilityCache.get(cwd)?.cliPath ?? null;
+  if (!cliPath) return null;
+  try {
+    return existsImpl(cliPath)
+      ? resolveDirectCliExecutable(cliPath, { ...opts, existsImpl })
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Invoke the CLI with one recovery attempt for a path that disappeared after
+ * resolution. The availability cache is intentionally retained, so only an
+ * observed ENOENT triggers a fresh resolution.
+ */
+export function runCliWithStalePathRecovery({
+  backend,
+  cwd,
+  bin,
+  cliOptions,
+  runCliFn = runCliBackend,
+  resolveCliFn = resolveClaudeCliBinary,
+}) {
+  try {
+    return runCliFn({ ...cliOptions, bin });
+  } catch (error) {
+    if (backend !== "auto" || error?.code !== "ENOENT") throw error;
+    const freshBin = resolveCliFn(cwd);
+    if (!freshBin) throw error;
+    return runCliFn({ ...cliOptions, bin: freshBin });
+  }
+}
+
+/**
+ * Check whether the configured execution backend is locally usable without
+ * making a paid model request. CLI checks reuse the production resolver;
+ * API checks verify that a key is configured, not that the key is accepted.
+ */
+export function checkExecutionBackend({
+  requested = process.env.FORGEDOCK_BACKEND || "auto",
+  cwd = process.cwd(),
+  apiKey = process.env.ANTHROPIC_API_KEY,
+  resolveCliFn = resolveClaudeCliBinary,
+  spawnImpl = spawnSync,
+  sdkAvailableFn = () => {
+    try {
+      createRequire(import.meta.url).resolve("@anthropic-ai/sdk");
+      return true;
+    } catch {
+      return false;
+    }
+  },
+} = {}) {
+  if (!VALID_BACKENDS.has(requested)) {
+    return { ready: false, backend: requested, reason: "invalid-backend" };
+  }
+
+  if (requested !== "api") {
+    const cliPath = resolveCliFn(cwd);
+    if (cliPath) {
+      const result = spawnImpl(cliPath, ["--version"], {
+        cwd,
+        shell: false,
+        encoding: "utf-8",
+        timeout: CLI_PROBE_TIMEOUT_MS,
+      });
+      if (!result?.error && result?.status === 0) {
+        return { ready: true, backend: "cli", reason: "resolved-cli" };
+      }
+    }
+    if (requested === "cli") {
+      return { ready: false, backend: "cli", reason: "cli-unavailable" };
+    }
+  }
+
+  if (apiKey && sdkAvailableFn()) {
+    return { ready: true, backend: "api", reason: "api-key-and-sdk-configured" };
+  }
+  if (apiKey) return { ready: false, backend: "api", reason: "api-sdk-missing" };
+  return { ready: false, backend: "api", reason: "api-key-missing" };
+}
+
 /**
  * Shared backend-resolution primitive (issue #2026) used by both
  * `resolveBackend()` (below, `forgedock run`'s engine ladder — issue #2003)
@@ -386,19 +646,28 @@ 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
- * `.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.
+ * Windows npm `.cmd`/`.bat` shims cannot be launched by Node with
+ * `shell:false`. `resolveDirectCliExecutable()` therefore parses only the
+ * strict npm-shim form that delegates directly to a native `.exe`/`.com` and
+ * returns that trusted target. Unknown batch scripts fail closed instead of
+ * requiring cmd.exe interpolation of the untrusted user message.
+ *
+ * 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
+ * native executable path (including the target extracted from a recognized
+ * npm shim) 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 +723,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 +1099,11 @@ 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) — Windows npm shims
+    // have already been reduced to their native target, so spawnSync never
+    // needs shell/PATHEXT resolution.
     const result = spawnFn(bin, cliArgs, {
       cwd,
       encoding: "utf-8",
@@ -867,7 +1144,9 @@ export function runCliBackend({
       );
     }
     if (result.error) {
-      throw new Error(`Failed to invoke claude CLI: ${result.error.message}`);
+      const error = new Error(`Failed to invoke claude CLI: ${result.error.message}`);
+      error.code = result.error.code;
+      throw error;
     }
 
     const output = (stdout + stderr).trim();
@@ -1825,7 +2104,12 @@ export async function runCommand(opts = {}) {
   // misbehaving. An explicitly invalid `backend` value DOES throw here —
   // surfacing a bad --backend/FORGEDOCK_BACKEND value immediately, before any
   // work is attempted, rather than silently ignoring it.
-  const resolvedBackend = resolveBackend({ requested: backend, cwd });
+  let resolvedBackend = resolveBackend({ requested: backend, cwd });
+
+  if (resolvedBackend === "cli" && backend === "auto") {
+    const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey });
+    if (readiness.backend === "api") resolvedBackend = "api";
+  }
 
   if (dryRun) {
     logger.log(
@@ -1896,7 +2180,34 @@ 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);
+    if (!resolvedBin && backend === "auto") {
+      resolvedBackend = "api";
+    } else if (!resolvedBin) {
+      const err = new Error("The configured claude CLI path disappeared before invocation.");
+      err.code = "CLI_BACKEND_UNAVAILABLE";
+      throw err;
+    } else {
+      return runCliWithStalePathRecovery({
+        backend,
+        cwd,
+        bin: resolvedBin,
+        cliOptions: {
+          spec,
+          userMessage,
+          systemPrompt: cliSystemPrompt,
+          args,
+          cwd,
+          logger,
+        },
+      });
+    }
   }
 
   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
 
@@ -1131,8 +1136,23 @@ Background dispatch (via `run_in_background=true` on each `Agent()` call) is the
 Check both at the start of Phase 4, before the first dispatch:
 
 ```bash
+# Runtime selection is explicit for non-Claude adapters. OpenCode runs nested
+# work-on phases through its native task path, so it must not be treated as a
+# failed Claude probe.
+FORGE_RUNTIME="${FORGE_RUNTIME:-}"
+if [ -n "${OPENCODE_SESSION_ID:-}" ] || [ -n "${OPENCODE_PID:-}" ] || [ -n "${OPENCODE:-}" ]; then
+  FORGE_RUNTIME="opencode"
+fi
+
+if [ "$FORGE_RUNTIME" = "opencode" ]; then
+  echo "OpenCode runtime detected: native task dispatch selected; Claude background dispatch is not required."
+  BACKGROUND_DISPATCH_ENABLED=false
+fi
+
 # Feature gate check — run once before Phase 4 dispatch begins
-BACKGROUND_DISPATCH_ENABLED=true
+if [ "${BACKGROUND_DISPATCH_ENABLED:-}" != "false" ]; then
+  BACKGROUND_DISPATCH_ENABLED=true
+fi
 
 if [ -n "${CLAUDE_CODE_DISABLE_BACKGROUND_TASKS:-}" ]; then
   echo "Background dispatch disabled: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS is set."
@@ -1142,7 +1162,7 @@ fi
 # Version check: if the Claude Code version can be read, compare it.
 # If the version cannot be determined, default to ENABLED (optimistic).
 CC_VERSION=$(claude --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+' | head -1 || echo "")
-if [ -n "$CC_VERSION" ]; then
+if [ "$FORGE_RUNTIME" != "opencode" ] && [ -n "$CC_VERSION" ]; then
   # Compare major.minor.patch numerically
   IFS='.' read -r CC_MAJOR CC_MINOR CC_PATCH <<< "$CC_VERSION"
   if [ "$CC_MAJOR" -lt 2 ] || \
@@ -1154,6 +1174,12 @@ if [ -n "$CC_VERSION" ]; then
 fi
 ```
 
+When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), do not
+interpret a missing `claude` executable as an environment failure. The Phase 4
+dispatcher must use OpenCode's inline continuation contract instead of the
+Claude `Agent(...)` fallback. Claude remains the default when no runtime marker
+is present, preserving the existing Claude behavior.
+
 **When `BACKGROUND_DISPATCH_ENABLED=false`**: fall back to the current streaming dispatch behavior — `run_in_background=true` is still set on each `Agent()` call (existing behavior, already correct), but treat completions as synchronous and do not rely on `agent_completed` notifications. Poll issue labels for terminal state instead.
 
 **When `BACKGROUND_DISPATCH_ENABLED=true`**: use `run_in_background=true` (already in the Step 4A Agent() template) and react to `agent_completed` notifications as documented in Step 4B. Do NOT poll.
@@ -1354,4 +1380,3 @@ done
 **Why this keeps context small**: Each `Agent()` call returns an agent ID stored only in `AGENT_ISSUE_MAP`, which is rebuilt per Step 4A.pre dispatch batch. After compaction, the map is gone — but the DAG state, including `blocked-on-human-merge` tracking (a durable `FORGE:BLOCKED_ON_HUMAN_MERGE` comment plus label, not an in-context variable), is fully on GitHub. The reconstruction above re-derives the ready set, the gated set, and the blocked-on-human-merge set from labels and comments alone, so the orchestrator context never needs to hold cumulative dispatch history.
 
 ---
-