forgedock 1.12.0 → 1.12.1

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

@@ -38,6 +38,7 @@ const state = { v: 0, run: "r", issue: 3499, lane: "staging", committed: ["inves
   phase: null, branch: "fix/example-3499", pr: 77, terminal: false, terminalReason: null, lease: null };
 const ctx = { repo: "acme/widgets" };
 const io = {
+  gh: async () => "",
   git: async () =>
     "worktree /repo/.claude/worktrees/fix-example-3499\nHEAD 1111111\nbranch refs/heads/fix/example-3499\n",
 };
@@ -52,7 +53,7 @@ describe("engine phase args satisfy each target spec's argument-hint (forge#3499
     it(`${phase.id} (${phase.command})`, async () => {
       assert.equal(typeof phase.buildArgs, "function", `${phase.id} must define buildArgs`);
       const hint = parseHint(argumentHint(phase.command));
-      const args = await phase.buildArgs({ ...state, terminalReason: phase.id === "remediate" ? "needs-human" : null }, ctx, io);
+      const args = await phase.buildArgs({ ...state, terminalReason: phase.id === "remediate" ? "needs-human" : null, remediationKind: phase.id === "remediate" ? "inpr-fix" : null }, ctx, io);
 
       assert.ok(Array.isArray(args) && args.every((a) => typeof a === "string"), "args must be an array of strings");
       assert.ok(args.length > 1, `${phase.id} must not be invoked with only a positional`);

package/bin/engine/phases.mjs

@@ -30,33 +30,130 @@ import { PHASE_MARKERS } from "../../packages/protocol/src/phases.js";
 export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed", "engine-error", "awaiting-merge"];
 
 /**
- * Fetch the issue's comments. Returns both:
- *  - `blob`: all bodies joined into one string, for simple marker-presence checks
- *    (`has(blob, marker)`) where it doesn't matter which comment posted the marker.
- *  - `comments`: an array of individual comment bodies, preserving per-comment
- *    boundaries, for extraction that MUST be scoped to a specific comment (see
- *    `parseBranchFromMarkers()` below — forge#2184).
+ * Trust predicate for FORGE marker comments (forge#3542) — a JS port of
+ * `scripts/trusted-comments.sh`, the ONE predicate the specs use. A comment is
+ * trusted when
+ *   - its `author_association` is in FORGE_TRAIL_TRUSTED_ASSOCIATIONS
+ *     (default OWNER,MEMBER,COLLABORATOR; an explicitly EMPTY value trusts no
+ *     association — `??`, not `||`), OR
+ *   - its `user.type` is "Bot" (a GitHub App installation always reports
+ *     association NONE), OR
+ *   - its `user.login` is in FORGE_TRAIL_TRUSTED_LOGINS (default empty).
+ * A comment carrying no author data at all (a bare string, `{body}` only) is
+ * UNTRUSTED: fail closed.
+ */
+export function isTrustedComment(c) {
+  if (!c || typeof c !== "object") return false;
+  const list = (v) => String(v).split(",").map((x) => x.trim()).filter(Boolean);
+  const assoc = list(process.env.FORGE_TRAIL_TRUSTED_ASSOCIATIONS ?? "OWNER,MEMBER,COLLABORATOR");
+  const logins = list(process.env.FORGE_TRAIL_TRUSTED_LOGINS ?? "");
+  return assoc.includes(c.author_association ?? "")
+    || (c.user?.type ?? "") === "Bot"
+    || logins.includes(c.user?.login ?? "");
+}
+
+/**
+ * Fetch the issue's comments, keeping ONLY trusted ones (forge#3542). Returns
+ * `{ comments }`: an array of trusted comment bodies, preserving per-comment
+ * boundaries and chronological order. Every marker gate below goes through
+ * `markedComments()`/`hasMarker()`/`latestMarked()`, which additionally require
+ * the marker to be ANCHORED (typed header leading, sentinel on its own line) —
+ * prose that merely quotes a marker never matches.
  *
- * The `--jq '[.[].body]'` query asks `gh` for a JSON array of bodies. If the
- * response isn't valid JSON (a non-JSON gh error string, or a test mock that
- * supplies a raw marker string instead of the real API shape), fall back to
- * treating the whole blob as a single pseudo-comment — `has()` checks are
- * unaffected either way, and comment-scoped extraction simply won't match,
- * which is the safe, conservative behavior.
+ * The `--jq` query asks `gh` for one JSON object per comment
+ * (`{body, author_association, user:{type,login}}`, paginated, one per line); a
+ * single JSON array of such objects is also accepted. Anything unparsable, or a
+ * comment without author data, yields no trusted comment (fail closed) — there is
+ * deliberately no "trust unauthored" escape hatch; tests supply authored comments.
  */
 async function issueMarkers(issue, io) {
-  const out = await io.gh(["api", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq", "[.[].body]"]);
-  const blob = out || "";
-  let comments = [];
+  // `--paginate` so an issue with >30 comments still exposes its newest trail;
+  // `{...} | @json` emits one JSON document per line per page, which (unlike
+  // `[.[]]`, one array per page) concatenates safely across pages.
+  const out = await io.gh(["api", "--paginate", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq",
+    ".[] | {body, author_association, user: {type: .user.type, login: .user.login}} | @json"]);
+  const text = out || "";
+  let raw = null;
   try {
-    const parsed = JSON.parse(out);
-    if (Array.isArray(parsed)) {
-      comments = parsed.map((c) => (typeof c === "string" ? c : (c && c.body) || ""));
-    }
-  } catch {
-    comments = blob ? [blob] : [];
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) raw = parsed;
+  } catch { /* not a single JSON document — try one JSON value per line */ }
+  if (!raw) {
+    try {
+      const vals = text.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
+      // Tolerate a line that is itself an array (concatenated pages).
+      if (vals.length > 0) raw = vals.flatMap((v) => (Array.isArray(v) ? v : [v]));
+    } catch { /* fall through */ }
   }
-  return { blob, comments };
+  const comments = (raw || [])
+    .filter((c) => c && typeof c === "object" && typeof c.body === "string" && isTrustedComment(c))
+    .map((c) => c.body);
+  return { comments };
+}
+
+const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** True when `body` STARTS with the typed header `<!-- {header}` (e.g. `FORGE:BUILDER`). */
+function startsWithHeader(body, header) {
+  return typeof body === "string" && new RegExp(`^\\s*<!--\\s*${reEscape(header)}(?![A-Za-z0-9_])`).test(body);
+}
+/** True when `body` carries `<!-- {sentinel} -->` as a full line of its own. */
+function hasSentinelLine(body, sentinel) {
+  return new RegExp(`^[ \\t]*<!--[ \\t]*${reEscape(sentinel)}[ \\t]*-->[ \\t]*$`, "m").test(body);
+}
+/**
+ * Trusted comments that START with `header` AND carry `sentinel` as a full line.
+ * The sentinel is not required to be the LAST line: `FORGE:BUILDER:COMPLETE` is
+ * appended in place to an existing builder comment (validate.md Phase V5).
+ */
+function markedComments(comments, header, sentinel) {
+  return comments.filter((b) => startsWithHeader(b, header) && hasSentinelLine(b, sentinel));
+}
+function hasMarker(comments, header, sentinel) { return markedComments(comments, header, sentinel).length > 0; }
+/** Newest marked comment, or null. */
+function latestMarked(comments, header, sentinel) {
+  const all = markedComments(comments, header, sentinel);
+  return all.length ? all[all.length - 1] : null;
+}
+/**
+ * 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).
+ */
+async function trustedCommentBodies(issue, io) {
+  try { return (await issueMarkers(issue, io)).comments; } catch { return []; }
+}
+
+/** build.md B5.5 Step 2: a SIZE_OVERRIDE needs a non-empty justification — the first non-blank, non-HTML-comment line after the marker line. */
+function overrideHasJustification(body) {
+  const lines = String(body).replace(/\r\n/g, "\n").split("\n");
+  return lines.slice(1).some((l) => l.trim() !== "" && !l.trimStart().startsWith("<!--"));
+}
+
+/**
+ * Size-gate routing (build.md B5.5). True only when the latest `FORGE:DIFF_SIZE`
+ * says `result: OVER`, carries a `### Split Proposal` (the discriminator against
+ * the decompose-loop-guard Blocked exit, which also posts OVER but must not
+ * re-enter decompose), and no justified `FORGE:SIZE_OVERRIDE` comment follows it,
+ * and the issue is not already decomposed. `comments` MUST be TRUSTED bodies in
+ * chronological order (see trustedCommentBodies); an untrusted comment never
+ * reaches this function.
+ */
+function sizeGateRoutesToDecompose(comments) {
+  const gate = PHASE_MARKERS.build.sizeGateMarker;
+  const override = PHASE_MARKERS.build.sizeOverrideMarker;
+  const starts = (c, m) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${m}`);
+  if (comments.some((c) => starts(c, "FORGE:DECOMPOSED"))) return false;
+  let idx = -1;
+  for (let i = comments.length - 1; i >= 0; i--) if (starts(comments[i], gate)) { idx = i; break; }
+  if (idx < 0) return false;
+  const body = comments[idx].replace(/\r\n/g, "\n");
+  const m = /^result:[ \t]*(OK|OVERRIDDEN|OVER)[ \t]*$/m.exec(body);
+  if (!m || m[1] !== "OVER" || !/^###[ \t]+Split Proposal\b/m.test(body)) return false;
+  return !comments.slice(idx + 1).some((c) => starts(c, override) && overrideHasJustification(c));
+}
+/** Cheap untrusted pre-check: does ANY comment look like an OVER gate? Only then is the trusted fetch worth making. */
+function mayRouteToDecompose(comments) {
+  const gate = PHASE_MARKERS.build.sizeGateMarker;
+  return comments.some((c) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${gate}`) && /^result:[ \t]*OVER[ \t]*\r?$/m.test(c));
 }
 /**
  * Count commits on `branch` ahead of `lane`'s base. On the first build the
@@ -94,28 +191,6 @@ async function commitsAhead(lane, branch, io) {
     return -1;
   }
 }
-/**
- * Marker-presence check used throughout this file — including
- * `FORGE:BUILDER:COMPLETE` eligibility gates in the "build" phase's
- * `reconcile`/`detectOutcome` below (forge#2194 — investigated, no change).
- *
- * This is a plain substring test, deliberately, for consistency: every other
- * marker gate in this file (`INVESTIGATION:INVALID`, `DECOMPOSE:YES`,
- * `INVESTIGATION:COMPLETE`, `FORGE:CONTEXT:COMPLETE`,
- * `FORGE:ARCHITECT:COMPLETE`, `workflow:merged`) uses the identical
- * substring/membership technique — singling out `FORGE:BUILDER:COMPLETE`
- * alone for a "structured" parse would be inconsistent and would not close
- * any real gap: the actual trust boundary for issue-comment content is
- * *authorship* (can an untrusted actor post a comment on this issue at all),
- * not *format*. Nothing in this engine validates comment authorship for any
- * marker today, so an actor able to post an arbitrary comment could just as
- * easily post whatever "structured" shape a parser would accept — format
- * hardening alone buys nothing here. If comment-spoofing is ever a concern
- * worth addressing, the fix is an author allowlist applied uniformly to all
- * markers, not a bespoke parser for this one field.
- */
-function has(blob, marker) { return blob.includes(marker); }
-
 /**
  * The interactive workflow persists its conservative complexity decision in a
  * FORGE:FAST_PATH comment. The engine must consume that decision too; otherwise
@@ -126,7 +201,7 @@ function has(blob, marker) { return blob.includes(marker); }
 function complexityBand(comments) {
   for (let i = comments.length - 1; i >= 0; i--) {
     const body = comments[i];
-    if (!body?.includes("FORGE:FAST_PATH")) continue;
+    if (!startsWithHeader(body, "FORGE:FAST_PATH")) continue;
     const match = body.match(/\*\*COMPLEXITY_BAND\*\*:\s*([A-Z_]+)/);
     if (match) return match[1];
   }
@@ -171,8 +246,9 @@ export async function issueSnapshot(issue, io) {
  * reliable source, since the branch name is slug-derived from the issue
  * title and cannot be guessed or precomputed (forge#2174).
  *
- * SCOPING (forge#2184): only comments whose body contains `FORGE:BUILDER:COMPLETE`
- * — the same completion marker the build phase already gates on — are eligible
+ * SCOPING (forge#2184, forge#3542): only TRUSTED comments that start with the
+ * `<!-- FORGE:BUILDER` header and carry `<!-- FORGE:BUILDER:COMPLETE -->` as a full
+ * line — the same anchored completion check the build phase gates on — are eligible
  * to supply the branch. A `**Branch**:` field inside any other comment (a
  * FORGE:CONTRACT, FORGE:ARCHITECT, FORGE:CONTEXT, reviewer, or remediation
  * comment) is never considered, even if it happens to match the same regex
@@ -203,7 +279,7 @@ function parseBranchFromMarkers(comments) {
   const re = /\*\*Branch\*\*:\s*`([^`]+)`/;
   for (let i = comments.length - 1; i >= 0; i--) {
     const body = comments[i];
-    if (!body || !body.includes(PHASE_MARKERS.build.completionMarker)) continue;
+    if (!body || !startsWithHeader(body, PHASE_MARKERS.build.header) || !hasSentinelLine(body, PHASE_MARKERS.build.completionMarker)) continue;
     const match = body.match(re);
     if (match) return match[1];
   }
@@ -229,13 +305,11 @@ function resolveBranch(state, comments) {
  * skips both children). A BLOCKED / missing-arg child is not hidden here: it
  * shows up as `absent`, never as a fabricated "skipped" commit.
  */
-function buildChildEvidence(blob, comments) {
+function buildChildEvidence(comments) {
   const trivial = complexityBand(comments) === "TRIVIAL";
-  const state = (marker) => (has(blob, marker) ? "complete" : trivial ? "skipped-trivial" : "absent");
-  return {
-    context: state(PHASE_MARKERS.context.completionMarker),
-    architect: state(PHASE_MARKERS.architect.completionMarker),
-  };
+  const state = (phase) => (hasMarker(comments, PHASE_MARKERS[phase].header, PHASE_MARKERS[phase].completionMarker)
+    ? "complete" : trivial ? "skipped-trivial" : "absent");
+  return { context: state("context"), architect: state("architect") };
 }
 
 // ---------------------------------------------------------------------------
@@ -255,6 +329,20 @@ export class PhaseArgsError extends Error {
   constructor(message) { super(message); this.name = "PhaseArgsError"; this.code = "PHASE_ARGS_INVALID"; }
 }
 
+/**
+ * forge#3530: review `remediation` kind -> the bound marker router Phase 4R posts
+ * (commands/work-on.md). review.md R4 counts these; remediate.md M0 keys its per-kind
+ * guard on them.
+ */
+export const REMEDIATION_BOUND_MARKERS = Object.freeze({
+  "ci-gate": "CI_REMEDIATION",
+  "inpr-fix": "INPR_REMEDIATION",
+  "base-sync": "BASESYNC_REMEDIATION",
+});
+function isRemediationKind(k) {
+  return typeof k === "string" && Object.hasOwn(REMEDIATION_BOUND_MARKERS, k);
+}
+
 const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const BRANCH_RE = /^[A-Za-z0-9._][A-Za-z0-9._\/-]*$/;
 const LANE_RE = BRANCH_RE;
@@ -299,6 +387,29 @@ async function reviewArgs(state, ctx, io) {
           "--branch", need(state.branch, "branch", BRANCH_RE), ...baseArgs(state)];
 }
 
+/**
+ * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
+ * trusted `<!-- FORGE:INVESTIGATOR` report (forge#3542 selects it; forge#3543's
+ * parsing applies within it). Within the comment the strict structured signals
+ * decide, in order: the `**YES**`/`**NO**` verdict under `### Decomposition
+ * Assessment`, then a marker alone on its own line (`<!-- DECOMPOSE:YES|NO -->`).
+ * Quoted markers mid-line are ignored. A heading/marker conflict fails safe (not
+ * decomposed) and is logged.
+ */
+function isDecomposed(report) {
+  const text = String(report || "").replace(/\r\n/g, "\n");
+  const section = text.match(/^### Decomposition Assessment[^\n]*\n([\s\S]*?)(?=^###[^#]|(?![\s\S]))/m);
+  const verdict = section ? (/^\s*\*\*(YES|NO)\*\*/m.exec(section[1]) || [])[1] : undefined;
+  const markers = new Set();
+  for (const m of text.matchAll(/^<!-- DECOMPOSE:(YES|NO) -->[ \t]*$/gm)) markers.add(m[1]);
+  const marker = markers.size === 1 ? [...markers][0] : undefined;
+  if (markers.size > 1 || (verdict && marker && verdict !== marker)) {
+    console.error(`[engine] conflicting decomposition signals (heading=${verdict ?? "none"}, markers=${[...markers].join("+") || "none"}); treating as not decomposed`);
+    return false;
+  }
+  return (verdict ?? marker) === "YES";
+}
+
 /** @type {Phase[]} */
 export const PHASES = [
   {
@@ -307,13 +418,24 @@ export const PHASES = [
     buildArgs: async (state, ctx) => [String(state.issue), ...repoArgs(ctx)],
     entryCondition: () => true,
     async detectOutcome(state, io) {
-      const { blob } = await issueMarkers(state.issue, io);
-      if (has(blob, PHASE_MARKERS.investigate.invalidMarker))
+      // forge#3542: evaluate ONE comment — the newest trusted comment that starts with
+      // the `<!-- FORGE:INVESTIGATOR` header — and read its verdict from its LAST
+      // non-empty line (the sentinel investigate.md Phase 1C closes with). A report that
+      // merely quotes `INVESTIGATION:INVALID` in prose, or any untrusted comment, can
+      // never flip the verdict.
+      const { comments } = await issueMarkers(state.issue, io);
+      const report = [...comments].reverse().find((b) => startsWithHeader(b, PHASE_MARKERS.investigate.header));
+      const closing = report ? report.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).pop() : "";
+      const invalid = `<!-- ${PHASE_MARKERS.investigate.invalidMarker} -->`;
+      const complete = `<!-- ${PHASE_MARKERS.investigate.completionMarker} -->`;
+      if (closing === invalid)
         return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
-      if (has(blob, PHASE_MARKERS.investigate.decomposedMarker))
-        return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
-      if (has(blob, PHASE_MARKERS.investigate.completionMarker))
+      if (closing === complete) {
+        // investigate.md emits `### Decomposition Assessment` then `**YES**|**NO**`.
+        if (isDecomposed(report))
+          return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
         return { status: "committed", outputs: { verdict: "CONFIRMED" } };
+      }
       return { status: "failed", detail: `no ${PHASE_MARKERS.investigate.completionMarker} marker` };
     },
     // forge#2379: no longer terminal after "decomposed" — that reason now
@@ -337,8 +459,8 @@ export const PHASES = [
     buildArgs: async (state, ctx) => [String(state.issue), ...repoArgs(ctx)],
     entryCondition: (s) => s.terminalReason === "decomposed",
     async detectOutcome(state, io) {
-      const { blob } = await issueMarkers(state.issue, io);
-      if (has(blob, PHASE_MARKERS.decompose.completionMarker))
+      const { comments } = await issueMarkers(state.issue, io);
+      if (hasMarker(comments, PHASE_MARKERS.decompose.header, PHASE_MARKERS.decompose.completionMarker))
         return { status: "committed", terminalReason: "decomposed", outputs: {} };
       return { status: "failed", detail: `no ${PHASE_MARKERS.decompose.completionMarker} marker` };
     },
@@ -359,16 +481,22 @@ 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 { blob, comments } = await issueMarkers(state.issue, io);
+      const { comments } = await issueMarkers(state.issue, io);
       const branch = resolveBranch(state, comments);
-      if (branch && has(blob, PHASE_MARKERS.build.completionMarker) && (await commitsAhead(state.lane, branch, io)) > 0) {
+      if (branch && hasMarker(comments, PHASE_MARKERS.build.header, PHASE_MARKERS.build.completionMarker) && (await commitsAhead(state.lane, branch, io)) > 0) {
         return { satisfied: true, outputs: { branch } };
       }
+      // forge#3535: work already merged into the lane has ahead=0 by definition;
+      // positive merged-PR evidence (base === lane) means build is satisfied.
+      if (branch && hasMarker(comments, PHASE_MARKERS.build.header, PHASE_MARKERS.build.completionMarker)) {
+        const merged = await mergedPrForBranch(branch, state.lane, io);
+        if (merged) return { satisfied: true, outputs: { branch, pr: merged.number } };
+      }
       return { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const { blob, comments } = await issueMarkers(state.issue, io);
-      const complete = has(blob, PHASE_MARKERS.build.completionMarker); // #1305: require :COMPLETE …
+      const { comments } = await issueMarkers(state.issue, io);
+      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
       // resolveBranch()/parseBranchFromMarkers() above (forge#2174, forge#2184).
@@ -380,7 +508,14 @@ export const PHASES = [
       // non-retryable guard below on the very first attempt.
       const ahead = branch ? await commitsAhead(state.lane, branch, io) : -1; // … AND real commits
       if (complete && ahead > 0) {
-        return { status: "committed", outputs: { branch, ...buildChildEvidence(blob, comments) } };
+        return { status: "committed", outputs: { branch, ...buildChildEvidence(comments) } };
+      }
+      // 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))) {
+        return { status: "committed", terminalReason: "decomposed", outputs: branch ? { branch } : {} };
       }
       const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
       // forge#2176: when the builder has already posted FORGE:BUILDER:COMPLETE
@@ -409,6 +544,15 @@ export const PHASES = [
       // resolve, so both must stay retryable. Only a successfully-computed
       // ahead of 0 on a *resolved* branch (a real "nothing new to commit"
       // result) is the true fixed point this non-retryable signal targets.
+      // forge#3535: before the fixed point, check whether the branch already
+      // merged into the lane — then ahead=0 is the success state, not a missing
+      // build. Only positive evidence converts; everything else falls through.
+      if (complete && branch) {
+        const merged = await mergedPrForBranch(branch, state.lane, io);
+        if (merged) {
+          return { status: "committed", outputs: { branch, pr: merged.number, ...buildChildEvidence(comments) } };
+        }
+      }
       if (complete && ahead !== -1) return { status: "failed", detail, retryable: false };
       return { status: "failed", detail };
     },
@@ -427,13 +571,21 @@ export const PHASES = [
       if (!pr) return { status: "failed", detail: "no PR created" };
       if (pr.merged) return { status: "committed", outputs: { pr: pr.number } };
       // forge#3521: the spec (commands/work-on/review.md) signals an in-PR fix
-      // by labelling the ISSUE needs-human and returning REVIEW_RESULT
-      // `status: NEXT / next: remediate`; the PR label is back-compat only.
+      // by returning REVIEW_RESULT `status: NEXT / next: remediate`. forge#3541: the
+      // issue is labelled `workflow:remediating` (non-human "autonomous remediation
+      // pending"), no longer `needs-human`; both labels still trigger the handoff below
+      // (needs-human = back-compat for older runs). The PR label is back-compat only.
       // The PR number from GitHub (openPrFor) always wins over parsed text.
       const outputs = { pr: pr.number };
       const escalated = { status: "blocked", detail: "review escalated", outputs };
-      if (pr.needsHuman) return escalated;
       const rr = parseReviewResult(result?.text);
+      // forge#3530: carry the review's remediation kind (router Phase 4R parity) so the
+      // remediate phase can post the matching bound marker. Untrusted model output: only
+      // the three known kinds are carried verbatim; any other non-empty value is recorded as
+      // the "unknown" sentinel (never the raw text) so remediate's buildArgs fails closed.
+      if (rr && rr.status === "NEXT" && rr.next === "remediate" && rr.remediation)
+        outputs.remediation = isRemediationKind(rr.remediation) ? rr.remediation : "unknown";
+      if (pr.needsHuman || pr.remediating) return escalated;
       if (rr && rr.status === "NEXT" && rr.next === "remediate") return escalated;
       // An explicit REVIEW_RESULT status is authoritative: BLOCKED/COMPLETE exits
       // (phase trail, ci gate, base conflict, merge refusal) also label the issue
@@ -441,7 +593,7 @@ export const PHASES = [
       if (rr && rr.status) return { status: "failed", detail: "PR open, not merged", retryable: false, handoff: false, outputs };
       let snap = null;
       try { snap = await issueSnapshot(state.issue, io); } catch { snap = null; }
-      if (snap?.ok && snap.labels.includes("needs-human")) return escalated;
+      if (snap?.ok && (snap.labels.includes("needs-human") || snap.labels.includes("workflow:remediating"))) return escalated;
       return { status: "failed", detail: "PR open, not merged", retryable: false, outputs };
     },
   },
@@ -461,18 +613,62 @@ export const PHASES = [
     // handing the PR to remediation in the same run.
     id: "remediate",
     command: "work-on/remediate",
-    buildArgs: async (state, ctx) => [
-      need(state.pr, "pr", /^[0-9]+$/), "--issue", String(state.issue), ...repoArgs(ctx), ...baseArgs(state),
-    ],
+    // forge#3530: this is the engine's second implementation of router Phase 4R
+    // (commands/work-on.md): post the per-kind bound marker immediately BEFORE
+    // dispatching remediation, so remediate.md M0's per-kind guard and review.md R4's
+    // loop bounds see it. Fail closed (PhaseArgsError -> engine-error, no runner call)
+    // on a missing/unknown kind or a marker that cannot be posted: an unrecorded bound
+    // must not run. Keep in sync with Phase 4R.
+    buildArgs: async (state, ctx, io) => {
+      const pr = need(state.pr, "pr", /^[0-9]+$/);
+      const kind = state.remediationKind ?? null;
+      const legacyArgs = () => [pr, "--issue", String(state.issue), ...repoArgs(ctx), ...baseArgs(state)];
+      // Legacy handoff with no kind (needs-human label fallback, or no REVIEW_RESULT): there
+      // is nothing to bind, so dispatch as before. remediate.md M0 then applies its default
+      // single-attempt guard. A present-but-unknown kind is never dispatched.
+      if (kind === null) return legacyArgs();
+      if (!isRemediationKind(kind))
+        throw new PhaseArgsError(`unknown remediation kind: ${JSON.stringify(kind)}`);
+      const boundMarker = REMEDIATION_BOUND_MARKERS[kind];
+      const marker = `<!-- FORGE:${boundMarker}: pr=${pr} -->`;
+      try {
+        const { comments } = await issueMarkers(state.issue, io);
+        // Resume idempotency: a handoff interrupted after the marker post must not double-count.
+        // forge#3542: only a full-line marker in a trusted comment counts.
+        if (!comments.some((b) => hasSentinelLine(b, `FORGE:${boundMarker}: pr=${pr}`))) {
+          await io.gh(["issue", "comment", String(state.issue), "--body",
+            `${marker}\nReview handed PR #${pr} to remediation (${kind}); the engine is dispatching it once.`]);
+        }
+      } catch (e) {
+        throw new PhaseArgsError(`github-unavailable: could not post FORGE:${boundMarker}; remediation not invoked (${e?.message || e})`);
+      }
+      return legacyArgs();
+    },
     entryCondition: (s) => s.committed.includes("review") && s.terminalReason === "needs-human",
     async detectOutcome(state, io) {
-      const { blob } = await issueMarkers(state.issue, io);
-      if (!has(blob, PHASE_MARKERS.remediate.completionMarker))
-        return { status: "failed", detail: `no ${PHASE_MARKERS.remediate.completionMarker} marker` };
+      // forge#3530: read the NEWEST completed trail only. A concatenated oldest-first blob
+      // returned a stale outcome from an earlier remediation when a later one posted nothing.
+      const { comments } = await issueMarkers(state.issue, io);
+      const completion = PHASE_MARKERS.remediate.completionMarker;
+      // forge#3542: trusted, header-led comment with the sentinel as its own line.
+      // The trail must also belong to THIS run: when a per-kind bound marker was posted for
+      // this PR (buildArgs above), only trails posted AFTER the newest such trusted marker
+      // count — a stale earlier trail (or a forged one that predates dispatch) never decides.
+      let scoped = comments;
+      if (isRemediationKind(state.remediationKind ?? null) && state.pr != null) {
+        const bound = `FORGE:${REMEDIATION_BOUND_MARKERS[state.remediationKind]}: pr=${state.pr}`;
+        let at = -1;
+        comments.forEach((b, i) => { if (hasSentinelLine(b, bound)) at = i; });
+        if (at >= 0) scoped = comments.slice(at + 1);
+      }
+      const latest = latestMarked(scoped, PHASE_MARKERS.remediate.header, completion);
+      if (latest === null)
+        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).
-      const match = blob.match(/\*\*Re-gate outcome\*\*:\s*([A-Z-]+)/);
+      const matches = [...latest.matchAll(/\*\*Re-gate outcome\*\*:\s*([A-Z-]+)/g)];
+      const match = matches.length ? matches[matches.length - 1] : null;
       const reGateOutcome = match ? match[1] : null;
       switch (reGateOutcome) {
         case "AUTO-LANDED":
@@ -580,6 +776,26 @@ async function openPrFor(state, io) {
   const out = await io.gh(["pr", "list", "--head", state.branch, "--json", "number", "--state", "all"]);
   try { const a = JSON.parse(out || "[]"); return a[0]?.number ?? null; } catch { return null; }
 }
+/**
+ * forge#3535: the merged PR (if any) that shipped `branch` into `lane`.
+ * Build keys off the branch resolved from FORGE:BUILDER:COMPLETE, not
+ * `state.branch` (null on a fresh re-run), so this takes the branch explicitly.
+ * A PR merged into a different base, a closed-unmerged PR, no PR, or any
+ * gh/JSON error yields null: unknown is never "merged" (forge#3504/#3506).
+ * Returns `{ number }` with a real integer PR number, else null.
+ */
+async function mergedPrForBranch(branch, lane, io) {
+  if (!branch || !lane) return null;
+  try {
+    const out = await io.gh(["pr", "list", "--head", branch, "--state", "all",
+      "--json", "number,state,mergedAt,baseRefName"]);
+    const a = JSON.parse(out || "[]");
+    if (!Array.isArray(a)) return null;
+    const hit = a.find((p) => p && typeof p === "object" && Number.isInteger(p.number)
+      && (!!p.mergedAt || p.state === "MERGED") && p.baseRefName === lane);
+    return hit ? { number: hit.number } : null;
+  } catch { return null; }
+}
 async function prStatusFor(state, io) {
   const n = await openPrFor(state, io);
   if (!n) return null;
@@ -588,7 +804,8 @@ async function prStatusFor(state, io) {
   try { j = JSON.parse(out || "{}"); } catch { return null; }
   const labels = (j.labels || []).map((l) => l.name || l);
   return { number: j.number, merged: !!j.mergedAt || j.state === "MERGED",
-           needsHuman: labels.includes("needs-human") };
+           needsHuman: labels.includes("needs-human"),
+           remediating: labels.includes("workflow:remediating") };
 }
 
 /** The engine's transition function: first uncommitted phase whose gate holds. */

package/bin/engine/runlog.mjs

@@ -57,7 +57,10 @@ export function deriveState(events) {
   /** @type {import("./phases.mjs").RunState} */
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
-              terminalReason: null, lease: null, lastRateLimit: null };
+              terminalReason: null, lease: null, lastRateLimit: null,
+              remediationKind: null };
+  // forge#3528: handoff reason of the LAST PHASE_COMMIT only (replaced, not sticky).
+  let lastCommitReason = null;
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -71,6 +74,11 @@ export function deriveState(events) {
         // forge#3504: a blocked phase persists its reason so a resumed run still routes to
         // remediate instead of defaulting to a "merged" close.
         if (e.terminalReason) s.terminalReason = e.terminalReason;
+        lastCommitReason = e.terminalReason ?? null;
+        // forge#3530: the review's remediation kind must survive resume. A later review
+        // commit replaces it; a committed remediate consumes it, so it is never reused.
+        if (e.phase === "review") s.remediationKind = e.outputs?.remediation ?? null;
+        else if (e.phase === "remediate") s.remediationKind = null;
         break;
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
@@ -78,8 +86,11 @@ export function deriveState(events) {
       // forge#3511: an explicit `run-issue --retry` reopens an engine-error
       // terminal. Bumping `v` makes the local state newer than the stale
       // remote terminal index so reconcile remirrors instead of re-terminating.
+      // forge#3528: RUN_TERMINAL overwrote the persisted handoff reason
+      // (needs-human / decomposed); restore the last commit's reason so the
+      // retry re-enters remediate/decompose instead of close/build.
       case "RUN_REOPEN":
-        s.terminal = false; s.terminalReason = null; s.v = e.seq;
+        s.terminal = false; s.terminalReason = lastCommitReason; s.v = e.seq;
         break;
       // forge#2524: a session-limit pause is purely informational — it does
       // NOT touch committed/terminal/terminalReason. The phase that hit the

package/bin/engine-cli.mjs

@@ -26,6 +26,7 @@ export const ACTIVE_WORKFLOW_LABELS = [
   "workflow:ready-to-build",
   "workflow:building",
   "workflow:in-review",
+  "workflow:remediating",
 ];
 
 const pexec = promisify(execFile);

package/bin/engine.mjs

@@ -359,10 +359,13 @@ export async function runIssue(opts) {
     // decompose) and before RUN_TERMINAL leaves its persisted reason on the commit event. Resume
     // must honour that reason instead of picking the next phase (close would throw in buildArgs
     // and end as engine-error; build would run on a decomposed parent). Review's `needs-human`
-    // is a handoff to remediate, so only these two committed phases trigger the guard.
+    // is a handoff to remediate, so only these committed phases trigger the guard.
     if (state.terminalReason && TERMINAL_REASONS.includes(state.terminalReason) &&
         ((state.committed.includes("remediate") && !["merged", "decomposed", "invalid"].includes(state.terminalReason)) ||
-         (state.committed.includes("decompose") && state.terminalReason === "decomposed")))
+         (state.committed.includes("decompose") && state.terminalReason === "decomposed") ||
+         // forge#3512: investigate persists `invalid` on its own commit. Only when investigate is
+         // the LAST committed phase: a later remediate/close commit carrying `invalid` is a handoff.
+         (state.committed[state.committed.length - 1] === "investigate" && state.terminalReason === "invalid")))
       return await terminate(state, state.terminalReason);
     // forge#2352: state-vs-GitHub divergence guard. Every phase's own
     // `entryCondition` only ever checked `state.committed` (local run-log
@@ -674,7 +677,8 @@ export async function runIssue(opts) {
     // is seen), phase.id is "decompose" — not "investigate" — so this
     // exemption does not apply and the normal terminate() path below fires,
     // ending the run for real.
-    const isDecomposeHandoff = phase.id === "investigate" && terminalReason === "decomposed";
+    // build also hands off: the B5.5 size gate (NEEDS_DECOMPOSE) reports "decomposed".
+    const isDecomposeHandoff = (phase.id === "investigate" || phase.id === "build") && terminalReason === "decomposed";
     if (terminalReason && TERMINAL_REASONS.includes(terminalReason) &&
         !isDecomposeHandoff && !isRemediationHandoff)
       return await terminate(state, terminalReason, outcome.detail);
@@ -822,6 +826,7 @@ function eventsFromIndex(idx) {
     const outputs = {};
     if (phase === "build" && idx.branch) outputs.branch = idx.branch;
     if (phase === "review" && idx.pr != null) outputs.pr = idx.pr;
+    if (phase === "review" && idx.remediationKind) outputs.remediation = idx.remediationKind;
     events.push({ event: "PHASE_COMMIT", phase, outputs });
   }
   // forge#3506: a non-terminal reason is a handoff (e.g. review -> remediate). Replay it on

package/bin/hooks/interactive-engine.mjs

@@ -116,6 +116,9 @@ const PHASE_MARKERS = [
  * @param {string} text
  * @returns {{ phaseId: string|null, terminalReason: string|null }}
  */
+// forge#3542: this scans a session TRANSCRIPT (tool results / assistant text), which carries no
+// comment authorship, so it is outside the headless engine's trusted + anchored marker model
+// (bin/engine/phases.mjs). Advisory phase detection only.
 export function detectPhaseFromText(text) {
   const str = typeof text === "string" ? text : "";
   let phaseId = null;