forgedock 1.28.0 → 1.29.1

package/bin/lean/orchestrate.mjs

@@ -50,8 +50,23 @@
  * With `remote.fallbackLocal`, a lane placed remote runs on the host path instead of waiting when `max` remote lanes run,
  * and instead of stopping when the budget refuses. The final `{where, reason}` is kept on the run record and the row as
  * `placement` and passed to `runOne` as `ctx.placement` (the lane records it in its FORGE:STATE).
+ *
+ * In-batch recovery (#4267), on by default: this module recovers only when `recovery: {maxAttempts}` is passed, and the
+ * CLI always passes it (forge.yaml `orchestration.recovery.max_attempts`, default 1; 0 disables): a row `classifyNeedsHuman` calls
+ * recoverable (needs-human `ci.red` / `base.conflict` / `builder.block_untyped`, `contract.invalid` after a mid-run issue
+ * edit, `ci-pending` whose PR `conflicting(issue, pr)` says conflicts) is not final while its persisted `recoveries` stay
+ * under `maxAttempts`: it is requeued as a recovery lane (`ctx.recover = {code, attempt, final}`, `final` when attempt ==
+ * `maxAttempts`) under the same admission as any lane, so its dependents stay queued. Only a final lane relabels needs-human
+ * itself; a non-final attempt that ends needs-human/ci-pending without a successor is relabelled here, once (#4302). A recovery
+ * still queued when the batch exits (breaker, budget, hold, or a resume that does not relaunch it) is relabelled once with the
+ * full persisted lane reason (#4315).
+ * A merged recovery row carries `recovered: <code>`; any other end is final with `recovery` evidence. Human codes (`builder.blocked`) are never recovered. Every operational decision the runner takes
+ * (recovery, engine-error relaunch, dependency requeue, sub-issues added) goes to `decide({issue, what, why, alternative})`,
+ * fire-and-forget: the runner never waits on it.
  */
 import { parseDependsOn } from "../engine/phases.mjs";
+import { classifyNeedsHuman, recoveryCodeOf } from "../engine/outcome-codes.mjs";
+import { recoveryEvidence } from "./render.mjs";
 
 // A dependency that finished like this no longer blocks its dependents.
 const SATISFIED = new Set(["merged", "invalid"]);
@@ -144,7 +159,8 @@ const toMap = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [Number(k),
  */
 export async function orchestrate({ issues, parallel = 3, runOne, readBody, prefilter = null, resolveLane = null, now = () => Date.now(), onUpdate = () => {}, onCrossLane = () => {},
   store = null, adopt = null, getParallel = null, breaker = null, maxDeferrals = DEFAULT_MAX_DEFERRALS, sleep = cancellableSleep, pollMs = 5000,
-  classify = null, maintenance = null, limits = null, identity = () => "default", batchId = null, drift = null, sched = null, priorityOf = null, remote = null, beforeAdmit = null }) {
+  classify = null, maintenance = null, limits = null, identity = () => "default", batchId = null, drift = null, sched = null, priorityOf = null, remote = null, beforeAdmit = null,
+  recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
   const set = new Set(order);
@@ -193,13 +209,22 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   const sandboxUse = toMap(saved?.sandbox); // issue -> {minutes, cost_usd, attempts} (#4255)
   const remoteCpm = Number(remote?.costPerMinute) > 0 ? Number(remote.costPerMinute) : 0;
   let budgetStop = null, budgetHit = null; // this pass's refusal under on_budget stop; the last refusal reason
+  const recoveryMax = Number.isInteger(recovery?.maxAttempts) && recovery.maxAttempts > 0 ? recovery.maxAttempts : 0;
+  const recoveries = toMap(saved?.recoveries); // issue -> recovery lanes launched (#4267)
+  const recovering = toMap(saved?.recovering); // issue -> {code, attempt, detail, outcome, ...} of the recovery lane queued or running
+  const relabelled = new Set(saved?.relabelled ?? []); // #4315: queued recoveries relabelled needs-human when a batch stopped
+  // #4267: decisions are recorded, never awaited: a failing or slow recorder cannot block the batch.
+  const decided = (d) => { try { Promise.resolve(decide?.(d)).catch(() => {}); } catch { /* best effort */ } };
+  const firstLine = (x) => String(x ?? "").split("\n")[0].slice(0, 300);
 
   const save = () => {
     if (!store) return;
     store.save({ v: 1, order, deps: toObj(deps), lanes: toObj(lanes), crossSeen: [...crossSeen], results: toObj(results), running: toObj(runRecs),
       pending, notBefore: toObj(notBefore), requeues: toObj(requeues), deferrals: toObj(deferrals), engineErrors: toObj(engineErrors),
       prefilter: toObj(checked), errorTimes, breaker: tripped, ...(budget ? { classes: toObj(classes), dispatch: { ...dispatch } } : {}),
-      ...(reg ? { priorities: toObj(priorities) } : {}), ...(sandboxUse.size ? { sandbox: toObj(sandboxUse) } : {}) });
+      ...(reg ? { priorities: toObj(priorities) } : {}), ...(sandboxUse.size ? { sandbox: toObj(sandboxUse) } : {}),
+      ...(recoveries.size || recovering.size ? { recoveries: toObj(recoveries), recovering: toObj(recovering) } : {}),
+      ...(relabelled.size ? { relabelled: [...relabelled] } : {}) });
   };
   const update = (row) => { store?.log?.(row); onUpdate(row); };
   const classifyOne = async (n) => {
@@ -320,7 +345,9 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
 
   // Apply one lane's result: requeue it (deferred, dependency-open, engine-error) or record its final row.
   const settle = async (n, r, rec, pf) => {
-    const row = { issue: n, outcome: r?.terminalReason ?? "engine-error", pr: r?.pr ?? null, cost_usd: (r?.cost_usd ?? 0) + (pf?.cost_usd ?? 0), minutes: Math.round((now() - rec.startedAt) / 6000) / 10, detail: r?.detail, ...(r?.code ? { code: r.code } : {}), ...(pf ? { prefilter: pf } : {}),
+    // #4304: the pre-filter runs once per issue; a recovery pass's row adds the earlier attempt's cost, which already holds it.
+    const pfCost = recovering.has(n) ? 0 : (pf?.cost_usd ?? 0);
+    const row = { issue: n, outcome: r?.terminalReason ?? "engine-error", pr: r?.pr ?? null, cost_usd: (r?.cost_usd ?? 0) + pfCost, minutes: Math.round((now() - rec.startedAt) / 6000) / 10, detail: r?.detail, ...(r?.code ? { code: r.code } : {}), ...(pf ? { prefilter: pf } : {}),
       ...(r?.waits && typeof r.waits === "object" ? { waits: r.waits } : {}), ...(Number.isInteger(r?.heavyQueueMax) ? { heavyQueueMax: r.heavyQueueMax } : {}),
       ...(rec?.placement ? { placement: rec.placement } : {}) };
     const depList = (Array.isArray(r?.dependencies) ? r.dependencies : []).filter((d) => Number.isSafeInteger(d) && d > 0 && d !== n);
@@ -341,6 +368,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       // Dependencies already done but still open on GitHub: a delay instead of a hot relaunch loop.
       const allDone = depList.every((d) => results.has(d) && SATISFIED.has(results.get(d).outcome));
       requeue(n, allDone ? DEP_REQUEUE_DELAY_S * 1000 : 0); done(); save();
+      decided({ issue: n, what: `requeued behind ${depList.map((d) => `#${d}`).join(", ")} (Depends on edge added)`, why: firstLine(row.detail) || "the lane reported an open dependency",
+        alternative: "skip the issue and its dependents" });
       update({ ...row, detail: `requeued behind ${depList.map((d) => `#${d}`).join(", ")}` });
       return;
     }
@@ -365,15 +394,57 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       if ((engineErrors.get(n) ?? 0) < ENGINE_ERROR_RELAUNCHES) {
         engineErrors.set(n, (engineErrors.get(n) ?? 0) + 1);
         requeue(n, 0); done(); save();
+        decided({ issue: n, what: "relaunch once after engine-error", why: firstLine(row.detail) || "engine-error", alternative: "end the issue engine-error and skip its dependents" });
         update({ ...row, detail: `relaunching once: ${row.detail ?? ""}` });
         return;
       }
     }
     if (row.outcome === "decomposed" && subs.length) {
       await addIssues(subs);
+      decided({ issue: n, what: `added sub-issues ${subs.map((d) => `#${d}`).join(", ")} to the batch; dependents wait on them`, why: "the builder decomposed the issue",
+        alternative: "end the batch row decomposed and let dependents wait for a later batch" });
       for (const [m, ds] of deps) if (ds.includes(n)) deps.set(m, [...new Set(ds.flatMap((d) => (d === n ? subs : [d])))]);
       noteCrossLane();
     }
+    // #4267: a recovery pass ends here; a recoverable row under the attempt cap is requeued as a recovery lane.
+    const prior = recovering.get(n) ?? null;
+    const evidence = () => recoveryEvidence({ code: prior.code, attempt: prior.attempt, outcome: row.outcome, resultCode: row.code, detail: row.detail });
+    if (prior) {
+      recovering.delete(n);
+      // #4298: the row reports the whole issue: earlier attempts' cost and minutes are summed into the recovery's.
+      row.cost_usd = Math.round(((Number(row.cost_usd) || 0) + (Number(prior.cost_usd) || 0)) * 1e6) / 1e6;
+      row.minutes = Math.round(((Number(row.minutes) || 0) + (Number(prior.minutes) || 0)) * 10) / 10;
+      if (row.outcome === "merged") row.recovered = prior.code;
+      else row.recovery = { code: prior.code, attempts: recoveries.get(n) ?? prior.attempt, outcome: row.outcome, ...(row.code ? { result_code: row.code } : {}), detail: firstLine(row.detail) };
+      // A recovery that failed for good keeps needs-human. The lane relabels needs-human/ci-pending itself; engine-error (after its
+      // relaunch) and deferred (no longer requeued) end here, so the runner does it, once. invalid/decomposed/dependency-*/merged never.
+      if (["engine-error", "deferred"].includes(row.outcome) && typeof relabelNeedsHuman === "function") {
+        try { await relabelNeedsHuman({ issue: n, evidence: evidence() }); } catch { /* best effort */ }
+      }
+    }
+    if (recoveryMax && (row.outcome === "needs-human" || row.outcome === "ci-pending")) {
+      let isConflicting = false;
+      if (row.outcome === "ci-pending" && typeof conflicting === "function" && Number.isInteger(row.pr)) {
+        try { isConflicting = (await conflicting(n, row.pr)) === true; } catch { isConflicting = false; }
+      }
+      const facts = { ...row, issueEdited: r?.issueEdited === true, conflicting: isConflicting };
+      const used = recoveries.get(n) ?? 0;
+      if (classifyNeedsHuman(facts) === "recoverable" && used < recoveryMax) {
+        const code = recoveryCodeOf(facts), attempt = used + 1;
+        // #4315: the full lane detail is kept (never firstLine) for the relabel when the batch stops before this attempt
+        recoveries.set(n, attempt); recovering.set(n, { code, attempt, cost_usd: Number(row.cost_usd) || 0, minutes: Number(row.minutes) || 0,
+          detail: String(row.detail ?? ""), outcome: row.outcome, ...(row.code ? { result_code: row.code } : {}), prev_attempt: prior?.attempt ?? 0 });
+        requeue(n, 0); done(); save();
+        decided({ issue: n, what: `recovery lane for ${code} (attempt ${attempt}/${recoveryMax}); dependents stay queued`, why: firstLine(row.detail) || code,
+          alternative: "leave needs-human for the operator and skip the dependents" });
+        update({ ...row, outcome: "recovering", detail: `recovering (${code}), attempt ${attempt}/${recoveryMax}: ${firstLine(row.detail)}` });
+        return;
+      }
+    }
+    // #4302: a non-final recovery attempt left needs-human/ci-pending unlabelled for its successor; none is launched, so relabel once.
+    if (prior && prior.attempt < recoveryMax && ["needs-human", "ci-pending"].includes(row.outcome) && typeof relabelNeedsHuman === "function") {
+      try { await relabelNeedsHuman({ issue: n, evidence: evidence() }); } catch { /* best effort */ }
+    }
     results.set(n, row);
     if (row.outcome === "merged" && drift?.onMerged && r?.structure && String(rec?.lane ?? r?.lane ?? "").startsWith("milestone/")) {
       save(); update(row);
@@ -394,6 +465,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       return;
     }
     const lane = ln?.lane;
+    if (relabelled.delete(n)) save(); // #4315: the recovery lane launches after all; it removes needs-human itself
     const pl = placed.get(n);
     placed.delete(n);
     const rec = { startedAt: now(), ...(lane ? { lane } : {}), ...(remoteRun.has(n) ? { remote: true } : {}), ...(pl ? { placement: pl } : {}) };
@@ -406,7 +478,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       if (pf?.closed) r = { terminalReason: "invalid", cost_usd: 0, detail: `pre-filter: ${pf.detail}` };
       else {
         try {
-          r = await runOne(n, lane, { remote: !!rec.remote, ...(rec.placement ? { placement: rec.placement } : {}), onStart: (info) => {
+          r = await runOne(n, lane, { remote: !!rec.remote, ...(rec.placement ? { placement: rec.placement } : {}), ...(recovering.has(n) ? { recover: { code: recovering.get(n).code, attempt: recovering.get(n).attempt, final: recovering.get(n).attempt >= recoveryMax } } : {}), onStart: (info) => {
             Object.assign(rec, info ?? {}); save();
             if (reg && slotted.has(n) && info?.pid) reg.setLanePid(keyOf(n), info.pid);
           } });
@@ -517,8 +589,43 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     }
   }
   if (reg) withdrawExcept(new Set());
+  const heldDetail = (n) => tripped?.detail ?? (driftHeld.has(n) ? `drift: ${driftHeld.get(n)} flagged` : budgetStop ? `execution budget: ${budgetStop}` : budgetHeld ? "maintenance share" : "not run");
+  // #4315: a recovery queued but never launched (the batch stopped: breaker, budget, hold; or a resume that did not relaunch a
+  // lost run) left the issue without needs-human, since a non-final attempt does not relabel. Relabel it once, with the full reason.
+  for (const [n, q] of recovering) {
+    if (running.has(n) || results.has(n) || relabelled.has(n) || typeof relabelNeedsHuman !== "function") continue;
+    const cause = heldDetail(n) === "not run" ? "batch stopped" : heldDetail(n);
+    const evidence = recoveryEvidence({ code: q.code, attempt: q.prev_attempt, outcome: q.outcome, resultCode: q.result_code, detail: q.detail, full: true,
+      queued: q.attempt, cause, recoveryMax });
+    try { await relabelNeedsHuman({ issue: n, evidence }); } catch { /* best effort */ }
+    relabelled.add(n);
+  }
   save();
-  return order.map((n) => results.get(n) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: tripped?.detail ?? (driftHeld.has(n) ? `drift: ${driftHeld.get(n)} flagged` : budgetStop ? `execution budget: ${budgetStop}` : budgetHeld ? "maintenance share" : "not run") });
+  return order.map((n) => results.get(n) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: heldDetail(n),
+    ...(recovering.has(n) ? { recovery: { code: recovering.get(n).code, attempts: recoveries.get(n) ?? recovering.get(n).attempt, outcome: recovering.get(n).outcome ?? "needs-human",
+      ...(recovering.get(n).result_code ? { result_code: recovering.get(n).result_code } : {}), detail: firstLine(recovering.get(n).detail ?? recovering.get(n).code) } } : {}) });
+}
+
+/** Max chars of one row's detail in the batch-report outcome lists (#4298). */
+export const OUTCOME_LINE_MAX = 200;
+/**
+ * #4267 batch-report lines after the table: `recovered: #A (ci.red) #B (base.conflict)`, one `unrecovered:` line per
+ * mechanical needs-human row (failed recovery or a terminal code), then one escalation list holding only human codes,
+ * asked once at the end of the batch. Empty when there is nothing to list.
+ */
+export function formatOutcomeLists(rows) {
+  const out = [];
+  const one = (x) => String(x ?? "").split("\n")[0].slice(0, OUTCOME_LINE_MAX);
+  const rec = (rows ?? []).filter((r) => r?.recovered);
+  if (rec.length) out.push(`recovered: ${rec.map((r) => `#${r.issue} (${r.recovered})`).join(" ")}`);
+  for (const r of rows ?? []) {
+    if (!r || r.recovered) continue;
+    const human = r.outcome === "needs-human" && classifyNeedsHuman(r) === "human";
+    if (!human && (r.outcome === "needs-human" || r.recovery)) out.push(`unrecovered: #${r.issue} (${r.code ?? r.recovery?.code ?? "unclassified"}: ${one(r.recovery ? `recovery ${r.recovery.code} ended ${r.recovery.outcome}: ${r.recovery.detail}` : r.detail)})`);
+  }
+  const esc = (rows ?? []).filter((r) => r?.outcome === "needs-human" && classifyNeedsHuman(r) === "human");
+  if (esc.length) out.push(["escalations (human decisions, asked once):", ...esc.map((r) => `- #${r.issue} (${r.code}): ${one(r.detail)}`)].join("\n"));
+  return out;
 }
 
 export function formatTable(rows) {

package/bin/lean/prefilter.mjs

@@ -4,14 +4,18 @@
  * Already-fixed pre-filter (#4123): cheap checks before any lane starts, so an issue that a merged PR or a later green
  * CI run already resolved does not cost a worktree, a lease and a builder session.
  *   1. merged PRs (and lane commits) that claim to fix #N  -> candidate
- *   2. auto-filed CI-failure issue whose workflow is green again on the failing branch -> closed with the run link
+ *   2. auto-filed CI-failure issue whose workflow is green again on the failing branch -> closed with the run link,
+ *      unless it is flaky (#4305): flaky wording or label, a reopen after an earlier pre-filter close, or a failed run
+ *      of the workflow at the green run's SHA. Then the shortcut is skipped and the issue goes on as normal.
  *   3. every repo path the issue names is gone from origin/<lane> -> candidate
  * A candidate gets ONE read-only, single-turn validation on a small model in the main checkout (no worktree). Only an
  * ALREADY-FIXED/INVALID verdict with evidence closes the issue; everything else, and every error, goes to the normal lane.
  * All effects are injected (gh, git, runner, transitionLabel, projector?) so it is unit-testable.
  */
-import { capComment, sanitizeMd } from "./render.mjs";
+import { capComment, sanitizeMd, noComments } from "./render.mjs";
 import { PREFILTER_SYSTEM, prefilterPrompt, parsePrefilterVerdict } from "./prompts.mjs";
+import { isTrustedComment } from "../engine/phases.mjs";
+import { APP_SLUG } from "../init-repo.mjs";
 
 export const DEFAULT_PREFILTER_MODEL = "claude-haiku-5-5";
 export const PREFILTER_MARKER = "FORGE:PREFILTER";
@@ -35,17 +39,51 @@ export function ciFailureRun(iss) {
   return m && CI_FAIL_RE.test(text) ? { repo: m[1], id: Number(m[2]) } : null;
 }
 
+// #4316: a bare "sometimes" is ordinary prose; only "fails sometimes" / "sometimes fails" says the failure is intermittent
+const FLAKY_RE = /\b(?:intermittent\w*|flaky|flak(?:e|es|iness)|fail(?:s|ed|ing)?\s+sometimes|sometimes\s+fail(?:s|ed|ing)?|non-?deterministic\w*)\b/i;
+const loginOf = (c) => String(c?.author?.login ?? c?.user?.login ?? "");
+const trusted = (c) => {
+  const login = loginOf(c);
+  return isTrustedComment({ author_association: c?.authorAssociation ?? c?.author_association, user: { login, type: c?.user?.type ?? (/\[bot\]$|^app\//.test(login) ? "Bot" : "User") } });
+};
+/** #4315: a login compared as the engine posts it: lowercased, without `app/` or a `[bot]` suffix (`gh issue view` drops both). */
+const bareLogin = (l) => String(l ?? "").trim().toLowerCase().replace(/^app\//, "").replace(/\[bot\]$/, "");
+const isMarked = (c) => String(c?.body ?? "").trimStart().startsWith(`<!-- ${PREFILTER_MARKER} -->`);
+/**
+ * #4315: the logins the engine posts as: the ForgeDock App (`gh issue view` reports it as `rapiercraft-forgedock` with
+ * CONTRIBUTOR, never `[bot]`) plus the token's own user (`gh api user`; an App installation token cannot read it).
+ */
+export async function ownLogins(gh) {
+  const out = new Set([bareLogin(APP_SLUG)]);
+  try { const me = bareLogin(await gh(["api", "user", "--jq", ".login"])); if (me) out.add(me); } catch { /* installation token: the App slug only */ }
+  return [...out];
+}
+/**
+ * #4305: why one green run is no proof for this issue, without an API call: flaky wording or a `flaky` label, or an
+ * earlier pre-filter close by the pipeline (the issue is open again, so an operator reopened it). {reason, why} or null.
+ * #4315: a marker comment is the pipeline's own when it is trusted or written by one of `own` (bare logins).
+ */
+export function flakyReason(iss, own = [bareLogin(APP_SLUG)]) {
+  if (FLAKY_RE.test(`${iss.title ?? ""}\n${noComments(String(iss.body ?? ""), " ")}`)) return { reason: "flaky", why: "issue says the failure is intermittent" };
+  if ((iss.labels ?? []).some((l) => String(l?.name ?? l).toLowerCase() === "flaky")) return { reason: "flaky", why: "flaky label" };
+  const mine = new Set((own ?? []).map(bareLogin));
+  if ((iss.comments ?? []).some((c) => isMarked(c) && (trusted(c) || mine.has(bareLogin(loginOf(c)))))) return { reason: "reopened", why: "reopened after a pre-filter close" };
+  return null;
+}
+/** The own logins, looked up only when an otherwise-untrusted marker comment needs them (no call for most issues). */
+const ownFor = async (iss, resolve) => ((iss.comments ?? []).some((c) => isMarked(c) && !trusted(c)) ? resolve() : undefined);
+
 const PATH_RE = /(?:^|[\s`'"(\[])((?:\.{0,2}\/)?(?:[\w@.-]+\/)+[\w@.-]+\.[A-Za-z0-9]{1,8})(?::\d+(?:-\d+)?)?(?=$|[\s`'"),.:;\]])/gm;
 /** Repo-relative file paths the issue names (`dir/file.ext`, optionally `:line`); URLs and HTML comments are ignored. */
 export function namedPaths(text) {
-  const s = sanitizeMd(text).replace(/<!--[\s\S]*?-->/g, " ").replace(/\b[a-z]+:\/\/\S+/gi, " ");
+  const s = noComments(sanitizeMd(text), " ").replace(/\b[a-z]+:\/\/\S+/gi, " ");
   return [...new Set([...s.matchAll(PATH_RE)].map((m) => m[1].replace(/^\.\//, "")).filter((p) => !p.startsWith("/") && !p.startsWith("../")))];
 }
 
 /**
- * @returns {Promise<{prs:object[], commits:object[], ci:?object, missingPaths:string[], namedPaths:string[]}>}
+ * @returns {Promise<{prs:object[], commits:object[], ci:?object, ciSkip?:{reason:string, why:string}, missingPaths:string[], namedPaths:string[]}>}
  */
-export async function collectSignals({ iss, repo, lane, io, cwd }) {
+export async function collectSignals({ iss, repo, lane, io, cwd, selfLogins = null }) {
   const n = iss.number;
   const sig = { prs: [], commits: [], ci: null, missingPaths: [], namedPaths: [] };
   try {
@@ -63,7 +101,19 @@ export async function collectSignals({ iss, repo, lane, io, cwd }) {
       const branch = failed.head_branch || lane;
       const latest = JSON.parse(String(await io.gh(["api", `repos/${repo}/actions/workflows/${failed.workflow_id}/runs?branch=${encodeURIComponent(branch)}&status=completed&per_page=1`])))?.workflow_runs?.[0];
       if (latest && latest.id !== failed.id && latest.conclusion === "success" && Date.parse(latest.created_at) > Date.parse(failed.created_at)) {
-        sig.ci = { workflow: failed.name ?? latest.name ?? String(failed.workflow_id), branch, failedUrl: failed.html_url, greenUrl: latest.html_url, greenSha: latest.head_sha ?? "" };
+        const sha = latest.head_sha ?? "";
+        // #4305: a workflow that failed and passed at the same SHA is flaky; the lookup is any branch (PR run vs push)
+        // and only made when the issue itself gave no reason. An unreadable lookup throws: no CI signal.
+        const own = await ownFor(iss, typeof selfLogins === "function" ? selfLogins : selfLogins ? async () => selfLogins : () => ownLogins(io.gh));
+        let skip = flakyReason(iss, own);
+        const same = { reason: "same-sha", why: `failed and passed at ${sha.slice(0, 12)}` };
+        if (!skip && sha && failed.head_sha === sha) skip = same;
+        if (!skip && sha) {
+          const atSha = JSON.parse(String(await io.gh(["api", `repos/${repo}/actions/workflows/${failed.workflow_id}/runs?head_sha=${sha}&status=completed&per_page=100`])))?.workflow_runs ?? [];
+          if (atSha.some((r) => r?.conclusion === "failure")) skip = same;
+        }
+        if (skip) sig.ciSkip = skip;
+        else sig.ci = { workflow: failed.name ?? latest.name ?? String(failed.workflow_id), branch, failedUrl: failed.html_url, greenUrl: latest.html_url, greenSha: sha };
       }
     } catch { /* run unreadable: no CI signal */ }
   }
@@ -82,10 +132,10 @@ export async function collectSignals({ iss, repo, lane, io, cwd }) {
  * Pre-filter one issue. Never throws.
  * @returns {Promise<{issue:number, closed:boolean, kind:?string, candidate:boolean, verdict:?string, cost_usd:number, detail:string}>}
  */
-export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAULT_PREFILTER_MODEL, dryRun = false, agentId = null, maxMinutes = 5 }) {
+export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAULT_PREFILTER_MODEL, dryRun = false, agentId = null, maxMinutes = 5, selfLogins = null }) {
   const out = { issue, closed: false, kind: null, candidate: false, verdict: null, cost_usd: 0, detail: "" };
   try {
-    const iss = JSON.parse(String(await io.gh(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state,labels"])));
+    const iss = JSON.parse(String(await io.gh(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state,labels,comments"])));
     if (String(iss.state).toUpperCase() !== "OPEN") return { ...out, detail: "not open" };
     if ((iss.labels ?? []).some((l) => ["needs-human", "workflow:merged"].includes(l?.name ?? l))) return { ...out, detail: "labelled, left to the lane" };
     if (io.projector) {
@@ -93,35 +143,48 @@ export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAU
       try { st = await io.projector.readState(issue); } catch { /* unreadable: proceed */ }
       if (st?.lease && st.lease.until > Date.now() && st.lease.by !== agentId) return { ...out, detail: `leased by ${st.lease.by}` };
     }
-    const sig = await collectSignals({ iss, repo, lane, io, cwd });
+    const sig = await collectSignals({ iss, repo, lane, io, cwd, selfLogins });
     const close = async (kind, body, detail) => {
+      let note = "";
       if (!dryRun) {
-        await io.gh(["issue", "comment", String(issue), "-R", repo, "--body", capComment(`<!-- ${PREFILTER_MARKER} -->\n<!-- FORGE:VALIDATE -->\n${body}`)]);
+        // #4315: close first: the marker is posted only on an issue that was closed, so it always means "reopened" later
         await io.gh(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
+        // #4314: the issue IS closed from here on: the result is closed:true whatever the comment does, so no lane starts on it.
+        // The comment is retried once, then a marker-only comment (a second, tiny payload) keeps the #4305 reopen guard working.
+        const comment = (text) => io.gh(["issue", "comment", String(issue), "-R", repo, "--body", text]);
+        const full = capComment(`<!-- ${PREFILTER_MARKER} -->\n<!-- FORGE:VALIDATE -->\n${body}`);
+        const minimal = `<!-- ${PREFILTER_MARKER} -->\nClosed by the pre-filter (${kind}); the explanation comment could not be posted. Reopen if this is wrong.`;
+        let posted = false;
+        for (const text of [full, full, minimal]) {
+          try { await comment(text); posted = true; break; } catch { /* next attempt */ }
+        }
+        if (!posted) note = " (closed, but no marker comment could be posted: a reopen is not recognised)";
         try { await io.transitionLabel?.(issue, "invalid"); } catch { /* labels are best effort */ }
       }
-      return { ...out, closed: !dryRun, kind, detail };
+      return { ...out, closed: !dryRun, kind, detail: `${detail}${note}` };
     };
 
+    // #4305: a skipped CI-green shortcut is named in every non-closing detail line that follows (#4316: with its reason).
+    const keep = (detail) => ({ ...out, detail: sig.ciSkip ? `skipped CI-green shortcut: ${sig.ciSkip.reason} (${sig.ciSkip.why}); ${detail}` : detail });
     if (sig.ci) {
       out.candidate = true;
       const c = sig.ci;
       return await close("ci-green", `## Pre-filter: CI failure no longer reproduces\n**Workflow:** ${c.workflow} on \`${c.branch}\`\n**Failing run:** ${c.failedUrl}\n**Latest run (green):** ${c.greenUrl}${c.greenSha ? ` at \`${c.greenSha.slice(0, 12)}\`` : ""}\n\nClosed without a lane. Reopen if the failure comes back.`,
         `CI green again: ${c.greenUrl}`);
     }
-    if (!sig.prs.length && !sig.commits.length && !sig.missingPaths.length) return { ...out, detail: "no already-fixed signal" };
+    if (!sig.prs.length && !sig.commits.length && !sig.missingPaths.length) return keep("no already-fixed signal");
     out.candidate = true;
     const why = [...sig.prs.map((p) => `PR #${p.number}`), ...sig.commits.map((c) => c.sha.slice(0, 12)), ...(sig.missingPaths.length ? ["named paths missing"] : [])].join(", ");
-    if (dryRun) return { ...out, detail: `candidate: ${why}` };
+    if (dryRun) return keep(`candidate: ${why}`);
     let r;
     try {
       r = await io.runner({ role: "prefilter", issue, cwd, model, resume: null, system: PREFILTER_SYSTEM, readOnly: true,
         prompt: prefilterPrompt({ issue: iss, lane, signals: sig }), maxMs: Math.round(maxMinutes * 60000) });
-    } catch (e) { return { ...out, detail: `validation failed (${String(e?.message ?? e).slice(0, 120)}): lane` }; }
+    } catch (e) { return keep(`validation failed (${String(e?.message ?? e).slice(0, 120)}): lane`); }
     out.cost_usd = Number.isFinite(r?.costUsd) ? r.costUsd : 0;
     const v = parsePrefilterVerdict(r?.text);
     out.verdict = v?.verdict ?? null;
-    if (!v || v.verdict === "CONFIRMED" || !v.evidence.length) return { ...out, detail: `candidate (${why}) ${v ? (v.verdict === "CONFIRMED" ? "confirmed" : "without evidence") : "unparseable verdict"}: lane` };
+    if (!v || v.verdict === "CONFIRMED" || !v.evidence.length) return keep(`candidate (${why}) ${v ? (v.verdict === "CONFIRMED" ? "confirmed" : "without evidence") : "unparseable verdict"}: lane`);
     const ev = v.evidence.map((x) => `- ${sanitizeMd(x).replace(/\s+/g, " ").slice(0, 400)}`).join("\n");
     return await close("validated", `## Pre-filter: ${v.verdict}\n**Signal:** ${why}\n**Summary:** ${sanitizeMd(v.summary).replace(/\s+/g, " ").slice(0, 600) || "not reported"}\n\n**Evidence:**\n${ev}\n\nValidated by a single read-only check (${model}), without a lane. Reopen if this is wrong.`,
       `${v.verdict.toLowerCase()} (${why})`);
@@ -132,7 +195,9 @@ export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAU
 
 /** Per-issue hook for `orchestrate({ prefilter })`; `lane` is the issue's own resolved lane (#4125). */
 export function makePrefilter(opts) {
-  return (issue, lane) => prefilterIssue({ ...opts, issue, ...(lane ? { lane } : {}) });
+  let own = null; // #4315: one `gh api user` per batch, and only when a marker comment needs it
+  const selfLogins = opts.selfLogins ?? (() => (own ??= ownLogins(opts.io.gh)));
+  return (issue, lane) => prefilterIssue({ ...opts, selfLogins, issue, ...(lane ? { lane } : {}) });
 }
 
 /** One report line: how many the pre-filter checked, flagged and closed, what validation cost, and the spend avoided. */

package/bin/lean/prefilter.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { prefilterIssue, makePrefilter, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
+import { prefilterIssue, flakyReason, makePrefilter, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
 import { parsePrefilterVerdict, prefilterPrompt } from "./prompts.mjs";
 import { orchestrate, formatTable } from "./orchestrate.mjs";
 import { triageFromCli } from "../engine-cli.mjs";
@@ -12,7 +12,7 @@ const fence = (o) => "```json\n" + JSON.stringify(o) + "\n```";
 /** Fake GitHub + git for one repo `o/r`, lane `staging`. */
 function world(o = {}) {
   const w = { comments: [], closed: [], labels: [], runner: [], lanes: [], gitCalls: [],
-    issues: o.issues ?? {}, prs: o.prs ?? [], commits: o.commits ?? "", paths: new Set(o.paths ?? []), runs: o.runs ?? {}, workflowRuns: o.workflowRuns ?? {},
+    issues: o.issues ?? {}, prs: o.prs ?? [], commits: o.commits ?? "", paths: new Set(o.paths ?? []), runs: o.runs ?? {}, workflowRuns: o.workflowRuns ?? {}, shaRuns: o.shaRuns ?? {},
     verdict: o.verdict ?? null };
   w.io = {
     gh: async (a) => {
@@ -25,6 +25,8 @@ function world(o = {}) {
         if (m) return JSON.stringify(w.runs[m[1]]);
         const wf = /actions\/workflows\/(\d+)\/runs\?branch=([^&]+)/.exec(a[1]);
         if (wf) return JSON.stringify({ workflow_runs: w.workflowRuns[`${wf[1]}:${decodeURIComponent(wf[2])}`] ?? [] });
+        const at = /actions\/workflows\/\d+\/runs\?head_sha=([^&]+)/.exec(a[1]);
+        if (at) { w.shaQueries = (w.shaQueries ?? 0) + 1; return JSON.stringify({ workflow_runs: w.shaRuns[at[1]] ?? [] }); }
       }
       if (k === "issue comment") { w.comments.push([Number(a[2]), a[a.indexOf("--body") + 1]]); return ""; }
       if (k === "issue close") { w.closed.push([Number(a[2]), a[a.indexOf("--reason") + 1]]); return ""; }
@@ -100,6 +102,90 @@ describe("pre-filter (#4123)", () => {
     assert.deepEqual(w.closed, [[34, "not planned"]]);
   });
 
+  it("#4305 the CI-green shortcut is skipped for intermittent, reopened and same-SHA-flaky CI failures", async () => {
+    const link = "Run: https://github.com/o/r/actions/runs/500";
+    const green = (issue, extra = {}) => world({ issues: { 34: { title: "shell-compat failed on staging", body: `Workflow failed.\n${link}`, ...issue } },
+      runs: { 500: { id: 500, workflow_id: 7, name: "shell-compat", head_branch: "staging", head_sha: "1111111111111111", created_at: "2026-10-10T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/500" } },
+      workflowRuns: { "7:staging": [{ id: 600, conclusion: "success", created_at: "2026-10-12T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/600", head_sha: "8d9f6ba0aaaaaaaa" }] }, ...extra });
+    const bot = { author: { login: "rapiercraft-forgedock[bot]" }, authorAssociation: "NONE", body: "<!-- FORGE:PREFILTER -->\n<!-- FORGE:VALIDATE -->\n## Pre-filter: CI failure no longer reproduces" };
+    const stranger = { author: { login: "someone" }, authorAssociation: "NONE", body: bot.body };
+    const cases = [
+      ["intermittent wording", green({ body: `\`a.test.sh\` fails intermittently on macOS.\n${link}` }), /issue says the failure is intermittent/, "flaky"],
+      ["flaky label", green({ labels: [{ name: "flaky" }] }), /flaky label/, "flaky"],
+      ["reopened after a pre-filter close", green({ comments: [bot] }), /reopened after a pre-filter close/, "reopened"],
+      ["failed and passed at the same SHA", green({}, { shaRuns: { "8d9f6ba0aaaaaaaa": [{ id: 601, conclusion: "failure" }, { id: 600, conclusion: "success" }] } }), /failed and passed at 8d9f6ba0aaaa/, "same-sha"],
+    ];
+    for (const [name, w, why, reason] of cases) {
+      const r = await pf(w, 34);
+      assert.equal(r.closed, false, name); assert.notEqual(r.kind, "ci-green", name);
+      assert.deepEqual(w.closed, [], name); assert.deepEqual(w.comments, [], name); assert.equal(w.runner.length, 0, name);
+      assert.ok(r.detail.startsWith(`skipped CI-green shortcut: ${reason} (`), `${name}: ${r.detail}`); assert.match(r.detail, why, name);
+      assert.match(r.detail, /no already-fixed signal$/, name);
+    }
+    // wording and the reopen marker need no runs lookup; an untrusted marker comment is no reopen, and a green-only SHA still closes
+    const quiet = green({ body: `fails intermittently ${link}` });
+    await pf(quiet, 34); assert.equal(quiet.shaQueries ?? 0, 0);
+    const forged = green({ comments: [stranger] }, { shaRuns: { "8d9f6ba0aaaaaaaa": [{ id: 600, conclusion: "success" }] } });
+    const r = await pf(forged, 34);
+    assert.equal(r.kind, "ci-green"); assert.equal(forged.shaQueries, 1);
+    // an unreadable same-SHA lookup is no proof either: no shortcut
+    const down = green();
+    const gh0 = down.io.gh; down.io.gh = async (a) => (/head_sha=/.test(a[1] ?? "") ? (() => { throw new Error("HTTP 502"); })() : gh0(a));
+    assert.equal((await pf(down, 34)).closed, false);
+  });
+
+  it("#4316 a bare \"sometimes\" is prose, not flaky wording; \"fails sometimes\" and \"sometimes fails\" are", () => {
+    assert.equal(flakyReason({ title: "deploy check failed", body: "This sometimes happens after a deploy." }), null);
+    assert.equal(flakyReason({ title: "x", body: "Sometimes we rerun it by hand." }), null);
+    for (const body of ["the job fails sometimes on macOS", "it sometimes fails on macOS", "shell-compat failed sometimes", "intermittent timeout", "a flaky test"]) {
+      assert.equal(flakyReason({ title: "ci failed", body })?.reason, "flaky", body);
+    }
+  });
+  it("#4315 a comment shaped like #4235's real pre-filter comment is the pipeline's own: a reopened CI-failure issue is kept for a lane", async () => {
+    const link = "Run: https://github.com/o/r/actions/runs/500";
+    const green = (issue, extra = {}) => world({ issues: { 34: { title: "shell-compat failed on staging", body: `Workflow failed.\n${link}`, ...issue } },
+      runs: { 500: { id: 500, workflow_id: 7, name: "shell-compat", head_branch: "staging", head_sha: "1111111111111111", created_at: "2026-10-10T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/500" } },
+      workflowRuns: { "7:staging": [{ id: 600, conclusion: "success", created_at: "2026-10-12T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/600", head_sha: "8d9f6ba0aaaaaaaa" }] },
+      shaRuns: { "8d9f6ba0aaaaaaaa": [{ id: 600, conclusion: "success" }] }, ...extra });
+    // the shape `gh issue view --json comments` returns for the ForgeDock App on #4235: no `[bot]`, CONTRIBUTOR, marker first
+    const body = "<!-- FORGE:PREFILTER -->\n<!-- FORGE:VALIDATE -->\n## Pre-filter: CI failure no longer reproduces\n**Workflow:** shell-compat on `staging`";
+    const real = { author: { login: "rapiercraft-forgedock" }, authorAssociation: "CONTRIBUTOR", body };
+    const w = green({ comments: [real] });
+    const r = await pf(w, 34);
+    assert.equal(r.closed, false); assert.notEqual(r.kind, "ci-green");
+    assert.match(r.detail, /reopened after a pre-filter close/);
+    assert.deepEqual(w.closed, []); assert.deepEqual(w.comments, []);
+    // the token's own user (`gh api user`) counts too, cached once per makePrefilter batch; a CONTRIBUTOR stranger does not
+    const mine = green({ comments: [{ ...real, author: { login: "Op-User" } }] });
+    let userCalls = 0; const gh0 = mine.io.gh;
+    mine.io.gh = async (a) => (a[0] === "api" && a[1] === "user" ? (userCalls++, "op-user\n") : gh0(a));
+    const run = makePrefilter({ repo: "o/r", cwd: "/repo", io: mine.io });
+    assert.match((await run(34, "staging")).detail, /reopened after a pre-filter close/);
+    await run(34, "staging"); assert.equal(userCalls, 1);
+    const stranger = green({ comments: [{ ...real, author: { login: "someone" } }] });
+    assert.equal((await pf(stranger, 34)).kind, "ci-green");
+    // BUG-4: the marker is posted only after a successful close; a failed close posts no marker
+    const order = [];
+    const ok = green(); const g2 = ok.io.gh;
+    ok.io.gh = async (a) => { if (["issue close", "issue comment"].includes(a.slice(0, 2).join(" "))) order.push(a[1]); return g2(a); };
+    assert.equal((await pf(ok, 34)).closed, true); assert.deepEqual(order, ["close", "comment"]);
+    const fails = green(); const g3 = fails.io.gh;
+    fails.io.gh = async (a) => (a.slice(0, 2).join(" ") === "issue close" ? (() => { throw new Error("HTTP 403"); })() : g3(a));
+    const f = await pf(fails, 34);
+    assert.equal(f.closed, false); assert.deepEqual(fails.comments, []); assert.match(f.detail, /pre-filter error/);
+    // #4314: a failing comment after a successful close still counts as closed (no lane), via retry, then a marker-only comment
+    const flaky = (n, big) => { const x = green(); const g = x.io.gh; let calls = 0;
+      x.io.gh = async (a) => { if (a.slice(0, 2).join(" ") === "issue comment") { calls++; if (calls <= n || (big && a[a.indexOf("--body") + 1].includes("## Pre-filter"))) throw new Error("HTTP 502"); } return g(a); };
+      return x; };
+    const once = flaky(1); const r1 = await pf(once, 34);
+    assert.equal(r1.closed, true); assert.equal(once.comments.length, 1); assert.doesNotMatch(r1.detail, /no marker/);
+    const tiny = flaky(0, true); const r2 = await pf(tiny, 34);
+    assert.equal(r2.closed, true); assert.equal(tiny.comments.length, 1); assert.match(tiny.comments[0][1], /^<!-- FORGE:PREFILTER -->/);
+    assert.match(flakyReason({ comments: [{ body: tiny.comments[0][1], author: { login: "forgedock-app[bot]" }, authorAssociation: "NONE" }] }, ["forgedock-app"])?.reason ?? "", /reopened/);
+    const dead = flaky(99); const r3 = await pf(dead, 34);
+    assert.equal(r3.closed, true); assert.equal(dead.runner.length, 0); assert.deepEqual(dead.closed, [[34, "not planned"]]); assert.match(r3.detail, /no marker comment/);
+  });
+
   it("a CI-failure issue whose workflow is still red (or whose latest run is the failing one) goes to a lane", async () => {
     const base = { issues: { 34: { title: "ci failed", body: "https://github.com/o/r/actions/runs/500" } },
       runs: { 500: { id: 500, workflow_id: 7, head_branch: "staging", created_at: "2026-10-10T00:00:00Z" } } };
@@ -112,6 +198,9 @@ describe("pre-filter (#4123)", () => {
 
   it("every named path missing on the lane is a candidate; any surviving path is not", async () => {
     assert.deepEqual(namedPaths("see `src/old/foo.js:12` and lib/bar.py, not https://x.io/a/b.js <!-- FORGE:STATE {\"a\":\"c/d.js\"} -->"), ["src/old/foo.js", "lib/bar.py"]);
+    // #4298: the scan-based noComments: a `--!>` closer ends a comment and an unclosed one runs to the end (the old
+    // one-pass regex kept both hidden paths).
+    assert.deepEqual(namedPaths("fix lib/a.js <!-- x/hidden.js --!> visible/e.js and <!-- unclosed c/d.js"), ["lib/a.js", "visible/e.js"]);
     const gone = world({ issues: { 5: { body: "crash in src/old/foo.js:12" } }, verdict: { verdict: "INVALID", evidence: ["src/old/foo.js removed in abc123"] } });
     assert.equal((await pf(gone, 5)).closed, true);
     assert.match(gone.runner[0].prompt, /do not exist on origin\/staging: src\/old\/foo\.js/);

package/bin/lean/prompts.mjs

@@ -50,14 +50,17 @@ export function ciUnavailablePrompt() {
 /** #4163: the extra host-rules line when the engine pinned the repo's toolchain on PATH; "" otherwise (prompt unchanged). */
 const toolchainRule = (t) => (t ? `\nThe engine pinned this repo's toolchain on PATH (${t}). Use it as is: do not install global shims or other versions and do not edit PATH; if the pinned tool itself fails, report it as a toolchain/environment problem instead of working around it.` : "");
 
+/** #4272: the extra line citing the repo-facts cache by path (never its content) when it exists; "" otherwise (prompt unchanged). */
+const factsRule = (f) => (f ? `\nRepo facts (toolchain pins, slow suites, layer rules, hotspots) are cached in ${f}: read it before choosing checks or placing code.` : "");
+
 /** #4221: the extra host-rules line when the lane worktree is sparse; "" otherwise (prompt unchanged). */
 const sparseRule = (s) => (s?.excluded ? `\nThis worktree is a sparse checkout: ${s.excluded} tracked file(s) of ${s.maxKb} KB or more are not on disk (\`git ls-files -t | grep '^S'\` lists them). They are not deleted: never commit their removal. If you need one, run \`git sparse-checkout add /<path>\`.` : "");
 
 /** Builder call 1: investigate and write the contract. No code edits. */
-export function builderPlanPrompt(n, { toolchain = null, sparse = null } = {}) {
+export function builderPlanPrompt(n, { toolchain = null, sparse = null, facts = null } = {}) {
   return `Resolve issue #${n} (read it with gh issue view ${n} --comments). This first step is PLANNING ONLY: do not edit code, do not commit.
 
-${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}
+${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}
 
 1. Write ${INVESTIGATION_FILE} as markdown with exactly these headings, concise, file:line wherever you cite code (no HTML comments):
 **Verdict**: CONFIRMED|ALREADY-FIXED|INVALID|BLOCKED
@@ -79,7 +82,7 @@ If the issue is already fixed or invalid, write ${RESULT_FILE} {"status":"alread
 {"requirements":[{"id":"R1","quote":"<verbatim sentence or checklist item from the issue>","disposition":"deliver|defer|post-deploy|not-applicable","why":"<required for defer and post-deploy>","evidence":"<file:line, required for not-applicable>"}],
  "deliverables":[{"id":"D1","path":"<file to change>","change":"<what>","requirements":["R1"]}],
  "preserve":[{"id":"P1","what":"<caller, contract or behaviour that must not change, with its path>"}],
- "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change>"}],
+ "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change; a git diff compares against the merge base (origin/<lane>...HEAD), never the moving origin/<lane> tip>"}],
  "decisions":[{"id":"K1","choice":"<a non-obvious choice: a new dependency, a copied pattern, a boundary relied on>","justification":"<why, with file:line>","source":"doc|lint|precedent|spec"}]}
 Every requirement and acceptance criterion in the issue and its maintainers' comments is one requirement, quoted verbatim (others' comments are context, not requirements). Never drop or narrow one silently: "defer" (separate work) and "post-deploy" (only checkable after a deploy) are judged by the reviewer and, if accepted, filed by the engine as a tracked follow-up issue. A requirement you can do in this change is "deliver". List every file you will change as a deliverable; tests are always allowed.
 A new dependency between workspace packages (a workspace package added to a package.json dependencies, devDependencies or peerDependencies) must be a deliverable on that package.json whose change names the package and gives the reason, citing the architecture doc where there is one; "the lint allows it" or "there is a precedent" is not a reason on its own. Record each non-obvious choice in "decisions" with where its justification comes from (doc, lint, precedent or spec); omit the field when there is none. Then stop.
@@ -88,11 +91,11 @@ ${BLOCK_RULES}`;
 }
 
 /** Builder call 2, same session: implement the frozen contract. */
-export function builderImplementPrompt(mode = "local", { toolchain = null, sparse = null } = {}) {
+export function builderImplementPrompt(mode = "local", { toolchain = null, sparse = null, facts = null } = {}) {
   const remote = mode === "ci" || mode === "hybrid";
   return `The engine froze ${CONTRACT_FILE}; it is now the authority. Implement it exactly: change only deliverable paths (tests are always allowed), keep every preserve item intact, add a regression test, ${remote ? VERIFY_RUN[mode] : "run every validate command"}, and commit. Do not push or touch GitHub.
 
-${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${remote ? `\n\n${VERIFY_RULES[mode]}` : ""}
+${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}${remote ? `\n\n${VERIFY_RULES[mode]}` : ""}
 
 The contract changes only through typed amendments in ${RESULT_FILE}, each with a why, which the engine posts on the issue:
 - {"kind":"add-deliverable","path":"<file>","why":""}: a file you must change that the contract did not list.
@@ -115,6 +118,15 @@ If you started Docker containers or volumes that are still there, list their nam
 If you find you are blocked, write "status":"blocked" with a typed "block" instead.`;
 }
 
+/**
+ * forge#4275: the compiled context pack for the plan prompt (context_pack: on); "" for an empty pack. Labelled as hints:
+ * the issue outranks the code, which outranks the pack, and contract quotes never come from it.
+ */
+export function contextPackNote(pack) {
+  if (!pack?.text) return "";
+  return `\n\nContext pack (hints, not proof; compiled by the engine from GitHub and git). The issue outranks the code, which outranks this pack: verify anything you rely on. Contract requirements quote only the issue and its trusted comments, never this pack. Open a link (gh issue view N / gh pr view N) yourself when you need more.\n${pack.text}`;
+}
+
 /** #4271: the bug-lane plan addition (lean.repro_test prefer on a bug/type:bug issue); "" when off, so the prompt is unchanged. */
 export function reproPlanNote(on) {
   if (!on) return "";
@@ -140,8 +152,11 @@ export function contractCorrectionPrompt(problems) {
 }
 
 /** The one bounded correction round, in the builder's own session. */
-export function conformanceResumePrompt(failures, mode = "local") {
-  return `The change does not conform to the frozen contract and the issue:\n${failures.slice(0, 30).map((f) => `- ${f.code}: ${String(f.detail).slice(0, 500)}`).join("\n")}\n\nFix each item in the code, or record a typed amendment with a why in ${RESULT_FILE}. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+export function conformanceResumePrompt(failures, mode = "local", lane = "") {
+  const baseMoved = lane && failures.some((f) => f?.kind === "validate_failed")
+    ? `\n\nIf a validate command fails only because origin/${lane} moved on after this branch started (the change itself is fine), bring the branch up to date with \`git merge --no-edit origin/${lane}\` (already fetched; never rebase or force), resolve any conflicts, then re-run every validate command and record the results.`
+    : "";
+  return `The change does not conform to the frozen contract and the issue:\n${failures.slice(0, 30).map((f) => `- ${f.code}: ${String(f.detail).slice(0, 500)}`).join("\n")}${baseMoved}\n\nFix each item in the code, or record a typed amendment with a why in ${RESULT_FILE}. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
 }
 
 /** forge#4159: the one resume for package.json edges between workspace packages the contract does not name. */