forgedock 1.16.2 → 1.17.0

package/bin/engine.mjs

@@ -4,6 +4,7 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import { createHash, scryptSync } from "node:crypto";
 import { hostname as osHostname, homedir } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
@@ -11,6 +12,7 @@ import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postC
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { VALID_BACKENDS } from "./runner.mjs";
+import { OUTCOME_CODES, UNCLASSIFIED, normalizeCode, codeForRunnerError, codeForTerminalReason } from "./engine/outcome-codes.mjs";
 
 // Exported (forge#2175) so bin/engine-cli.mjs can render "failed N/M attempts"
 // diagnostics without duplicating the retry budget constant.
@@ -297,6 +299,12 @@ export const MAX_RESUME_RATE_LIMIT_WAIT_MS = 6 * 60 * 60 * 1000;
  * @param {string} [opts.hostname] - injectable host name (tests).
  * @param {Function} [opts.killFn] - injectable `process.kill` (tests).
  */
+// forge#3824: stamped on RUN_START for per-release cost attribution; null when unreadable.
+export const ENGINE_VERSION = (() => {
+  try { return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || null; }
+  catch { return null; }
+})();
+
 export async function runIssue(opts) {
   const { issue, dir, agentId, lane = "staging", io, runner,
           now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
@@ -322,12 +330,23 @@ export async function runIssue(opts) {
           waitLease = false,
           hostname = osHostname(),
           killFn = process.kill.bind(process),
-          onProgress = () => {} } = opts;
+          onProgress = () => {},
+          // forge#3696: per-attempt telemetry seam (FORGE:TELEMETRY emitter, #3834). No-op by
+          // default; failures are swallowed so telemetry can never fail a phase.
+          emitTelemetry = () => {} } = opts;
 
   // forge#2452: extracted into makeProgressEmitter() — see its docstring for
   // the forge#2240 rationale this wrapper implements.
   const emitProgress = makeProgressEmitter(onProgress);
 
+  // forge#3833: one seam for coded outcome records that are not run-log phase events. Appends the
+  // event and forwards it to the telemetry hook (#3834 owns the FORGE:TELEMETRY writer), which can
+  // never fail the run.
+  const emitOutcome = async (rec) => {
+    appendEvent(dir, issue, rec);
+    try { await emitTelemetry?.({ ...rec, issue }); } catch { /* telemetry never fails a run */ }
+  };
+
   // forge#2452: extracted into validateRunIssueOptions() — see its docstring
   // for the forge#2054/#2313/#2329 rationale and required call-order (before
   // any state I/O or timer creation, unchanged from the inline block this
@@ -344,6 +363,7 @@ export async function runIssue(opts) {
     !isLeaseHolderDead({ by: r.lease.by, host: hostname, killFn }));
   const deferredResult = (r) => ({
     terminalReason: "deferred",
+    code: OUTCOME_CODES.LEASE_HELD,
     leaseUntil: r.lease.until,
     detail: `issue ${issue} leased by ${r.lease.by} until ${new Date(r.lease.until).toISOString()}`,
   });
@@ -370,16 +390,27 @@ export async function runIssue(opts) {
     remote = cur;
     ({ state, action } = reconcileState(local, remote));
   }
+  // forge#3824: hoisted so RUN_START can carry the repo (lazy, memoised; null when unresolved).
+  let repoPromise = null;
+  const resolveRepo = () => (repoPromise ??= (async () => {
+    if (repo) return String(repo).trim();
+    try {
+      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+      return String(out || "").trim() || null;
+    } catch { return null; }
+  })());
+
+  const runMeta = async () => ({ version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo: await resolveRepo().catch(() => null) });
   if (!state) {
     state = freshState(issue, lane);
-    appendEvent(dir, issue, { event: "RUN_START", issue, run: state.run, lane });
+    appendEvent(dir, issue, { event: "RUN_START", issue, run: state.run, lane, ...(await runMeta()) });
   } else if (action === "hydrate") {
     // GitHub is ahead of (or the only source of) local state. Rebuild the
     // local run-log to match the remote compact index so downstream
     // `deriveState(readLog(...))` calls stay consistent — otherwise the
     // post-commit re-derive below would fold over an empty/stale local log
     // and regress committed/issue/v (C2).
-    rewriteLog(dir, issue, eventsFromIndex(state));
+    rewriteLog(dir, issue, eventsFromIndex(state, await runMeta()));
     state = deriveState(readLog(dir, issue));
   }
 
@@ -494,14 +525,6 @@ export async function runIssue(opts) {
   // 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 repoPromise = null;
-  const resolveRepo = () => (repoPromise ??= (async () => {
-    if (repo) return String(repo).trim();
-    try {
-      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
-      return String(out || "").trim() || null;
-    } catch { return null; }
-  })());
 
   // forge#3574: a relaunch after a crash mid rate-limit pause must not re-run
   // the phase early. Same-host resume reads the LOCAL run-log's lastRateLimit
@@ -550,7 +573,7 @@ export async function runIssue(opts) {
          // forge#3512: investigate persists `invalid` on its own commit. Only when investigate is
          // the LAST committed phase: a later remediate/close commit carrying `invalid` is a handoff.
          (state.committed[state.committed.length - 1] === "investigate" && state.terminalReason === "invalid")))
-      return await terminate(state, state.terminalReason);
+      return await terminate(state, state.terminalReason, undefined, state.outcomeCode);
     // forge#2352: state-vs-GitHub divergence guard. Every phase's own
     // `entryCondition` only ever checked `state.committed` (local run-log
     // progress) — never the issue's live GitHub state/labels — so a phase
@@ -593,7 +616,7 @@ export async function runIssue(opts) {
         if (isDead) {
           const detail = `issue ${issue} is ${snap.state === "CLOSED" ? "closed" : "open"} ` +
             `with divergent state before phase ${phase.id} (labels: ${snap.labels.join(", ") || "none"})`;
-          return await terminate(state, "invalid", detail);
+          return await terminate(state, "invalid", detail, OUTCOME_CODES.INVALID);
         }
         // `needs-human` is a PAUSE, not a death sentence — a human may still
         // resolve it, and /orchestrate's classify_predecessor_state() already
@@ -699,7 +722,7 @@ export async function runIssue(opts) {
         let pauseCount = 0;
         for (;;) {
           try {
-            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId });
+            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry });
             break;
           } catch (e) {
             const resetAtMs = e.resetAtEpochMs;
@@ -788,7 +811,7 @@ export async function runIssue(opts) {
           // harmless idempotent safety net for the `throw e;` path.
           clearInterval(renewTimer);
           if (pendingRenewal) await pendingRenewal;
-          return await terminate(state, "engine-error", detail);
+          return await terminate(state, "engine-error", detail, codeForRunnerError(e));
         }
         throw e;
       } finally {
@@ -818,11 +841,12 @@ export async function runIssue(opts) {
       // PHASE_COMMIT would strand the PR (`deferred` is not --retry-able, and a committed remediate lets `close` run on
       // an unmerged PR). Release our lease and exit with nothing written; the next dispatch re-picks remediate.
       if (phase.id === "remediate" && outcome.reason === "deferred") {
-        await projector.writeState(issue, { ...state, lease: null });
-        return { terminalReason: "deferred", detail: outcome.detail };
+        await releaseLease(state);
+        await emitOutcome({ event: "PHASE_DEFERRED", phase: phase.id, code: normalizeCode(outcome.code), reason: outcome.detail });
+        return { terminalReason: "deferred", code: normalizeCode(outcome.code), detail: outcome.detail };
       }
       if (!isRemediationHandoff)
-        return await terminate(state, outcome.reason || "needs-human", outcome.detail);
+        return await terminate(state, outcome.reason || "needs-human", outcome.detail, outcome.code);
     } else {
       // committed
       // forge#2321: only report a phase_exit if a matching phase_enter was
@@ -854,11 +878,15 @@ export async function runIssue(opts) {
     // `decomposed`, remediate `merged`/`awaiting-merge`/`needs-human`). Persist them on the
     // commit event too, so a crash before RUN_TERMINAL or a rebuild cannot drop them.
     const commitReason = blockedReason ?? outcome.terminalReason ?? null;
+    // forge#3833: the handoff/blocked cause, persisted on the commit event like the reason.
+    const commitCode = commitReason ? normalizeCode(outcome.code ?? codeForTerminalReason(commitReason)) : null;
     appendEvent(dir, issue, {
-      event: "PHASE_COMMIT", phase: phase.id, outputs: commitOutputs, usage: outcome.usage ?? null,
+      event: "PHASE_COMMIT", phase: phase.id, outputs: commitOutputs,
+      // forge#3696: `usage` is cumulative over every attempt of the phase; the last attempt's alone is `last_attempt_usage`.
+      usage: outcome.usage ?? null, last_attempt_usage: outcome.last_attempt_usage ?? null,
       // forge#3589: model + turn count per phase (null when the backend does not report them).
       model: outcome.model ?? null, turns: outcome.turns ?? null,
-      ...(commitReason ? { terminalReason: commitReason } : {}),
+      ...(commitReason ? { terminalReason: commitReason, code: commitCode } : {}),
     });
     state = deriveState(readLog(dir, issue));
     const terminalReason = blockedReason ?? outcome.terminalReason;
@@ -890,29 +918,74 @@ export async function runIssue(opts) {
       outcome.outputs?.closeHandoff === true && terminalReason === "merged";
     if (terminalReason && TERMINAL_REASONS.includes(terminalReason) &&
         !isDecomposeHandoff && !isRemediationHandoff && !isCloseHandoff)
-      return await terminate(state, terminalReason, outcome.detail);
+      return await terminate(state, terminalReason, outcome.detail, commitCode);
     if (phase.isTerminalAfter && !isCloseHandoff && phase.isTerminalAfter(state))
       return await terminate(state, state.terminalReason || "merged");
   }
   return await terminate(state, state.terminalReason || "merged");
 
-  async function terminate(s, reason, detail) {
-    appendEvent(dir, issue, { event: "RUN_TERMINAL", reason });
-    const final = { ...deriveState(readLog(dir, issue)), terminal: true, terminalReason: reason, lease: null };
+  // Re-read remote state and return the lease another LIVE agent holds, if any. `undefined` = none;
+  // `null` = the read failed (unknown). Our stale in-memory snapshot must never overwrite a live
+  // holder's lease. Residual TOCTOU: projector.writeState has no CAS, so this narrows the window
+  // from a whole phase to one read/write round trip.
+  async function foreignLiveLease() {
+    try {
+      const r = await projector.readState(issue);
+      return leaseHeld(r) ? r.lease : undefined;
+    } catch { return null; }
+  }
+
+  // Guarded lease release (race: another engine claimed the lease after ours expired).
+  // Writes `lease: null` only when no other live agent holds it; on read failure, fail safe (skip).
+  async function releaseLease(s) {
+    if (await foreignLiveLease() !== undefined) return false;
+    await projector.writeState(issue, { ...s, lease: null });
+    return true;
+  }
+
+  async function terminate(s, reason, detail, code) {
+    // forge#3833: absent -> the reason's own code; unknown -> `unclassified` with the raw text kept in `detail`.
+    const outcomeCode = code == null ? codeForTerminalReason(reason) : normalizeCode(code);
+    appendEvent(dir, issue, { event: "RUN_TERMINAL", reason, code: outcomeCode,
+      ...(outcomeCode === UNCLASSIFIED && detail ? { detail } : {}) });
+    // forge#3835: forward the terminal record to the telemetry seam (best-effort, never fails the run).
+    try { await emitTelemetry?.({ event: "RUN_TERMINAL", reason, code: outcomeCode, issue }); } catch { /* telemetry never fails a run */ }
+    // The terminal write must always land; only the lease field is preserved when another live
+    // agent holds it. A failed read falls back to clearing (a lost terminal write would strand the issue).
+    const foreign = await foreignLiveLease();
+    const final = { ...deriveState(readLog(dir, issue)), terminal: true, terminalReason: reason, outcomeCode, lease: foreign ?? null };
     await projector.writeState(issue, final);
+    // forge#3566: the terminal projection must not leave a stranded `workflow:remediating`
+    // next to the terminal label. Best-effort: runs after the terminal write and never throws.
+    // forge#3876: skipped when another live engine holds the lease (it owns the labels); an unreadable lease (null) falls back to cleanup.
+    let wasRemediating = false;
+    if (foreign == null && (reason === "needs-human" || reason === "engine-error")) {
+      try {
+        const lv = JSON.parse(await io.gh(["issue", "view", String(issue), "--json", "labels"]));
+        wasRemediating = (lv?.labels ?? []).some((l) => (typeof l === "string" ? l : l?.name) === "workflow:remediating");
+      } catch { /* unreadable: treat as not remediating */ }
+      try { await projector.removeLabel(issue, "workflow:remediating"); }
+      catch { /* best-effort: a transient label failure must not lose the terminal state */ }
+    }
     if (reason === "needs-human") await projector.setLabel(issue, "needs-human");
     // forge#2261: a distinct label for engine/tool-level failures (broken CLI
     // invocation, exhausted retries where the runner itself never once
     // succeeded) — NOT needs-human. /orchestrate's classify_predecessor_state()
     // (commands/orchestrate/phase-4-execution.md) must not treat this as GATED:
     // there is no human decision pending, just a tool that needs to be re-run.
-    else if (reason === "engine-error") await projector.setLabel(issue, "workflow:engine-error");
-    return { terminalReason: reason, detail };
+    else if (reason === "engine-error") {
+      await projector.setLabel(issue, "workflow:engine-error");
+      // A crashed remediate has no human signal otherwise (remediate.md Stranded-state rule).
+      if (wasRemediating) {
+        try { await projector.setLabel(issue, "needs-human"); } catch { /* best-effort */ }
+      }
+    }
+    return { terminalReason: reason, code: outcomeCode, detail };
   }
 }
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId } = ctx;
+  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry } = ctx;
   // forge#3499: build the phase's full argument set ONCE, up front. Every
   // work-on phase sub-skill stops with BLOCKED when a required flag is absent,
   // so an incomplete/invalid set is a deterministic engine failure — fail
@@ -924,8 +997,8 @@ async function runPhaseWithRetry(phase, state, ctx) {
   } catch (e) {
     if (e?.code !== "PHASE_ARGS_INVALID") throw e;
     const detail = `phase ${phase.id} args unresolved: ${e.message}`;
-    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt: 0, reason: detail, maxAttempts });
-    return { status: "blocked", detail, reason: "engine-error", usage: null };
+    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt: 0, reason: detail, code: OUTCOME_CODES.ENGINE_ERROR, maxAttempts });
+    return { status: "blocked", detail, reason: "engine-error", code: OUTCOME_CODES.ENGINE_ERROR, usage: null };
   }
   // forge#2261: true only if EVERY attempt failed by the runner itself
   // throwing (never once reached phase.detectOutcome()). This is the signal
@@ -936,6 +1009,8 @@ async function runPhaseWithRetry(phase, state, ctx) {
   // Flips to false the instant any attempt's runner() call succeeds, even if
   // that attempt's detectOutcome() itself reports failure.
   let allAttemptsThrew = true;
+  // forge#3833: code of the most recent failed attempt (an attempt whose runner threw counts as engine.error).
+  let lastCode = UNCLASSIFIED;
   // forge#2377: the last successful attempt's `usage` (from runner()'s ==
   // runCommand()'s resolved value — {input_tokens, output_tokens,
   // cache_creation_input_tokens, cache_read_input_tokens} on the API
@@ -945,9 +1020,28 @@ async function runPhaseWithRetry(phase, state, ctx) {
   // attempt (if any) set it to, which is correct: it always reflects the
   // most recent attempt that actually produced a result.
   let lastUsage = null;
+  // forge#3696: usage summed over every attempt (null if none reported usage — never 0).
+  let cumulativeUsage = null;
+  const addUsage = (u) => {
+    if (!u || typeof u !== "object") return;
+    cumulativeUsage ??= { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+    for (const k of Object.keys(cumulativeUsage)) cumulativeUsage[k] += Number.isFinite(u[k]) ? u[k] : 0;
+  };
+  // One PHASE_ATTEMPT_USAGE event per attempt (null for anything unreported), then the
+  // telemetry seam, which must never throw into the phase.
+  const recordAttempt = async (attempt, usage, t0, extra) => {
+    const rec = {
+      event: "PHASE_ATTEMPT_USAGE", phase: phase.id, attempt,
+      usage: usage ?? null, duration_ms: Math.round(performance.now() - t0),
+      cost_usd: extra?.cost_usd ?? null, model: extra?.model ?? null, turns: extra?.turns ?? null,
+    };
+    appendEvent(dir, issue, rec);
+    try { await emitTelemetry?.({ ...rec, issue }); } catch { /* telemetry never fails a phase */ }
+  };
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     appendEvent(dir, issue, { event: "PHASE_START", phase: phase.id, attempt });
     let result;
+    const t0 = performance.now();
     try {
       result = await runner({
         commandsDir, commandName: phase.command, args: phaseArgs,
@@ -978,8 +1072,10 @@ async function runPhaseWithRetry(phase, state, ctx) {
       // NOT a commit: record the exhausted attempt, then rethrow so runIssue terminates
       // `engine-error` with no PHASE_COMMIT — `--retry` then re-enters this same phase.
       if (e.code === "CLI_MAX_TURNS") {
+        addUsage(e.usage);
+        await recordAttempt(attempt, e.usage, t0, { turns: e.numTurns });
         appendEvent(dir, issue, {
-          event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, maxAttempts,
+          event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts,
           turns: e.numTurns ?? null, usage: e.usage ?? null,
         });
         throw e;
@@ -990,7 +1086,9 @@ async function runPhaseWithRetry(phase, state, ctx) {
       // Do not fabricate a value; omitting the field (rather than a stale
       // `lastUsage` from a prior attempt) keeps this event's usage
       // trustworthy as "usage actually observed on this attempt".
-      appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, maxAttempts });
+      await recordAttempt(attempt, null, t0, null);
+      appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts });
+      lastCode = OUTCOME_CODES.ENGINE_ERROR;
       continue;
     }
     allAttemptsThrew = false;
@@ -998,9 +1096,11 @@ async function runPhaseWithRetry(phase, state, ctx) {
     // forge#3589: model/turns recorded alongside usage (additive; null when absent).
     const lastModel = result?.cliModel ?? result?.model ?? null;
     const lastTurns = result?.turns ?? null;
+    addUsage(lastUsage);
+    await recordAttempt(attempt, lastUsage, t0, { cost_usd: result?.costUsd ?? null, model: lastModel, turns: lastTurns });
     const outcome = await phase.detectOutcome(state, io, result);
-    if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: lastUsage, model: lastModel, turns: lastTurns };
-    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, maxAttempts, usage: lastUsage, model: lastModel, turns: lastTurns });
+    if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: cumulativeUsage, last_attempt_usage: lastUsage, model: lastModel, turns: lastTurns };
+    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, code: normalizeCode(outcome.code), maxAttempts, usage: lastUsage, model: lastModel, turns: lastTurns });
     // 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
@@ -1011,11 +1111,12 @@ async function runPhaseWithRetry(phase, state, ctx) {
     // 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).
+    lastCode = normalizeCode(outcome.code);
     if (outcome.retryable === false) {
       // forge#3521: keep outcome.outputs (e.g. the PR number) for persistence and
       // forward `handoff` so only an explicit opt-in escalation is honoured; a
       // no-signal failure carries no handoff and stops at needs-human.
-      return { status: "blocked", detail: outcome.detail, outputs: outcome.outputs, handoff: outcome.handoff, usage: lastUsage };
+      return { status: "blocked", detail: outcome.detail, outputs: outcome.outputs, handoff: outcome.handoff, code: lastCode, usage: cumulativeUsage, last_attempt_usage: lastUsage };
     }
   }
   // Exhausted transient retries → escalate (spec §7).
@@ -1033,18 +1134,22 @@ async function runPhaseWithRetry(phase, state, ctx) {
       status: "blocked",
       detail: `phase ${phase.id} failed after ${maxAttempts} attempts (runner threw every attempt)`,
       reason: "engine-error",
+      code: OUTCOME_CODES.ENGINE_ERROR,
       usage: null,
     };
   }
-  return { status: "blocked", detail: `phase ${phase.id} failed after ${maxAttempts} attempts`, usage: lastUsage };
+  return { status: "blocked", detail: `phase ${phase.id} failed after ${maxAttempts} attempts`, code: lastCode, usage: cumulativeUsage, last_attempt_usage: lastUsage };
 }
 
 /**
  * Build a run-log event sequence that reproduces a compact FORGE:STATE index,
  * used to reconstruct the local run-log on hydrate (C2).
  */
-function eventsFromIndex(idx) {
-  const events = [{ event: "RUN_START", issue: idx.issue, run: idx.run, lane: idx.lane }];
+function eventsFromIndex(idx, meta = {}) {
+  // forge#3824: `hydrated` marks a reconstructed log (no usage data) so cost-report can exclude it.
+  const events = [{ event: "RUN_START", issue: idx.issue, run: idx.run, lane: idx.lane,
+                    version: meta.version ?? null, forge_version: meta.forge_version ?? meta.version ?? null,
+                    repo: meta.repo ?? null, hydrated: true }];
   for (const phase of idx.committed) {
     const outputs = {};
     if (phase === "build" && idx.branch) outputs.branch = idx.branch;
@@ -1057,15 +1162,15 @@ function eventsFromIndex(idx) {
   // would terminate the run. Nothing to attach it to when no phase is committed.
   if (!idx.terminal && idx.terminalReason && idx.committed.length > 0) {
     for (let i = events.length - 1; i >= 0; i--) {
-      if (events[i].event === "PHASE_COMMIT") { events[i].terminalReason = idx.terminalReason; break; }
+      if (events[i].event === "PHASE_COMMIT") { events[i].terminalReason = idx.terminalReason; if (idx.outcomeCode) events[i].code = idx.outcomeCode; break; }
     }
   }
-  if (idx.terminal) events.push({ event: "RUN_TERMINAL", reason: idx.terminalReason });
+  if (idx.terminal) events.push({ event: "RUN_TERMINAL", reason: idx.terminalReason, code: normalizeCode(idx.outcomeCode ?? codeForTerminalReason(idx.terminalReason)) });
   return events;
 }
 
 function freshState(issue, lane) {
   return { v: 0, run: `r_${issue}_${lane}`, issue, lane, committed: [], phase: null,
            branch: null, pr: null, terminal: false, terminalReason: null, lease: null,
-           lastRateLimit: null };
+           lastRateLimit: null, outcomeCode: null };
 }

package/bin/forgedock.mjs

@@ -3214,6 +3214,7 @@ function help() {
     ["npx forgedock config migrate [dir]", "Backfill missing optional sections into an existing forge.yaml (idempotent)"],
     ["npx forgedock watch [--repo owner/repo]", "Live per-agent orchestration view (Ctrl+C to exit)"],
     ["npx forgedock report [--days 30] [--md] [--json]", "30-day pipeline impact receipts for your repo"],
+    ["npx forgedock stats [--since <ver|date>] [--repo owner/repo] [--json] [--refresh]", "Version-over-version cost/time/flow/review/gate report from GitHub telemetry (no model)"],
     ["npx forgedock doctor", "Check installation health"],
     ["npx forgedock doctor --fix", "Auto-fix deterministic issues (symlinks, hook, labels, legacy block)"],
     ["npx forgedock update", "Pull latest & reinstall"],
@@ -3783,7 +3784,7 @@ async function watch() {
 const SPLASH_COMMANDS = new Set(["run", "run-issue", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "backend-check", "run-issue", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "help", "--help", "-h",
+  "run", "backend-check", "run-issue", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4003,6 +4004,11 @@ switch (command) {
     await runReport(restArgs);
     break;
   }
+  case "stats": {
+    const { runStats } = await import("./stats/index.mjs");
+    exitCode = await runStats(restArgs);
+    break;
+  }
   case "watch":
     await watch();
     break;

package/bin/hooks/interactive-engine.mjs

@@ -66,6 +66,7 @@ import { dirname, join, resolve } from "path";
 import { existsSync, readFileSync } from "fs";
 import { execFileSync } from "child_process";
 import { PHASE_MARKERS as PHASE_MARKER_REGISTRY } from "../../packages/protocol/src/phases.js";
+import { normalizeCode, codeForTerminalReason } from "../engine/outcome-codes.mjs";
 
 // ---------------------------------------------------------------------------
 // Bootstrap
@@ -236,11 +237,18 @@ async function main() {
   if (freshLog.length && deriveState(freshLog).committed.includes(phaseId)) return;
 
   if (bootstrapped) {
+    // forge#3824: attribute the run to a release and repo (best-effort; null when unavailable).
+    let version = null, repo = null;
+    try { version = JSON.parse(readFileSync(join(FORGE_HOME, "package.json"), "utf8")).version || null; } catch { /* fail-soft */ }
+    try { repo = String(await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]) || "").trim() || null; } catch { /* fail-soft */ }
     appendEvent(runLogDir, issueNumber, {
       event: "RUN_START",
       issue: issueNumber,
       run: state.run,
       lane: state.lane,
+      version,
+      forge_version: version,
+      repo,
       source: "interactive",
     });
   }
@@ -258,6 +266,8 @@ async function main() {
     appendEvent(runLogDir, issueNumber, {
       event: "RUN_TERMINAL",
       reason: terminalReason,
+      // forge#3833: same closed enum as the headless engine (absent -> the reason's own code).
+      code: normalizeCode(outcome.code ?? codeForTerminalReason(terminalReason)),
       source: "interactive",
     });
     state = deriveState(readLog(runLogDir, issueNumber));