forgedock 1.3.0 → 1.5.0

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/runlog.mjs

@@ -57,7 +57,7 @@ export function deriveState(events) {
   /** @type {import("./phases.mjs").RunState} */
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
-              terminalReason: null, lease: null };
+              terminalReason: null, lease: null, lastRateLimit: null };
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -72,6 +72,16 @@ export function deriveState(events) {
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
         break;
+      // forge#2524: a session-limit pause is purely informational — it does
+      // NOT touch committed/terminal/terminalReason. The phase that hit the
+      // pause is, by construction, not yet committed (the engine is about to
+      // retry it from scratch once the wait elapses), so a resumed/hydrated
+      // run correctly re-enters pickPhase at the same phase with no special
+      // casing needed here beyond recording the diagnostic below.
+      case "PHASE_RATE_LIMITED":
+        s.lastRateLimit = { phase: e.phase, resetAt: e.resetAt ?? null, waitMs: e.waitMs ?? null };
+        s.v = e.seq;
+        break;
       // PHASE_START / PHASE_FAILED do not change committed state
     }
   }

package/bin/engine/state.mjs

@@ -2,6 +2,11 @@
  * 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]*?)-->/;
@@ -12,25 +17,18 @@ export function serializeState(index) {
   // 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;");
+  // 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}`;
 }
 
@@ -38,21 +36,15 @@ export function serializeState(index) {
 export function parseState(issueBody) {
   const m = BLOCK_RE.exec(issueBody || "");
   if (!m) 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).
+  // 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(
-      m[1].trim()
-        .replace(/--(!?)&gt;/g, "--$1>")
-        .replace(/&lt;!--/g, "<!--")
-        .replace(/&amp;/g, "&"),
-    );
+    return JSON.parse(unescapeHtmlCommentDelimiters(m[1].trim()));
   } catch { return null; }
 }
 

package/bin/engine-cli.mjs

@@ -55,15 +55,60 @@ 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 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.
+ * `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
@@ -95,13 +140,15 @@ export function formatTerminalDiagnostics(dir, issue) {
     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(`  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");
 }
 
@@ -304,8 +351,30 @@ export async function runFromCli(argv, deps = {}) {
   const agentId = `cli_${process.pid}`;
   // 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"}`);
+    // forge#2524: session-limit pause — the engine is waiting in-process
+    // until the reported reset time before retrying this same phase, rather
+    // than terminating. Distinct glyph from the exit/blocked lines above so
+    // an operator tailing this stdout can tell "still alive, just waiting"
+    // from "phase actually failed".
+    else if (e.event === "phase_paused") console.log(`⏸ phase ${e.phase} paused: ${e.detail ?? "session limit"}`);
+  };
   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 } : {}),
@@ -319,6 +388,18 @@ export async function runFromCli(argv, deps = {}) {
   // 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;
 }