forgedock 1.7.1 → 1.8.1

package/bin/opencode-adapter.mjs

@@ -198,16 +198,43 @@ function openCodeReviewDispatchContract() {
   return [
     "OpenCode review-dispatch override:",
     "Before applying the workflow's Claude-specific Task/Agent availability check, treat an OpenCode runtime marker (`FORGE_RUNTIME=opencode`, `OPENCODE_SESSION_ID`, `OPENCODE_PID`, or `OPENCODE`) as native capability context and set `DISPATCH_TOOL=task`.",
-    "Do not enter the `Neither tool is available` branch solely because Claude's literal `Task` and `Agent` names are absent. Every native task call must use `{ description: \"...\", prompt: \"...\", subagent_type: \"general\"|\"explore\", background: true }`; use `general` for implementation/review and `explore` for read-only discovery.",
-    "Use `background: true` for independent orchestration and review work. OpenCode returns a running task marker immediately and injects a later task-result event into the parent; process each event immediately instead of waiting for the slowest sibling.",
+    "Do not enter the `Neither tool is available` branch solely because Claude's literal `Task` and `Agent` names are absent. Every native task call must use `{ description: \"...\", prompt: \"...\", subagent_type: \"general\"|\"explore\", background }`; use `general` for implementation/review and `explore` for read-only discovery.",
+    "Native tasks are foreground by default. Review, quality, remediation, and any other load-bearing child must await its completed task result and propagate its structured `*_RESULT` block before the parent continues. A progress message is not a result. `background: true` is reserved for the Phase 4 OpenCode ready-issue dispatcher, which persists the returned child-session id before handling its completion event.",
+    "For a `work-on/remediate` task, preserve the remediation state transition: after FIXABLE classification, replace `needs-human` with `workflow:in-review`; restore `needs-human` only for a fresh block or an UNFIXABLE policy escalation. Never retain both labels during automated remediation or re-review.",
     "If lowercase native `task` is genuinely absent from the current tool registry, post `FORGE:REVIEW_BLOCKED` and stop; never replace the required isolated review with inline work or another controller.",
   ].join("\n");
 }
 
+function openCodeOrchestrateContract(forgeHome) {
+  const preflightPath = portablePath(join(forgeHome, "bin", "orchestrate-preflight.mjs"));
+  return [
+    "OpenCode orchestration fast path:",
+    `Before reading config.md, the authoritative workflow, or any phase file, run node "$FORGE_HOME/bin/orchestrate-preflight.mjs" --repo "$GH_REPO" --args "$ARGUMENTS" from the target repository and parse its JSON output. The installed implementation is ${preflightPath}. The helper resolves the repository from forge.yaml when GH_REPO is empty.`,
+    "The preflight is deterministic and only handles issue resolution, eligibility filtering, explicit dependencies, scoped issue-body file overlap, database serialization, and the initial ready queue.",
+    "When supported is true, requiresDeepPlan is false, and confirmed is true, launch dispatchNow immediately with native task calls using the exact work-on skill contract. Without explicit --auto or --confirm, present the compact plan and ask for one confirmation; after the user confirms, launch the plan's ready queue without re-reading the large phase files. Do not load the full phase-3 or phase-4 files just to ask that question.",
+    "If requiresDeepPlan is true, the input is unsupported, preflight fails, or a task completion needs recovery, continue from the authoritative shared phase files. The fast path never closes, deduplicates, or edits issue bodies.",
+    "Treat queued as deferred by the concurrency cap and use task-result events to dispatch the next ready issue. Keep the full shared workflow's labels, annotations, leases, and terminal-state rules.",
+  ].join("\n");
+}
+
+function openCodeBuildStageContract(forgeHome) {
+  const implementPath = portablePath(join(forgeHome, "commands", "work-on", "build", "implement.md"));
+  const validatePath = portablePath(join(forgeHome, "commands", "work-on", "build", "validate.md"));
+  return [
+    "OpenCode sequential build dispatch:",
+    "The B5 and B6 calls in the authoritative workflow are serialized control-flow boundaries. Do not load either stage with the native `skill` tool: that tool only injects instructions and does not return a child-session result to this dispatcher.",
+    "For B5, call native `task` with `subagent_type: \"general\"` and `background: false`. Its prompt must load and execute `" + implementPath + "` with the exact build arguments, stage changes, and return only `IMPLEMENT_RESULT`. Wait for the completed task result before continuing.",
+    "Parse `IMPLEMENT_RESULT` from the completed B5 task. Continue to B6 only for `COMPLETE` or `ALREADY_DONE`; preserve the workflow's existing terminal handling for every other status.",
+    "For B6, call native `task` with `subagent_type: \"general\"` and `background: false`. Its prompt must load and execute `" + validatePath + "` with the worktree and B5 changed-file list, then return only `VALIDATE_RESULT`. Wait for completion before the acceptance gate.",
+    "Foreground is the native default for every load-bearing child. Only the Phase 4 OpenCode ready-issue dispatcher uses `background: true`.",
+  ].join("\n");
+}
+
 export function renderOpenCodeCommand({ description, forgeHome, command }) {
   const specPath = portablePath(join(forgeHome, "commands", `${command}.md`));
   const commandsPath = portablePath(join(forgeHome, "commands"));
   const nativeSkillExpression = '${x.replaceAll(":", "-").replaceAll("/", "-")}';
+  const isOrchestrate = command === "orchestrate";
   return [
     "---",
     `description: ${yamlString(`ForgeDock: ${description}`)}`,
@@ -215,16 +242,20 @@ export function renderOpenCodeCommand({ description, forgeHome, command }) {
     "---",
     COMMAND_SENTINEL,
     "",
-    "Run the authoritative ForgeDock workflow at `" + specPath + "` with these exact arguments:",
+    (isOrchestrate
+      ? "Run the OpenCode preflight before loading the authoritative ForgeDock workflow at `" + specPath + "` with these exact arguments:"
+      : "Run the authoritative ForgeDock workflow at `" + specPath + "` with these exact arguments:"),
     "",
     "$ARGUMENTS",
     "",
-    "Use `read` to load that spec, then execute it. Keep loading token-efficient: do not preload sibling specs, catalogs, adapters, or documentation.",
+    ...(isOrchestrate
+      ? ["Do not use `read` to load the authoritative spec yet. Run the deterministic preflight first; only load the shared spec if the preflight requires the full workflow.", "", openCodeOrchestrateContract(forgeHome)]
+      : ["Use `read` to load that spec, then execute it. Keep loading token-efficient: do not preload sibling specs, catalogs, adapters, or documentation."]),
     "",
     "OpenCode runtime mapping:",
     "",
     "- `Skill(skill=\"x\", args=\"y\")` means use the registered native OpenCode skill named `" + nativeSkillExpression + "` in the current context with the exact arguments. Its authoritative source is `" + commandsPath + "/${x.replaceAll(\":\", \"/\")}.md`. If the native skill or source is unavailable, stop with `FORGE_OPENCODE_CAPABILITY_ERROR` and an actionable path; never invoke `forgedock run-issue`, `npx forgedock run-issue`, or recursive `opencode run` as a fallback.",
-    "- `Task(...)` or a permitted `Agent(...)` means use OpenCode's `task` tool with a top-level argument object shaped like `{ description: \"...\", prompt: \"...\", subagent_type: \"general\"|\"explore\", background: true }`. `subagent_type` is mandatory: map Claude `general-purpose` to `general` for implementation/review and `codebase-explorer` to `explore` for read-only discovery. If the source omits a type, set `subagent_type: \"general\"` before calling the tool; never emit a call containing only `description` and `prompt`. Unsupported types must stop with `FORGE_OPENCODE_CAPABILITY_ERROR`. Preserve requested isolation and parallelism, resume by task ID when requested, and never inline a required isolated review.",
+    "- `Task(...)` or a permitted `Agent(...)` means use OpenCode's `task` tool with a top-level argument object shaped like `{ description: \"...\", prompt: \"...\", subagent_type: \"general\"|\"explore\", background }`. `subagent_type` is mandatory: map Claude `general-purpose` to `general` for implementation/review and `codebase-explorer` to `explore` for read-only discovery. If the source omits a type, set `subagent_type: \"general\"` before calling the tool; never emit a call containing only `description` and `prompt`. Omitted `background` means foreground and the parent must await the result. Set `background: true` only for Phase 4 OpenCode ready-issue dispatch after persisting its returned child-session id. Unsupported types must stop with `FORGE_OPENCODE_CAPABILITY_ERROR`. Preserve requested isolation and parallelism, and never inline a required isolated review.",
     openCodeReviewDispatchContract(),
     "- Map Claude tool names to the corresponding OpenCode tools. Do not skip a step merely because its source uses Claude-style invocation syntax.",
     "- OpenCode injects `FORGE_HOME` into shell commands through the ForgeDock plugin. GitHub labels, FORGE annotations, worktree isolation, and terminal-state rules remain unchanged.",
@@ -236,6 +267,7 @@ export function renderOpenCodeSkill({ description, forgeHome, command }) {
   const specPath = portablePath(join(forgeHome, "commands", `${command}.md`));
   const commandsPath = portablePath(join(forgeHome, "commands"));
   const name = normalizeOpenCodeSkillName(command);
+  const isOrchestrate = command === "orchestrate";
   return `---
 name: ${name}
 description: ${yamlString(`ForgeDock: ${description}`)}
@@ -246,11 +278,13 @@ metadata:
 ---
 ${SKILL_SENTINEL}
 
-Load and execute the authoritative ForgeDock workflow at \`${specPath}\` in the current context.
+${isOrchestrate
+  ? `Run the deterministic OpenCode preflight before loading the authoritative ForgeDock workflow at \`${specPath}\` in the current context.`
+  : `Load and execute the authoritative ForgeDock workflow at \`${specPath}\` in the current context.`}
 
-The parent workflow's exact arguments are already present in the current context. Preserve them; do not invent new arguments or launch a second controller. Keep loading token-efficient: read only this workflow and the next spec explicitly reached by its dispatcher.
+The parent workflow's exact arguments are already present in the current context. Preserve them; do not invent new arguments or launch a second controller. Keep loading token-efficient: ${isOrchestrate ? "do not read the shared orchestrate spec until preflight routes to the full workflow." : "read only this workflow and the next spec explicitly reached by its dispatcher."}
 
-${openCodeReviewDispatchContract()}
+${command === "orchestrate" ? `${openCodeOrchestrateContract(forgeHome)}\n\n` : ""}${command === "work-on/build" ? `${openCodeBuildStageContract(forgeHome)}\n\n` : ""}${openCodeReviewDispatchContract()}
 
 If the workflow source or a required native capability is unavailable, stop and report exactly:
 \`FORGE_OPENCODE_CAPABILITY_ERROR\`: ForgeDock workflow \`${command}\` is unavailable at \`${specPath}\`.
@@ -258,7 +292,7 @@ Do not invoke \`forgedock run-issue\`, \`npx forgedock run-issue\`, or recursive
 OpenCode runtime mapping:
 
 - \`Skill(skill="x", args="y")\` means lazily read \`${commandsPath}/\${x.replaceAll(":", "/")}.md\` and execute that workflow in the current context with the exact arguments. Colon separators become slash separators; existing slash separators remain unchanged. This matches Claude Code Skill's in-conversation loading; it is not a reason to spawn a subagent.
-- \`Task(...)\` or a permitted \`Agent(...)\` means use OpenCode's \`task\` tool with \`{ description, prompt, subagent_type, background }\`. Translate \`general-purpose\` to \`general\` and \`codebase-explorer\` to \`explore\`; never omit \`subagent_type\`. Resume by task ID when requested. A successful background call returns \`<task id=... state="running">\`; a later \`state="completed"\` or \`state="error"\` task result is the completion event for that one issue. Do not wait for all tasks before processing an event.
+- \`Task(...)\` or a permitted \`Agent(...)\` means use OpenCode's \`task\` tool with \`{ description, prompt, subagent_type, background }\`. Translate \`general-purpose\` to \`general\` and \`codebase-explorer\` to \`explore\`; never omit \`subagent_type\`. Omitted \`background\` is foreground and must be awaited. Only Phase 4 OpenCode ready-issue dispatch sets \`background: true\`; it persists the returned child-session id, then processes each later \`state="completed"\` or \`state="error"\` event independently.
 - Map Claude tool names to the corresponding OpenCode tools. Do not skip a step merely because its source uses Claude-style invocation syntax.
 - OpenCode injects \`FORGE_HOME\` into shell commands through the ForgeDock plugin. GitHub labels, FORGE annotations, worktree isolation, and terminal-state rules remain unchanged.
 - If a Claude-version, Claude-transcript, or Claude-cache rule has no OpenCode equivalent, ignore only that runtime-specific optimization and preserve the workflow invariant it was intended to protect.
@@ -312,10 +346,10 @@ function normalizeTaskArgs(args) {
   }
 
   args.subagent_type = subagentType
-  // The shared OpenCode workflow requires streaming task completions. The only
-  // supported opt-out is the explicit environment flag, so an omitted or
-  // false per-call value cannot silently reintroduce a wave barrier.
-  if (process.env[BACKGROUND_FLAG] !== "false") args.background = true
+  // A parent may only complete after load-bearing child work completes. The
+  // orchestration dispatcher is the sole caller that opts into background work.
+  if (args.background === undefined || args.background === null) args.background = false
+  if (process.env[BACKGROUND_FLAG] === "false") args.background = false
 }
 `;
   return `${PLUGIN_SENTINEL}

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
@@ -239,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
 // ---------------------------------------------------------------------------
@@ -1079,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