forgedock 1.6.0 → 1.7.1

package/bin/registry.mjs

@@ -513,12 +513,13 @@ export function getInstalledCommandsDriftStatus(forgeHome) {
   let sourceVersion = "";
   try {
     const pkg = JSON.parse(readFileSync(join(forgeHome, "package.json"), "utf-8"));
-    sourceVersion = pkg.version || "";
+    sourceVersion = typeof pkg.version === "string" ? pkg.version.trim() : "";
   } catch {
     // Missing/unreadable/corrupt package.json — cannot determine the source
     // version at all; degrade to unknown rather than guessing.
     return notFound;
   }
+  if (!sourceVersion) return notFound;
 
   // Prefer the version registry.mjs last recorded for persistHome()'s write
   // (the single source of truth update()/install also write through),

package/bin/runner.mjs

@@ -47,9 +47,10 @@ import {
   rmSync,
   realpathSync,
 } from "fs";
-import { join, dirname, basename, relative, isAbsolute, extname } 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.
@@ -125,6 +127,35 @@ function readOnlySet(values) {
  * simultaneously. Treat it as immutable; mutation attempts throw.
  */
 export const VALID_BACKENDS = readOnlySet(["cli", "api", "auto"]);
+
+export const FORGE_OPENCODE_CAPABILITY_ERROR = "FORGE_OPENCODE_CAPABILITY_ERROR";
+
+/**
+ * Whether the caller is an OpenCode session. The adapter sets this marker on
+ * every shell environment; keeping the predicate small makes all Claude
+ * backend entrypoints agree on the same runtime boundary.
+ */
+export function isOpenCodeRuntime(env = process.env) {
+  return String(env?.FORGE_RUNTIME || "").toLowerCase() === "opencode";
+}
+
+/**
+ * Refuse Claude-backed execution from an OpenCode workflow. OpenCode has its
+ * own Skill/Task execution path; falling through to this runner would create a
+ * competing controller and may consume Claude credentials or quota.
+ */
+export function assertOpenCodeNativeRuntime({
+  env = process.env,
+  operation = "Claude-backed ForgeDock execution",
+} = {}) {
+  if (!isOpenCodeRuntime(env)) return;
+  const error = new Error(
+    `${FORGE_OPENCODE_CAPABILITY_ERROR}: ${operation} is unavailable when FORGE_RUNTIME=opencode. Use native ForgeDock Skill/Task dispatch instead.`,
+  );
+  error.code = FORGE_OPENCODE_CAPABILITY_ERROR;
+  throw error;
+}
+
 // Per-process memoization for isClaudeCliAvailable(), keyed by `cwd` (issue
 // #2011). `runCommand()` calls resolveBackend() — and therefore, for the
 // default "auto" backend, isClaudeCliAvailable() — unconditionally on every
@@ -153,12 +184,9 @@ export const VALID_BACKENDS = readOnlySet(["cli", "api", "auto"]);
 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.
+// 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.
@@ -216,13 +244,10 @@ export function resolveConfiguredDefaultModel(cwd) {
 // ---------------------------------------------------------------------------
 
 /**
- * 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.
+ * 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.
@@ -230,20 +255,16 @@ export function resolveConfiguredDefaultModel(cwd) {
  * @param {string} raw
  * @returns {string[]} Leading path-like lines, in original order.
  */
-function parseProbeOutput(raw) {
+export 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;
+  const boundary = lines.indexOf(CLI_PROBE_OUTPUT_SENTINEL);
+  if (boundary < 0) return [];
+  return lines
+    .slice(0, boundary)
+    .filter((line) => line.includes("/") || line.includes("\\"));
 }
 
 /**
@@ -266,9 +287,12 @@ function parseProbeOutput(raw) {
  * @param {string[]} pathLines
  * @returns {string|null}
  */
-function selectResolvedCliPath(pathLines) {
+export function selectResolvedCliPath(
+  pathLines,
+  { platform = process.platform, existsImpl = existsSync } = {},
+) {
   if (pathLines.length === 0) return null;
-  if (process.platform !== "win32") return pathLines[0];
+  if (platform !== "win32") return pathLines[0];
 
   const withExt = pathLines.find((line) =>
     WINDOWS_SPAWNABLE_EXTENSIONS.has(extname(line).toLowerCase()),
@@ -280,11 +304,49 @@ function selectResolvedCliPath(pathLines) {
   const base = basename(bare);
   for (const ext of [".cmd", ".exe", ".bat", ".com"]) {
     const candidate = join(dir, `${base}${ext}`);
-    if (existsSync(candidate)) return candidate;
+    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
@@ -345,7 +407,10 @@ function selectResolvedCliPath(pathLines) {
  *   `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;
@@ -354,14 +419,17 @@ export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync
   let available;
   let cliPath = null;
   try {
-    const raw = execImpl(`${resolveCmd} && 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));
+    cliPath = selectResolvedCliPath(parseProbeOutput(raw), { platform, existsImpl });
   } catch {
     available = false;
   }
@@ -397,7 +465,107 @@ export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync
  */
 export function resolveClaudeCliBinary(cwd = process.cwd(), opts = {}) {
   isClaudeCliAvailable(cwd, opts);
-  return cliAvailabilityCache.get(cwd)?.cliPath ?? null;
+  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({
+  env = process.env,
+  requested = env.FORGEDOCK_BACKEND || "auto",
+  cwd = process.cwd(),
+  apiKey = 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 (isOpenCodeRuntime(env)) {
+    return { ready: false, backend: "opencode", reason: "native-opencode-required" };
+  }
+
+  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" };
 }
 
 /**
@@ -472,14 +640,16 @@ export function resolveBackendLadder({
  * @param {object} [opts]
  * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
  * @param {string} [opts.cwd]       - Working directory for the CLI probe.
+ * @param {object} [opts.env]       - Runtime environment used for capability checks.
  * @returns {"cli"|"api"}
  */
-export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {}) {
+export function resolveBackend({ requested = "auto", cwd = process.cwd(), env = process.env } = {}) {
   if (!VALID_BACKENDS.has(requested)) {
     throw new Error(
       `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
     );
   }
+  assertOpenCodeNativeRuntime({ env, operation: "Claude-backed backend resolution" });
   return resolveBackendLadder({
     override: requested === "auto" ? undefined : requested,
     validOverrides: new Set(["cli", "api"]),
@@ -512,15 +682,11 @@ 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`/`.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 for a `claude.cmd` sitting directly on a real PATH entry.
+ * 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
@@ -534,8 +700,8 @@ export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {})
  * 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
+ * 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.
  *
@@ -971,10 +1137,9 @@ export function runCliBackend({
     // No `shell` option (defaults to false): argv is passed as discrete,
     // 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.
+    // 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",
@@ -1015,7 +1180,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();
@@ -1955,9 +2122,15 @@ export async function runCommand(opts = {}) {
     maxIterations = DEFAULT_MAX_ITERATIONS,
     dryRun = false,
     backend = process.env.FORGEDOCK_BACKEND || "auto",
+    runtimeEnv = process.env,
     logger = console,
   } = opts;
 
+  assertOpenCodeNativeRuntime({
+    env: runtimeEnv,
+    operation: "Claude-backed ForgeDock runner",
+  });
+
   const spec = loadCommandSpec(commandsDir, commandName);
   const systemPrompt = buildSystemPrompt(spec, { repoRoot: cwd });
   // CLI-backend-specific prompt (issue #2019) — see buildCliSystemPrompt's
@@ -1973,7 +2146,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, env: runtimeEnv });
+
+  if (resolvedBackend === "cli" && backend === "auto") {
+    const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
+    if (readiness.backend === "api") resolvedBackend = "api";
+  }
 
   if (dryRun) {
     logger.log(
@@ -2050,16 +2228,28 @@ export async function runCommand(opts = {}) {
     // 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,
-    });
+    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

@@ -1136,8 +1136,30 @@ 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."
+  # ForgeDock's OpenCode plugin opts into background task events by default so
+  # each completed DAG node can wake this parent without a wave barrier.
+  if [ "${OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS:-true}" = "false" ]; then
+    echo "OpenCode background subagents explicitly disabled: orchestration is degraded to foreground task dispatch."
+    BACKGROUND_DISPATCH_ENABLED=false
+  else
+    BACKGROUND_DISPATCH_ENABLED=true
+  fi
+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."
@@ -1147,7 +1169,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 ] || \
@@ -1159,9 +1181,25 @@ if [ -n "$CC_VERSION" ]; then
 fi
 ```
 
-**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.
+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 native `task` contract instead of the Claude
+`Agent(...)` fallback. With background subagents enabled, each task is launched
+with `background=true` and its injected task-result event immediately drives
+predecessor classification and newly-ready dispatch. Claude remains the default
+when no runtime marker is present, preserving the existing Claude behavior.
+
+**When `BACKGROUND_DISPATCH_ENABLED=false`**: Claude falls back to its existing
+synchronous/polling behavior. OpenCode reaches this branch only after an
+explicit `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false`; use independent
+foreground `task` calls where the host can execute them concurrently, and
+report that per-completion streaming is unavailable. Do not use Claude's
+`Agent(...)` fallback and do not claim the event-driven DAG guarantee.
+
+**When `BACKGROUND_DISPATCH_ENABLED=true`**: Claude uses
+`run_in_background=true` and reacts to `agent_completed` notifications. OpenCode
+uses `task(..., background=true)` and reacts to each injected task-result event.
+Do NOT poll or wait for a whole wave in either enabled path.
 
 ### Orchestrator state reconstruction on wake / after compaction
 
@@ -1359,4 +1397,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.
 
 ---
-