forgedock 1.13.1 → 1.15.0

package/bin/engine/phases-args.test.mjs

@@ -100,6 +100,17 @@ describe("engine phase args satisfy each target spec's argument-hint (forge#3499
     await assert.rejects(() => close.buildArgs({ ...state, pr: null, terminalReason: "merged" }, ctx, io), PhaseArgsError);
   });
 
+  it("close investigation: --terminal-state investigation, never --pr (forge#3534)", async () => {
+    const close = PHASES.find((p) => p.id === "close");
+    for (const pr of [null, 12]) {
+      const args = await close.buildArgs({ ...state, pr, terminalReason: "investigation" }, ctx, io);
+      assert.equal(args[args.indexOf("--terminal-state") + 1], "investigation");
+      assert.ok(!args.includes("--pr"));
+    }
+    for (const reason of ["needs-human", "awaiting-merge", "engine-error"])
+      await assert.rejects(() => close.buildArgs({ ...state, terminalReason: reason }, ctx, io), PhaseArgsError);
+  });
+
   it("close derives --terminal-state from the run's terminal reason", async () => {
     const close = PHASES.find((p) => p.id === "close");
     for (const [reason, expected] of [[null, "merged"], ["invalid", "invalid"], ["decomposed", "decomposed"]]) {

package/bin/engine/phases.mjs

@@ -27,7 +27,11 @@ import { PHASE_MARKERS } from "../../packages/protocol/src/phases.js";
 // matching engine-level terminal reason to report instead of overloading
 // "needs-human" (which would misrepresent a clean-but-unmet-bar re-review as
 // a fresh human-judgment escalation).
-export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed", "engine-error", "awaiting-merge"];
+export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed", "engine-error", "awaiting-merge", "phase-complete"];
+// forge#3545: "phase-complete" is close's CLOSE_RESULT PHASE_COMPLETE exit: the PR
+// merged but later phases of a multi-phase issue remain, so the issue is
+// deliberately left OPEN (FORGE:PHASE:COMPLETE posted). Distinct from "merged"
+// (nothing shipped-and-closed) and "awaiting-merge" (no PR merged yet).
 
 /**
  * Trust predicate for FORGE marker comments (forge#3542) — a JS port of
@@ -91,6 +95,8 @@ async function issueMarkers(issue, io) {
   return { comments };
 }
 
+/** Non-terminal held-resume record (remediate.md Phase M8, forge#3685): header and sentinel are the same line; never a COMPLETE marker. */
+const REMEDIATION_HELD_MARKER = "FORGE:REMEDIATION_HELD";
 const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /** True when `body` STARTS with the typed header `<!-- {header}` (e.g. `FORGE:BUILDER`). */
 function startsWithHeader(body, header) {
@@ -114,6 +120,104 @@ function latestMarked(comments, header, sentinel) {
   const all = markedComments(comments, header, sentinel);
   return all.length ? all[all.length - 1] : null;
 }
+/**
+ * Cycle boundary (forge#3657). `--retry` on a phase-complete run starts a new
+ * cycle; the engine publishes `<!-- FORGE:CYCLE: n -->` so builder evidence from
+ * earlier cycles (branch, merged PR) is not re-adopted. Callers pass TRUSTED
+ * comments only (issueMarkers), so an untrusted comment cannot move the boundary.
+ */
+export function cycleMarker(n) { return `<!-- FORGE:CYCLE: ${n} -->`; }
+const CYCLE_RE = /^[ \t]*<!--[ \t]*FORGE:CYCLE:[ \t]*(\d+)[ \t]*-->[ \t]*$/m;
+function cycleNumber(body) {
+  if (!startsWithHeader(body, "FORGE:CYCLE")) return null;
+  const m = String(body).match(CYCLE_RE);
+  return m ? Number(m[1]) : null;
+}
+/** Comments after the newest cycle marker; all comments when none is present. */
+export function sliceToCurrentCycle(comments) {
+  for (let i = comments.length - 1; i >= 0; i--) {
+    if (cycleNumber(comments[i]) !== null) return comments.slice(i + 1);
+  }
+  return comments;
+}
+/**
+ * Next cycle number: one past the higher of the newest trusted FORGE:CYCLE on
+ * GitHub and `localCycles` (the local RUN_NEXT_CYCLE count). A rehydrated log
+ * never replays RUN_NEXT_CYCLE, so the local count alone can reset to 0 while
+ * GitHub already carries markers. Errors propagate (caller fails closed).
+ */
+export async function nextCycleNumber(issue, localCycles, 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;
+}
+/**
+ * Idempotently publish the FORGE:CYCLE marker for cycle `n`: skipped when the
+ * newest trusted cycle marker already is `n` (crash between post and the log
+ * append retries safely). Errors propagate so the caller can fail closed.
+ */
+export async function postCycleMarker(issue, n, io) {
+  const { comments } = await issueMarkers(issue, io);
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const c = cycleNumber(comments[i]);
+    if (c !== null) { if (c === n) return { posted: false }; break; }
+  }
+  await io.gh(["issue", "comment", String(issue), "--body", cycleMarker(n)]);
+  return { posted: true };
+}
+
+/**
+ * Acceptance-gate state (build.md B6.5; forge#3545). `FORGE:BUILDER:COMPLETE` is
+ * appended at validate V5, BEFORE the gate runs, so the marker alone is not proof
+ * the build passed. Newest marker wins, by comment ORDER (never blob presence):
+ * `FORGE:ACCEPTANCE_GATE:PASSED` => "pass"; `:FAILED`, `:BLOCKED` or a
+ * `FORGE:BUILD_BLOCKED` comment => "blocked"; none => "none" (legacy / crash
+ * paths keep their prior behaviour). `comments` are trusted bodies, oldest first.
+ * Stays fail-closed by design. A blocked state clears only via a newer PASSED, which a
+ * re-invocation posts: build.md B0 "gate resume" re-enters B6.5 instead of returning
+ * ALREADY_DONE when the newest gate marker is blocked (forge#3725).
+ */
+function latestGateState(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, gate)) continue;
+    if (hasSentinelLine(b, `${gate}:PASSED`)) return "pass";
+    if (hasSentinelLine(b, `${gate}:FAILED`) || hasSentinelLine(b, `${gate}:BLOCKED`)) return "blocked";
+  }
+  return "none";
+}
+/**
+ * Investigation exit evidence (forge#3534): a trusted comment led by
+ * `<!-- FORGE:INVESTIGATION:DELIVERABLES -->` as a full line. Anchored like every
+ * other marker, so the string quoted inside another comment never counts.
+ */
+function hasInvestigationMarker(comments) {
+  const m = PHASE_MARKERS.build.investigationMarker;
+  return hasMarker(comments, m, m);
+}
+/**
+ * forge#3534 (SEC-3716-1): does the issue carry a trusted current-cycle investigation exit marker?
+ * The implement child closes an investigation issue itself (CLOSED, no `workflow:merged`), so the
+ * engine's divergence guard must not read that as a dead issue before build.reconcile runs.
+ * Fail closed: any fetch error means "no marker" (the guard then behaves as before).
+ */
+export async function hasInvestigationExit(issue, io) {
+  try {
+    const { comments } = await issueMarkers(issue, io);
+    return hasInvestigationMarker(sliceToCurrentCycle(comments));
+  } catch { return false; }
+}
+/** close.md C2 PHASE_COMPLETE evidence in the current cycle (forge#3545). */
+function hasPhaseComplete(comments) {
+  return hasMarker(comments, "FORGE:PHASE:COMPLETE", "FORGE:PHASE:COMPLETE");
+}
+
 /**
  * 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).
@@ -150,6 +254,33 @@ function sizeGateRoutesToDecompose(comments) {
   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));
 }
+/**
+ * Decompose loop guard (mirrors build.md B5.5 and decompose.md Guard 1). 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`.
+ * `comments` MUST be trusted bodies. A body-fetch failure fails toward the guard
+ * (not decomposed) so an error can never route into a refusing decompose phase.
+ */
+async function decomposeLoopGuard(issue, comments, io) {
+  const starts = (c, m) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${m}`);
+  if (comments.some((c) => starts(c, "FORGE:DECOMPOSED"))) return "already decomposed (FORGE:DECOMPOSED)";
+  if (comments.some((c) => starts(c, PHASE_MARKERS.build.sizeOverrideMarker) && overrideHasJustification(c)))
+    return "justified FORGE:SIZE_OVERRIDE";
+  let body;
+  try {
+    const out = String((await io.gh(["issue", "view", String(issue), "--json", "body", "--jq", ".body"])) ?? "");
+    body = out;
+    if (out.trimStart().startsWith("{")) {
+      try { const j = JSON.parse(out); if (j && typeof j.body === "string") body = j.body; } catch { /* raw text */ }
+    }
+  } catch {
+    return "issue body unavailable (failing toward not decomposed)";
+  }
+  if (/^\*\*Parent\*\*:[ \t]*#\d+/m.test(body.replace(/\r\n/g, "\n"))) return "sub-issue (**Parent**: #N)";
+  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;
@@ -387,6 +518,9 @@ 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;
+
 /**
  * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
  * trusted `<!-- FORGE:INVESTIGATOR` report (forge#3542 selects it; forge#3543's
@@ -407,7 +541,25 @@ function isDecomposed(report) {
     console.error(`[engine] conflicting decomposition signals (heading=${verdict ?? "none"}, markers=${[...markers].join("+") || "none"}); treating as not decomposed`);
     return false;
   }
-  return (verdict ?? marker) === "YES";
+  if ((verdict ?? marker) === "YES") 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. 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 parsedFactor = fac ? Number(fac[1]) : NaN;
+  const factor = Number.isFinite(parsedFactor) && parsedFactor > 0 ? parsedFactor : DEFAULT_ESTIMATE_FACTOR;
+  if (est && gate) {
+    const estimate = Number(est[1]);
+    const threshold = Number(gate[1]);
+    if (threshold > 0 && estimate > threshold * factor) {
+      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
+      return true;
+    }
+  }
+  return false;
 }
 
 /** @type {Phase[]} */
@@ -432,8 +584,16 @@ export const PHASES = [
         return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
       if (closing === complete) {
         // investigate.md emits `### Decomposition Assessment` then `**YES**|**NO**`.
-        if (isDecomposed(report))
+        if (isDecomposed(report)) {
+          // Lazy: the body fetch only happens on the decompose path. A child / already
+          // decomposed / overridden issue cannot be decomposed (decompose Guard 1 BLOCKs).
+          const guard = await decomposeLoopGuard(state.issue, comments, io);
+          if (guard) {
+            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", outputs: { verdict: "CONFIRMED" } };
       }
       return { status: "failed", detail: `no ${PHASE_MARKERS.investigate.completionMarker} marker` };
@@ -481,8 +641,11 @@ export const PHASES = [
       // Idempotent resume: resolve the real branch from ground truth (FORGE:BUILDER
       // comment) rather than trusting a possibly-stale/absent state.branch, then
       // check it's already ahead of base → treat as done, skip the LLM (forge#2174).
-      const { comments } = await issueMarkers(state.issue, io);
+      const { comments: allComments } = await issueMarkers(state.issue, io);
+      const comments = sliceToCurrentCycle(allComments); // forge#3657: current-cycle evidence only
       const branch = resolveBranch(state, comments);
+      // forge#3545: a failed/blocked acceptance gate newer than any PASSED means build is NOT done.
+      if (latestGateState(comments) === "blocked") return { satisfied: false };
       if (branch && hasMarker(comments, PHASE_MARKERS.build.header, PHASE_MARKERS.build.completionMarker) && (await commitsAhead(state.lane, branch, io)) > 0) {
         return { satisfied: true, outputs: { branch } };
       }
@@ -492,10 +655,13 @@ export const PHASES = [
         const merged = await mergedPrForBranch(branch, state.lane, io);
         if (merged) return { satisfied: true, outputs: { branch, pr: merged.number } };
       }
+      // forge#3534: an investigation exit already posted its deliverables marker: build is done.
+      if (hasInvestigationMarker(comments)) return { satisfied: true, terminalReason: "investigation", outputs: {} };
       return { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const { comments } = await issueMarkers(state.issue, io);
+      const { comments: allComments } = await issueMarkers(state.issue, io);
+      const comments = sliceToCurrentCycle(allComments); // forge#3657
       const complete = hasMarker(comments, PHASE_MARKERS.build.header, PHASE_MARKERS.build.completionMarker); // #1305: require :COMPLETE …
       // Resolve the branch the builder actually created from the FORGE:BUILDER:COMPLETE
       // comment (ground truth), scoped to that specific comment — see
@@ -507,14 +673,28 @@ export const PHASES = [
       // from a genuine git-confirmed zero and would wrongly trip the
       // non-retryable guard below on the very first attempt.
       const ahead = branch ? await commitsAhead(state.lane, branch, io) : -1; // … AND real commits
+      // forge#3545: fail closed. COMPLETE is written before the B6.5 acceptance gate, so a
+      // newer FAILED/BLOCKED gate (or BUILD_BLOCKED) must not be committed and move on to
+      // 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).
+      if (latestGateState(comments) === "blocked") {
+        return { status: "failed", detail: `acceptance gate blocked (builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"})`, retryable: false };
+      }
       if (complete && ahead > 0) {
         return { status: "committed", outputs: { branch, ...buildChildEvidence(comments) } };
       }
+      // forge#3534: INVESTIGATION_COMPLETE writes no code and opens no PR, so it never
+      // posts FORGE:BUILDER:COMPLETE with commits. The durable deliverables marker is the
+      // ground truth. Not retried; review is skipped and close runs `--terminal-state investigation`.
+      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(await trustedCommentBodies(state.issue, io))) {
+      if (!complete && mayRouteToDecompose(comments) && sizeGateRoutesToDecompose(comments)) {
         return { status: "committed", terminalReason: "decomposed", outputs: branch ? { branch } : {} };
       }
       const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
@@ -561,7 +741,8 @@ export const PHASES = [
     id: "review",
     command: "work-on/review",
     buildArgs: reviewArgs,
-    entryCondition: (s) => s.committed.includes("build"),
+    // forge#3534: an investigation build has no PR to review; close runs directly.
+    entryCondition: (s) => s.committed.includes("build") && s.terminalReason !== "investigation",
     async reconcile(state, io) {
       const pr = await openPrFor(state, io);   // adopt an existing PR instead of opening a second
       return pr ? { satisfied: false, outputs: { pr } } : { satisfied: false };
@@ -663,8 +844,48 @@ export const PHASES = [
         if (at >= 0) scoped = comments.slice(at + 1);
       }
       const latest = latestMarked(scoped, PHASE_MARKERS.remediate.header, completion);
-      if (latest === null)
+      // forge#3647: ground-truth PR read. An interrupted or rate-limited remediation can leave the
+      // PR already merged with no COMPLETE marker (or a stale HELD-AWAITING-MERGE report). The
+      // reported outcome is never upgraded to a merge decision; only the live PR state is. Same
+      // merged predicate as reconcile (`mergedAt` or state MERGED). Unreadable => null (fail closed).
+      const prMerged = async () => {
+        if (state.pr == null) return false;
+        try {
+          const out = await io.gh(["pr", "view", String(state.pr), "--json", "state,mergedAt,baseRefName"]);
+          const j = JSON.parse(out || "{}");
+          return !!j.mergedAt || j.state === "MERGED";
+        } catch { return false; }
+      };
+      // Shared with the AUTO-LANDED case: CLOSED + workflow:merged means genuinely finished;
+      // anything else (including an unreadable snapshot) hands off to idempotent `close`.
+      const mergedResult = async (reGateOutcome) => {
+        let closed = false;
+        try {
+          const snap = await issueSnapshot(state.issue, io);
+          closed = snap.ok && snap.state === "CLOSED" &&
+            snap.labels.includes(PHASE_MARKERS.close.completionLabel);
+        } catch { closed = false; }
+        return closed
+          ? { status: "committed", terminalReason: "merged", outputs: { reGateOutcome } }
+          : { status: "committed", terminalReason: "merged", outputs: { reGateOutcome, closeHandoff: true } };
+      };
+      // forge#3685: a resume that ends HELD posts a non-terminal FORGE:REMEDIATION_HELD record (no COMPLETE).
+      // Newest-wins between the held record and COMPLETE, by position in the (trusted, scoped) comment list.
+      const isHeld = (b) => startsWithHeader(b, REMEDIATION_HELD_MARKER) && hasSentinelLine(b, REMEDIATION_HELD_MARKER);
+      let heldAt = -1, completeAt = -1;
+      scoped.forEach((b, i) => {
+        if (isHeld(b)) heldAt = i;
+        if (startsWithHeader(b, PHASE_MARKERS.remediate.header) && hasSentinelLine(b, completion)) completeAt = i;
+      });
+      if (heldAt >= 0 && heldAt > completeAt) {
+        // Merged PR hands to close; otherwise awaiting-merge (terminal for the engine, re-entered by an operator), never a retry.
+        if (await prMerged()) return mergedResult("AUTO-LANDED");
+        return { status: "committed", terminalReason: "awaiting-merge", outputs: { reGateOutcome: "HELD-AWAITING-MERGE" } };
+      }
+      if (latest === null) {
+        if (await prMerged()) return mergedResult("AUTO-LANDED");
         return { status: "failed", 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
       // first whitespace-delimited token after the colon).
@@ -672,7 +893,7 @@ export const PHASES = [
       const match = matches.length ? matches[matches.length - 1] : null;
       const reGateOutcome = match ? match[1] : null;
       switch (reGateOutcome) {
-        case "AUTO-LANDED": {
+        case "AUTO-LANDED":
           // forge#3624: remediate.md M8 drives close itself on this outcome, but an
           // engine phase session may skip or fail that delegated close and nothing
           // verified it. Check the issue's real state: CLOSED + workflow:merged means
@@ -680,17 +901,10 @@ export const PHASES = [
           // an unreadable snapshot, hands off to `close` (idempotent via its reconcile).
           // The reason stays "merged" either way so the commit replaces the review's
           // sticky "needs-human" and close.buildArgs accepts --terminal-state merged.
-          let closed = false;
-          try {
-            const snap = await issueSnapshot(state.issue, io);
-            closed = snap.ok && snap.state === "CLOSED" &&
-              snap.labels.includes(PHASE_MARKERS.close.completionLabel);
-          } catch { closed = false; }
-          return closed
-            ? { status: "committed", terminalReason: "merged", outputs: { reGateOutcome } }
-            : { status: "committed", terminalReason: "merged", outputs: { reGateOutcome, closeHandoff: true } };
-        }
+          return mergedResult(reGateOutcome);
         case "HELD-AWAITING-MERGE":
+          // forge#3647: a HELD report for a PR that has since merged must still drive close.
+          if (await prMerged()) return mergedResult(reGateOutcome);
           return { status: "committed", terminalReason: "awaiting-merge", outputs: { reGateOutcome } };
         case "RE-ESCALATED":
         case "UNFIXABLE":
@@ -715,20 +929,23 @@ export const PHASES = [
       // non-merged handoff reason (needs-human, awaiting-merge, engine-error, ...) must never
       // be closed as merged.
       const reason = state.terminalReason ?? null;
-      if (reason !== null && !["merged", "decomposed", "invalid"].includes(reason))
+      if (reason !== null && !["merged", "decomposed", "invalid", "investigation"].includes(reason))
         throw new PhaseArgsError(`refusing close --terminal-state merged from terminalReason ${JSON.stringify(reason)}`);
       const terminal = reason === "decomposed" ? "decomposed"
-        : reason === "invalid" ? "invalid" : "merged";
+        : reason === "invalid" ? "invalid"
+        : reason === "investigation" ? "investigation" : "merged";
       const args = [String(state.issue), ...repoArgs(ctx), ...baseArgs(state)];
       // forge#3504: a merged close with no PR is fabricated evidence — require it.
-      if (state.pr != null || terminal === "merged") args.push("--pr", need(state.pr, "pr", /^[0-9]+$/));
+      // forge#3534: an investigation close is PR-less by definition; never pass --pr.
+      if (terminal !== "investigation" && (state.pr != null || terminal === "merged")) args.push("--pr", need(state.pr, "pr", /^[0-9]+$/));
       if (state.branch) args.push("--branch", need(state.branch, "branch", BRANCH_RE));
       const wt = await resolveWorktree(state, io);
       if (wt && PATH_RE.test(wt)) args.push("--worktree", wt);
       args.push("--terminal-state", terminal);
       return args;
     },
-    entryCondition: (s) => s.committed.includes("review"),
+    entryCondition: (s) => s.committed.includes("review")
+      || (s.committed.includes("build") && s.terminalReason === "investigation"), // forge#3534
     async reconcile(state, io) {
       // Idempotent resume: issue already CLOSED → skip the LLM re-run. forge#3644: the
       // workflow:merged label alone is NOT proof close ran — remediate M7 labels the issue
@@ -738,7 +955,25 @@ export const PHASES = [
       // strict subset of what satisfies this predicate on a CLOSED issue).
       const snap = await issueSnapshot(state.issue, io);
       if (!snap.ok) return { satisfied: false };
-      return snap.state === "CLOSED" ? { satisfied: true } : { satisfied: false };
+      if (snap.state === "CLOSED" && state.terminalReason === "investigation") {
+        // forge#3534: the implement child closes an investigation issue itself, so CLOSED is no
+        // proof close.md ran (board, summary, trajectory). Its own idempotency key is the
+        // FORGE:TRAJECTORY comment; only that makes this satisfied.
+        try {
+          const { comments } = await issueMarkers(state.issue, io);
+          return { satisfied: comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY")), terminalReason: "investigation" };
+        } catch { return { satisfied: false }; }
+      }
+      if (snap.state === "CLOSED") return { satisfied: true };
+      // forge#3545: a current-cycle FORGE:PHASE:COMPLETE means close already ran to its
+      // PHASE_COMPLETE exit; do not re-run it.
+      if (snap.state === "OPEN") {
+        try {
+          const { comments } = await issueMarkers(state.issue, io);
+          if (hasPhaseComplete(sliceToCurrentCycle(comments))) return { satisfied: true, terminalReason: "phase-complete" };
+        } catch { /* fail closed: not satisfied */ }
+      }
+      return { satisfied: false };
     },
     async detectOutcome(state, io) {
       const snap = await issueSnapshot(state.issue, io);
@@ -756,8 +991,16 @@ export const PHASES = [
       // (already in TERMINAL_REASONS) rather than inventing a new one.
       if (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")
-        return { status: "committed", terminalReason: "invalid", outputs: {} };
+        return { status: "committed", terminalReason: state.terminalReason === "investigation" ? "investigation" : "invalid", outputs: {} };
+      // forge#3545: PHASE_COMPLETE is a valid close exit (multi-phase issue: PR merged,
+      // issue deliberately left OPEN). Only the current cycle's marker counts.
+      if (snap.state === "OPEN") {
+        const { comments } = await issueMarkers(state.issue, io);
+        if (hasPhaseComplete(sliceToCurrentCycle(comments)))
+          return { status: "committed", terminalReason: "phase-complete", outputs: {} };
+      }
       return { status: "failed", detail: "issue not closed" };
     },
     isTerminalAfter: () => true,

package/bin/engine/phases.test.mjs

@@ -0,0 +1,24 @@
+// Spec-contract test (forge#3725): the build.md B0 resume block must re-enter
+// B6.5 when the newest acceptance-gate marker is blocked (see latestGateState
+// in phases.mjs), instead of returning ALREADY_DONE.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("latestGateState / ACCEPTANCE_GATE spec contract (forge#3725)", () => {
+  it("build.md B0 gate resume re-enters B6.5 before returning ALREADY_DONE", () => {
+    const spec = readFileSync(path.join(ROOT, "commands/work-on/build.md"), "utf8");
+    const start = spec.indexOf("**Resume check**");
+    const end = spec.indexOf("- If there is no `<!-- FORGE:INVESTIGATOR -->`", start);
+    assert.ok(start >= 0 && end > start, "B0 resume block found");
+    const b0 = spec.slice(start, end);
+    assert.match(b0, /ACCEPTANCE_GATE:(FAILED|BLOCKED)/);
+    assert.match(b0, /BUILD_BLOCKED/);
+    assert.match(b0, /re-enter at \*\*Phase B6\.5\*\*/);
+    assert.ok(b0.indexOf("Gate resume") < b0.indexOf("status: ALREADY_DONE"), "gate resume precedes ALREADY_DONE");
+  });
+});

package/bin/engine-cli.mjs

@@ -7,9 +7,9 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { join } from "node:path";
-import { runIssue, DEFAULT_MAX_ATTEMPTS } from "./engine.mjs";
+import { runIssue, DEFAULT_MAX_ATTEMPTS, sanitizeLeaseHost } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { readLog, deriveState } from "./engine/runlog.mjs";
 import { assertOpenCodeNativeRuntime } from "./runner.mjs";
@@ -338,6 +338,10 @@ export function lastLocalRun(dir) {
  *                          `runCommand()` call; only applies on the "api" backend.
  *                          Omit to keep runner.mjs's default (`FORGEDOCK_MODEL` env
  *                          or its built-in default).
+ *   --wait-lease           Optional (forge#3574). If another live holder owns the
+ *                          run's lease, wait (bounded by the lease TTL) until it
+ *                          expires or its same-host pid is dead, then continue.
+ *                          Without it, a held lease exits `deferred` (code 75).
  *   --retry                Optional (forge#3511). Reopen a run that ended `engine-error`
  *                          (e.g. a session-limit hit) and resume from its last committed
  *                          phase. A run that ended `phase-complete` (multi-phase issue, phase merged,
@@ -346,7 +350,7 @@ export function lastLocalRun(dir) {
  */
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
-  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane> [--retry]");
+  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane> [--retry] [--wait-lease]");
   assertOpenCodeNativeRuntime({ operation: "forgedock run-issue" });
   const lane = flag(argv, "--lane");
   if (!lane) throw new Error("--lane is required: e.g. --lane main or --lane staging. No default to prevent accidental production targeting.");
@@ -355,10 +359,13 @@ export async function runFromCli(argv, deps = {}) {
   const model = flag(argv, "--model");
   // Boolean flag: only counts at a flag position, never as another flag's value.
   const retry = argv.some((a, i) => a === "--retry" && !["--lane", "--repo", "--backend", "--model"].includes(argv[i - 1]));
+  // forge#3574: --wait-lease blocks (bounded by the lease TTL) until a live
+  // holder's lease expires or becomes reclaimable. Same flag-position guard.
+  const waitLease = argv.some((a, i) => a === "--wait-lease" && !["--lane", "--repo", "--backend", "--model"].includes(argv[i - 1]));
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
-  const agentId = `cli_${process.pid}`;
+  const agentId = `cli_${sanitizeLeaseHost(hostname())}_${process.pid}`;
   // Injectable for tests (forge#2175) — defaults to the real ~/.forge/runs dir.
   const dir = deps.dir ?? runDir();
   // forge#2240: print the run-log path at the very start of the run, not only
@@ -390,8 +397,14 @@ export async function runFromCli(argv, deps = {}) {
     // runIssue's/runner.mjs's existing defaults (forge#2028).
     ...(backend ? { backend } : {}),
     ...(model ? { model } : {}),
-    ...(retry ? { retry: true } : {}) });
+    ...(retry ? { retry: true } : {}),
+    ...(waitLease ? { waitLease: true } : {}) });
   console.log(`issue #${issue} → ${res.terminalReason}`);
+  if (res.terminalReason === "deferred") {
+    // forge#3574: say WHY (holder + expiry); the empty-log diagnostics add nothing.
+    console.log(res.detail ?? "run deferred: another holder owns the lease");
+    return res;
+  }
   if (res.terminalReason === "not-retryable") {
     console.log(res.detail ?? "run is not retryable");
     return res;