forgedock 1.1.11 → 1.3.0

package/README.md

@@ -4,9 +4,13 @@
 
 <h1>ForgeDock</h1>
 
-<p><strong>Deterministic orchestration for autonomous software engineering.</strong></p>
+<p><strong>Point it at an issue and get a merged, reviewed PR; point it at a <strong>milestone</strong> and get parallel pipelines with conflict-aware scheduling.</strong></p>
 
-<p>LLMs generate the code. ForgeDock owns everything else — <strong>state, scheduling, recovery, review, and memory</strong> — as durable, inspectable structure on the GitHub you already have. Issues are the queue. PRs are the ledger. Annotations are the memory. Point it at an issue and get a merged, reviewed PR; point it at a <strong>milestone</strong> and get parallel pipelines with conflict-aware scheduling.</p>
+<p>LLMs generate the code. ForgeDock owns everything else — <strong>state, scheduling, recovery, review, and memory</strong> — as durable, inspectable structure on the GitHub you already have. Issues are the queue. PRs are the ledger. Annotations are the memory. Deterministic orchestration for autonomous software engineering.</p>
+
+<p><em>ForgeDock (not ForgeRock) — this project is unrelated to ForgeRock's identity and access management platform.</em></p>
+
+<p>📖 <a href="https://rapiercraftstudios.github.io/ForgeDock/">Full documentation site</a></p>
 
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" /></a>
 <a href="https://github.com/RapierCraftStudios/ForgeDock/stargazers"><img src="https://img.shields.io/github/stars/RapierCraftStudios/ForgeDock?style=social" alt="GitHub Stars" /></a>
@@ -52,6 +56,8 @@ $ /work-on #1230        "orchestrate: Layer 5 co-change signal is dead code"
 
 ### Try it in 30 seconds — on a throwaway repo, nothing to lose
 
+**Requires:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (subscription or `ANTHROPIC_API_KEY`) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
+
 ```bash
 npx forgedock demo     # spins up a risk-free demo repo and shows you the pipeline end to end
 ```
@@ -250,7 +256,7 @@ Then just open Claude Code and run `/work-on <issue>`.
 
 Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock init` to generate `forge.yaml`.
 
-**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan; with an `ANTHROPIC_API_KEY`, `npx forgedock run` drives the same command specs through a hardened tool-use loop, and `npx forgedock run-issue <issue>` executes them on the durable engine (event-sourced run log, leases, crash-safe resume).
+**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan. `npx forgedock run` picks an execution backend automatically (`--backend auto`, the default): if the Claude Code CLI (`claude`) is installed and already authenticated (Pro/Max subscription or a CLI-managed key), it drives the command through that — **no separate `ANTHROPIC_API_KEY` required**. Otherwise it falls back to the Anthropic API directly (`ANTHROPIC_API_KEY` required). Force either path explicitly with `--backend cli` / `--backend api` (or `FORGEDOCK_BACKEND=cli|api`) — the API backend is what CI environments without an interactive `claude` login should use. `npx forgedock run-issue <issue>` executes the same command specs on the durable engine (event-sourced run log, leases, crash-safe resume).
 
 **Explicit install command:**
 

package/bin/cli-spawn-shared.mjs

@@ -0,0 +1,25 @@
+/**
+ * cli-spawn-shared.mjs — shared constants for `claude` CLI `spawnSync`
+ * invocations across the codebase.
+ *
+ * Extracted (issue #2032) to stop `maxBuffer: 50 * 1024 * 1024` from
+ * drifting independently at each spawn call site (bin/runner.mjs's
+ * `runCliBackend` and `run_bash`, bin/init-enrich-cli.mjs's `enrich()`) —
+ * all three invoke the same local `claude` CLI and should share one
+ * default rather than three copies of the same magic number.
+ *
+ * Isolated: imports no external modules, so it is safe to import from any
+ * module without creating a cycle.
+ */
+
+/**
+ * Default `maxBuffer` (bytes) for a `spawnSync` call against the local
+ * `claude` CLI. 50 MB comfortably covers a full headless response (stdout)
+ * plus any diagnostic stderr without risking silent truncation.
+ *
+ * `bin/runner.mjs`'s `run_bash` tool handler additionally allows this
+ * default to be overridden per-call via `FORGEDOCK_MAX_BUFFER_BYTES` — that
+ * override logic lives in `runner.mjs` itself; this constant is only the
+ * shared *default*.
+ */
+export const DEFAULT_SPAWN_MAX_BUFFER_BYTES = 50 * 1024 * 1024;

package/bin/engine/phases.mjs

@@ -7,27 +7,146 @@
 
 export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed"];
 
-/** Fetch the issue's comment bodies as one blob for marker checks. */
+/**
+ * Fetch the issue's comments. Returns both:
+ *  - `blob`: all bodies joined into one string, for simple marker-presence checks
+ *    (`has(blob, marker)`) where it doesn't matter which comment posted the marker.
+ *  - `comments`: an array of individual comment bodies, preserving per-comment
+ *    boundaries, for extraction that MUST be scoped to a specific comment (see
+ *    `parseBranchFromMarkers()` below — forge#2184).
+ *
+ * The `--jq '[.[].body]'` query asks `gh` for a JSON array of bodies. If the
+ * response isn't valid JSON (a non-JSON gh error string, or a test mock that
+ * supplies a raw marker string instead of the real API shape), fall back to
+ * treating the whole blob as a single pseudo-comment — `has()` checks are
+ * unaffected either way, and comment-scoped extraction simply won't match,
+ * which is the safe, conservative behavior.
+ */
 async function issueMarkers(issue, io) {
-  const out = await io.gh(["api", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq", ".[].body"]);
-  return out || "";
+  const out = await io.gh(["api", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq", "[.[].body]"]);
+  const blob = out || "";
+  let comments = [];
+  try {
+    const parsed = JSON.parse(out);
+    if (Array.isArray(parsed)) {
+      comments = parsed.map((c) => (typeof c === "string" ? c : (c && c.body) || ""));
+    }
+  } catch {
+    comments = blob ? [blob] : [];
+  }
+  return { blob, comments };
 }
 /**
- * Count commits on branch ahead of the lane base. On the first build the
+ * Count commits on `branch` ahead of `lane`'s base. On the first build the
  * branch does not exist yet, so real git rejects the ref range — swallow
  * that (and any other git failure) as "0 ahead" rather than letting it
  * propagate and crash runIssue (C1).
+ *
+ * Takes explicit `lane`/`branch` args (rather than reading them off `state`)
+ * so every call site is forced to resolve the branch it means to check —
+ * see `resolveBranch()` below (forge#2174: the previous `state.branch`-only
+ * signature let the build phase evaluate this against a guessed branch name
+ * that never matched the branch the builder actually created).
+ *
+ * Returns -1 (rather than 0) when the underlying `git` call itself failed
+ * (lock contention, transient I/O error, ref not yet fetched, etc.) — distinct
+ * from a genuine, successfully-computed 0. This distinction matters to the
+ * build phase's `detectOutcome` (forge#2176): a *genuine* 0 ahead (git ran
+ * cleanly and reported no new commits) is a stable fixed point safe to mark
+ * non-retryable, but a transient git error folded into the same 0 would not
+ * be — the very next attempt could see a different, non-erroring result with
+ * no external input having changed, so it must remain retryable. Callers that
+ * only compare `> 0` (reconcile()'s satisfied check) are unaffected: -1 is
+ * still not `> 0`, so existing behavior there is unchanged.
  */
-async function commitsAhead(state, io) {
+async function commitsAhead(lane, branch, io) {
   try {
-    const n = await io.git(["rev-list", "--count", `origin/${state.lane}..${state.branch}`]);
+    const n = await io.git(["rev-list", "--count", `origin/${lane}..${branch}`]);
     return parseInt(String(n).trim(), 10) || 0;
   } catch {
-    return 0;
+    return -1;
   }
 }
+/**
+ * Marker-presence check used throughout this file — including
+ * `FORGE:BUILDER:COMPLETE` eligibility gates in the "build" phase's
+ * `reconcile`/`detectOutcome` below (forge#2194 — investigated, no change).
+ *
+ * This is a plain substring test, deliberately, for consistency: every other
+ * marker gate in this file (`INVESTIGATION:INVALID`, `DECOMPOSE:YES`,
+ * `INVESTIGATION:COMPLETE`, `FORGE:CONTEXT:COMPLETE`,
+ * `FORGE:ARCHITECT:COMPLETE`, `workflow:merged`) uses the identical
+ * substring/membership technique — singling out `FORGE:BUILDER:COMPLETE`
+ * alone for a "structured" parse would be inconsistent and would not close
+ * any real gap: the actual trust boundary for issue-comment content is
+ * *authorship* (can an untrusted actor post a comment on this issue at all),
+ * not *format*. Nothing in this engine validates comment authorship for any
+ * marker today, so an actor able to post an arbitrary comment could just as
+ * easily post whatever "structured" shape a parser would accept — format
+ * hardening alone buys nothing here. If comment-spoofing is ever a concern
+ * worth addressing, the fix is an author allowlist applied uniformly to all
+ * markers, not a bespoke parser for this one field.
+ */
 function has(blob, marker) { return blob.includes(marker); }
 
+/**
+ * Parse the real branch name out of the `FORGE:BUILDER` comment's
+ * `**Branch**: \`{BRANCH}\`` field (see `commands/work-on/build/implement.md`
+ * Phase I6 — this is the exact format the builder posts). Ground truth for
+ * "what branch did the builder actually create" — the engine has no other
+ * reliable source, since the branch name is slug-derived from the issue
+ * title and cannot be guessed or precomputed (forge#2174).
+ *
+ * SCOPING (forge#2184): only comments whose body contains `FORGE:BUILDER:COMPLETE`
+ * — the same completion marker the build phase already gates on — are eligible
+ * to supply the branch. A `**Branch**:` field inside any other comment (a
+ * FORGE:CONTRACT, FORGE:ARCHITECT, FORGE:CONTEXT, reviewer, or remediation
+ * comment) is never considered, even if it happens to match the same regex
+ * shape. If more than one FORGE:BUILDER:COMPLETE comment exists (e.g. a
+ * resumed/retried build re-posting a fresh completion comment), the LAST one
+ * — by array/chronological order — wins, so the most recent build attempt's
+ * branch is used. Returns null (never invents a value) if no eligible comment
+ * contains the field.
+ *
+ * WITHIN-COMMENT FIELD ORDER (forge#2193 — investigated, no change): once the
+ * winning comment is selected (comment-level last-match, above — settled by
+ * forge#2184, do not conflate with this paragraph), `body.match(re)` returns
+ * the FIRST `**Branch**:` occurrence in that comment, because `re` has no
+ * `/g` flag. This is intentional, not an oversight: there is exactly one
+ * producer of this field — `commands/work-on/build/implement.md` Phase I6 —
+ * which posts `**Branch**: \`{BRANCH}\`` exactly once per FORGE:BUILDER
+ * comment. `FORGE:BUILDER:COMPLETE` is appended IN PLACE to that same
+ * existing comment by `commands/work-on/build/validate.md` Phase V5 (an edit,
+ * not a new comment), so no code path in this pipeline ever produces two
+ * `**Branch**:` fields inside one FORGE:BUILDER:COMPLETE-eligible comment.
+ * First-match and last-match are therefore equivalent for every real input;
+ * first-match is kept because it's the simpler default. If a future producer
+ * ever posts more than one `**Branch**:` field in a single eligible comment,
+ * this will silently keep returning the first one — revisit this comment
+ * before changing that invariant.
+ */
+function parseBranchFromMarkers(comments) {
+  const re = /\*\*Branch\*\*:\s*`([^`]+)`/;
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const body = comments[i];
+    if (!body || !body.includes("FORGE:BUILDER:COMPLETE")) continue;
+    const match = body.match(re);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+/**
+ * Resolve the branch to evaluate the build phase against: ground truth from
+ * the FORGE:BUILDER:COMPLETE comment if present (see `parseBranchFromMarkers()`
+ * for the exact scoping rule), else whatever `state.branch` already holds
+ * (e.g. a real branch carried forward from a prior PHASE_COMMIT — see
+ * `runlog.mjs:deriveState`). Never invents a value.
+ */
+function resolveBranch(state, comments) {
+  return parseBranchFromMarkers(comments) || state.branch || null;
+}
+
 /** @type {Phase[]} */
 export const PHASES = [
   {
@@ -35,12 +154,12 @@ export const PHASES = [
     command: "work-on/investigate",
     entryCondition: () => true,
     async detectOutcome(state, io) {
-      const m = await issueMarkers(state.issue, io);
-      if (has(m, "INVESTIGATION:INVALID"))
+      const { blob } = await issueMarkers(state.issue, io);
+      if (has(blob, "INVESTIGATION:INVALID"))
         return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
-      if (has(m, "DECOMPOSE:YES"))
+      if (has(blob, "DECOMPOSE:YES"))
         return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
-      if (has(m, "INVESTIGATION:COMPLETE"))
+      if (has(blob, "INVESTIGATION:COMPLETE"))
         return { status: "committed", outputs: { verdict: "CONFIRMED" } };
       return { status: "failed", detail: "no INVESTIGATION:COMPLETE marker" };
     },
@@ -53,13 +172,13 @@ export const PHASES = [
     async reconcile(state, io) {
       // Idempotent resume: FORGE:CONTEXT:COMPLETE present → skip the LLM re-run.
       // Bare FORGE:CONTEXT matches a partial/interrupted annotation — require :COMPLETE.
-      const m = await issueMarkers(state.issue, io);
-      return has(m, "FORGE:CONTEXT:COMPLETE") ? { satisfied: true } : { satisfied: false };
+      const { blob } = await issueMarkers(state.issue, io);
+      return has(blob, "FORGE:CONTEXT:COMPLETE") ? { satisfied: true } : { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const m = await issueMarkers(state.issue, io);
+      const { blob } = await issueMarkers(state.issue, io);
       // Context is non-critical: a missing marker is a VISIBLE skip, not a hard fail (spec §7).
-      if (has(m, "FORGE:CONTEXT")) return { status: "committed", outputs: {} };
+      if (has(blob, "FORGE:CONTEXT")) return { status: "committed", outputs: {} };
       return { status: "committed", outputs: { skipped: true, which: "context" } };
     },
   },
@@ -70,12 +189,12 @@ export const PHASES = [
     async reconcile(state, io) {
       // Idempotent resume: FORGE:ARCHITECT:COMPLETE present → skip the LLM re-run.
       // Bare FORGE:ARCHITECT matches a partial/interrupted annotation — require :COMPLETE.
-      const m = await issueMarkers(state.issue, io);
-      return has(m, "FORGE:ARCHITECT:COMPLETE") ? { satisfied: true } : { satisfied: false };
+      const { blob } = await issueMarkers(state.issue, io);
+      return has(blob, "FORGE:ARCHITECT:COMPLETE") ? { satisfied: true } : { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const m = await issueMarkers(state.issue, io);
-      return has(m, "FORGE:ARCHITECT:COMPLETE")
+      const { blob } = await issueMarkers(state.issue, io);
+      return has(blob, "FORGE:ARCHITECT:COMPLETE")
         ? { status: "committed", outputs: {} }
         : { status: "failed", detail: "no FORGE:ARCHITECT:COMPLETE" };
     },
@@ -85,19 +204,50 @@ export const PHASES = [
     command: "work-on/build",
     entryCondition: (s) => s.committed.includes("architect"),
     async reconcile(state, io) {
-      // Idempotent resume: branch already ahead of base → treat as done, skip the LLM.
-      if (state.branch && (await commitsAhead(state, io)) > 0) {
-        const m = await issueMarkers(state.issue, io);
-        if (has(m, "FORGE:BUILDER:COMPLETE")) return { satisfied: true, outputs: { branch: state.branch } };
+      // Idempotent resume: resolve the real branch from ground truth (FORGE:BUILDER
+      // comment) rather than trusting a possibly-stale/absent state.branch, then
+      // check it's already ahead of base → treat as done, skip the LLM (forge#2174).
+      const { blob, comments } = await issueMarkers(state.issue, io);
+      const branch = resolveBranch(state, comments);
+      if (branch && has(blob, "FORGE:BUILDER:COMPLETE") && (await commitsAhead(state.lane, branch, io)) > 0) {
+        return { satisfied: true, outputs: { branch } };
       }
       return { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const m = await issueMarkers(state.issue, io);
-      const complete = has(m, "FORGE:BUILDER:COMPLETE");           // #1305: require :COMPLETE …
-      const ahead = state.branch ? await commitsAhead(state, io) : 0; // … AND real commits
-      if (complete && ahead > 0) return { status: "committed", outputs: { branch: state.branch } };
-      return { status: "failed", detail: `builder complete=${complete} commitsAhead=${ahead}` };
+      const { blob, comments } = await issueMarkers(state.issue, io);
+      const complete = has(blob, "FORGE:BUILDER:COMPLETE");        // #1305: require :COMPLETE …
+      // Resolve the branch the builder actually created from the FORGE:BUILDER:COMPLETE
+      // comment (ground truth), scoped to that specific comment — see
+      // resolveBranch()/parseBranchFromMarkers() above (forge#2174, forge#2184).
+      const branch = resolveBranch(state, comments);
+      const ahead = branch ? await commitsAhead(state.lane, branch, io) : 0; // … AND real commits
+      if (complete && ahead > 0) return { status: "committed", outputs: { branch } };
+      const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
+      // forge#2176: when the builder has already posted FORGE:BUILDER:COMPLETE
+      // but the resolved (real, ground-truth) branch has zero commits ahead of
+      // the lane base, this is a stable fixed point, not a transient failure.
+      // commands/work-on/build.md's own early-exit (Phase B0) means any
+      // subsequent re-invocation of this phase's runner will see
+      // FORGE:BUILDER:COMPLETE already present and immediately no-op with
+      // `BUILD_RESULT: status: ALREADY_DONE` — it will never touch git again,
+      // so `ahead` cannot change without new, out-of-band input (e.g. a human
+      // pushing a commit). Retrying is therefore guaranteed to reproduce this
+      // exact result; mark it non-retryable so the engine escalates after a
+      // single attempt instead of burning the full attempt budget.
+      //
+      // When `complete` is false, the builder never finished at all (crashed,
+      // ran out of iterations, or was interrupted) — that IS worth a fresh
+      // retry, so this branch intentionally leaves `retryable` unset
+      // (defaults to retryable in bin/engine.mjs's runPhaseWithRetry).
+      //
+      // `ahead === -1` means commitsAhead() itself failed (transient git
+      // error), NOT a confirmed zero — that is exactly the kind of failure
+      // a retry might resolve, so it must stay retryable too. Only a
+      // successfully-computed ahead of 0 (a real "nothing new to commit"
+      // result) is the true fixed point this non-retryable signal targets.
+      if (complete && ahead !== -1) return { status: "failed", detail, retryable: false };
+      return { status: "failed", detail };
     },
   },
   {

package/bin/engine/state.mjs

@@ -8,11 +8,29 @@ const BLOCK_RE = /<!-- FORGE:STATE\s*([\s\S]*?)-->/;
 
 /** @param {import("./phases.mjs").RunState} index */
 export function serializeState(index) {
-  // Escape both HTML comment-close forms: the standard "-->" and the "--!>"
-  // variant that browsers/HTML parsers also honour. JSON.stringify does not
-  // escape either, so a payload value containing them could otherwise close
-  // the <!-- FORGE:STATE ... --> block early (CodeQL js/bad-tag-filter).
-  const payload = JSON.stringify(index).replace(/--(!?)>/g, "--$1&gt;");
+  // Escape all three HTML comment delimiter forms so a payload value can never
+  // open or close an HTML comment in GitHub's renderer:
+  //   - "<!--"  the comment opener — an unescaped opener would start a new
+  //     (nested-looking) comment, visually swallowing subsequent content
+  //     (mirrors packages/protocol/src/emit.js's sanitizeFieldValue, forge#1638/#2119)
+  //   - "-->" and "--!>"  the two comment-close forms browsers/HTML parsers
+  //     honour. JSON.stringify does not escape any of these, so a payload
+  //     value containing them could otherwise open/close the
+  //     <!-- FORGE:STATE ... --> block early (CodeQL js/bad-tag-filter).
+  //
+  // The "&" escape below MUST run first, before the delimiter escapes. Without
+  // it, a payload value that already contains literal entity-like text (e.g.
+  // "<!--&gt;" or "&lt;!--") collides with the encoded form of an unrelated
+  // real delimiter — the encoder is not injective and the collision is
+  // unrecoverable on decode (forge#2137). Escaping "&" first guarantees every
+  // "&lt;!--"/"--&gt;"/"--!&gt;" sequence present in the output was produced
+  // by *this* encode pass, never by pre-existing entity text (which is now
+  // doubly-escaped, e.g. "&" -> "&amp;" -> untouched by the delimiter pass
+  // that only matches literal "<!--"/"--"+">" character sequences).
+  const payload = JSON.stringify(index)
+    .replace(/&/g, "&amp;")
+    .replace(/<!--/g, "&lt;!--")
+    .replace(/--(!?)>/g, "--$1&gt;");
   return `${OPEN}\n${payload}\n${CLOSE}`;
 }
 
@@ -20,8 +38,22 @@ export function serializeState(index) {
 export function parseState(issueBody) {
   const m = BLOCK_RE.exec(issueBody || "");
   if (!m) return null;
-  // Inverse of serializeState: restore both "--&gt;" and "--!&gt;".
-  try { return JSON.parse(m[1].trim().replace(/--(!?)&gt;/g, "--$1>")); } catch { return null; }
+  // Inverse of serializeState: restore "--&gt;", "--!&gt;", "&lt;!--", then
+  // "&amp;" — in that order. Unescape the closer forms first (most-specific
+  // "--!&gt;" before "--&gt;") so a dangling "!" is never left behind, then
+  // restore the opener — same ordering rationale as
+  // packages/protocol/src/parse.js's unescapeFieldValue. The "&amp;" -> "&"
+  // unescape MUST run LAST (mirroring the encode side running it FIRST) so it
+  // never touches the "&" that is part of a just-restored "<!--"/"-->"/"--!>"
+  // sequence (forge#2137).
+  try {
+    return JSON.parse(
+      m[1].trim()
+        .replace(/--(!?)&gt;/g, "--$1>")
+        .replace(/&lt;!--/g, "<!--")
+        .replace(/&amp;/g, "&"),
+    );
+  } catch { return null; }
 }
 
 /** Replace the FORGE:STATE block in place, or append one if absent. */

package/bin/engine-cli.mjs

@@ -9,7 +9,7 @@ import { promisify } from "node:util";
 import { readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { runIssue } from "./engine.mjs";
+import { runIssue, DEFAULT_MAX_ATTEMPTS } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { readLog, deriveState } from "./engine/runlog.mjs";
 
@@ -55,6 +55,56 @@ export function makeIo() {
 
 export function runDir() { return join(homedir(), ".forge", "runs"); }
 
+/**
+ * Renders the diagnostic block printed below the bare terminal line whenever
+ * a run does not terminate `merged` (forge#2175). Reconstructs the failing
+ * phase, attempt count, and `PHASE_FAILED.reason` from the durable run-log
+ * (the same data `bin/engine.mjs`'s `runPhaseWithRetry()` already appends via
+ * `appendEvent()`), plus the final committed/branch/pr state and the run-log
+ * path — closing the gap where an operator previously had to manually open
+ * `~/.forge/runs/{issue}.jsonl` and read engine source to interpret a bare
+ * `issue #N -> needs-human` line.
+ *
+ * Best-effort: if the run-log is empty/unreadable (e.g. a `deferred` early
+ * return before any event was appended), only the run-log path line is
+ * printed — never throws.
+ *
+ * Validates `issue` internally (mirrors the `Number.isInteger` guard in
+ * `lastLocalRun()` below) rather than relying solely on the caller —
+ * `runFromCli()` already validates before calling this, but this is an
+ * exported helper and a future caller could forget to (forge#2190).
+ *
+ * @param {string} dir - runDir() (or an injected override for tests)
+ * @param {number} issue
+ * @returns {string} multi-line diagnostic block (no trailing newline)
+ */
+export function formatTerminalDiagnostics(dir, issue) {
+  if (!Number.isInteger(issue)) {
+    return `  run-log: <invalid issue: ${JSON.stringify(issue)}>`;
+  }
+  const runLogPath = join(dir, `${issue}.jsonl`);
+  let events = [];
+  try {
+    events = readLog(dir, issue);
+  } catch {
+    // Corrupt/unreadable log — degrade to just the run-log path line below.
+  }
+
+  const lines = [];
+  if (events.length > 0) {
+    const state = deriveState(events);
+    const lastFailure = [...events].reverse().find((e) => e.event === "PHASE_FAILED");
+    if (lastFailure) {
+      lines.push(`  phase:   ${lastFailure.phase} (failed ${lastFailure.attempt}/${DEFAULT_MAX_ATTEMPTS} attempts)`);
+      lines.push(`  reason:  ${lastFailure.reason}`);
+    }
+    const committed = state.committed.length ? state.committed.join(",") : "";
+    lines.push(`  state:   committed=[${committed}] branch=${state.branch ?? "null"} pr=${state.pr ?? "null"}`);
+  }
+  lines.push(`  run-log: ${runLogPath}`);
+  return lines.join("\n");
+}
+
 /**
  * Resolves the repo `gh` would target by default (i.e. resolved from the cwd
  * git remote), via `gh repo view`. Used to validate an explicit `--repo` flag
@@ -224,6 +274,21 @@ export function lastLocalRun(dir) {
  * @param {{io?: {gh: Function}, runIssue?: Function}} [deps]
  *   Injectable for tests — defaults to real `gh`/`git` (makeIo()) and the real
  *   `runIssue` engine driver.
+ *
+ * Flags:
+ *   --lane <lane>          Required — e.g. `main` or `staging`.
+ *   --repo <owner/repo>    Optional — must match the cwd-resolved repo (forge#1593).
+ *   --backend <cli|api|auto>  Optional (forge#2028). Forwarded to every phase's
+ *                          `runCommand()` call. Omit to keep runner.mjs's own
+ *                          default ("auto" ladder — probes the `claude` CLI, falls
+ *                          back to the API). Mirrors `bin/forgedock.mjs`'s `run()`
+ *                          `--backend` semantics — validation (rejecting invalid
+ *                          values) is left to `runCommand()`'s own `resolveBackend()`
+ *                          rather than duplicated here.
+ *   --model <id>           Optional (forge#2028). Forwarded to every phase's
+ *                          `runCommand()` call; only applies on the "api" backend.
+ *                          Omit to keep runner.mjs's default (`FORGEDOCK_MODEL` env
+ *                          or its built-in default).
  */
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
@@ -231,13 +296,30 @@ export async function runFromCli(argv, deps = {}) {
   const lane = flag(argv, "--lane");
   if (!lane) throw new Error("--lane is required: e.g. --lane main or --lane staging. No default to prevent accidental production targeting.");
   const repo = flag(argv, "--repo");
+  const backend = flag(argv, "--backend");
+  const model = flag(argv, "--model");
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
   const agentId = `cli_${process.pid}`;
-  const res = await runIssueFn({ issue, dir: runDir(), agentId, lane, io,
-    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now() });
+  // Injectable for tests (forge#2175) — defaults to the real ~/.forge/runs dir.
+  const dir = deps.dir ?? runDir();
+  const res = await runIssueFn({ issue, dir, agentId, lane, io,
+    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
+    // Only forwarded when explicitly provided — omitting them preserves
+    // runIssue's/runner.mjs's existing defaults (forge#2028).
+    ...(backend ? { backend } : {}),
+    ...(model ? { model } : {}) });
   console.log(`issue #${issue} → ${res.terminalReason}`);
+  // forge#2175: a non-success termination previously printed nothing beyond
+  // the bare reason above — the actual failing phase/attempt/reason was only
+  // recoverable by manually reading ~/.forge/runs/{issue}.jsonl and then the
+  // engine source. Print it here instead, reconstructed from the same
+  // run-log runIssue() just wrote. Skipped for "merged" (the success case)
+  // to avoid regressing/cluttering the existing happy-path output.
+  if (res.terminalReason !== "merged") {
+    console.log(formatTerminalDiagnostics(dir, issue));
+  }
   return res;
 }
 

package/bin/engine.mjs

@@ -8,13 +8,51 @@ import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.m
 import { pickPhase, TERMINAL_REASONS } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
+import { VALID_BACKENDS } from "./runner.mjs";
 
-const DEFAULT_MAX_ATTEMPTS = 3;
+// Exported (forge#2175) so bin/engine-cli.mjs can render "failed N/M attempts"
+// diagnostics without duplicating the retry budget constant.
+export const DEFAULT_MAX_ATTEMPTS = 3;
 
+/**
+ * @param {object} opts
+ * @param {string} [opts.backend] - "cli" | "api" | "auto" (forge#2028). Forwarded
+ *   to every phase's `runner()` call when supplied. Omit to keep runner.mjs's own
+ *   default ("auto" ladder — probes the `claude` CLI, falls back to the API).
+ *   An invalid value throws synchronously (see below) rather than being forwarded.
+ * @param {string} [opts.model] - Model id (forge#2028). Forwarded to every phase's
+ *   `runner()` call when supplied; only applies on the "api" backend. Omit to keep
+ *   runner.mjs's default (`FORGEDOCK_MODEL` env or its built-in default).
+ */
 export async function runIssue(opts) {
   const { issue, dir, agentId, lane = "staging", io, runner,
           now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
-          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)) } = opts;
+          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)),
+          // Optional execution-backend override for every phase's `runner()`
+          // call (forge#2028 / MAT-3). Left undefined by default so existing
+          // callers keep runner.mjs's own "auto" ladder default unchanged —
+          // this is purely additive pass-through, not a new default.
+          backend, model } = opts;
+
+  // forge#2054: validate `backend` before anything else — before state is
+  // read/written and before the phase/retry loop begins below. An invalid
+  // value must fail fast and non-retryably. Without this check, an invalid
+  // backend instead reaches runner.mjs's resolveBackend() deep inside
+  // runPhaseWithRetry()'s per-attempt try/catch, throws an uncoded Error, and
+  // is silently retried up to `maxAttempts` times (the catch there only
+  // fast-fails on `.code === "NO_API_KEY"/"NO_SDK"`) before escalating to
+  // needs-human — burning retries on what is actually a config error, not a
+  // transient phase failure. runIssue() is the single production choke point
+  // (its only caller is bin/engine-cli.mjs's runFromCli()), so validating
+  // here protects every current and future caller without requiring each one
+  // to remember to validate independently.
+  if (backend !== undefined && !VALID_BACKENDS.has(backend)) {
+    throw Object.assign(
+      new Error(`Invalid backend "${backend}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`),
+      { code: "INVALID_BACKEND" },
+    );
+  }
+
   const projector = makeProjector(io);
 
   // 1. Load + reconcile (GitHub wins).
@@ -49,11 +87,17 @@ export async function runIssue(opts) {
   }
 
   // 2. Drive phases until terminal.
+  //
+  // Note: the build phase's branch is NOT precomputed here. The real branch
+  // name is slug-derived from the issue title by `commands/work-on/build.md`
+  // (Phase B1A) and cannot be guessed ahead of time — a prior guessed default
+  // (`fix/pipeline-{issue}`) was never communicated to the builder and never
+  // matched the branch it actually created, so `commitsAhead()` always ran
+  // against a nonexistent ref and silently evaluated to 0 (forge#2174). The
+  // build phase's `reconcile`/`detectOutcome` (bin/engine/phases.mjs) resolve
+  // the real branch from the `FORGE:BUILDER` comment instead.
   let phase;
   while ((phase = pickPhase(state))) {
-    // Every issue's build works on a deterministic branch; set it before build runs.
-    if (phase.id === "build" && !state.branch) state.branch = `fix/pipeline-${issue}`;
-
     let reconciled;
     try {
       reconciled = phase.reconcile ? await phase.reconcile(state, io) : { satisfied: false };
@@ -67,7 +111,7 @@ export async function runIssue(opts) {
       outcome = { status: "committed", outputs: reconciled.outputs || {} };
     } else {
       if (reconciled.outputs?.pr) state.pr = reconciled.outputs.pr;
-      outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts });
+      outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model });
     }
 
     if (outcome.status === "blocked") return await terminate(state, "needs-human", outcome.detail);
@@ -95,11 +139,17 @@ export async function runIssue(opts) {
 }
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts } = ctx;
+  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model } = ctx;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     appendEvent(dir, issue, { event: "PHASE_START", phase: phase.id, attempt });
     try {
-      await runner({ commandsDir, commandName: phase.command, args: [String(issue)] });
+      await runner({
+        commandsDir, commandName: phase.command, args: [String(issue)],
+        // Only forwarded when explicitly provided — omitting them preserves
+        // runner.mjs's existing default ("auto" backend / DEFAULT_MODEL).
+        ...(backend ? { backend } : {}),
+        ...(model ? { model } : {}),
+      });
     } catch (e) {
       // A missing API key / SDK is a config error, not a transient phase
       // failure — surface it distinctly instead of burning retries and
@@ -111,6 +161,19 @@ async function runPhaseWithRetry(phase, state, ctx) {
     const outcome = await phase.detectOutcome(state, io);
     if (outcome.status === "committed" || outcome.status === "blocked") return outcome;
     appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail });
+    // forge#2176: a phase's detectOutcome can mark a failure as a known,
+    // state-derived fixed point — re-running the phase's runner is
+    // guaranteed to reproduce the identical failure (e.g. the build phase's
+    // builder already completed and will no-op on any re-invocation, per
+    // commands/work-on/build.md's own `BUILD_RESULT: status: ALREADY_DONE`
+    // early-exit). Honor that signal by stopping immediately rather than
+    // burning the remaining attempt budget on a guaranteed-identical result.
+    // Absent/undefined `retryable` defaults to retryable (existing behavior
+    // for every phase that doesn't opt in — investigate/context/architect/
+    // review/close — is unchanged, preserving transient-failure retries).
+    if (outcome.retryable === false) {
+      return { status: "blocked", detail: outcome.detail };
+    }
   }
   // Exhausted transient retries → escalate (spec §7).
   return { status: "blocked", detail: `phase ${phase.id} failed after ${maxAttempts} attempts` };