forgedock 1.13.1 → 1.14.0

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
@@ -114,6 +118,80 @@ 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.
+ */
+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";
+}
+/** 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).
@@ -387,6 +465,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); mirrored here for the isDecomposed safety net. */
+const 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 +488,21 @@ 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.
+  const est = /^ESTIMATED_DIFF_LINES:[ \t]*(\d+)[ \t]*$/m.exec(text);
+  const gate = /^GATE_THRESHOLD:[ \t]*(\d+)[ \t]*$/m.exec(text);
+  if (est && gate) {
+    const estimate = Number(est[1]);
+    const threshold = Number(gate[1]);
+    if (threshold > 0 && estimate > threshold * ESTIMATE_FACTOR) {
+      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${ESTIMATE_FACTOR}; routing to decompose`);
+      return true;
+    }
+  }
+  return false;
 }
 
 /** @type {Phase[]} */
@@ -481,8 +576,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 } };
       }
@@ -495,7 +593,8 @@ export const PHASES = [
       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,6 +606,13 @@ 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 repaired build posts a newer PASSED, which clears this.
+      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) } };
       }
@@ -514,7 +620,7 @@ export const PHASES = [
       // 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"}`;
@@ -663,8 +769,35 @@ 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 } };
+      };
+      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 +805,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 +813,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":
@@ -738,7 +864,16 @@ 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") 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);
@@ -758,6 +893,13 @@ export const PHASES = [
         return { status: "committed", terminalReason: "merged", outputs: {} };
       if (snap.state === "CLOSED")
         return { status: "committed", terminalReason: "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-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;

package/bin/engine.mjs

@@ -4,8 +4,9 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
+import { hostname as osHostname } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
-import { pickPhase, TERMINAL_REASONS, issueSnapshot } from "./engine/phases.mjs";
+import { pickPhase, TERMINAL_REASONS, issueSnapshot, postCycleMarker, nextCycleNumber } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { VALID_BACKENDS } from "./runner.mjs";
@@ -177,6 +178,48 @@ function makeProgressEmitter(onProgress) {
   };
 }
 
+
+// forge#3574: lease holder ids are `cli_<host>_<pid>`. The host component lets a
+// relaunch on the SAME host probe whether the holder pid is still alive and
+// reclaim a dead holder's lease without waiting out the TTL. Strict regex: the
+// host cannot contain `_` (the separator) and the pid is digits only, so a
+// malformed or legacy `cli_<pid>` id never parses as reclaimable.
+const LEASE_HOLDER_RE = /^cli_([A-Za-z0-9.-]+)_(\d+)$/;
+
+/** Sanitize a hostname for use inside a lease id (no `_`, only `[A-Za-z0-9.-]`). */
+export function sanitizeLeaseHost(host) {
+  return String(host || "unknown").replace(/[^A-Za-z0-9.-]/g, "-") || "unknown";
+}
+
+/** Parse a `cli_<host>_<pid>` lease holder id. Returns null for anything else. */
+export function parseLeaseHolder(by) {
+  const m = LEASE_HOLDER_RE.exec(String(by ?? ""));
+  if (!m) return null;
+  const pid = Number(m[2]);
+  return Number.isSafeInteger(pid) && pid > 0 ? { host: m[1], pid } : null;
+}
+
+/**
+ * True only when the lease holder is provably dead: id parses, host equals this
+ * host, and `kill(pid, 0)` throws ESRCH. EPERM (exists, not ours) and any other
+ * result mean alive. Legacy/other-host/unparseable ids are never reclaimed (TTL
+ * fallback). Best-effort like the I3 guard itself: PID reuse and containers
+ * sharing a hostname are accepted residual risk.
+ */
+export function isLeaseHolderDead({ by, host = osHostname(), killFn = process.kill.bind(process) } = {}) {
+  const parsed = parseLeaseHolder(by);
+  if (!parsed || parsed.host !== sanitizeLeaseHost(host)) return false;
+  try {
+    killFn(parsed.pid, 0);
+    return false;
+  } catch (e) {
+    return e?.code === "ESRCH";
+  }
+}
+
+/** Max startup wait for a persisted rate-limit reset (guards a corrupt far-future resetAt). */
+export const MAX_RESUME_RATE_LIMIT_WAIT_MS = 6 * 60 * 60 * 1000;
+
 /**
  * @param {object} opts
  * @param {string} [opts.backend] - "cli" | "api" | "auto" (forge#2028). Forwarded
@@ -230,6 +273,11 @@ function makeProgressEmitter(onProgress) {
  *   cycle (RUN_NEXT_CYCLE) that resets committed/branch/pr and restarts at
  *   investigate. Any other terminal reason is left untouched and returns
  *   `not-retryable`.
+ * @param {boolean} [opts.waitLease] - forge#3574: when another live holder owns
+ *   the lease, poll (via `sleep`, bounded by `leaseTtlMs`) until it expires or
+ *   its holder is reclaimable, then continue; `deferred` on timeout.
+ * @param {string} [opts.hostname] - injectable host name (tests).
+ * @param {Function} [opts.killFn] - injectable `process.kill` (tests).
  */
 export async function runIssue(opts) {
   const { issue, dir, agentId, lane = "staging", io, runner,
@@ -253,6 +301,9 @@ export async function runIssue(opts) {
           maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES,
           sessionLimitDefaultWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS,
           retry = false,
+          waitLease = false,
+          hostname = osHostname(),
+          killFn = process.kill.bind(process),
           onProgress = () => {} } = opts;
 
   // forge#2452: extracted into makeProgressEmitter() — see its docstring for
@@ -269,18 +320,38 @@ export async function runIssue(opts) {
 
   // 1. Load + reconcile (GitHub wins).
   const local = readLog(dir, issue).length ? deriveState(readLog(dir, issue)) : null;
-  const remote = await projector.readState(issue);
+  let remote = await projector.readState(issue);
   let { state, action } = reconcileState(local, remote);
+  const leaseHeld = (r) => !!(r?.lease && r.lease.until > now() && r.lease.by !== agentId &&
+    !isLeaseHolderDead({ by: r.lease.by, host: hostname, killFn }));
+  const deferredResult = (r) => ({
+    terminalReason: "deferred",
+    leaseUntil: r.lease.until,
+    detail: `issue ${issue} leased by ${r.lease.by} until ${new Date(r.lease.until).toISOString()}`,
+  });
 
   // I3 (best-effort): GitHub issue-edit is not an atomic CAS, so this is a
   // courtesy check, not a hard mutual-exclusion guarantee — a concurrent
   // start can still race between this read and the next lease write.
   // MUST come before any projector.writeState() — remirror/hydrate branches
   // must not overwrite GitHub state when another agent holds a valid lease.
-  if (remote?.lease && remote.lease.until > now() && remote.lease.by !== agentId) {
-    return { terminalReason: "deferred", detail: `issue ${issue} leased by ${remote.lease.by}` };
+  if (leaseHeld(remote)) {
+    if (!waitLease) return deferredResult(remote);
+    // forge#3574: bounded wait — never longer than one lease TTL.
+    const deadline = now() + leaseTtlMs;
+    let cur = remote;
+    while (leaseHeld(cur)) {
+      const remaining = deadline - now();
+      if (remaining <= 0) return deferredResult(cur);
+      emitProgress({ event: "lease_wait", detail: `waiting for lease held by ${cur.lease.by}` });
+      await sleep(Math.min(remaining, Math.max(0, cur.lease.until - now()), 15000) || 1);
+      cur = await projector.readState(issue);
+    }
+    // The holder may have committed phases (or finished) while we waited: re-reconcile
+    // against the post-wait remote so the lease write below cannot regress its state.
+    remote = cur;
+    ({ state, action } = reconcileState(local, remote));
   }
-
   if (!state) {
     state = freshState(issue, lane);
     appendEvent(dir, issue, { event: "RUN_START", issue, run: state.run, lane });
@@ -325,6 +396,17 @@ export async function runIssue(opts) {
         };
       }
     }
+    // forge#3657: publish the cycle boundary on GitHub BEFORE the log flips, so
+    // build's reconcilers never re-adopt cycle-1 evidence. Fail closed.
+    if (state.terminalReason === "phase-complete") {
+      const localCycles = readLog(dir, issue).filter((e) => e.event === "RUN_NEXT_CYCLE").length;
+      try { await postCycleMarker(issue, await nextCycleNumber(issue, localCycles, io), io); } catch {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue}: could not post FORGE:CYCLE marker; --retry did not start a new cycle`,
+        };
+      }
+    }
     appendEvent(dir, issue, {
       event: state.terminalReason === "phase-complete" ? "RUN_NEXT_CYCLE" : "RUN_REOPEN",
       issue,
@@ -376,6 +458,26 @@ export async function runIssue(opts) {
     } catch { return null; }
   })());
 
+  // forge#3574: a relaunch after a crash mid rate-limit pause must not re-run
+  // the phase early. Same-host resume reads the LOCAL run-log's lastRateLimit
+  // (the remote FORGE:STATE does not carry it). The lease is renewed while we
+  // wait so a second relaunch still defers.
+  const rl = local?.lastRateLimit;
+  const pendingPhase = pickPhase(state);
+  if (pendingPhase && rl && rl.phase === pendingPhase.id &&
+      typeof rl.resetAt === "number" && Number.isFinite(rl.resetAt) && rl.resetAt > now()) {
+    const waitMs = Math.min(rl.resetAt - now(), MAX_RESUME_RATE_LIMIT_WAIT_MS);
+    emitProgress({
+      event: "phase_paused", phase: pendingPhase.id, reason: "session-limit", resetAt: rl.resetAt,
+      detail: `resuming session-limit wait — pausing until ${new Date(rl.resetAt).toISOString()}`,
+    });
+    const resumeRenew = setInterval(() => {
+      projector.writeState(issue, { ...state, lease: { by: agentId, until: now() + leaseTtlMs } }).catch(() => {});
+    }, leaseRenewIntervalMs);
+    if (typeof resumeRenew.unref === "function") resumeRenew.unref();
+    try { await sleep(waitMs); } finally { clearInterval(resumeRenew); }
+  }
+
   let phase;
   while ((phase = pickPhase(state))) {
     // forge#3506 (SPEC-1/SPEC-2): a crash after a terminal-after phase committed (remediate or
@@ -462,7 +564,8 @@ export async function runIssue(opts) {
     }
     let outcome;
     if (reconciled.satisfied) {
-      outcome = { status: "committed", outputs: reconciled.outputs || {} };
+      outcome = { status: "committed", outputs: reconciled.outputs || {},
+                  ...(reconciled.terminalReason ? { terminalReason: reconciled.terminalReason } : {}) };
     } else {
       if (reconciled.outputs?.pr) state.pr = reconciled.outputs.pr;
       // forge#2240: the phase is actually about to run (not a resume no-op)

package/bin/forgedock.mjs

@@ -3207,7 +3207,7 @@ function help() {
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
     ["npx forgedock status [dir]", "Show ForgeDock state for a directory"],
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
-    ["npx forgedock run-issue <issue> --lane <lane> [--retry]", "Drive one issue through the durable engine (--retry reopens an engine-error run)"],
+    ["npx forgedock run-issue <issue> --lane <lane> [--retry] [--wait-lease]", "Drive one issue through the durable engine (--retry reopens an engine-error run; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
@@ -3972,6 +3972,9 @@ switch (command) {
       // runIssue() resolves cleanly with a terminalReason instead of throwing,
       // preserve that same non-zero exit code for this reason too.
       if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable")) exitCode = 1;
+      // forge#3574: a lease-held deferral did NOT run the issue; exit 75
+      // (EX_TEMPFAIL) so orchestrators neither count it as done nor as a failure.
+      if (result && result.terminalReason === "deferred") exitCode = 75;
     } catch (err) {
       process.stderr.write(`${RED}${err.message}${RESET}\n`);
       exitCode = 1;

package/commands/orchestrate/phase-3-dependency.md

@@ -80,6 +80,8 @@ Each issue's extraction also carries a **provenance** tag, in descending order o
 LAYER1_FILES=()
 declare -A EDGE_KIND    # "{PRED}:{SUCCESSOR}" → same-file | directory | shared-module (forge#1860)
 declare -A EDGE_FILES   # "{PRED}:{SUCCESSOR}" → the specific file(s) that triggered the edge (forge#1860)
+declare -A EDGE_SOFT    # "{PRED}:{SUCCESSOR}" → true when the Layer 1 edge is SOFT (either endpoint's FILE_SOURCE is body-fallback); unset = hard (forge#3697)
+declare -A EDGE_RELEASED # "{PRED}:{SUCCESSOR}" → true once a soft edge was released early in Step 4B (forge#3697)
 declare -A FILE_SOURCE  # {NUM} → contract-deliverables | affected-files-section | body-fallback | none (forge#2436, forge#2848)
 declare -A ISSUE_FILES  # {NUM} → newline-separated declared file set (forge#2844)
 
@@ -136,6 +138,7 @@ done
 - The issue with lower issue number goes first (stable ordering), unless an explicit `Depends on #` says otherwise
 - Add a conflict note to the DAG plan: "#{A} and #{B} both modify `{file}` — #{A} is predecessor of #{B}"
 - **Record the edge kind and shared file(s)** <!-- Added: forge#1860 -->: alongside the predecessor relationship, set `EDGE_KIND["${A}:${B}"]="same-file"` and `EDGE_FILES["${A}:${B}"]="{file}"` (space-separated if multiple files overlap). Layer 1 is the only point where the specific overlapping file is known — Step 3D's DAG only records that a predecessor relationship exists, not why. `EDGE_KIND`/`EDGE_FILES` have two consumers in `phase-4-execution.md` Step 4B: (1) the DONE-case "same-file current-state brief" forwarding (forge#1860, unchanged), and (2) `verify_file_overlap_edge()` (forge#1904, extended to the DONE path by forge#2848), which re-checks this guessed file list against the predecessor's *actual* PR diff once it reaches FAILED, GATED, **or DONE** — since Layer 1's file list is extracted from a pre-build investigation guess or a raw issue-body parse, never from real code, it can be wrong, and a predecessor that concludes without ever touching the guessed file should not keep a dependent gated/skipped on it, nor hand it a same-file brief about a file it never wrote. See `phase-4-execution.md`'s "File-overlap edge re-verification" section for the full mechanism.
+- **Tag soft edges** <!-- Added: forge#3697 -->: a Layer 1 edge is **soft** when `FILE_SOURCE` of EITHER endpoint is `body-fallback` — set `EDGE_SOFT["${A}:${B}"]=true`. Edges whose both endpoints come from `contract-deliverables` or `affected-files-section` are **hard** (no `EDGE_SOFT` entry). Layer 2/3/4/5 edges, explicit `Depends on`, and the DATABASE chain are never soft. Soft edges rest on a pre-investigation body guess, so Step 4B may release one *early*, while the predecessor is still `IN_PROGRESS`, once the predecessor's open PR diff positively shows no overlap with `EDGE_FILES` (`verify_soft_edge_early` in `phase-4-execution.md`; no PR, a fetch error, or any overlap means HOLD, never drop). A predecessor's `FORGE:ARCHITECT` / `FORGE:BUILDER` planned-files list, once posted, outranks `body-fallback` as evidence about that predecessor's file set. `EDGE_SOFT` is in-memory only and, like `EDGE_KIND`/`EDGE_FILES`, is not retained across wake/compaction, so early release is live-session only and a reconstructed edge fails safe to HOLD.
 
 #### Layer 2: Directory-proximity detection
 
@@ -410,7 +413,7 @@ Build a **directed acyclic graph (DAG)** of per-issue dependencies. Each issue g
 - **Explicit dependencies**: If issue B says "Depends on #A" or "Blocked by #A", add A to B's predecessors
 - **File-conflict edges**: If two issues share affected files (from Step 3C Layer 1), add a directed edge: lower issue number → higher issue number (unless explicit deps say otherwise). The later issue has the earlier issue in its predecessors.
 - **Domain serialization edges**: DATABASE issues form a linear chain (each has the previous DATABASE issue as its predecessor). Same-small-directory issues (Layer 2) and high-fan-in file issues (Layer 3) get directed edges as per Step 3C rules.
-- **Edge-kind tagging for same-file/directory/shared-module briefing and re-verification** <!-- Added: forge#1860; extended forge#1904 -->: Layer 1/2/3 edges are additionally tagged with `EDGE_KIND` (`same-file` / `directory` / `shared-module`) and `EDGE_FILES` at the point they're added (see Step 3C). Explicit-dependency edges, the DATABASE domain chain, Layer 4 conservative-fallback edges, and Layer 5 co-change edges deliberately do NOT receive one of these three `EDGE_KIND` values. This is what lets Step 4B distinguish "predecessor edge came from Step 3C Layer 1/2/3" from every other edge type, for two purposes: a same-file current-state brief (DONE case, forge#1860) and edge re-verification against the predecessor's actual PR diff once it reaches FAILED, GATED, or DONE (`verify_file_overlap_edge()`, forge#1904, DONE path added by forge#2848 — see `phase-4-execution.md` Step 4B). On the DONE path the two purposes are ordered: re-verification runs first and, on a `DROP`, suppresses the brief entirely. Non-`EDGE_KIND` edges are eligible for neither — they always `KEEP` in the re-verification check and are never candidates for the same-file brief.
+- **Edge-kind tagging for same-file/directory/shared-module briefing and re-verification** <!-- Added: forge#1860; extended forge#1904 -->: Layer 1/2/3 edges are additionally tagged with `EDGE_KIND` (`same-file` / `directory` / `shared-module`) and `EDGE_FILES` at the point they're added (see Step 3C). Explicit-dependency edges, the DATABASE domain chain, Layer 4 conservative-fallback edges, and Layer 5 co-change edges deliberately do NOT receive one of these three `EDGE_KIND` values. This is what lets Step 4B distinguish "predecessor edge came from Step 3C Layer 1/2/3" from every other edge type, for two purposes: a same-file current-state brief (DONE case, forge#1860) and edge re-verification against the predecessor's actual PR diff once it reaches FAILED, GATED, or DONE (`verify_file_overlap_edge()`, forge#1904, DONE path added by forge#2848 — see `phase-4-execution.md` Step 4B). On the DONE path the two purposes are ordered: re-verification runs first and, on a `DROP`, suppresses the brief entirely. Non-`EDGE_KIND` edges are eligible for neither — they always `KEEP` in the re-verification check and are never candidates for the same-file brief. <!-- Added: forge#3697 --> Layer 1 edges backed by `body-fallback` provenance are additionally tagged soft (`EDGE_SOFT`, Step 3C) so Step 4B can release them early against a live predecessor PR diff while the predecessor is still `IN_PROGRESS` (`verify_soft_edge_early()`); hard edges are never released early.
 - **Conservative fallback edges**: Low-confidence issues (Layer 4) get edges to same-domain issues as per Step 3C rules.
 - **Co-change coupling edges** <!-- Added: forge#1196 -->: High co-change file pairs (Layer 5, 3+ shared commits in the bounded window) that span two different issues get a directed edge using the same lower-issue-number-is-predecessor convention as Layer 1. Verified-independent pairs (Layer 5, zero shared commits) may instead REMOVE an edge that Layer 2 or Layer 4 would otherwise have added for that pair — Layer 1 and Layer 3 edges are never removed by a Layer 5 downgrade.
 - **Claims-board downgrade (Layer 2/4 edges only)** <!-- Added: forge#1736 -->: After dispatch begins (Phase 4A), when both issues in a Layer-2 or Layer-4 serialized pair post `FORGE:CLAIM` annotations on the coordination issue and their claimed file sets are **disjoint** (no path appears in both claims), the serialization edge for that pair MAY be relaxed — the blocked issue becomes ready. This downgrade is **never** applied to Layer-1 (same-file) or Layer-3 (high-fan-in) edges. See Step 4B: Claims-board relaxation sweep for the runtime check.
@@ -1286,7 +1289,7 @@ The orchestrator context window must stay small regardless of how many issues ha
 
 This reconstruction MUST use the same three-way **DONE / GATED / FAILED** predecessor classification defined in `phase-4-execution.md` Step 4B ("Predecessor Classification") — not a binary terminal/non-terminal grep. A binary grep is exactly the bug forge#1812 fixed: it let `needs-human` simultaneously satisfy "predecessor is done, dispatch the successor" (this block, pre-fix) and "predecessor failed, skip the successor" (Step 4B's failure handler, pre-fix) — with no way to represent "predecessor is human-gated, its PR is still open, and its dependents should wait but not be abandoned." That third case is exactly what wake/compaction reconstruction hits most often, since a merge approved by a human typically happens *after* the orchestrator session that dispatched the predecessor has already ended — this block, not the live Step 4B loop, is the realistic trigger point for "gating PR merged while nobody was watching."
 
-For the same reason, this reconstruction also MUST call `verify_file_overlap_edge()` (also defined in `phase-4-execution.md` Step 4B, alongside `classify_predecessor_state()` — re-declare it here too if this block runs in a fresh context) before treating a GATED or FAILED predecessor's `EDGE_KIND` edge as still blocking. <!-- Added: forge#1904 --> A predecessor that reached `needs-human`/`workflow:invalid` with no PR, or whose PR never actually touched the guessed shared file, most realistically gets *discovered* at wake time — the session that would have caught it live has already ended. Re-verifying only in the live Step 4B loop and not here would leave this exact wake-time case unfixed.
+For the same reason, this reconstruction also MUST call `verify_file_overlap_edge()` (also defined in `phase-4-execution.md` Step 4B, alongside `classify_predecessor_state()` — re-declare it here too if this block runs in a fresh context) before treating a GATED or FAILED predecessor's `EDGE_KIND` edge as still blocking. <!-- Added: forge#1904 --> A predecessor that reached `needs-human`/`workflow:invalid` with no PR, or whose PR never actually touched the guessed shared file, most realistically gets *discovered* at wake time — the session that would have caught it live has already ended. Re-verifying only in the live Step 4B loop and not here would leave this exact wake-time case unfixed. <!-- Added: forge#3697 --> `EDGE_SOFT` is likewise not retained across wake/compaction: early release (`verify_soft_edge_early()`) is a live-session mechanism only, and a reconstructed edge simply holds until its predecessor concludes.
 
 ```bash
 # Reconstruct dispatch state from GitHub after compaction / wake