forgedock 1.13.1 → 1.15.0

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, hasInvestigationExit, 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
@@ -228,8 +271,15 @@ function makeProgressEmitter(onProgress) {
  *   the last committed phase. forge#3562: when it is `phase-complete` (a
  *   multi-phase issue whose phase merged with more remaining), start a new
  *   cycle (RUN_NEXT_CYCLE) that resets committed/branch/pr and restarts at
- *   investigate. Any other terminal reason is left untouched and returns
+ *   investigate. forge#3571: `needs-human` is reopened (RUN_REOPEN) only when
+ *   a live read shows the issue OPEN with the label cleared. Any other terminal
+ *   reason (or an unreadable snapshot) 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 +303,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 +322,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 });
@@ -298,18 +371,45 @@ export async function runIssue(opts) {
   // so the run resumes from its last committed phase. Placed AFTER the I3
   // lease guard (never weaken that ordering) and BEFORE the unconditional
   // lease write below, which then publishes `terminal:false` at the reopen's
-  // higher `v`. Only `engine-error` is ever reopened; needs-human / merged /
-  // decomposed / etc. terminals are left untouched.
+  // higher `v`. `engine-error` is reopened unconditionally; forge#3571:
+  // `needs-human` only once the label is cleared. merged / decomposed / etc.
+  // terminals are left untouched.
   // forge#3562: `phase-complete` is also retryable, but as a NEW cycle
   // (RUN_NEXT_CYCLE clears committed) rather than a reopen of the same one.
   let reopened = false;
   if (retry && state?.terminal) {
-    if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete") {
+    if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete" &&
+        state.terminalReason !== "needs-human") {
       return {
         terminalReason: "not-retryable",
-        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error or phase-complete run`,
+        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error, phase-complete or needs-human run`,
       };
     }
+    // forge#3571: a human clearing `needs-human` is the hand-back signal. Reopen
+    // only on a live read showing the issue OPEN and the label gone; a label
+    // still present keeps today's refusal, and an unreadable snapshot fails closed.
+    if (state.terminalReason === "needs-human") {
+      let snap;
+      try { snap = await issueSnapshot(issue, io); } catch { snap = { ok: false, state: null }; }
+      if (!snap.ok) {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} state could not be read; --retry did not reopen the needs-human run`,
+        };
+      }
+      if (snap.state === "CLOSED") {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} is CLOSED; --retry does not reopen a needs-human run on a closed issue`,
+        };
+      }
+      if ((snap.labels || []).includes("needs-human")) {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} still carries needs-human; resolve it and remove the label before --retry`,
+        };
+      }
+    }
     // forge#3562 (SEC-3): a new cycle discards `committed`, so check the live
     // issue first. A CLOSED issue has nothing left to run; an unreadable
     // snapshot fails closed rather than resetting a possibly-finished run.
@@ -325,6 +425,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 +487,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
@@ -422,8 +553,13 @@ export async function runIssue(opts) {
         // Reuses the existing "invalid" terminal reason (TERMINAL_REASONS)
         // rather than inventing a new one; #2353 makes the same choice for
         // `close`'s own CLOSED-not-merged case.
-        const isDead = snap.labels.includes("workflow:invalid") ||
+        let isDead = snap.labels.includes("workflow:invalid") ||
           (snap.state === "CLOSED" && !snap.labels.includes("workflow:merged"));
+        // forge#3534: an investigation exit closes the issue itself without `workflow:merged`.
+        // With the trusted deliverables marker present, a CLOSED (not invalid) issue is not
+        // divergent: build.reconcile must run so the run reaches close --terminal-state investigation.
+        if (isDead && phase.id === "build" && snap.state === "CLOSED" && !snap.labels.includes("workflow:invalid") &&
+            await hasInvestigationExit(issue, io)) isDead = false;
         if (isDead) {
           const detail = `issue ${issue} is ${snap.state === "CLOSED" ? "closed" : "open"} ` +
             `with divergent state before phase ${phase.id} (labels: ${snap.labels.join(", ") || "none"})`;
@@ -462,7 +598,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, or a needs-human run once the label is cleared; --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/issue.md

@@ -367,8 +367,23 @@ Run the deterministic dedup script first (authoritative check), then fall back t
 # empty, so this is a no-op for that path.
 DEDUP_EXCLUDE_ARGS=()
 [ -n "$PROGRAMMATIC_EXCLUDE" ] && DEDUP_EXCLUDE_ARGS=(--exclude "$PROGRAMMATIC_EXCLUDE")
-DEDUP_RESULT=$(scripts/issue-dedup.sh "{PROPOSED_TITLE}" {GH_FLAG} "${DEDUP_EXCLUDE_ARGS[@]}" 2>&1)
-DEDUP_EXIT=$?
+# HELPER_SCRIPT resolver (DEDUP_SCRIPT; trusted-install tiers only, never the working directory or the target repo, #3400/#3483): plugin root, FORGE_ROOT, FORGEDOCK_HOME, FORGE_HOME, install symlink, marketplaces, newest pinned plugin cache under CLAUDE_CONFIG_DIR then ~/.claude. The cache scan matters because the plugin-root placeholder is not always substituted in forked runs.
+_l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
+_tc="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l" "$HOME/.claude/plugins/marketplaces/forgedock")"
+for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
+  [ -n "$_cfg" ] && _tc="$_tc"$'\n'"$(find -L "$_cfg/plugins/cache/forgedock/forgedock" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | awk -F/ '$NF ~ /^[0-9]+\.[0-9]+\.[0-9]+$/{split($NF,a,".");printf "%d %d %d %s\n",a[1],a[2],a[3],$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr | cut -d' ' -f4- || true)"
+done
+DEDUP_SCRIPT=""
+while IFS= read -r _c; do
+  case "$_c" in /*) [ -z "$DEDUP_SCRIPT" ] && [ -f "$_c/scripts/issue-dedup.sh" ] && DEDUP_SCRIPT="$_c/scripts/issue-dedup.sh" ;; esac
+done <<< "$_tc"
+# Unresolved helper: no deterministic result (exit 0, empty) so the LLM fallback below still runs; never exit 1 (duplicate STOP).
+if [ -n "$DEDUP_SCRIPT" ]; then
+  DEDUP_RESULT=$(bash "$DEDUP_SCRIPT" "{PROPOSED_TITLE}" {GH_FLAG} "${DEDUP_EXCLUDE_ARGS[@]}" 2>&1)
+  DEDUP_EXIT=$?
+else
+  DEDUP_RESULT=""; DEDUP_EXIT=0
+fi
 
 if [ "$DEDUP_EXIT" -eq 1 ]; then
   echo "Near-duplicate detected: $DEDUP_RESULT"

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