forgedock 1.2.0 → 1.4.0

package/bin/engine/resolve.mjs

@@ -0,0 +1,256 @@
+/**
+ * Issue-set resolution predicate model — standing-query re-resolution (forge#2236).
+ *
+ * `/orchestrate`'s Phase 1 (`commands/orchestrate/phase-1-resolve.md`) turns
+ * `$ARGUMENTS` into a concrete list of issue numbers exactly once, at T0, and
+ * that list is frozen for the rest of the run (`commands/orchestrate/phase-4-execution.md`
+ * states this plainly: "Phase 1 only runs once, at the start."). Of the 8
+ * input patterns Phase 1 accepts, only one (`#1 #2 #3` — an explicit literal
+ * set) is actually a one-time snapshot by nature. The other 7
+ * (`milestone <slug>`, `next <N>`, `next <N> all-repos`, `fast-lane`,
+ * `priority:P0`/`priority:P1`/..., `mcp:fast`/`n8n:next 3`, a bare `<slug>`)
+ * are standing queries/predicates — "work all P0s", "work this milestone" —
+ * and a new issue matching that predicate mid-run is currently invisible to
+ * the DAG until the operator re-invokes `/orchestrate` by hand.
+ *
+ * This module is the typed reference implementation for two decisions Phase 1
+ * and Phase 4 need to make about that gap:
+ *
+ *   1. `classifyInputPattern` — is this input a `literal` set (never
+ *      re-resolve — the list of numbers IS the intent) or a `query`
+ *      (re-resolve periodically — the predicate is the intent)?
+ *   2. `shouldReResolve` — given that classification and the run's
+ *      `orchestration.reresolve` config, should Phase 4's Step 4B loop
+ *      actually re-run the query this round?
+ *   3. `foldNewMatches` — of the issue numbers a re-resolution just
+ *      returned, which ones are genuinely new (not already in this run's
+ *      processed-issue registry) and therefore candidates to fold into the
+ *      live DAG?
+ *
+ * As with `bin/engine/admission.mjs` (forge#2234), this module does not
+ * itself shell out to `gh`/`yq` — the orchestrator is LLM-executed prose,
+ * not a `bin/engine/` call site, so `commands/orchestrate/phase-1-resolve.md`
+ * and `commands/orchestrate/phase-4-execution.md` mirror these rules by hand
+ * in bash. Any change to the classification table or defaults here MUST be
+ * mirrored there too (see forge#1837 — mirrored-logic drift between grep ERE
+ * and a typed reference is a recurring review-finding class in this pair of
+ * files).
+ *
+ * Hard invariant (by design, not configurable): `foldNewMatches` only ever
+ * narrows a re-resolved set down to "not yet processed" — it does not itself
+ * decide admission. Every folded-in issue (`newMatches`) MUST still be
+ * dispatched through the exact same path a T0-resolved issue takes —
+ * standard DAG dependency analysis (`phase-3-dependency.md`) followed by
+ * Step 4A/4B's `dispatch_headroom`-gated dispatch (see
+ * `phase-4-execution.md` Step 4B.6) — before an agent is dispatched on it.
+ * This is deliberately **not** Step 4C's `admission.mjs`'s
+ * `evaluateCascadeFinding` chain: that gate's rules (comment/typo keyword
+ * heuristic, P3+same-file defer, generation cap) are shaped for
+ * cascade-spawned review-findings — a different issue-origin stream — and
+ * would incorrectly restrict legitimate re-resolved standing-query issues
+ * if applied here. A mid-run check that detects new work but never
+ * actually wires into dispatch is exactly the dead-code failure class
+ * documented in forge#1832 (`SURFACE_BATCHED_FINDINGS`) — this module must
+ * not become a second instance of it.
+ */
+
+/**
+ * @typedef {"literal"|"query"} InputKind
+ */
+
+/**
+ * @typedef {Object} ClassifiedInput
+ * @property {InputKind} kind
+ * @property {string} pattern - Canonical name of the matched pattern, e.g.
+ *   "literal-numbers", "milestone", "next-n", "next-n-all-repos",
+ *   "fast-lane", "priority", "repo-scoped", "bare-slug".
+ * @property {string[]} args - The raw argument tokens (excluding the pattern
+ *   keyword itself) that produced this classification, preserved so a
+ *   re-resolution round can replay the exact same query. Exceptions:
+ *   `priority` and `repo-scoped` keep the FULL token list instead of
+ *   slicing off a leading keyword token — for those two patterns the
+ *   pattern keyword is fused into the same token as its argument
+ *   (`priority:P0`, `mcp:fast-lane`, `n8n:next`), so there is no separable
+ *   leading keyword token to drop the way there is for `milestone <slug>`
+ *   or `next <N>`. Slicing here would destroy the only copy of the data a
+ *   re-resolution round needs to replay the query.
+ */
+
+/**
+ * Classify a raw `/orchestrate` input string per the Phase 1 input-pattern
+ * table (`commands/orchestrate/phase-1-resolve.md` "Input Patterns").
+ *
+ * Only an explicit list of bare/`#`-prefixed, optionally repo-prefixed issue
+ * numbers (`#1 #2 #3`, `1 2 3`, `#123 mcp:5 n8n:12`) classifies as `literal`.
+ * Every other recognized pattern is a `query` — the predicate, not the
+ * resolved list, is the caller's actual intent, per the issue's finding that
+ * a query re-run mid-batch is what a standing predicate like `priority:P0`
+ * or `fast-lane` implies. An input that matches no known pattern still
+ * classifies as `query` with `pattern: "unknown"` — unrecognized input is
+ * handed to Phase 1's existing milestone/label fallback resolution, which is
+ * itself a query (bare `<slug>` row), not a literal set.
+ *
+ * @param {string} input - Raw `$ARGUMENTS` string (already trimmed).
+ * @returns {ClassifiedInput}
+ */
+export function classifyInputPattern(input) {
+  const trimmed = (input ?? "").trim();
+  const tokens = trimmed.length > 0 ? trimmed.split(/\s+/) : [];
+
+  // literal-numbers: every token is a bare integer or a (optionally
+  // repo-prefixed) `#`-prefixed integer, e.g. "1 2 3", "#1 #2 #3",
+  // "#123 mcp:5 n8n:12". At least one token is required — empty input is
+  // not a literal set, it falls through to "unknown".
+  const literalNumberToken = /^([a-zA-Z0-9_-]+:)?#?\d+$/;
+  if (tokens.length > 0 && tokens.every((t) => literalNumberToken.test(t))) {
+    return { kind: "literal", pattern: "literal-numbers", args: tokens };
+  }
+
+  const lower = trimmed.toLowerCase();
+
+  if (/^milestone\s+/.test(lower)) {
+    return { kind: "query", pattern: "milestone", args: tokens.slice(1) };
+  }
+
+  if (/^next\s+\d+\s+all-repos$/.test(lower)) {
+    return { kind: "query", pattern: "next-n-all-repos", args: tokens.slice(1) };
+  }
+
+  if (/^next\s+\d+$/.test(lower)) {
+    return { kind: "query", pattern: "next-n", args: tokens.slice(1) };
+  }
+
+  if (lower === "fast-lane" || lower === "fast") {
+    return { kind: "query", pattern: "fast-lane", args: [] };
+  }
+
+  if (/^priority:p\d+$/.test(lower) || /^[a-zA-Z0-9_-]+:priority:p\d+$/.test(lower)) {
+    return { kind: "query", pattern: "priority", args: tokens };
+  }
+
+  // repo-scoped queries: "mcp:fast", "n8n:next 3", "mcp:cascade", etc. — a
+  // repo prefix followed by a colon and a recognized query keyword. Checked
+  // after the more specific patterns above so e.g. "mcp:5" (a repo-prefixed
+  // literal number) is not mis-classified here — literalNumberToken already
+  // claimed that shape.
+  if (/^[a-zA-Z0-9_-]+:(fast-lane|fast|next|cascade|review-findings|findings)\b/.test(lower)) {
+    return { kind: "query", pattern: "repo-scoped", args: tokens };
+  }
+
+  if (/^(cascade|review-findings|findings)\b/.test(lower)) {
+    return { kind: "query", pattern: "cascade", args: tokens.slice(1) };
+  }
+
+  if (tokens.length === 1 && tokens[0].length > 0) {
+    // bare `<slug>` — try milestone first, then label search (Phase 1's own
+    // fallback order). Still a query: the slug's membership can change.
+    return { kind: "query", pattern: "bare-slug", args: tokens };
+  }
+
+  return { kind: "query", pattern: "unknown", args: tokens };
+}
+
+/**
+ * @typedef {Object} ReResolveConfig
+ * @property {boolean|string} [enabled] - Explicit off switch. `false` or the
+ *   string `"off"` (case-insensitive) disables re-resolution regardless of
+ *   `kind`. Absent/`undefined`/`true`/`"on"` leaves the default (on for
+ *   query-kind input) in effect. This mirrors the validate-warn-fall-back
+ *   idiom's spirit but re-resolution has only two valid states, so an
+ *   unrecognized value is treated as `true` (default-on) rather than an
+ *   error — the safer default in this context is "keep the existing
+ *   behavior of periodic re-check", not "silently stop tracking a standing
+ *   predicate".
+ * @property {number} [maxRounds] - Bound on how many times a single run may
+ *   re-resolve the same predicate. Required to satisfy the issue's
+ *   "termination is bounded" acceptance criterion — a standing predicate
+ *   that keeps matching must not re-resolve forever. `undefined`/absent
+ *   means "no additional bound beyond the caller's own token-budget /
+ *   generation caps" (those are enforced downstream, by `admission.mjs`,
+ *   not here).
+ */
+
+/**
+ * Decide whether Phase 4's Step 4B loop should re-run the originating query
+ * this round.
+ *
+ * @param {ClassifiedInput} classified - Result of `classifyInputPattern`.
+ * @param {ReResolveConfig} [config]
+ * @param {number} [roundsSoFar] - How many re-resolution rounds have already
+ *   run this batch (0 on the first call).
+ * @returns {{ reResolve: boolean, reason: string }}
+ */
+export function shouldReResolve(classified, config = {}, roundsSoFar = 0) {
+  if (classified.kind === "literal") {
+    return {
+      reResolve: false,
+      reason: "literal issue-number set — the list IS the intent, never re-resolve",
+    };
+  }
+
+  const enabledRaw = config.enabled;
+  // The `"off"` string branch IS reachable via the real `yq`-based bash
+  // mirror in `phase-4-execution.md` Step 4B.6 — not just from direct JS
+  // callers (e.g. this file's own unit tests). `yq`'s default core schema
+  // only coerces the literal scalars `true`/`false` to booleans; an
+  // unquoted `enabled: off` in forge.yaml is parsed as the plain string
+  // `"off"` (verified: `yq '.a.enabled' <<< 'a: {enabled: off}'` prints
+  // `off`, `... | type` prints `!!str`), which then survives
+  // `process.argv[3] === "false" ? false : process.argv[3]` unchanged and
+  // reaches this branch as the string `"off"`. Only `enabled: false`
+  // (unquoted) is coerced by `yq` to boolean `false` before this code
+  // runs. Do not remove this branch as unreachable dead code.
+  const disabled =
+    enabledRaw === false || (typeof enabledRaw === "string" && enabledRaw.trim().toLowerCase() === "off");
+  if (disabled) {
+    return { reResolve: false, reason: "orchestration.reresolve.enabled is off" };
+  }
+
+  if (typeof config.maxRounds === "number" && Number.isFinite(config.maxRounds) && roundsSoFar >= config.maxRounds) {
+    return {
+      reResolve: false,
+      reason: `orchestration.reresolve.max_rounds (${config.maxRounds}) reached — bounded termination`,
+    };
+  }
+
+  return {
+    reResolve: true,
+    reason: `query pattern "${classified.pattern}" is a standing predicate — re-resolving`,
+  };
+}
+
+/**
+ * Narrow a freshly re-resolved issue-number list down to genuinely new
+ * issues — ones not already present in the run's processed-issue registry
+ * (T0-resolved issues plus any already admitted in a prior re-resolution
+ * round). This function does NOT decide admission; every returned number
+ * (`newMatches`) must still be dispatched through the same path a
+ * T0-resolved issue takes — standard DAG dependency analysis followed by
+ * Step 4A/4B's dispatch (`phase-4-execution.md` Step 4B.6) — NOT through
+ * Step 4C's `admission.mjs`'s `evaluateCascadeFinding` chain, which is
+ * reserved for the cascade-spawned review-finding stream — see module
+ * docstring's "Hard invariant".
+ *
+ * @param {number[]} reResolvedNumbers - Issue numbers the query returned this round.
+ * @param {Iterable<number>} processedRegistry - Issue numbers already
+ *   resolved at T0 or admitted in an earlier re-resolution round this run.
+ * @returns {{ newMatches: number[], alreadyProcessed: number[] }}
+ */
+export function foldNewMatches(reResolvedNumbers, processedRegistry) {
+  const processed = new Set(processedRegistry);
+  const newMatches = [];
+  const alreadyProcessed = [];
+  const seenThisCall = new Set();
+
+  for (const n of reResolvedNumbers ?? []) {
+    if (seenThisCall.has(n)) continue; // de-dupe within the same re-resolution result
+    seenThisCall.add(n);
+    if (processed.has(n)) {
+      alreadyProcessed.push(n);
+    } else {
+      newMatches.push(n);
+    }
+  }
+
+  return { newMatches, alreadyProcessed };
+}

package/bin/engine/resolve.test.mjs

@@ -0,0 +1,149 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { classifyInputPattern, shouldReResolve, foldNewMatches } from "./resolve.mjs";
+
+describe("classifyInputPattern — literal sets", () => {
+  it("classifies bare issue numbers as literal", () => {
+    assert.deepEqual(classifyInputPattern("1 2 3"), {
+      kind: "literal",
+      pattern: "literal-numbers",
+      args: ["1", "2", "3"],
+    });
+  });
+
+  it("classifies #-prefixed issue numbers as literal", () => {
+    const r = classifyInputPattern("#1 #2 #3");
+    assert.equal(r.kind, "literal");
+    assert.equal(r.pattern, "literal-numbers");
+  });
+
+  it("classifies repo-prefixed literal numbers as literal", () => {
+    const r = classifyInputPattern("#123 mcp:5 n8n:12");
+    assert.equal(r.kind, "literal");
+    assert.equal(r.pattern, "literal-numbers");
+  });
+
+  it("classifies a single bare number as literal", () => {
+    const r = classifyInputPattern("42");
+    assert.equal(r.kind, "literal");
+  });
+});
+
+describe("classifyInputPattern — query patterns", () => {
+  it("classifies milestone <slug> as a query", () => {
+    const r = classifyInputPattern("milestone modular-pipeline-architecture");
+    assert.equal(r.kind, "query");
+    assert.equal(r.pattern, "milestone");
+    assert.deepEqual(r.args, ["modular-pipeline-architecture"]);
+  });
+
+  it("classifies next <N> as a query", () => {
+    const r = classifyInputPattern("next 5");
+    assert.equal(r.kind, "query");
+    assert.equal(r.pattern, "next-n");
+  });
+
+  it("classifies next <N> all-repos as a query", () => {
+    const r = classifyInputPattern("next 5 all-repos");
+    assert.equal(r.kind, "query");
+    assert.equal(r.pattern, "next-n-all-repos");
+  });
+
+  it("classifies fast-lane / fast as a query", () => {
+    assert.equal(classifyInputPattern("fast-lane").pattern, "fast-lane");
+    assert.equal(classifyInputPattern("fast").pattern, "fast-lane");
+    assert.equal(classifyInputPattern("fast-lane").kind, "query");
+  });
+
+  it("classifies priority:P0 / priority:P1 as a query (both label schemas, forge#2232)", () => {
+    assert.equal(classifyInputPattern("priority:P0").pattern, "priority");
+    assert.equal(classifyInputPattern("priority:P1").kind, "query");
+    assert.equal(classifyInputPattern("mcp:priority:P2").pattern, "priority");
+  });
+
+  it("classifies repo-scoped queries as a query", () => {
+    assert.equal(classifyInputPattern("mcp:fast").pattern, "repo-scoped");
+    assert.equal(classifyInputPattern("n8n:next 3").pattern, "repo-scoped");
+  });
+
+  it("classifies cascade/review-findings/findings as a query", () => {
+    assert.equal(classifyInputPattern("cascade").pattern, "cascade");
+    assert.equal(classifyInputPattern("review-findings").pattern, "cascade");
+    assert.equal(classifyInputPattern("findings --include-deferred").pattern, "cascade");
+  });
+
+  it("classifies a bare slug as a query", () => {
+    const r = classifyInputPattern("some-milestone-slug");
+    assert.equal(r.kind, "query");
+    assert.equal(r.pattern, "bare-slug");
+  });
+
+  it("classifies empty/unrecognized input as an unknown query, never literal", () => {
+    assert.equal(classifyInputPattern("").kind, "query");
+    assert.equal(classifyInputPattern("").pattern, "unknown");
+  });
+});
+
+describe("shouldReResolve", () => {
+  it("never re-resolves a literal set, regardless of config", () => {
+    const classified = { kind: "literal", pattern: "literal-numbers", args: ["1"] };
+    const r = shouldReResolve(classified, { enabled: true, maxRounds: 100 }, 0);
+    assert.equal(r.reResolve, false);
+    assert.match(r.reason, /never re-resolve/);
+  });
+
+  it("re-resolves a query pattern by default (no config)", () => {
+    const classified = { kind: "query", pattern: "priority", args: [] };
+    const r = shouldReResolve(classified);
+    assert.equal(r.reResolve, true);
+  });
+
+  it("respects an explicit off switch (boolean false)", () => {
+    const classified = { kind: "query", pattern: "fast-lane", args: [] };
+    const r = shouldReResolve(classified, { enabled: false });
+    assert.equal(r.reResolve, false);
+    assert.match(r.reason, /off/);
+  });
+
+  it("respects an explicit off switch (string 'off', case-insensitive)", () => {
+    const classified = { kind: "query", pattern: "fast-lane", args: [] };
+    assert.equal(shouldReResolve(classified, { enabled: "off" }).reResolve, false);
+    assert.equal(shouldReResolve(classified, { enabled: "OFF" }).reResolve, false);
+  });
+
+  it("bounds termination via maxRounds", () => {
+    const classified = { kind: "query", pattern: "milestone", args: [] };
+    assert.equal(shouldReResolve(classified, { maxRounds: 3 }, 2).reResolve, true);
+    const atLimit = shouldReResolve(classified, { maxRounds: 3 }, 3);
+    assert.equal(atLimit.reResolve, false);
+    assert.match(atLimit.reason, /max_rounds/);
+  });
+});
+
+describe("foldNewMatches", () => {
+  it("returns issues not already in the processed registry", () => {
+    const r = foldNewMatches([10, 11, 12], [10, 11]);
+    assert.deepEqual(r.newMatches, [12]);
+    assert.deepEqual(r.alreadyProcessed, [10, 11]);
+  });
+
+  it("is idempotent — re-running with an updated registry returns nothing new", () => {
+    const first = foldNewMatches([10, 11, 12], [10, 11]);
+    assert.deepEqual(first.newMatches, [12]);
+    const registryAfterFold = new Set([10, 11, ...first.newMatches]);
+    const second = foldNewMatches([10, 11, 12], registryAfterFold);
+    assert.deepEqual(second.newMatches, []);
+    assert.deepEqual(second.alreadyProcessed, [10, 11, 12]);
+  });
+
+  it("de-dupes duplicate numbers within the same re-resolution result", () => {
+    const r = foldNewMatches([5, 5, 6], []);
+    assert.deepEqual(r.newMatches, [5, 6]);
+  });
+
+  it("handles an empty re-resolution result", () => {
+    const r = foldNewMatches([], [1, 2, 3]);
+    assert.deepEqual(r.newMatches, []);
+    assert.deepEqual(r.alreadyProcessed, []);
+  });
+});

package/bin/engine/state.mjs

@@ -2,17 +2,33 @@
  * Codec for the single machine-readable FORGE:STATE HTML-comment block on an
  * issue body. Carries the COMPACT INDEX only (no rich per-phase outputs).
  */
+import {
+  escapeHtmlCommentDelimiters,
+  unescapeHtmlCommentDelimiters,
+} from "../../packages/protocol/src/html-comment-escape.js";
+
 const OPEN = "<!-- FORGE:STATE";
 const CLOSE = "-->";
 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
+  //   - "-->" 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).
+  //
+  // Delegated to the shared escapeHtmlCommentDelimiters() helper (forge#2225),
+  // which is also used by packages/protocol/src/emit.js's sanitizeFieldValue —
+  // this scheme previously had two hand-duplicated copies kept in sync only by
+  // cross-referencing code comments, and had already drifted once (forge#1638's
+  // fix landed here only after forge#2119). A single shared implementation
+  // removes that drift vector entirely.
+  const payload = escapeHtmlCommentDelimiters(JSON.stringify(index));
   return `${OPEN}\n${payload}\n${CLOSE}`;
 }
 
@@ -20,8 +36,16 @@ 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 — delegated to the shared
+  // unescapeHtmlCommentDelimiters() helper (forge#2225), same ordering
+  // rationale as packages/protocol/src/parse.js's unescapeFieldValue: closer
+  // forms restored first (most-specific "--!&gt;" before "--&gt;"), opener
+  // restored next, and "&amp;" -> "&" unescaped LAST so it never touches the
+  // "&" that is part of a just-restored "<!--"/"-->"/"--!>" sequence
+  // (forge#2137).
+  try {
+    return JSON.parse(unescapeHtmlCommentDelimiters(m[1].trim()));
+  } 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,103 @@ export function makeIo() {
 
 export function runDir() { return join(homedir(), ".forge", "runs"); }
 
+/**
+ * Sums the four token-usage fields across every `PHASE_COMMIT`/`PHASE_FAILED`
+ * run-log event that carries a non-null `usage` object. Mirrors the writer
+ * shape and `?? 0` accumulation convention used by `bin/engine.mjs:411,500`
+ * (`usage: outcome.usage ?? null`) and `bin/runner.mjs:1699-1723` (the
+ * canonical per-run accumulator) — same field names, same null-safe adds.
+ *
+ * Only `PHASE_COMMIT`/`PHASE_FAILED` events carry `usage`; other event types
+ * are skipped without inspecting their shape.
+ *
+ * @param {Array<object>} events - run-log events (from readLog())
+ * @returns {{input_tokens: number, output_tokens: number, cache_creation_input_tokens: number, cache_read_input_tokens: number} | null}
+ *   `null` when no event carried usage data (e.g. an all-CLI-backend run) —
+ *   callers MUST treat `null` as "omit the line", never substitute zeros
+ *   (a `0 tokens` line would misleadingly imply usage was measured and was
+ *   zero, rather than "not measured at all").
+ */
+export function aggregateUsage(events) {
+  let found = false;
+  const total = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+  for (const e of events) {
+    if (e.event !== "PHASE_COMMIT" && e.event !== "PHASE_FAILED") continue;
+    if (!e.usage || typeof e.usage !== "object") continue;
+    found = true;
+    total.input_tokens += e.usage.input_tokens ?? 0;
+    total.output_tokens += e.usage.output_tokens ?? 0;
+    total.cache_creation_input_tokens += e.usage.cache_creation_input_tokens ?? 0;
+    total.cache_read_input_tokens += e.usage.cache_read_input_tokens ?? 0;
+  }
+  return found ? total : null;
+}
+
+/**
+ * Renders a single usage-summary line from an `aggregateUsage()` result, or
+ * `""` when `usage` is `null` — callers must skip printing entirely in that
+ * case rather than print a placeholder/zero line.
+ * @param {{input_tokens:number, output_tokens:number, cache_creation_input_tokens:number, cache_read_input_tokens:number} | null} usage
+ * @returns {string}
+ */
+export function formatUsageLine(usage) {
+  if (!usage) return "";
+  return `  usage:   ${usage.input_tokens} in / ${usage.output_tokens} out (${usage.cache_read_input_tokens} cache-read / ${usage.cache_creation_input_tokens} cache-write)`;
+}
+
+/**
+ * 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, the aggregate
+ * per-run token usage (forge#2399 — omitted when no event carries usage
+ * data), 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}/${lastFailure.maxAttempts ?? 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}`);
+  const usageLine = formatUsageLine(aggregateUsage(events));
+  if (usageLine) lines.push(usageLine);
+  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
@@ -252,13 +349,52 @@ export async function runFromCli(argv, deps = {}) {
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
   const agentId = `cli_${process.pid}`;
-  const res = await runIssueFn({ issue, dir: runDir(), agentId, lane, io,
+  // Injectable for tests (forge#2175) — defaults to the real ~/.forge/runs dir.
+  const dir = deps.dir ?? runDir();
+  // forge#2240: print the run-log path at the very start of the run, not only
+  // in the non-merged completion diagnostics (formatTerminalDiagnostics prints
+  // it too, but only post-completion and only for non-"merged" outcomes). A
+  // caller tailing this process's stdout should be able to find the run-log
+  // to inspect immediately, without waiting for the run to finish.
+  console.log(`run-log: ${join(dir, `${issue}.jsonl`)}`);
+  // forge#2240: phase-boundary progress lines — the only stdout emitted
+  // during the run itself. `runIssue()`'s `onProgress` callback defaults to a
+  // no-op, so this is purely additive; engine.mjs never calls console.log
+  // directly (keeps it injectable/testable — see its onProgress param doc).
+  const onProgress = (e) => {
+    if (e.event === "phase_enter") console.log(`→ phase ${e.phase} started`);
+    else if (e.event === "phase_exit" && e.status === "committed") console.log(`✓ phase ${e.phase} committed`);
+    else if (e.event === "phase_exit" && e.status === "blocked") console.log(`✗ phase ${e.phase} blocked: ${e.detail ?? "no detail"}`);
+  };
+  const res = await runIssueFn({ issue, dir, agentId, lane, io,
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
+    onProgress,
     // 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));
+  } else {
+    // forge#2399: formatTerminalDiagnostics() (and its phase/reason/state
+    // block) intentionally stays gated to non-merged outcomes above, but the
+    // aggregate token-usage total should print for "total tokens per run" to
+    // hold on the common success case too — surface just the usage line here
+    // rather than the full diagnostic block.
+    try {
+      const usageLine = formatUsageLine(aggregateUsage(readLog(dir, issue)));
+      if (usageLine) console.log(usageLine);
+    } catch {
+      // Corrupt/unreadable log — degrade silently, same as formatTerminalDiagnostics.
+    }
+  }
   return res;
 }