forgedock 1.16.2 → 1.18.0

package/bin/engine/outcome-codes.mjs

@@ -0,0 +1,114 @@
+/**
+ * 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",
+  REVIEW_BLOCKING_ISSUE: "review.blocking_issue",
+  REVIEW_PR_OPEN: "review.pr_open",
+  BUILD_ACCEPTANCE_FAILED: "build.acceptance_failed",
+  BUILD_ACCEPTANCE_MALFORMED: "build.acceptance_malformed",
+  BUILD_SIZE_OVER_GATE: "build.size_over_gate", // retired (forge#3862): never emitted; kept so historic runs parse
+  BUILD_COHESIVE: "build.cohesive", // retired (forge#3862): never emitted
+  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",
+  INFRA_DISK_QUOTA: "infra.disk_quota",
+  LEASE_HELD: "lease.held",
+  DEPENDENCY_OPEN: "dependency.open",
+  DEPENDENCY_UNREADABLE: "dependency.unreadable",
+  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;
+}
+
+const DISK_QUOTA_RE = /EDQUOT|ENOSPC|(?:errno|system error) -?(?:28|122)\b|No space left|Disk quota exceeded/i;
+
+/** True when runner/stderr text reports a full disk or exhausted quota (forge#3572). Match runner error text only, never review prose. */
+export function isDiskQuotaText(text) {
+  return typeof text === "string" && DISK_QUOTA_RE.test(text);
+}
+
+/** True when a thrown runner error is a disk-full/quota failure (message, errno or stderr). */
+export function isDiskQuotaError(err) {
+  if (!err || typeof err !== "object") return false;
+  if (err.code === "ENOSPC" || err.code === "EDQUOT" || err.errno === -28 || err.errno === -122) return true;
+  return isDiskQuotaText(err.message) || isDiskQuotaText(err.stderr);
+}
+
+/** 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 (isDiskQuotaError(err)) return OUTCOME_CODES.INFRA_DISK_QUOTA;
+  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;
+    case "dependency-open": return OUTCOME_CODES.DEPENDENCY_OPEN;
+    case "dependency-unreadable": return OUTCOME_CODES.DEPENDENCY_UNREADABLE;
+    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, "\\$&");
@@ -151,13 +165,21 @@ export function sliceToCurrentCycle(comments) {
  * GitHub already carries markers. Errors propagate (caller fails closed).
  */
 export async function nextCycleNumber(issue, localCycles, io) {
+  return Math.max(await newestCycle(issue, io), localCycles) + 1;
+}
+/**
+ * Highest trusted FORGE:CYCLE number on the issue (0 when none). Reads only
+ * trusted comments via issueMarkers/cycleNumber; errors propagate so the caller
+ * fails closed (forge#3931: hydration must not reset on an unreadable trail).
+ */
+export async function newestCycle(issue, io) {
   const { comments } = await issueMarkers(issue, io);
   let highest = 0;
   for (const body of comments) {
     const c = cycleNumber(body);
     if (c !== null && c > highest) highest = c;
   }
-  return Math.max(highest, localCycles) + 1;
+  return highest;
 }
 /**
  * Idempotently publish the FORGE:CYCLE marker for cycle `n`: skipped when the
@@ -186,15 +208,22 @@ 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 used by latestGateState. 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 };
 }
 /**
  * Investigation exit evidence (forge#3534): a trusted comment led by
@@ -242,44 +271,75 @@ async function hasInvestigationCloseEvidence(issue, io) {
     || hasPhaseComplete(sliceToCurrentCycle(comments));
 }
 
+/** A SIZE_OVERRIDE needs a non-empty justification — the first non-blank, non-HTML-comment line after the marker line. */
+function overrideHasJustification(body) {
+  const lines = String(body).replace(/\r\n/g, "\n").split("\n");
+  return lines.slice(1).some((l) => l.trim() !== "" && !l.trimStart().startsWith("<!--"));
+}
+
 /**
- * Trusted comment bodies, chronological — the same single fetch + trust predicate
- * as issueMarkers() (one path, forge#3542). Fail closed: a fetch error yields `[]` here (issueMarkers itself propagates it).
+ * forge#3862 / forge#3932: does trusted GitHub state show a REVOKED decomposition?
+ * Revoked = a trusted `<!-- FORGE:DECOMPOSED:REVOKED -->` comment newer than the newest
+ * trusted `FORGE:DECOMPOSED` comment (or one with no `FORGE:DECOMPOSED` left). The revocation
+ * alone is the operator's explicit signal: the size gate that once required a justified
+ * `FORGE:SIZE_OVERRIDE` alongside it is gone, so no override clause remains. An untrusted
+ * revocation never counts. Fail closed: an unreadable comment trail is `false`, never "revoked".
  */
-async function trustedCommentBodies(issue, io) {
-  try { return (await issueMarkers(issue, io)).comments; } catch { return []; }
+export async function decompositionRevoked(issue, io) {
+  let comments;
+  try { comments = (await issueMarkers(issue, io)).comments; } catch { return false; }
+  const last = (pred) => { for (let i = comments.length - 1; i >= 0; i--) if (pred(comments[i])) return i; return -1; };
+  const revokedAt = last((c) => startsWithHeader(c, "FORGE:DECOMPOSED:REVOKED"));
+  if (revokedAt < 0) return false;
+  // `startsWithHeader` also matches `FORGE:DECOMPOSED:REVOKED` for the header `FORGE:DECOMPOSED` (":" ends
+  // the identifier), so the live decomposition record is the newest one that is not the revocation itself.
+  const decomposedAt = last((c) => startsWithHeader(c, "FORGE:DECOMPOSED") && !startsWithHeader(c, "FORGE:DECOMPOSED:REVOKED"));
+  return decomposedAt <= revokedAt;
 }
 
-/** build.md B5.5 Step 2: a SIZE_OVERRIDE needs a non-empty justification — the first non-blank, non-HTML-comment line after the marker line. */
-function overrideHasJustification(body) {
-  const lines = String(body).replace(/\r\n/g, "\n").split("\n");
-  return lines.slice(1).some((l) => l.trim() !== "" && !l.trimStart().startsWith("<!--"));
+/** Read one issue's REST record (`state`, `body`, author provenance). Throws on a failed read; null on unparsable/non-object output. */
+async function readIssueRecord(n, io) {
+  const out = String((await io.gh(["api", `repos/{owner}/{repo}/issues/${n}`])) ?? "").trim();
+  if (!out) return { empty: true };
+  try {
+    const j = JSON.parse(out);
+    return j && typeof j === "object" && !Array.isArray(j) ? j : null;
+  } catch { return null; }
 }
 
 /**
- * Size-gate routing (build.md B5.5). True only when the latest `FORGE:DIFF_SIZE`
- * says `result: OVER`, carries a `### Split Proposal` (the discriminator against
- * the decompose-loop-guard Blocked exit, which also posts OVER but must not
- * re-enter decompose), and no justified `FORGE:SIZE_OVERRIDE` comment follows it,
- * and the issue is not already decomposed. `comments` MUST be TRUSTED bodies in
- * chronological order (see trustedCommentBodies); an untrusted comment never
- * reaches this function.
+ * forge#3932: does the issue declare a `**Depends on**: #N` dependency that is still OPEN?
+ * Honoured only when the issue BODY's author is trusted (`isTrustedComment`: OWNER/MEMBER/COLLABORATOR,
+ * Bot, or FORGE_TRAIL_TRUSTED_LOGINS) and only for the exact line decompose.md emits
+ * (`**Depends on**: #N` at line start; loose "depends on/after" prose is ignored). A self-reference is
+ * ignored. Returns `null` (nothing blocking), `{ open: [N, ...] }`, or `{ unreadable: true, detail }`
+ * when the issue or a declared dependency cannot be read (fail closed: the caller refuses the run).
+ * An empty read of the issue itself means "no body to trust" and yields `null`.
  */
-function sizeGateRoutesToDecompose(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;
-  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;
-  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));
+export async function openDependency(issue, io) {
+  let rec;
+  try { rec = await readIssueRecord(issue, io); } catch (e) {
+    return { unreadable: true, detail: `issue ${issue} could not be read for its **Depends on** line: ${e?.message || e}` };
+  }
+  if (rec === null) return { unreadable: true, detail: `issue ${issue} could not be parsed for its **Depends on** line` };
+  if (rec.empty || typeof rec.body !== "string" || !isTrustedComment(rec)) return null;
+  const deps = [...new Set([...rec.body.replace(/\r\n/g, "\n").matchAll(/^\*\*Depends on\*\*:[ \t]*#(\d+)\b/gm)].map((m) => Number(m[1])))]
+    .filter((n) => n > 0 && n !== Number(issue));
+  const open = [];
+  for (const dep of deps) {
+    let d;
+    try { d = await readIssueRecord(dep, io); } catch (e) {
+      return { unreadable: true, detail: `dependency #${dep} of issue ${issue} could not be read: ${e?.message || e}` };
+    }
+    const st = typeof d?.state === "string" ? d.state.toLowerCase() : "";
+    if (st === "open") open.push(dep);
+    else if (st !== "closed") return { unreadable: true, detail: `dependency #${dep} of issue ${issue} has no readable state` };
+  }
+  return open.length ? { open } : null;
 }
+
 /**
- * Decompose loop guard (mirrors build.md B5.5 and decompose.md Guard 1). Returns a
+ * Decompose loop guard (mirrors decompose.md Guard 1; forge#3676). Returns a
  * short reason string when the issue must NOT be routed to decompose, else null:
  * a `**Parent**: #N` body line (a sub-issue; decompose Guard 1 would BLOCK it), a
  * TRUSTED `FORGE:DECOMPOSED` comment, or a TRUSTED justified `FORGE:SIZE_OVERRIDE`.
@@ -305,11 +365,6 @@ async function decomposeLoopGuard(issue, comments, io) {
   return null;
 }
 
-/** Cheap untrusted pre-check: does ANY comment look like an OVER gate? Only then is the trusted fetch worth making. */
-function mayRouteToDecompose(comments) {
-  const gate = PHASE_MARKERS.build.sizeGateMarker;
-  return comments.some((c) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${gate}`) && /^result:[ \t]*OVER[ \t]*\r?$/m.test(c));
-}
 /**
  * Count commits on `branch` ahead of `lane`'s base. On the first build the
  * branch does not exist yet, so real git rejects the ref range — swallow
@@ -542,11 +597,6 @@ async function reviewArgs(state, ctx, io) {
           "--branch", need(state.branch, "branch", BRANCH_RE), ...baseArgs(state)];
 }
 
-/** Default `build.diff_size.estimate_factor` (docs/CONFIG.md); used when the report carries no valid `ESTIMATE_FACTOR:` field. */
-const DEFAULT_ESTIMATE_FACTOR = 1.2;
-/** Default `build.diff_size.batch_seam_min` (docs/CONFIG.md); the engine cannot read forge.yaml here. */
-const DEFAULT_BATCH_SEAM_MIN = 3;
-
 /**
  * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
  * trusted `<!-- FORGE:INVESTIGATOR` report (forge#3542 selects it; forge#3543's
@@ -567,42 +617,24 @@ function isDecomposed(report) {
     console.error(`[engine] conflicting decomposition signals (heading=${verdict ?? "none"}, markers=${[...markers].join("+") || "none"}); treating as not decomposed`);
     return false;
   }
-  // forge#3573 safety net inputs: own-line, whole-number fields only; absent/0/non-numeric
-  // fields have no effect. The factor is the investigator's effective `ESTIMATE_FACTOR:`
-  // (positive decimal); absent/invalid -> 1.2.
-  const est = /^ESTIMATED_DIFF_LINES:[ \t]*(\d+)[ \t]*$/m.exec(text);
-  const gate = /^GATE_THRESHOLD:[ \t]*(\d+)[ \t]*$/m.exec(text);
-  const fac = /^ESTIMATE_FACTOR:[ \t]*(\d+(?:\.\d+)?)[ \t]*$/m.exec(text);
-  const seamsM = /^INDEPENDENT_SEAMS:[ \t]*(\d+)[ \t]*$/m.exec(text);
-  const parsedFactor = fac ? Number(fac[1]) : NaN;
-  const factor = Number.isFinite(parsedFactor) && parsedFactor > 0 ? parsedFactor : DEFAULT_ESTIMATE_FACTOR;
-  const sized = est && gate && Number(gate[1]) > 0;
-  const estimate = sized ? Number(est[1]) : 0;
-  const threshold = sized ? Number(gate[1]) : 0;
+  // forge#3862: decomposition is a planning decision on SEPARABILITY, never on size. The engine has
+  // no line-count rule and no estimate net: an estimate, however large, never routes to decompose.
+  // A YES must be backed by the separability evidence the investigator records: an own-line
+  // `INDEPENDENT_SEAMS:` of at least 2 and an own-line `DECOMPOSE_JUSTIFICATION:`. A report that
+  // carries the seam field but not that evidence is downgraded to NO (fail toward building).
+  // A YES with no `INDEPENDENT_SEAMS:` field at all (an older or malformed report) is kept.
   if ((verdict ?? marker) === "YES") {
-    // forge#3786: a YES the numbers do not require is downgraded to NO unless the report
-    // carries an own-line `DECOMPOSE_JUSTIFICATION:` line. Required = estimate over
-    // threshold x factor, or the seam clause (seams >= batch_seam_min and estimate over
-    // threshold / 2). The engine cannot see the `batch` label or the configured
-    // `batch_seam_min`, so it uses the default 3 and stays lenient for batches. Absent
-    // numeric fields keep the YES (no silent downgrade of a malformed report).
-    if (sized) {
-      const seams = seamsM ? Number(seamsM[1]) : 0;
-      const required = estimate > threshold * factor || (seams >= DEFAULT_BATCH_SEAM_MIN && estimate > threshold / 2);
+    const seamsM = /^INDEPENDENT_SEAMS:[ \t]*(\d+)[ \t]*$/m.exec(text);
+    if (seamsM) {
+      const seams = Number(seamsM[1]);
       const justified = /^DECOMPOSE_JUSTIFICATION:[ \t]*\S/m.test(text);
-      if (!required && !justified) {
-        console.error(`[engine] unsupported DECOMPOSE:YES (estimate ${estimate}, seams ${seams}, gate ${threshold} x ${factor}, no DECOMPOSE_JUSTIFICATION); treating as not decomposed`);
+      if (seams < 2 || !justified) {
+        console.error(`[engine] unsupported DECOMPOSE:YES (separable seams ${seams}${justified ? "" : ", no DECOMPOSE_JUSTIFICATION"}); treating as not decomposed`);
         return false;
       }
     }
     return true;
   }
-  // forge#3573 safety net: an investigator NO whose own size estimate is clearly over
-  // the gate (estimate > threshold x factor) fails toward decompose.
-  if (sized && estimate > threshold * factor) {
-    console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
-    return true;
-  }
   return false;
 }
 
@@ -625,7 +657,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 +668,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 +697,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 +754,9 @@ 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#3862: the build never routes to decompose (no size-gate decomposed outcome).
       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) } };
@@ -734,13 +767,6 @@ export const PHASES = [
       if (hasInvestigationMarker(comments)) {
         return { status: "committed", terminalReason: "investigation", outputs: {} };
       }
-      // B5.5 NEEDS_DECOMPOSE: the size gate posts no FORGE:BUILDER:COMPLETE and
-      // build.md says the router (not build) dispatches decompose with no
-      // 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 } : {} };
-      }
       const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
       // forge#2176: when the builder has already posted FORGE:BUILDER:COMPLETE
       // but the resolved (real, ground-truth) branch has zero commits ahead of
@@ -803,7 +829,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,15 +838,18 @@ 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.
-      if (rr && rr.status) return { status: "failed", detail: "PR open, not merged", retryable: false, handoff: false, outputs };
+      if (rr && rr.status) return { status: "failed", detail: "PR open, not merged", retryable: false, handoff: false, outputs, code: OC.REVIEW_PR_OPEN };
       let snap = null;
       try { snap = await issueSnapshot(state.issue, io); } catch { snap = null; }
       if (snap?.ok && (snap.labels.includes("needs-human") || snap.labels.includes("workflow:remediating"))) return escalated;
-      return { status: "failed", detail: "PR open, not merged", retryable: false, outputs };
+      // forge#3931: an idempotent re-review at an unchanged head posts nothing new, so the only evidence of a
+      // blocking finding is the trusted FORGE:NOTE_DISPOSITION already on the PR for this head. Hand off to remediate.
+      if (await blockingDispositionAtHead(pr, io)) return { ...escalated, detail: "blocking ISSUE finding at unchanged head", code: OC.REVIEW_BLOCKING_ISSUE };
+      return { status: "failed", detail: "PR open, not merged", retryable: false, outputs, code: OC.REVIEW_PR_OPEN };
     },
   },
   {
@@ -854,7 +883,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 +909,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 +975,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
@@ -968,12 +1012,18 @@ export const PHASES = [
           return { status: "committed", terminalReason: "awaiting-merge", outputs: { reGateOutcome } };
         case "RE-ESCALATED":
         case "UNFIXABLE":
+          // forge#3931: a trail recorded against an older PR head must not be replayed as this run's outcome.
+          if (await remediationHeadStale(state, io))
+            return { status: "failed", code: OC.REMEDIATE_NO_MARKER, detail: `stale ${completion} trail: PR head moved since it was recorded` };
           // Both leave the issue at needs-human (a fresh escalation, or a
           // 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"}` };
       }
@@ -1051,7 +1101,11 @@ export const PHASES = [
       // that label is still a real terminal state (nothing left for this phase
       // to do), just not a "merged" one — reuse the existing "invalid" reason
       // (already in TERMINAL_REASONS) rather than inventing a new one.
-      if (snap.labels.includes(PHASE_MARKERS.close.completionLabel))
+      // SEC-1: the label alone is not proof either. A reopened or never-closed issue can still
+      // carry a stale `workflow:merged`, so "merged" requires CLOSED together with the label
+      // (same predicate as the remediate `mergedResult`). A label without CLOSED falls through
+      // to the OPEN / PHASE_COMPLETE / "issue not closed" paths below.
+      if (snap.state === "CLOSED" && snap.labels.includes(PHASE_MARKERS.close.completionLabel))
         return { status: "committed", terminalReason: "merged", outputs: {} };
       // forge#3534: an investigation exit closes the issue itself; keep that reason honest.
       if (snap.state === "CLOSED") {
@@ -1152,16 +1206,73 @@ async function mergedPrForBranch(branch, lane, io) {
     return hit ? { number: hit.number } : null;
   } catch { return null; }
 }
+/**
+ * forge#3931: true when the newest trusted FORGE:NOTE_DISPOSITION on the PR covers the live head
+ * (`reviewed_sha`) and filed at least one ISSUE (`findings_filed` > 0). Trusted comments only; an
+ * unreadable PR, missing head or unparsable record returns false (fail closed: no handoff).
+ */
+async function blockingDispositionAtHead(pr, io) {
+  if (!pr?.head) return false;
+  try {
+    const { comments } = await issueMarkers(pr.number, io);
+    const recs = comments.filter((b) => /^\s*<!--\s*FORGE:NOTE_DISPOSITION:/.test(b));
+    if (!recs.length) return false;
+    const first = recs[recs.length - 1].split("\n", 1)[0];
+    const sha = /\breviewed_sha=([0-9a-f]{40,64})\b/.exec(first)?.[1];
+    const filed = /\bfindings_filed=(\d+)\b/.exec(first)?.[1];
+    return sha === pr.head && Number(filed) > 0;
+  } catch { return false; }
+}
 async function prStatusFor(state, io) {
   const n = await openPrFor(state, io);
   if (!n) return null;
-  const out = await io.gh(["pr", "view", String(n), "--json", "number,state,labels,mergedAt"]);
+  const out = await io.gh(["pr", "view", String(n), "--json", "number,state,labels,mergedAt,headRefOid"]);
   let j;
   try { j = JSON.parse(out || "{}"); } catch { return null; }
   const labels = (j.labels || []).map((l) => l.name || l);
   return { number: j.number, merged: !!j.mergedAt || j.state === "MERGED",
            needsHuman: labels.includes("needs-human"),
-           remediating: labels.includes("workflow:remediating") };
+           remediating: labels.includes("workflow:remediating"),
+           head: typeof j.headRefOid === "string" && SHA_RE.test(j.headRefOid) ? j.headRefOid : null };
+}
+const SHA_RE = /^[0-9a-f]{40,64}$/;
+
+/**
+ * forge#3931: true only when the newest trusted FORGE:REMEDIATION:COMPLETE names a
+ * `**Head**:` SHA that differs from the live PR head, i.e. the trail was produced for
+ * an older head. Any unreadable input (no pr, no trail, `unknown`/missing head, gh or
+ * parse failure) returns false so callers keep today's behaviour (fail closed).
+ */
+export async function remediationHeadStale(state, io) {
+  if (state?.pr == null) return false;
+  try {
+    const { comments } = await issueMarkers(state.issue, io);
+    const latest = latestMarked(comments, PHASE_MARKERS.remediate.header, PHASE_MARKERS.remediate.completionMarker);
+    const recorded = latest === null ? null : /\*\*Head\*\*:[ \t]*([0-9a-f]{40,64})\b/.exec(latest)?.[1] ?? null;
+    if (!recorded) return false;
+    const j = JSON.parse((await io.gh(["pr", "view", String(state.pr), "--json", "headRefOid"])) || "{}");
+    return typeof j.headRefOid === "string" && SHA_RE.test(j.headRefOid) && j.headRefOid !== recorded;
+  } catch { return false; }
+}
+
+/**
+ * forge#3931 (CONC-1): hydrate-time cycle reset is safe only when the hydrated progress is provably from an
+ * OLDER cycle. The index carries no cycle number, so a same-cycle mid-flight or blocked run must not reset.
+ * Provable = a terminal index AND live GitHub state showing the issue OPEN with `needs-human` and
+ * `workflow:remediating` both clear AND no OPEN PR on the branch. Any unreadable input returns false.
+ */
+export async function cycleResetProvable(state, io) {
+  if (!state?.terminal) return false;
+  try {
+    const snap = await issueSnapshot(state.issue, io);
+    if (!snap.ok || snap.state !== "OPEN") return false;
+    if (snap.labels.includes("needs-human") || snap.labels.includes("workflow:remediating")) return false;
+    if (state.branch) {
+      const a = JSON.parse((await io.gh(["pr", "list", "--head", state.branch, "--json", "number,state", "--state", "all"])) || "[]");
+      if (!Array.isArray(a) || a.some((p) => p && p.state === "OPEN")) return false;
+    }
+    return true;
+  } catch { return false; }
 }
 
 /** The engine's transition function: first uncommitted phase whose gate holds. */