forgedock 1.16.2 → 1.17.0

package/bin/engine/outcome-codes.mjs

@@ -0,0 +1,92 @@
+/**
+ * Closed, versioned enum of engine outcome codes (forge#3833).
+ *
+ * Every PHASE_FAILED, blocked PHASE_COMMIT and RUN_TERMINAL run-log event carries
+ * one `code` from this enum so stall causes can be counted and grouped without a
+ * model reading prose. Codes are derived in code from structured evidence
+ * (REVIEW_RESULT fields, FORGE markers, `err.code`), never from free-text `detail`.
+ * The free-text `reason`/`detail` stays alongside for humans. Documented in
+ * docs/OUTCOME-CODES.md (a test asserts enum/doc parity). Pure module: no I/O.
+ */
+
+/** Bump when a code is renamed or removed; adding a code is additive. */
+export const OUTCOME_CODES_VERSION = 1;
+
+/** Fallback for an absent or unknown code; the raw reason is kept alongside. */
+export const UNCLASSIFIED = "unclassified";
+
+export const OUTCOME_CODES = Object.freeze({
+  REVIEW_CHANGES_REQUESTED: "review.changes_requested",
+  REVIEW_ESCALATED: "review.escalated",
+  REVIEW_REREVIEW_SKIPPED: "review.rereview_skipped",
+  BUILD_ACCEPTANCE_FAILED: "build.acceptance_failed",
+  BUILD_ACCEPTANCE_MALFORMED: "build.acceptance_malformed",
+  BUILD_SIZE_OVER_GATE: "build.size_over_gate",
+  BUILD_COHESIVE: "build.cohesive",
+  REMEDIATE_NO_MARKER: "remediate.no_marker",
+  REMEDIATE_DEFERRED_LIVE_RUN: "remediate.deferred_live_run",
+  REMEDIATE_RE_ESCALATED: "remediate.re_escalated",
+  REMEDIATE_UNFIXABLE: "remediate.unfixable",
+  CI_RED: "ci.red",
+  CI_TIMEOUT: "ci.timeout",
+  BASE_CONFLICT: "base.conflict",
+  RATE_LIMITED: "rate_limited",
+  ENGINE_ERROR: "engine.error",
+  LEASE_HELD: "lease.held",
+  INVALID: "invalid",
+  DECOMPOSED: "decomposed",
+  // Non-failure terminals, so a RUN_TERMINAL for a healthy run is not counted as a gap.
+  COMPLETED: "completed",
+  AWAITING_MERGE: "awaiting_merge",
+  UNCLASSIFIED,
+});
+
+const CODE_SET = new Set(Object.values(OUTCOME_CODES));
+
+/** Every code, in declaration order. */
+export const ALL_OUTCOME_CODES = Object.freeze([...CODE_SET]);
+
+export function isOutcomeCode(code) {
+  return typeof code === "string" && CODE_SET.has(code);
+}
+
+/** Absent or unknown -> `unclassified`; never throws. */
+export function normalizeCode(code) {
+  return isOutcomeCode(code) ? code : UNCLASSIFIED;
+}
+
+/** Code for a thrown runner error, from `err.code` / session-limit evidence only. */
+export function codeForRunnerError(err) {
+  if (!err || typeof err !== "object") return UNCLASSIFIED;
+  if (err.usageLimit === true || (typeof err.resetAtEpochMs === "number" && Number.isFinite(err.resetAtEpochMs)))
+    return OUTCOME_CODES.RATE_LIMITED;
+  switch (err.code) {
+    case "NO_API_KEY":
+    case "NO_SDK":
+    case "CLI_BACKEND_FAILED":
+    case "PHASE_ARGS_INVALID":
+    case "CLI_MAX_TURNS":
+      return OUTCOME_CODES.ENGINE_ERROR;
+    default:
+      return UNCLASSIFIED;
+  }
+}
+
+/**
+ * Default code for a terminal reason when the producer supplied none. Only reasons that
+ * name one cause map; `needs-human` has many causes, so it stays `unclassified`.
+ */
+export function codeForTerminalReason(reason) {
+  switch (reason) {
+    case "merged":
+    case "phase-complete":
+    case "investigation":
+      return OUTCOME_CODES.COMPLETED;
+    case "awaiting-merge": return OUTCOME_CODES.AWAITING_MERGE;
+    case "invalid": return OUTCOME_CODES.INVALID;
+    case "decomposed": return OUTCOME_CODES.DECOMPOSED;
+    case "engine-error": return OUTCOME_CODES.ENGINE_ERROR;
+    case "deferred": return OUTCOME_CODES.LEASE_HELD;
+    default: return UNCLASSIFIED;
+  }
+}

package/bin/engine/phases.mjs

@@ -12,6 +12,8 @@
 // imports the identical registry, so the two can no longer drift apart the way
 // they did in forge#2375/PR#2395.
 import { PHASE_MARKERS } from "../../packages/protocol/src/phases.js";
+// forge#3833: closed outcome-code enum; every code below comes from structured evidence, never `detail` prose.
+import { OUTCOME_CODES as OC } from "./outcome-codes.mjs";
 
 // forge#2261: "engine-error" is a distinct terminal reason for engine/tool-level
 // failures (e.g. an exhausted retry loop where the runner itself never once
@@ -48,12 +50,22 @@ export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed
  */
 export function isTrustedComment(c) {
   if (!c || typeof c !== "object") return false;
+  return isTrustedActor({ association: c.author_association, type: c.user?.type, login: c.user?.login });
+}
+
+/**
+ * The ONE actor predicate behind `isTrustedComment` and the issue-body
+ * FORGE:STATE gate (projector). `association` is the GitHub author association,
+ * `type` the actor's `__typename`/`user.type` ("Bot", "User"...), `login` its
+ * login. Missing fields fail closed.
+ */
+export function isTrustedActor({ association, type, login } = {}) {
   const list = (v) => String(v).split(",").map((x) => x.trim()).filter(Boolean);
   const assoc = list(process.env.FORGE_TRAIL_TRUSTED_ASSOCIATIONS ?? "OWNER,MEMBER,COLLABORATOR");
   const logins = list(process.env.FORGE_TRAIL_TRUSTED_LOGINS ?? "");
-  return assoc.includes(c.author_association ?? "")
-    || (c.user?.type ?? "") === "Bot"
-    || logins.includes(c.user?.login ?? "");
+  return assoc.includes(association ?? "")
+    || (type ?? "") === "Bot"
+    || logins.includes(login ?? "");
 }
 
 /**
@@ -99,6 +111,8 @@ async function issueMarkers(issue, io) {
 const REMEDIATION_HELD_MARKER = "FORGE:REMEDIATION_HELD";
 /** Non-terminal deferral record (remediate.md Phase M0 liveness step): a live earlier run holds the lease. Never a COMPLETE/trail marker. */
 const REMEDIATION_DEFERRED_MARKER = "FORGE:REMEDIATION_DEFERRED";
+/** Per-dispatch record the engine posts on every remediate dispatch (forge#3807): scopes a DEFERRED record to its own dispatch. Never a COMPLETE/trail marker. */
+const REMEDIATION_DISPATCH_MARKER = "FORGE:REMEDIATION_DISPATCH";
 /** Lease holder ids the engine mints (`cli_<host>_<pid>`) are passed to remediate only when they match this shape (same as remediate-liveness.sh). */
 const LEASE_HOLDER_RE = /^[A-Za-z0-9._-]{1,128}$/;
 const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -186,15 +200,32 @@ export async function postCycleMarker(issue, n, io) {
  * ALREADY_DONE when the newest gate marker is blocked (forge#3725).
  */
 function latestGateState(comments) {
+  return latestGateMarker(comments).state;
+}
+/**
+ * Single newest-first scan shared by latestGateState and latestBlockedIndex so their
+ * predicates cannot drift. Returns the newest gate marker's state and its comment index
+ * (`{state: "none", index: -1}` when there is none).
+ */
+function latestGateMarker(comments) {
   const gate = "FORGE:ACCEPTANCE_GATE";
   for (let i = comments.length - 1; i >= 0; i--) {
     const b = comments[i];
-    if (startsWithHeader(b, "FORGE:BUILD_BLOCKED")) return "blocked";
+    if (startsWithHeader(b, "FORGE:BUILD_BLOCKED")) return { state: "blocked", index: i };
     if (!startsWithHeader(b, gate)) continue;
-    if (hasSentinelLine(b, `${gate}:PASSED`)) return "pass";
-    if (hasSentinelLine(b, `${gate}:FAILED`) || hasSentinelLine(b, `${gate}:BLOCKED`)) return "blocked";
+    if (hasSentinelLine(b, `${gate}:PASSED`)) return { state: "pass", index: i };
+    if (hasSentinelLine(b, `${gate}:FAILED`) || hasSentinelLine(b, `${gate}:BLOCKED`)) return { state: "blocked", index: i };
   }
-  return "none";
+  return { state: "none", index: -1 };
+}
+/**
+ * Comment index of the newest blocked gate marker, or -1 when the newest gate marker is
+ * not blocked (a newer PASSED clears it). Recency anchor for build.detectOutcome so an
+ * older blocked marker cannot shadow a strictly newer size-gate routing marker.
+ */
+function latestBlockedIndex(comments) {
+  const m = latestGateMarker(comments);
+  return m.state === "blocked" ? m.index : -1;
 }
 /**
  * Investigation exit evidence (forge#3534): a trusted comment led by
@@ -265,18 +296,22 @@ function overrideHasJustification(body) {
  * chronological order (see trustedCommentBodies); an untrusted comment never
  * reaches this function.
  */
-function sizeGateRoutesToDecompose(comments) {
+function sizeGateRouteIndex(comments) {
   const gate = PHASE_MARKERS.build.sizeGateMarker;
   const override = PHASE_MARKERS.build.sizeOverrideMarker;
   const starts = (c, m) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${m}`);
-  if (comments.some((c) => starts(c, "FORGE:DECOMPOSED"))) return false;
+  if (comments.some((c) => starts(c, "FORGE:DECOMPOSED"))) return -1;
   let idx = -1;
   for (let i = comments.length - 1; i >= 0; i--) if (starts(comments[i], gate)) { idx = i; break; }
-  if (idx < 0) return false;
+  if (idx < 0) return -1;
   const body = comments[idx].replace(/\r\n/g, "\n");
   const m = /^result:[ \t]*(OK|OVERRIDDEN|COHESIVE|OVER)[ \t]*$/m.exec(body);
-  if (!m || m[1] !== "OVER" || !/^###[ \t]+Split Proposal\b/m.test(body)) return false;
-  return !comments.slice(idx + 1).some((c) => starts(c, override) && overrideHasJustification(c));
+  if (!m || m[1] !== "OVER" || !/^###[ \t]+Split Proposal\b/m.test(body)) return -1;
+  return comments.slice(idx + 1).some((c) => starts(c, override) && overrideHasJustification(c)) ? -1 : idx;
+}
+/** Boolean form of sizeGateRouteIndex (index of the routing DIFF_SIZE comment, or -1). */
+function sizeGateRoutesToDecompose(comments) {
+  return sizeGateRouteIndex(comments) >= 0;
 }
 /**
  * Decompose loop guard (mirrors build.md B5.5 and decompose.md Guard 1). Returns a
@@ -625,7 +660,7 @@ export const PHASES = [
       const invalid = `<!-- ${PHASE_MARKERS.investigate.invalidMarker} -->`;
       const complete = `<!-- ${PHASE_MARKERS.investigate.completionMarker} -->`;
       if (closing === invalid)
-        return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
+        return { status: "committed", terminalReason: "invalid", code: OC.INVALID, outputs: { verdict: "INVALID" } };
       if (closing === complete) {
         // investigate.md emits `### Decomposition Assessment` then `**YES**|**NO**`.
         if (isDecomposed(report)) {
@@ -636,7 +671,7 @@ export const PHASES = [
             console.error(`[engine] decompose suppressed for #${state.issue}: ${guard}; treating as not decomposed`);
             return { status: "committed", outputs: { verdict: "CONFIRMED" } };
           }
-          return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
+          return { status: "committed", terminalReason: "decomposed", code: OC.DECOMPOSED, outputs: { decompose: true } };
         }
         return { status: "committed", outputs: { verdict: "CONFIRMED" } };
       }
@@ -665,7 +700,7 @@ export const PHASES = [
     async detectOutcome(state, io) {
       const { comments } = await issueMarkers(state.issue, io);
       if (hasMarker(comments, PHASE_MARKERS.decompose.header, PHASE_MARKERS.decompose.completionMarker))
-        return { status: "committed", terminalReason: "decomposed", outputs: {} };
+        return { status: "committed", terminalReason: "decomposed", code: OC.DECOMPOSED, outputs: {} };
       return { status: "failed", detail: `no ${PHASE_MARKERS.decompose.completionMarker} marker` };
     },
     // Always terminal: decomposition spawns independent sub-issues, each of
@@ -722,8 +757,15 @@ export const PHASES = [
       // review. Non-retryable: a retry would only re-read the same append-only markers.
       // A newer PASSED clears this: either the in-build repair loop posts it, or a fresh
       // build invocation does via build.md B0 gate resume (re-enters B6.5; forge#3725).
+      // forge#3712: an OVER + Split Proposal size-gate marker STRICTLY NEWER (comment order)
+      // than the newest blocked marker is the retry's real outcome; route to decompose.
+      // Equal/absent index stays fail-closed, as does a newer blocked marker.
+      if (!complete && latestGateState(comments) === "blocked" && mayRouteToDecompose(comments)
+          && sizeGateRouteIndex(comments) > latestBlockedIndex(comments)) {
+        return { status: "committed", terminalReason: "decomposed", code: OC.BUILD_SIZE_OVER_GATE, outputs: branch ? { branch } : {} };
+      }
       if (latestGateState(comments) === "blocked") {
-        return { status: "failed", detail: `acceptance gate blocked (builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"})`, retryable: false };
+        return { status: "failed", detail: `acceptance gate blocked (builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"})`, code: OC.BUILD_ACCEPTANCE_FAILED, retryable: false };
       }
       if (complete && ahead > 0) {
         return { status: "committed", outputs: { branch, ...buildChildEvidence(comments) } };
@@ -739,7 +781,7 @@ export const PHASES = [
       // needs-human. Non-retryable by construction: a retry re-measures and
       // re-emits the same exit.
       if (!complete && mayRouteToDecompose(comments) && sizeGateRoutesToDecompose(comments)) {
-        return { status: "committed", terminalReason: "decomposed", outputs: branch ? { branch } : {} };
+        return { status: "committed", terminalReason: "decomposed", code: OC.BUILD_SIZE_OVER_GATE, outputs: branch ? { branch } : {} };
       }
       const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
       // forge#2176: when the builder has already posted FORGE:BUILDER:COMPLETE
@@ -803,7 +845,7 @@ export const PHASES = [
       // The PR number from GitHub (openPrFor) always wins over parsed text.
       const outputs = { pr: pr.number };
       // Opt-in: only an explicit escalation signal sets handoff:true. A PR number alone never hands off.
-      const escalated = { status: "blocked", detail: "review escalated", outputs, handoff: true };
+      const escalated = { status: "blocked", detail: "review escalated", outputs, handoff: true, code: OC.REVIEW_ESCALATED };
       const rr = parseReviewResult(result?.text);
       // forge#3530: carry the review's remediation kind (router Phase 4R parity) so the
       // remediate phase can post the matching bound marker. Untrusted model output: only
@@ -812,7 +854,7 @@ export const PHASES = [
       if (rr && rr.status === "NEXT" && rr.next === "remediate" && rr.remediation)
         outputs.remediation = isRemediationKind(rr.remediation) ? rr.remediation : "unknown";
       if (pr.needsHuman || pr.remediating) return escalated;
-      if (rr && rr.status === "NEXT" && rr.next === "remediate") return escalated;
+      if (rr && rr.status === "NEXT" && rr.next === "remediate") return { ...escalated, code: OC.REVIEW_CHANGES_REQUESTED };
       // An explicit REVIEW_RESULT status is authoritative: BLOCKED/COMPLETE exits
       // (phase trail, ci gate, base conflict, merge refusal) also label the issue
       // needs-human but are NOT remediation handoffs, so skip the label fallback.
@@ -854,7 +896,17 @@ export const PHASES = [
       // Legacy handoff with no kind (needs-human label fallback, or no REVIEW_RESULT): there
       // is nothing to bind, so dispatch as before. remediate.md M0 then applies its default
       // single-attempt guard. A present-but-unknown kind is never dispatched.
-      if (kind === null) return legacyArgs();
+      // forge#3807: every dispatch (kind-bound or legacy) posts a dispatch marker AFTER the bound marker,
+      // never deduped, so detectOutcome can tell a stale deferral from an earlier dispatch from this one's.
+      const postDispatchMarker = async () => {
+        try {
+          await io.gh(["issue", "comment", String(state.issue), "--body",
+            `<!-- ${REMEDIATION_DISPATCH_MARKER}: pr=${pr} -->\nEngine dispatching remediation for PR #${pr}.`]);
+        } catch (e) {
+          throw new PhaseArgsError(`github-unavailable: could not post ${REMEDIATION_DISPATCH_MARKER}; remediation not invoked (${e?.message || e})`);
+        }
+      };
+      if (kind === null) { await postDispatchMarker(); return legacyArgs(); }
       if (!isRemediationKind(kind))
         throw new PhaseArgsError(`unknown remediation kind: ${JSON.stringify(kind)}`);
       const boundMarker = REMEDIATION_BOUND_MARKERS[kind];
@@ -870,6 +922,7 @@ export const PHASES = [
       } catch (e) {
         throw new PhaseArgsError(`github-unavailable: could not post FORGE:${boundMarker}; remediation not invoked (${e?.message || e})`);
       }
+      await postDispatchMarker();
       return legacyArgs();
     },
     entryCondition: (s) => s.committed.includes("review") && s.terminalReason === "needs-human",
@@ -935,16 +988,20 @@ export const PHASES = [
         // lease that expired since is the NEXT dispatch's business). Only a trusted, full-line record for THIS
         // PR counts, and only while it is newer than every `FORGE:REMEDIATION` trail comment: a later run
         // that proceeded posts one, which retires the deferral.
-        let deferredAt = -1, trailAt = -1, deferred = null;
+        // forge#3807: a deferral older than this dispatch's marker is stale (a later dispatch proceeded and
+        // crashed before posting a trail), so it is a failed attempt. No marker (older runs) => dispatchAt -1.
+        let deferredAt = -1, trailAt = -1, dispatchAt = -1, deferred = null;
+        const dispatchSentinel = `${REMEDIATION_DISPATCH_MARKER}: pr=${state.pr}`;
         scoped.forEach((b, i) => {
+          if (state.pr != null && hasSentinelLine(b, dispatchSentinel)) dispatchAt = i;
           if (startsWithHeader(b, REMEDIATION_DEFERRED_MARKER) && hasSentinelLine(b, REMEDIATION_DEFERRED_MARKER)) { deferredAt = i; deferred = b; }
           else if (startsWithHeader(b, PHASE_MARKERS.remediate.header)) trailAt = i;
         });
-        if (deferred !== null && deferredAt > trailAt && (state.pr == null || /^pr=(\d+)\s*$/m.exec(deferred)?.[1] === String(state.pr))) {
+        if (deferred !== null && deferredAt > trailAt && deferredAt > dispatchAt && (state.pr == null || /^pr=(\d+)\s*$/m.exec(deferred)?.[1] === String(state.pr))) {
           const kind = /^kind=(\w+)\s*$/m.exec(deferred)?.[1] ?? "lease";
-          return { status: "blocked", reason: "deferred", retryable: false, detail: `deferred-live-run: ${kind}` };
+          return { status: "blocked", reason: "deferred", code: OC.REMEDIATE_DEFERRED_LIVE_RUN, retryable: false, detail: `deferred-live-run: ${kind}` };
         }
-        return { status: "failed", detail: `no ${completion} marker` };
+        return { status: "failed", code: OC.REMEDIATE_NO_MARKER, detail: `no ${completion} marker` };
       }
       // Parse the **Re-gate outcome**: field remediate.md's Phase M8 posts
       // (e.g. "**Re-gate outcome**: AUTO-LANDED to staging" — value is the
@@ -972,8 +1029,11 @@ export const PHASES = [
           // policy judgment call respectively) — reuse the existing
           // "needs-human" terminal reason rather than inventing two more,
           // matching the #2352/#2353 precedent of reusing an existing
-          // TERMINAL_REASONS value where semantically equivalent.
-          return { status: "committed", terminalReason: "needs-human", outputs: { reGateOutcome } };
+          // TERMINAL_REASONS value where semantically equivalent. forge#3833:
+          // the two stay distinguishable by outcome code.
+          return { status: "committed", terminalReason: "needs-human",
+                   code: reGateOutcome === "UNFIXABLE" ? OC.REMEDIATE_UNFIXABLE : OC.REMEDIATE_RE_ESCALATED,
+                   outputs: { reGateOutcome } };
         default:
           return { status: "failed", detail: `FORGE:REMEDIATION:COMPLETE present but Re-gate outcome unrecognized/missing: ${reGateOutcome || "none"}` };
       }

package/bin/engine/projector.mjs

@@ -3,6 +3,16 @@
  * `io.gh(args)` is injected (async, returns stdout) so this is testable offline.
  */
 import { parseState, upsertStateBlock } from "./state.mjs";
+import { isTrustedActor } from "./phases.mjs";
+
+// Defence in depth: a lease further out than 3x the engine's 10 min TTL (same
+// bound as scripts/remediate-liveness.sh MAX_LEASE_TTL_MS) is never honoured.
+export const MAX_LEASE_TTL_MS = 3 * 600_000;
+
+// Body + provenance in ONE call. `gh issue view --json` cannot return the last
+// editor or authorAssociation, so GraphQL is used. -F variables, never interpolation.
+const PROVENANCE_QUERY = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){"
+  + "issue(number:$number){body authorAssociation author{login __typename} editor{login __typename}}}}";
 
 export function makeProjector(io) {
   const gh = io.gh;
@@ -12,9 +22,46 @@ export function makeProjector(io) {
     try { return JSON.parse(out).body ?? ""; } catch { return ""; }
   }
 
+  /**
+   * Body of the issue iff its LAST EDITOR (`editor ?? author`) is trusted, else
+   * null. The reporter can edit their own body, so creator-only trust is wrong
+   * and engine writes (bot editor) must stay readable. Any error, malformed
+   * JSON or missing provenance fails closed (null).
+   */
+  async function getTrustedBody(issue) {
+    try {
+      const out = await gh(["api", "graphql", "-f", `query=${PROVENANCE_QUERY}`,
+        "-F", "owner={owner}", "-F", "name={repo}", "-F", `number=${Number(issue)}`]);
+      const i = JSON.parse(out)?.data?.repository?.issue;
+      if (!i || typeof i.body !== "string") return null;
+      const actor = i.editor ?? i.author;
+      if (!actor || typeof actor !== "object") return null;
+      // authorAssociation describes the CREATOR: valid for the actor only when
+      // the actor IS the creator. A distinct human editor's standing comes from
+      // the collaborator permission endpoint (fail closed to NONE).
+      let association = "NONE";
+      if (!i.editor || i.editor.login === i.author?.login) association = i.authorAssociation;
+      else if (actor.__typename !== "Bot" && typeof actor.login === "string" && /^[A-Za-z0-9-]+(\[bot\])?$/.test(actor.login)) {
+        try {
+          const perm = JSON.parse(await gh(["api", `repos/{owner}/{repo}/collaborators/${actor.login}/permission`, "--jq", "{permission}"])).permission;
+          association = perm === "admin" ? "OWNER" : (perm === "maintain" || perm === "write") ? "COLLABORATOR" : "NONE";
+        } catch { /* fail closed */ }
+      }
+      return isTrustedActor({ association, type: actor.__typename, login: actor.login }) ? i.body : null;
+    } catch { return null; }
+  }
+
   return {
     /** @returns {Promise<import("./phases.mjs").RunState|null>} */
-    async readState(issue) { return parseState(await getBody(issue)); },
+    async readState(issue) {
+      const body = await getTrustedBody(issue);
+      if (body === null) return null;
+      const st = parseState(body);
+      if (st?.lease && !(Number.isFinite(st.lease.until) && st.lease.until <= Date.now() + MAX_LEASE_TTL_MS)) {
+        return { ...st, lease: null };
+      }
+      return st;
+    },
 
     async writeState(issue, index) {
       const body = upsertStateBlock(await getBody(issue), index);

package/bin/engine/runlog.mjs

@@ -12,7 +12,10 @@ export function appendEvent(dir, issue, event) {
   mkdirSync(dir, { recursive: true });
   const path = logPath(dir, issue);
   const seq = readLog(dir, issue).length + 1;
-  appendFileSync(path, JSON.stringify({ seq, ...event }) + "\n");
+  // forge#3696: wall-clock ISO-8601 `ts` on every appended event. Placed before the
+  // spread so a caller-supplied `ts` wins. rewriteLog() deliberately does not stamp:
+  // a hydrated rewrite time would be a false timestamp. Old logs lack `ts` and still parse.
+  appendFileSync(path, JSON.stringify({ seq, ts: new Date().toISOString(), ...event }) + "\n");
 }
 
 /**
@@ -58,7 +61,9 @@ export function deriveState(events) {
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
               terminalReason: null, lease: null, lastRateLimit: null,
-              remediationKind: null };
+              remediationKind: null, outcomeCode: null };
+  // forge#3833: outcome code of the LAST PHASE_COMMIT only (replaced, like lastCommitReason).
+  let lastCommitCode = null;
   // forge#3528: handoff reason of the LAST PHASE_COMMIT only (replaced, not sticky).
   let lastCommitReason = null;
   // forge#3754: phase of the LAST PHASE_COMMIT, so a reopen can tell a remediate-terminal run.
@@ -80,6 +85,8 @@ export function deriveState(events) {
         // remediate instead of defaulting to a "merged" close.
         if (e.terminalReason) s.terminalReason = e.terminalReason;
         lastCommitReason = e.terminalReason ?? null;
+        lastCommitCode = e.code ?? null;
+        if (e.code) s.outcomeCode = e.code;
         lastCommitPhase = e.phase ?? null;
         // forge#3530: the review's remediation kind must survive resume. A later review
         // commit replaces it; a committed remediate consumes it, so it is never reused.
@@ -89,6 +96,7 @@ export function deriveState(events) {
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
         lastTerminalReason = s.terminalReason;
+        if (e.code) s.outcomeCode = e.code;
         break;
       // forge#3511: an explicit `run-issue --retry` reopens an engine-error
       // terminal. Bumping `v` makes the local state newer than the stale
@@ -97,7 +105,7 @@ export function deriveState(events) {
       // (needs-human / decomposed); restore the last commit's reason so the
       // retry re-enters remediate/decompose instead of close/build.
       case "RUN_REOPEN":
-        s.terminal = false; s.terminalReason = lastCommitReason; s.v = e.seq;
+        s.terminal = false; s.terminalReason = lastCommitReason; s.outcomeCode = lastCommitCode; s.v = e.seq;
         // forge#3754: a remediate that ended needs-human is re-run after a human clears the
         // label. Un-commit it (new array, no in-place mutation) so the forge#3506 resume guard
         // does not re-terminate and remediate's entryCondition re-selects it.
@@ -119,9 +127,9 @@ export function deriveState(events) {
       // lastCommitReason is reset so a stale handoff reason cannot leak into
       // the new cycle through a later RUN_REOPEN.
       case "RUN_NEXT_CYCLE":
-        s.terminal = false; s.terminalReason = null; s.committed = [];
+        s.terminal = false; s.terminalReason = null; s.committed = []; s.outcomeCode = null;
         s.branch = null; s.pr = null; s.remediationKind = null;
-        lastCommitReason = null; lastCommitPhase = null; lastTerminalReason = null; s.v = e.seq;
+        lastCommitReason = null; lastCommitPhase = null; lastCommitCode = null; lastTerminalReason = null; s.v = e.seq;
         s.lastRateLimit = null; // forge#3791
         break;
       // forge#2524: a session-limit pause is purely informational — it does

package/bin/engine/telemetry-seam.mjs

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#3835: the engine's `emitTelemetry` seam writer. Maps the run-log shaped records the engine hands to the
+ * seam onto FORGE:TELEMETRY events so `forgedock stats` can rebuild Cost, Time and outcome codes from GitHub alone:
+ *   PHASE_ATTEMPT_USAGE -> `phase_attempt` (attempt, model, turns, duration_ms, cost_usd, *_tokens)
+ *   RUN_TERMINAL        -> `run_terminal`  (reason, code, wall_ms)
+ * Other records are ignored. The returned function NEVER throws and honours FORGE_TELEMETRY=off. Telemetry values
+ * are scalars (the emitter stringifies objects), so the `usage` object is flattened here; absent values are omitted.
+ */
+import { execFileSync } from "node:child_process";
+import { emit } from "./telemetry.mjs";
+
+export function defaultResolveRepo() {
+  try {
+    const r = execFileSync("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15000 }).trim();
+    return /^[\w.-]+\/[\w.-]+$/.test(r) ? r : null;
+  } catch { return null; }
+}
+
+const scalar = (v) => (typeof v === "number" ? Number.isFinite(v) : typeof v === "string" && v !== "");
+const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => scalar(v)));
+const tok = (u, k) => (u && typeof u === "object" && Number.isFinite(u[k]) ? u[k] : undefined);
+
+/** Pure mapping, exported for tests: returns { event, payload, phase } or null when the record is not mapped. */
+export function mapRecord(rec, wallMs) {
+  if (!rec || typeof rec !== "object") return null;
+  if (rec.event === "PHASE_ATTEMPT_USAGE") {
+    return { event: "phase_attempt", phase: rec.phase, payload: compact({
+      attempt: rec.attempt, model: rec.model, turns: rec.turns, duration_ms: rec.duration_ms,
+      cost_usd: Number.isFinite(rec.cost_usd) ? Math.round(rec.cost_usd * 1e6) / 1e6 : undefined,
+      input_tokens: tok(rec.usage, "input_tokens"), output_tokens: tok(rec.usage, "output_tokens"),
+      cache_read_tokens: tok(rec.usage, "cache_read_input_tokens"), cache_creation_tokens: tok(rec.usage, "cache_creation_input_tokens"),
+    }) };
+  }
+  if (rec.event === "RUN_TERMINAL") {
+    return { event: "run_terminal", phase: null, payload: compact({ reason: rec.reason, code: rec.code, wall_ms: wallMs }) };
+  }
+  return null;
+}
+
+/**
+ * @param {{repo?: string|null, emitFn?: Function, now?: () => number, resolveRepo?: () => string|null, env?: object}} o
+ * @returns {(rec: object) => Promise<void>}
+ */
+export function makeEmitTelemetry({ repo = null, emitFn = emit, now = Date.now, resolveRepo = defaultResolveRepo, env = process.env } = {}) {
+  const startedAt = now();
+  let resolved = repo || env.FORGE_REPO || null;
+  let tried = Boolean(resolved);
+  return async (rec) => {
+    try {
+      if ((env.FORGE_TELEMETRY || "on") === "off") return;
+      const mapped = mapRecord(rec, now() - startedAt);
+      if (!mapped || rec.issue == null) return;
+      if (!tried) { tried = true; resolved = resolveRepo() || null; }
+      if (!resolved) return; // no destination: the Node emitter would drop it anyway
+      // ctx carries repo/issue/run/phase: emit() drops those reserved keys from the payload.
+      emitFn(mapped.event, mapped.payload, { repo: resolved, issue: rec.issue, run: `r_${rec.issue}_${Math.floor(startedAt / 1000)}`, phase: mapped.phase ?? undefined });
+    } catch { /* telemetry never fails a run */ }
+  };
+}

package/bin/engine/telemetry-seam.test.mjs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { makeEmitTelemetry, mapRecord } from "./telemetry-seam.mjs";
+
+const attempt = { event: "PHASE_ATTEMPT_USAGE", phase: "build", attempt: 2, issue: 7, duration_ms: 1234, cost_usd: 0.123456789, model: "sonnet", turns: null,
+  usage: { input_tokens: 1, output_tokens: 2, cache_read_input_tokens: 3, cache_creation_input_tokens: 4 } };
+
+function harness(over = {}) {
+  const calls = [];
+  const emit = makeEmitTelemetry({ repo: "o/r", emitFn: (...a) => { calls.push(a); }, now: () => 5000, env: {}, ...over });
+  return { calls, emit };
+}
+
+describe("engine telemetry seam", () => {
+  it("flattens usage, omits nulls and passes repo/issue/run/phase as ctx (not payload)", async () => {
+    const { calls, emit } = harness();
+    await emit(attempt);
+    const [event, payload, ctx] = calls[0];
+    assert.equal(event, "phase_attempt");
+    assert.deepEqual(payload, { attempt: 2, model: "sonnet", duration_ms: 1234, cost_usd: 0.123457, input_tokens: 1, output_tokens: 2, cache_read_tokens: 3, cache_creation_tokens: 4 });
+    assert.equal(ctx.repo, "o/r");
+    assert.equal(ctx.issue, 7);
+    assert.equal(ctx.phase, "build");
+    assert.match(ctx.run, /^r_7_\d+$/);
+    for (const v of Object.values(payload)) assert.notEqual(typeof v, "object");
+  });
+  it("maps RUN_TERMINAL with reason, code and wall time; ignores other records", async () => {
+    let t = 1000;
+    const { calls, emit } = harness({ now: () => t });
+    t = 61000;
+    await emit({ event: "RUN_TERMINAL", reason: "needs-human", code: "review.escalated", issue: 7 });
+    await emit({ event: "PHASE_START", phase: "build", issue: 7 });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][0], "run_terminal");
+    assert.deepEqual(calls[0][1], { reason: "needs-human", code: "review.escalated", wall_ms: 60000 });
+    assert.equal(calls[0][2].phase, undefined);
+  });
+  it("null usage yields a record with no token fields", () => {
+    assert.deepEqual(mapRecord({ event: "PHASE_ATTEMPT_USAGE", phase: "build", attempt: 1, usage: null, duration_ms: 5 }).payload, { attempt: 1, duration_ms: 5 });
+  });
+  it("never throws, even when the emitter throws, and honours FORGE_TELEMETRY=off", async () => {
+    const boom = harness({ emitFn: () => { throw new Error("down"); } });
+    await boom.emit(attempt);
+    const off = harness({ env: { FORGE_TELEMETRY: "off" } });
+    await off.emit(attempt);
+    assert.equal(off.calls.length, 0);
+  });
+  it("drops records with no resolvable repo (the Node emitter would drop them) and resolves lazily once", async () => {
+    let resolves = 0;
+    const none = harness({ repo: null, resolveRepo: () => { resolves++; return null; } });
+    await none.emit(attempt); await none.emit(attempt);
+    assert.equal(none.calls.length, 0);
+    assert.equal(resolves, 1);
+    const some = harness({ repo: null, resolveRepo: () => "a/b" });
+    await some.emit(attempt);
+    assert.equal(some.calls[0][2].repo, "a/b");
+  });
+});