forgedock 1.7.0 → 1.8.0

package/bin/orchestrate-preflight.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+/**
+ * Compact, deterministic preflight for OpenCode orchestration.
+ *
+ * The shared orchestration specs remain authoritative for the complete
+ * workflow. This module only handles the mechanical work needed before the
+ * first native task can start: issue resolution, eligibility filtering, basic
+ * dependency edges, and the initial ready queue.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyInputPattern } from "./engine/resolve.mjs";
+
+const VERSION = "opencode-preflight-v1";
+const IN_FLIGHT_LABELS = new Set(["workflow:building", "workflow:in-review"]);
+const EXCLUDED_LABELS = new Set([
+  "needs-human",
+  "workflow:decomposed",
+  "workflow:merged",
+  "workflow:invalid",
+  "workflow:awaiting-merge",
+  "blocked-on-human-merge",
+  "workflow:engine-error",
+  "epic",
+]);
+const FILE_EXTENSION = /\.(?:py|tsx?|jsx?|sql|json|ya?ml|mjs|js|sh|md)$/i;
+const DOMAIN_RULES = [
+  ["BILLING", /credit|billing|pricing|stripe|charge|refund/i],
+  ["AUTH", /auth|session|jwt|login|permission|oauth/i],
+  ["WORKER", /worker|queue|job|task|background|consumer/i],
+  ["DATABASE", /migration|\.sql\b|database|postgres|alembic/i],
+  ["FRONTEND", /component|page|layout|dashboard|ui|ux|frontend|web\/src/i],
+  ["INFRA", /docker|deploy|traefik|nginx|ci|cd|infra|github\.action/i],
+  ["AI", /llm|extract|schema|format|embedding|model/i],
+];
+
+function labelsOf(issue) {
+  return (issue?.labels || [])
+    .map((label) => (typeof label === "string" ? label : label?.name))
+    .filter(Boolean);
+}
+
+function normalizeSlug(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function priorityWeight(labels) {
+  if (labels.some((label) => label === "priority:P0" || label === "P0")) return 4;
+  if (labels.some((label) => label === "priority:P1" || label === "P1")) return 3;
+  if (labels.some((label) => label === "priority:P2" || label === "P2")) return 2;
+  if (labels.some((label) => label === "priority:P3" || label === "P3")) return 1;
+  return 1.5;
+}
+
+function isInvestigation(issue) {
+  const title = String(issue?.title || "");
+  const body = String(issue?.body || "");
+  return /investigate|audit|research|evaluate|assess|deep dive/i.test(title) ||
+    (/(- \[ \]|\* \[ \])/.test(body) && !/affected files|acceptance criteria/i.test(body)) ||
+    /deliverable:\s*execution plan|create issues/i.test(body);
+}
+
+function scopedSection(body) {
+  const source = String(body || "");
+  const heading = /^(?:##|###)\s+(Affected Files|Deliverables|Files to change)\s*$/im;
+  const match = heading.exec(source);
+  if (!match) return "";
+  const start = match.index + match[0].length;
+  const rest = source.slice(start);
+  const end = rest.search(/^#{1,6}\s+/m);
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+export function affectedFiles(body) {
+  const section = scopedSection(body);
+  if (!section) return [];
+  return [...section.matchAll(/`([^`\r\n]+)`/g)]
+    .map((match) => match[1].trim())
+    .filter((file) => FILE_EXTENSION.test(file))
+    .filter((file, index, files) => files.indexOf(file) === index)
+    .sort();
+}
+
+export function domainsFor(issue) {
+  const text = [issue?.title, issue?.body, ...labelsOf(issue)].join(" ");
+  const domains = DOMAIN_RULES.filter(([, pattern]) => pattern.test(text)).map(([name]) => name);
+  return domains.length ? domains : ["NONE"];
+}
+
+export function explicitDependencies(body) {
+  const dependencies = new Set();
+  const source = String(body || "");
+  const pattern = /(?:depends on|blocked by|after)\s+#?(\d+)\b/gi;
+  for (const match of source.matchAll(pattern)) dependencies.add(Number(match[1]));
+  return [...dependencies].sort((a, b) => a - b);
+}
+
+function controlFlags(input) {
+  const source = String(input || "");
+  const includeInFlight = /(?:^|\s)(?:--include-in-flight|--recover-in-flight)(?:\s|$)/i.test(source);
+  const deepPlan = /(?:^|\s)--deep-plan(?:\s|$)/i.test(source);
+  const includeBacklog = /(?:^|\s)--include-backlog(?:\s|$)/i.test(source);
+  const confirmed = /(?:^|\s)(?:--auto|--confirm)(?:\s|$)/i.test(source);
+  const cleaned = source
+    .replace(/(?:^|\s)(?:--include-in-flight|--recover-in-flight|--deep-plan|--include-backlog)(?=\s|$)/gi, " ")
+    .replace(/(?:^|\s)(?:--auto|--confirm)(?=\s|$)/gi, " ")
+    .replace(/(?:^|\s)--max-concurrent(?:=|\s+)[1-9]\d*(?=\s|$)/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const maxMatch = source.match(/(?:^|\s)--max-concurrent(?:=|\s+)([1-9]\d*)(?=\s|$)/i);
+  return {
+    input: cleaned,
+    includeInFlight,
+    deepPlan,
+    includeBacklog,
+    confirmed,
+    maxConcurrent: maxMatch ? Number(maxMatch[1]) : undefined,
+  };
+}
+
+function resolveQuery(input, issues, { includeInFlight }) {
+  const trimmed = String(input || "").trim();
+  const classified = classifyInputPattern(trimmed);
+  const lower = trimmed.toLowerCase();
+  let pattern = classified.pattern;
+  let selected = [...issues];
+  const deferred = [];
+  let supported = true;
+  let reason = "";
+
+  if (!trimmed) {
+    supported = false;
+    reason = "empty input has no safe issue-set predicate";
+  } else if (/^no:milestone$|^no-milestone$/i.test(trimmed)) {
+    pattern = "no-milestone";
+    selected = selected.filter((issue) => !issue.milestone);
+  } else if (classified.kind === "literal") {
+    const requested = new Set();
+    for (const token of trimmed.split(/\s+/)) {
+      const match = token.match(/^(?:[a-zA-Z0-9_-]+:)?#?(\d+)$/);
+      if (!match || token.includes(":")) {
+        supported = false;
+        reason = "satellite-prefixed literal issues require the full multi-repo resolver";
+        break;
+      }
+      requested.add(Number(match[1]));
+    }
+    selected = selected.filter((issue) => requested.has(Number(issue.number)));
+    const found = new Set(selected.map((issue) => Number(issue.number)));
+    for (const number of requested) {
+      if (!found.has(number)) selected.push({ number, title: `Issue #${number}`, body: "", labels: [], milestone: null });
+    }
+  } else if (classified.pattern === "milestone") {
+    const requested = normalizeSlug(classified.args.join("-"));
+    selected = selected.filter((issue) => normalizeSlug(issue.milestone?.title) === requested);
+  } else if (classified.pattern === "next-n") {
+    const count = Number(classified.args[0]);
+    selected = selected
+      .sort((a, b) => priorityWeight(labelsOf(b)) - priorityWeight(labelsOf(a)) || Number(a.number) - Number(b.number))
+      .slice(0, Number.isFinite(count) && count > 0 ? count : 0);
+  } else if (classified.pattern === "fast-lane") {
+    selected = selected.filter((issue) => {
+      const labels = labelsOf(issue);
+      return !issue.milestone && (labels.includes("bug") || labels.includes("fix") || /^fix[:(]/i.test(issue.title || ""));
+    });
+  } else if (classified.pattern === "priority") {
+    const requested = lower.split(":").at(-1);
+    selected = selected.filter((issue) => labelsOf(issue).some((label) => label.toLowerCase() === `priority:${requested}` || label.toLowerCase() === requested));
+  } else if (classified.pattern === "bare-slug") {
+    const requested = normalizeSlug(trimmed);
+    selected = selected.filter((issue) =>
+      normalizeSlug(issue.milestone?.title) === requested || labelsOf(issue).some((label) => normalizeSlug(label) === requested),
+    );
+  } else {
+    supported = false;
+    reason = `input pattern "${classified.pattern}" needs the full multi-phase resolver`;
+  }
+
+  if (!includeInFlight) {
+    for (const issue of selected) {
+      if (labelsOf(issue).some((label) => IN_FLIGHT_LABELS.has(label))) {
+        deferred.push({ number: Number(issue.number), reason: "in-flight" });
+      }
+    }
+    selected = selected.filter((issue) => !labelsOf(issue).some((label) => IN_FLIGHT_LABELS.has(label)));
+  }
+
+  return { supported, reason, pattern, classified, selected, deferred };
+}
+
+function addEdge(predecessors, predecessor, successor, kind, edges) {
+  if (predecessor === successor || !predecessors.has(successor) || !predecessors.has(predecessor)) return;
+  predecessors.get(successor).add(predecessor);
+  edges.push({ predecessor, successor, kind });
+}
+
+export function buildPreflightPlan({ input, repo = "", issues = [], maxConcurrent = 12 } = {}) {
+  const flags = controlFlags(input);
+  const query = resolveQuery(flags.input, issues, flags);
+  if (!query.supported) {
+    return {
+      version: VERSION,
+      supported: false,
+      mode: "full-spec-required",
+      input: flags.input,
+      repo,
+      reason: query.reason,
+      pattern: query.pattern,
+      confirmed: flags.confirmed,
+      dispatchNow: [],
+      deferred: query.deferred,
+      warnings: [query.reason],
+    };
+  }
+
+  const excluded = [];
+  const deferred = [...query.deferred];
+  const admitted = [];
+  for (const issue of query.selected) {
+    const labels = labelsOf(issue);
+    const excludedLabel = labels.find((label) => EXCLUDED_LABELS.has(label));
+    if (excludedLabel || String(issue.state || "").toUpperCase() === "CLOSED") {
+      excluded.push({ number: Number(issue.number), reason: excludedLabel || "closed" });
+      continue;
+    }
+    admitted.push(issue);
+  }
+
+  const numbers = new Set(admitted.map((issue) => Number(issue.number)));
+  const predecessors = new Map(admitted.map((issue) => [Number(issue.number), new Set()]));
+  const edges = [];
+  const externalDependencies = new Map();
+
+  for (const issue of admitted) {
+    const number = Number(issue.number);
+    const dependencies = explicitDependencies(issue.body);
+    const external = dependencies.filter((dependency) => !numbers.has(dependency));
+    if (external.length) externalDependencies.set(number, external);
+    for (const dependency of dependencies) addEdge(predecessors, dependency, number, "explicit", edges);
+  }
+
+  const filesByIssue = new Map(admitted.map((issue) => [Number(issue.number), affectedFiles(issue.body)]));
+  const owners = new Map();
+  for (const [number, files] of filesByIssue) {
+    for (const file of files) {
+      const existing = owners.get(file) || [];
+      for (const other of existing) {
+        const predecessor = Math.min(number, other);
+        const successor = Math.max(number, other);
+        addEdge(predecessors, predecessor, successor, "same-file", edges);
+      }
+      existing.push(number);
+      owners.set(file, existing);
+    }
+  }
+
+  const databaseIssues = admitted
+    .filter((issue) => domainsFor(issue).includes("DATABASE"))
+    .map((issue) => Number(issue.number))
+    .sort((a, b) => a - b);
+  for (let index = 1; index < databaseIssues.length; index++) {
+    addEdge(predecessors, databaseIssues[index - 1], databaseIssues[index], "database", edges);
+  }
+
+  const records = admitted
+    .map((issue) => {
+      const number = Number(issue.number);
+      const labels = labelsOf(issue);
+      return {
+        number,
+        title: issue.title || `Issue #${number}`,
+        labels,
+        classification: isInvestigation(issue) ? "INVESTIGATION" : "IMPLEMENTATION",
+        domain: domainsFor(issue),
+        files: filesByIssue.get(number) || [],
+        predecessors: [...(predecessors.get(number) || [])].sort((a, b) => a - b),
+        externalDependencies: externalDependencies.get(number) || [],
+        priority: priorityWeight(labels),
+        inFlight: labels.some((label) => IN_FLIGHT_LABELS.has(label)),
+      };
+    })
+    .sort((a, b) => b.priority - a.priority || a.number - b.number);
+
+  const investigations = records.filter((issue) => issue.classification === "INVESTIGATION");
+  const ready = records
+    .filter((issue) => issue.predecessors.length === 0 && issue.externalDependencies.length === 0)
+    .sort((a, b) => b.priority - a.priority || a.number - b.number)
+    .map((issue) => issue.number);
+  const effectiveMax = Number.isInteger(maxConcurrent) && maxConcurrent > 0 ? maxConcurrent : 12;
+  const deepPlan = flags.deepPlan || query.pattern === "cascade" || query.pattern === "repo-scoped";
+  const requiresDeepPlan = deepPlan || investigations.length > 0;
+  const warnings = [
+    "Compact preflight uses explicit dependencies, scoped issue-body files, and the database serialization rule.",
+    "The full Phase 3 conflict/history analysis remains available with --deep-plan or when this preflight is unsupported.",
+  ];
+  if (flags.includeInFlight) warnings.push("In-flight issues were explicitly admitted for recovery.");
+  if (deferred.length) warnings.push(`${deferred.length} in-flight issue(s) were deferred; use --include-in-flight for explicit recovery.`);
+  if (flags.includeBacklog) warnings.push("Review-finding backlog scope requires the full cascade resolver.");
+
+  return {
+    version: VERSION,
+    supported: true,
+    mode: requiresDeepPlan ? "compact-with-full-spec-followup" : "compact",
+    input: flags.input,
+    repo,
+    pattern: query.pattern,
+    total: records.length,
+    issues: records,
+    investigations: investigations.map((issue) => issue.number),
+    inFlight: records.filter((issue) => issue.inFlight).map((issue) => issue.number),
+    excluded,
+    deferred,
+    edges,
+    ready,
+    dispatchNow: requiresDeepPlan || !flags.confirmed ? [] : ready.slice(0, effectiveMax),
+    queued: requiresDeepPlan ? ready : ready.slice(effectiveMax),
+    confirmed: flags.confirmed,
+    requiresConfirmation: !flags.confirmed,
+    requiresDeepPlan,
+    warnings,
+  };
+}
+
+function ghJson(cwd, args) {
+  const result = spawnSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message || String(result.stderr || "gh command failed").trim();
+    throw new Error(`GitHub preflight failed: ${detail}`);
+  }
+  try {
+    return JSON.parse(result.stdout || "[]");
+  } catch {
+    throw new Error("GitHub preflight returned invalid JSON");
+  }
+}
+
+function forgeConfigPath(cwd) {
+  let current = resolve(cwd);
+  while (true) {
+    const path = join(current, "forge.yaml");
+    if (existsSync(path)) return path;
+    const parent = dirname(current);
+    if (parent === current) return "";
+    current = parent;
+  }
+}
+
+function configuredConcurrency(cwd) {
+  const path = forgeConfigPath(cwd);
+  if (!path) return 12;
+  const source = readFileSync(path, "utf8");
+  const match = source.match(/^\s*max_concurrent\s*:\s*([1-9]\d*)\s*$/m);
+  return match ? Number(match[1]) : 12;
+}
+
+function configuredRepo(cwd) {
+  const path = forgeConfigPath(cwd);
+  if (!path) return "";
+  const source = readFileSync(path, "utf8");
+  const owner = source.match(/^\s*owner\s*:\s*["']?([^\s"'#]+)["']?\s*$/m)?.[1];
+  const name = source.match(/^\s*repo\s*:\s*["']?([^\s"'#]+)["']?\s*$/m)?.[1];
+  return owner && name ? `${owner}/${name}` : "";
+}
+
+function parseCli(argv) {
+  const options = { cwd: process.cwd(), repo: "", input: "" };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--cwd" || arg === "--repo" || arg === "--args") {
+      options[arg.slice(2) === "args" ? "input" : arg.slice(2)] = argv[++index] || "";
+    } else if (!options.input) {
+      options.input = arg;
+    }
+  }
+  return options;
+}
+
+export function runPreflight({ cwd = process.cwd(), repo, input, gh = ghJson } = {}) {
+  repo ||= configuredRepo(cwd);
+  if (!repo) throw new Error("--repo is required or must be present in forge.yaml");
+  const flags = controlFlags(input);
+  const issueArgs = [
+    "issue",
+    "list",
+    "-R",
+    repo,
+    "--state",
+    "open",
+    "--limit",
+    "500",
+    "--json",
+    "number,title,body,labels,milestone,state,createdAt,updatedAt",
+  ];
+  let issues = gh(cwd, issueArgs);
+  if (!Array.isArray(issues)) issues = [];
+
+  if (classifyInputPattern(flags.input).kind === "literal") {
+    const requested = [...flags.input.matchAll(/(?:^|\s)(?:[a-zA-Z0-9_-]+:)?#?(\d+)/g)].map((match) => Number(match[1]));
+    const found = new Set(issues.map((issue) => Number(issue.number)));
+    for (const number of requested.filter((item) => !found.has(item))) {
+      issues.push(gh(cwd, ["issue", "view", String(number), "-R", repo, "--json", "number,title,body,labels,milestone,state,createdAt,updatedAt"]));
+    }
+  }
+
+  return buildPreflightPlan({
+    input,
+    repo,
+    issues,
+    maxConcurrent: flags.maxConcurrent || configuredConcurrency(cwd),
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  try {
+    const options = parseCli(process.argv.slice(2));
+    const plan = runPreflight(options);
+    process.stdout.write(`${JSON.stringify(plan)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/bin/runner.mjs

@@ -25,6 +25,7 @@
  *   renderDryRun(ctx)                       → string
  *   renderSummaryCard(ctx)                  → string
  *   resolveConfiguredDefaultModel(cwd)      → string|null   (forge.yaml agents.default_model, resolved)
+ *   resolveConfiguredCliTimeout(cwd)        → number|null   (forge.yaml pipeline.cli_timeout_minutes, ms)
  *   runCommand(opts)                        → Promise<{status, ...}>
  *
  * Design notes:
@@ -64,8 +65,10 @@ const DEFAULT_BASH_TIMEOUT_MS = 5 * 60 * 1000;
 // Default wall-clock limit for a single `claude --print` CLI-backend
 // invocation (issue #2003). This bounds an entire command run (the CLI's own
 // internal tool-use loop), not one bash step, so it is deliberately larger
-// than DEFAULT_BASH_TIMEOUT_MS. Override via FORGEDOCK_CLI_TIMEOUT_MS (ms).
-const DEFAULT_CLI_TIMEOUT_MS = 15 * 60 * 1000;
+// than DEFAULT_BASH_TIMEOUT_MS. This is a safety ceiling, not a cap on normal
+// build work. Override via FORGEDOCK_CLI_TIMEOUT_MS (ms) or forge.yaml's
+// pipeline.cli_timeout_minutes.
+const DEFAULT_CLI_TIMEOUT_MS = 60 * 60 * 1000;
 // Short bound for the `claude --version` presence probe used by backend
 // auto-detection — this must never make --dry-run (or a live run) hang, so
 // it is far shorter than DEFAULT_CLI_TIMEOUT_MS. Mirrors the timeout already
@@ -127,6 +130,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
@@ -210,6 +242,27 @@ export function resolveConfiguredDefaultModel(cwd) {
   }
 }
 
+/**
+ * Resolve the CLI backend timeout from forge.yaml's
+ * `pipeline.cli_timeout_minutes` field, if it is a positive integer.
+ *
+ * @param {string} cwd - Working directory to look for forge.yaml in.
+ * @returns {number|null} Timeout in milliseconds, or null when not configured.
+ */
+export function resolveConfiguredCliTimeout(cwd) {
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return null;
+    const raw = readFileSync(forgeYamlPath, "utf-8");
+    const minutes = Number(parseForgeYaml(raw)?.pipeline?.cli_timeout_minutes);
+    return Number.isFinite(minutes) && Number.isInteger(minutes) && minutes > 0
+      ? minutes * 60 * 1000
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Backend selection (issue #2003) — CLI vs API execution backend
 // ---------------------------------------------------------------------------
@@ -491,9 +544,10 @@ export function runCliWithStalePathRecovery({
  * API checks verify that a key is configured, not that the key is accepted.
  */
 export function checkExecutionBackend({
-  requested = process.env.FORGEDOCK_BACKEND || "auto",
+  env = process.env,
+  requested = env.FORGEDOCK_BACKEND || "auto",
   cwd = process.cwd(),
-  apiKey = process.env.ANTHROPIC_API_KEY,
+  apiKey = env.ANTHROPIC_API_KEY,
   resolveCliFn = resolveClaudeCliBinary,
   spawnImpl = spawnSync,
   sdkAvailableFn = () => {
@@ -509,6 +563,10 @@ export function checkExecutionBackend({
     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) {
@@ -606,14 +664,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"]),
@@ -1043,8 +1103,10 @@ export function runCliBackend({
   spawnFn = spawnSync,
 }) {
   const rawTimeout = parseInt(process.env.FORGEDOCK_CLI_TIMEOUT_MS, 10);
-  const timeoutMs =
-    Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : DEFAULT_CLI_TIMEOUT_MS;
+  const configuredTimeout = resolveConfiguredCliTimeout(cwd);
+  const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0
+    ? rawTimeout
+    : configuredTimeout ?? DEFAULT_CLI_TIMEOUT_MS;
 
   // Write the system prompt (command spec + framing) to a private temp file
   // rather than passing it inline as an argv string — see the SYSTEM PROMPT
@@ -2086,9 +2148,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
@@ -2104,10 +2172,10 @@ 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.
-  let 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 });
+    const readiness = checkExecutionBackend({ requested: "auto", cwd, apiKey, env: runtimeEnv });
     if (readiness.backend === "api") resolvedBackend = "api";
   }