forgedock 1.29.0 → 1.29.1

package/bin/lean/prefilter.mjs

@@ -4,7 +4,9 @@
  * 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.
@@ -12,6 +14,8 @@
  */
 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,6 +39,40 @@ 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) {
@@ -43,9 +81,9 @@ export function namedPaths(text) {
 }
 
 /**
- * @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" } } };

package/bin/lean/recovery.test.mjs

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { orchestrate, formatOutcomeLists, OUTCOME_LINE_MAX } from "./orchestrate.mjs";
 import { RECOVER_HOW } from "./lean.mjs";
+import { recoveryEvidence } from "./render.mjs";
 import { RECOVERABLE_CODES } from "../engine/outcome-codes.mjs";
 import { runFromCli, orchestrateFromCli } from "../engine-cli.mjs";
 // orchestrateFromCli opens the host lane registry (#4191): keep it in a temp dir.
@@ -17,7 +18,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
   // runOne: `script[n]` is a list of results, one per launch of issue n (the last repeats); ctx is recorded.
   const batch = (script, bodies = {}, extra = {}) => {
     const calls = [], decisions = [];
-    const p = orchestrate({ issues: Object.keys(script).map(Number), parallel: 3, recovery: { maxAttempts: 1 },
+    const p = orchestrate({ issues: Object.keys(script).map(Number), parallel: 3, recovery: { maxAttempts: extra.maxAttempts ?? 1 },
       readBody: async (n) => bodies[n] ?? "",
       runOne: async (n, _lane, ctx = {}) => {
         calls.push({ n, recover: ctx.recover ?? null });
@@ -37,7 +38,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     const r = byIssue(rows);
     assert.equal(r[1].outcome, "merged"); assert.equal(r[1].recovered, "ci.red");
     assert.equal(r[2].outcome, "merged", "the dependent was not skipped");
-    assert.deepEqual(calls.filter((c) => c.n === 1).map((c) => c.recover), [null, { code: "ci.red", attempt: 1 }]);
+    assert.deepEqual(calls.filter((c) => c.n === 1).map((c) => c.recover), [null, { code: "ci.red", attempt: 1, final: true }]);
     assert.ok(calls.findIndex((c) => c.n === 2) > calls.findLastIndex((c) => c.n === 1), "the dependent ran after the recovered merge");
     const d = decisions.find((x) => x.issue === 1);
     assert.match(d.what, /recovery lane for ci\.red/); assert.match(d.why, /Required check/); assert.ok(d.alternative);
@@ -138,7 +139,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     const ctxs = [];
     const rows = await orchestrate({ issues: [1], store, recovery: { maxAttempts: 1 }, readBody: async () => "",
       runOne: async (n, l, ctx) => { ctxs.push(ctx.recover); return NH("ci.red"); } });
-    assert.deepEqual(ctxs, [{ code: "ci.red", attempt: 1 }]);
+    assert.deepEqual(ctxs, [{ code: "ci.red", attempt: 1, final: true }]);
     assert.equal(rows[0].outcome, "needs-human"); assert.equal(rows[0].recovery.code, "ci.red");
     assert.deepEqual(state.recovering, {});
   });
@@ -160,7 +161,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
       await runFromCli(["7", "--lane", "staging", "--repo", "o/r", "--recover", "base.conflict", "--recover-attempt", "1"], { dir: tmpDir("core-rec-"), emitTelemetry: async () => {}, leanIo: {}, io: { gh: async () => "o/r\n" },
         leanModule: { runCore: async (o) => { got.push(o.recover); return { terminalReason: "merged" }; } } });
     } finally { console.log = l; }
-    assert.deepEqual(got, [{ code: "base.conflict", attempt: 1 }]);
+    assert.deepEqual(got, [{ code: "base.conflict", attempt: 1, final: true }]);
     // The batch: a ci.red lane is relaunched in-process with recover, the decision is recorded and the report lists it.
     const leanIo = {
       gh: async (a) => (a.includes("milestone") ? JSON.stringify({ milestone: null }) : JSON.stringify({ body: "" })),
@@ -174,7 +175,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
         io: { gh: async () => "o/r\n" }, leanIo, sched: null, orchestration: { breaker: null, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 1 } }, decide: (d) => decisions.push(d),
         leanModule: { runCore: async (o) => { runs.push(o.recover ?? null); return o.recover ? { terminalReason: "merged", pr: 55 } : { terminalReason: "needs-human", code: "ci.red", detail: "Required check(s) failed on PR #55: test" }; } } });
     } finally { console.log = l; }
-    assert.deepEqual(runs, [null, { code: "ci.red", attempt: 1 }]);
+    assert.deepEqual(runs, [null, { code: "ci.red", attempt: 1, final: true }]);
     assert.equal(res.ok, true);
     assert.ok(decisions.some((d) => d.issue === 5 && /recovery lane for ci\.red/.test(d.what)));
     assert.ok(logs.includes("recovered: #5 (ci.red)"), logs.join("\n"));
@@ -189,6 +190,130 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     assert.match(step3, /one question list[\s\S]*once, at the end of the batch/);
     assert.match(spec, /recovered: #A \(ci\.red\) #B \(base\.conflict\)/);
   });
+
+  it("#4302: with maxAttempts 2 only the last attempt is final; a non-final attempt is not relabelled while its successor runs", async () => {
+    const relabels = [];
+    const conf = { maxAttempts: 2, conflicting: async () => true, relabelNeedsHuman: async (x) => { relabels.push(x); } };
+    const pend = { terminalReason: "ci-pending", pr: 9, detail: "CI still running" };
+    const seen = [];
+    const { rows, calls } = await batch({ 1: [NH("base.conflict"), pend, pend] }, {}, { ...conf, onUpdate: (r) => seen.push([r.outcome, relabels.length]) });
+    assert.deepEqual(calls.map((c) => c.recover), [null, { code: "base.conflict", attempt: 1, final: false }, { code: "base.conflict", attempt: 2, final: true }]);
+    assert.equal(rows[0].outcome, "ci-pending");
+    assert.ok(seen.filter(([o]) => o === "recovering").every(([, k]) => k === 0), "no relabel between attempts");
+    assert.deepEqual(relabels, [], "the final lane relabels ci-pending itself; the runner does not");
+  });
+
+  it("#4302: a non-final attempt that ends needs-human/ci-pending without a successor is relabelled by the runner, once", async () => {
+    const relabels = [];
+    const rl = { maxAttempts: 2, relabelNeedsHuman: async (x) => { relabels.push(x); } };
+    // ci-pending on a PR that does not conflict is not recoverable: no attempt 2.
+    const a = await batch({ 1: [NH("ci.red"), { terminalReason: "ci-pending", pr: 9, detail: "CI still running" }] }, {}, { ...rl, conflicting: async () => false });
+    assert.equal(a.calls.length, 2); assert.equal(a.rows[0].outcome, "ci-pending");
+    assert.equal(relabels.length, 1); assert.match(relabels[0].evidence, /Recovery pass for `ci\.red` \(attempt 1\) did not merge: it ended `ci-pending`/);
+    // needs-human with a human code is never recovered: no attempt 2.
+    relabels.length = 0;
+    const b = await batch({ 1: [NH("ci.red"), NH("builder.blocked", "needs credentials")] }, {}, rl);
+    assert.equal(b.calls.length, 2); assert.equal(b.rows[0].outcome, "needs-human");
+    assert.equal(relabels.length, 1); assert.match(relabels[0].evidence, /ended `needs-human` \(`builder\.blocked`\)/);
+    // maxAttempts 1: the only attempt is final, so the lane relabels and the runner does not (unchanged).
+    relabels.length = 0;
+    const c = await batch({ 1: [NH("ci.red"), NH("builder.blocked")] }, {}, { ...rl, maxAttempts: 1 });
+    assert.deepEqual(c.calls.map((x) => x.recover), [null, { code: "ci.red", attempt: 1, final: true }]);
+    assert.deepEqual(relabels, []);
+  });
+
+  describe("#4315: a recovery queued when the batch stops is relabelled needs-human with the full reason", () => {
+    const LONG = `ci.red: ${"x".repeat(400)} END-OF-REASON`;
+    // issue 1 ends ci.red twice (original lane + non-final attempt 1/2); `stop` ends the batch before attempt 2 launches
+    const stopped = async (stop) => {
+      const relabels = [], calls = [];
+      let tick; const secondRun = new Promise((r) => { tick = r; });
+      const rows = await orchestrate({ issues: stop.issues ?? [1], parallel: 2, recovery: { maxAttempts: 2 }, readBody: async () => "",
+        relabelNeedsHuman: async (x) => { relabels.push(x); },
+        runOne: async (n, _l, ctx = {}) => {
+          calls.push({ n, recover: ctx.recover ?? null });
+          if (n === 2) { await secondRun; return { terminalReason: "engine-error", detail: "boom" }; }
+          if (calls.filter((c) => c.n === 1).length === 2) tick();
+          await new Promise((r) => setImmediate(r));
+          return NH("ci.red", LONG);
+        }, ...stop.opts(calls) });
+      return { rows, relabels, calls: calls.filter((c) => c.n === 1) };
+    };
+    const check = ({ rows, relabels, calls }, cause) => {
+      assert.deepEqual(calls.map((c) => c.recover), [null, { code: "ci.red", attempt: 1, final: false }], "attempt 2 never launched");
+      assert.equal(relabels.length, 1); assert.equal(relabels[0].issue, 1);
+      assert.match(relabels[0].evidence, /Recovery pass for `ci\.red` \(attempt 1\) did not merge: it ended `needs-human` \(`ci\.red`\)/);
+      assert.ok(relabels[0].evidence.includes(LONG), "full reason, not 300 chars");
+      assert.match(relabels[0].evidence, /Recovery attempt 2\/2 for `ci\.red` was queued, but the batch stopped \(/);
+      assert.match(relabels[0].evidence, cause);
+      const r1 = byIssue(rows)[1];
+      assert.equal(r1.outcome, "held"); assert.equal(r1.recovery.code, "ci.red"); assert.equal(r1.recovery.attempts, 2);
+      assert.match(formatOutcomeLists(rows).join("\n"), /unrecovered: #1/);
+    };
+
+    it("breaker", async () => {
+      check(await stopped({ issues: [1, 2], opts: () => ({ breaker: { errors: 1, window_min: 30 } }) }), /circuit breaker/);
+    });
+    it("execution budget (on_budget stop)", async () => {
+      check(await stopped({ opts: (calls) => ({ remote: { max: 3, isRemote: () => true, admit: () => (calls.length >= 2 ? { ok: false, reason: "cap $5 reached" } : { ok: true }) } }) }),
+        /execution budget: cap \$5 reached/);
+    });
+    it("drift hold", async () => {
+      check(await stopped({ opts: (calls) => ({ drift: { holds: () => (calls.length >= 2 ? "packages/ui" : null) } }) }), /drift: packages\/ui flagged/);
+    });
+
+    it("a resume of a lost run that does not relaunch it relabels once; a second resume does not repeat it", async () => {
+      let state = { v: 1, order: [1], deps: { 1: [] }, pending: [], results: {}, running: { 1: { startedAt: 1, pid: 999 } }, recoveries: { 1: 2 },
+        recovering: { 1: { code: "ci.red", attempt: 2, detail: LONG, outcome: "needs-human", result_code: "ci.red", prev_attempt: 1 } },
+        breaker: { at: 1, detail: "circuit breaker: 3 engine-errors within 30 min; admissions stopped" } };
+      const store = { load: () => state, save: (s) => { state = s; }, log: () => {} };
+      const relabels = [], ran = [];
+      const go = () => orchestrate({ issues: [1], store, recovery: { maxAttempts: 2 }, readBody: async () => "", adopt: async () => null,
+        relabelNeedsHuman: async (x) => { relabels.push(x); }, runOne: async (n) => { ran.push(n); return { terminalReason: "merged" }; } });
+      const rows = await go();
+      assert.deepEqual(ran, []); assert.equal(rows[0].outcome, "held");
+      assert.equal(relabels.length, 1); assert.ok(relabels[0].evidence.includes(LONG));
+      assert.match(relabels[0].evidence, /attempt 1\) did not merge.*[\s\S]*circuit breaker/);
+      assert.deepEqual(state.relabelled, [1]);
+      await go();
+      assert.equal(relabels.length, 1, "relabelled once across resumes");
+    });
+
+    it("a resume that relaunches the lost recovery lane does not relabel; the lane gets ctx.recover", async () => {
+      let state = { v: 1, order: [1], deps: { 1: [] }, pending: [], results: {}, running: { 1: { startedAt: 1, pid: 999 } }, recoveries: { 1: 2 },
+        recovering: { 1: { code: "ci.red", attempt: 2, detail: LONG, outcome: "needs-human", prev_attempt: 1 } }, relabelled: [1] };
+      const store = { load: () => state, save: (s) => { state = s; }, log: () => {} };
+      const relabels = [], ctxs = [];
+      const rows = await orchestrate({ issues: [1], store, recovery: { maxAttempts: 2 }, readBody: async () => "", adopt: async () => null,
+        relabelNeedsHuman: async (x) => { relabels.push(x); }, runOne: async (n, l, ctx) => { ctxs.push(ctx.recover); return { terminalReason: "merged" }; } });
+      assert.deepEqual(ctxs, [{ code: "ci.red", attempt: 2, final: true }]);
+      assert.equal(rows[0].outcome, "merged"); assert.deepEqual(relabels, []);
+      assert.equal(state.relabelled, undefined);
+    });
+
+    it("a store from before #4315 (no detail, no relabelled) still resumes and relabels with the code", async () => {
+      let state = { v: 1, order: [1], deps: { 1: [] }, pending: [1], results: {}, running: {}, recoveries: { 1: 1 }, recovering: { 1: { code: "ci.red", attempt: 1 } },
+        breaker: { at: 1, detail: "circuit breaker: tripped" } };
+      const store = { load: () => state, save: (s) => { state = s; }, log: () => {} };
+      const relabels = [];
+      const rows = await orchestrate({ issues: [1], store, recovery: { maxAttempts: 2 }, readBody: async () => "",
+        relabelNeedsHuman: async (x) => { relabels.push(x); }, runOne: async () => ({ terminalReason: "merged" }) });
+      assert.equal(rows[0].outcome, "held"); assert.equal(rows[0].recovery.detail, "ci.red");
+      assert.equal(relabels.length, 1); assert.match(relabels[0].evidence, /The lane did not merge: it ended `needs-human`/);
+    });
+  });
+
+  it("#4302: --recover-nonfinal reaches runCore as final: false; without it a recovery lane is final", async () => {
+    const got = [];
+    const l = console.log; console.log = () => {};
+    try {
+      for (const extra of [["--recover-nonfinal"], []]) {
+        await runFromCli(["7", "--lane", "staging", "--repo", "o/r", "--recover", "ci.red", "--recover-attempt", "1", ...extra], { dir: tmpDir("core-rec-"), emitTelemetry: async () => {}, leanIo: {}, io: { gh: async () => "o/r\n" },
+          leanModule: { runCore: async (o) => { got.push(o.recover); return { terminalReason: "merged" }; } } });
+      }
+    } finally { console.log = l; }
+    assert.deepEqual(got, [{ code: "ci.red", attempt: 1, final: false }, { code: "ci.red", attempt: 1, final: true }]);
+  });
 });
 
 describe("#4298 staging-review follow-ups: recovery", () => {
@@ -197,7 +322,7 @@ describe("#4298 staging-review follow-ups: recovery", () => {
     for (const c of RECOVERABLE_CODES) assert.ok(String(RECOVER_HOW[c]).length > 20, c);
   });
 
-  it("a recovered row reports the first attempt's cost and minutes summed with the recovery's; the lane sees only {code, attempt}", async () => {
+  it("a recovered row reports the first attempt's cost and minutes summed with the recovery's; the lane sees only {code, attempt, final}", async () => {
     let t = 0; const seen = [];
     const script = { 1: [{ terminalReason: "needs-human", code: "ci.red", detail: "red", cost_usd: 0.5 }, { terminalReason: "merged", pr: 9, cost_usd: 0.25 }],
       2: [{ terminalReason: "needs-human", code: "ci.red", detail: "red", cost_usd: 1 }, { terminalReason: "needs-human", code: "ci.red", detail: "red again", cost_usd: 2 }] };
@@ -207,7 +332,7 @@ describe("#4298 staging-review follow-ups: recovery", () => {
     const r = Object.fromEntries(rows.map((x) => [x.issue, x]));
     assert.equal(r[1].outcome, "merged"); assert.equal(r[1].cost_usd, 0.75); assert.equal(r[1].minutes, 6);
     assert.equal(r[2].outcome, "needs-human"); assert.equal(r[2].cost_usd, 3); assert.equal(r[2].minutes, 2);
-    assert.deepEqual(seen.filter(Boolean), [{ code: "ci.red", attempt: 1 }, { code: "ci.red", attempt: 1 }]);
+    assert.deepEqual(seen.filter(Boolean), [{ code: "ci.red", attempt: 1, final: true }, { code: "ci.red", attempt: 1, final: true }]);
   });
 
   it("formatOutcomeLists caps a detail at OUTCOME_LINE_MAX", () => {
@@ -228,3 +353,67 @@ describe("#4298 staging-review follow-ups: recovery", () => {
     assert.match(spec, /resumes every daemon-hosted batch that has no report yet/);
   });
 });
+
+describe("#4304 staging-review follow-ups: recovery", () => {
+  it("a recovery row counts the pre-filter cost once; a single pass still includes it", async () => {
+    const script = { 1: [{ terminalReason: "needs-human", code: "ci.red", detail: "red", cost_usd: 1 }, { terminalReason: "needs-human", code: "ci.red", detail: "red again", cost_usd: 1 }],
+      2: [{ terminalReason: "merged", pr: 4, cost_usd: 1 }] };
+    const k = { 1: 0, 2: 0 };
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, recovery: { maxAttempts: 1 }, readBody: async () => "", now: () => 0,
+      prefilter: async () => ({ closed: false, cost_usd: 0.1 }), runOne: async (n) => script[n][k[n]++] });
+    const r = Object.fromEntries(rows.map((x) => [x.issue, x]));
+    assert.equal(k[1], 2, "issue 1 ran a recovery lane");
+    assert.equal(r[1].cost_usd, 2.1);
+    assert.equal(r[2].cost_usd, 1.1);
+  });
+
+  const runBatchWith = async (enginePath) => {
+    const leanIo = {
+      gh: async (a) => (a.includes("milestone") ? JSON.stringify({ milestone: null }) : JSON.stringify({ body: "" })),
+      git: async (a) => (a[0] === "ls-remote" ? "abc\trefs/heads/staging\n" : ""),
+    };
+    const runs = [], logs = [], l = console.log;
+    console.log = (x) => logs.push(String(x));
+    try {
+      await orchestrateFromCli(["5", "--repo", "o/r", "--no-prefilter"], { dir: tmpDir("core-rec-"), batchRoot: tmpDir("core-rec-batch-"), allowTmpfs: true, emitTelemetry: async () => {},
+        io: { gh: async () => "o/r\n" }, leanIo, sched: null, enginePath, orchestration: { breaker: null, maxDeferrals: 3, globalParallel: null, recovery: { maxAttempts: 1 } }, decide: () => {},
+        relabelNeedsHuman: async () => {},
+        leanModule: { runCore: async (o) => { runs.push(o.recover ?? null); return { terminalReason: "needs-human", code: "ci.red", detail: "Required check(s) failed on PR #55: test" }; } } });
+    } finally { console.log = l; }
+    return { runs, logs };
+  };
+
+  it("engine.path full turns batch recovery off (run-issue rejects --recover there); core keeps it", async () => {
+    const full = await runBatchWith("full");
+    assert.deepEqual(full.runs, [null]);
+    assert.ok(full.logs.some((x) => /recovery: off \(engine\.path is full/.test(x)), full.logs.join("\n"));
+    const core = await runBatchWith("core");
+    assert.deepEqual(core.runs, [null, { code: "ci.red", attempt: 1, final: true }]);
+  });
+});
+
+describe("#4316 one shared recovery evidence text", () => {
+  it("lane, settle and batch-exit relabels render the same evidence shape", () => {
+    const long = `${"x".repeat(320)}\nsecond line`;
+    assert.equal(recoveryEvidence({ code: "ci.red", attempt: 1, outcome: "needs-human", resultCode: "ci.red", detail: "  red check\nmore  " }),
+      "Recovery pass for `ci.red` (attempt 1) did not merge: it ended `needs-human` (`ci.red`): red check. The issue stays `needs-human`.");
+    assert.equal(recoveryEvidence({ code: "ci.red", attempt: 2, outcome: "ci-pending", detail: "" }),
+      "Recovery pass for `ci.red` (attempt 2) did not merge: it ended `ci-pending`. The issue stays `needs-human`.");
+    assert.equal(recoveryEvidence({ code: "c", attempt: 1, outcome: "o", detail: long }).includes(`: ${"x".repeat(300)}. The issue`), true, "first line, 300 chars");
+    const queued = recoveryEvidence({ code: "base.conflict", attempt: 0, outcome: undefined, resultCode: "base.conflict", detail: long, full: true, queued: 1, cause: "breaker", recoveryMax: 2 });
+    assert.equal(queued, `The lane did not merge: it ended \`needs-human\` (\`base.conflict\`): ${long}\n\n`
+      + "Recovery attempt 1/2 for `base.conflict` was queued, but the batch stopped (breaker) before it launched. The issue stays `needs-human`.");
+    assert.match(recoveryEvidence({ code: "c", attempt: 1, outcome: "o", queued: 2, cause: "batch stopped" }), /^Recovery pass for `c` \(attempt 1\) did not merge: it ended `o`\n\nRecovery attempt 2\/2 /);
+  });
+  it("/orchestrate spec names the pre-filter's flaky exceptions and recovery being off on engine.path full", () => {
+    const spec = readFileSync(new URL("../../commands/orchestrate.md", import.meta.url), "utf8");
+    assert.match(spec, /unless it is flaky \(wording or `flaky` label\), was reopened after a pre-filter close, or\s+the workflow failed and passed at the same SHA/);
+    assert.match(spec, /recovery is off when `engine\.path: full`/);
+  });
+  it("orchestrate.mjs and lean.mjs build no copy of their own", () => {
+    for (const f of ["orchestrate.mjs", "lean.mjs"]) {
+      const src = readFileSync(new URL(`./${f}`, import.meta.url), "utf8");
+      assert.equal((src.match(/did not merge/g) ?? []).length, 0, f);
+    }
+  });
+});

package/bin/lean/render.mjs

@@ -50,6 +50,19 @@ export function capComment(body, max = MAX_COMMENT_CHARS) {
   const note = "\n\n_[truncated: comment exceeded the size cap]_";
   return s.slice(0, max - note.length) + note;
 }
+/**
+ * #4297/#4316: the one evidence text for a recovery that did not merge (lane, settle and batch-exit relabel). `attempt` 0 is
+ * the first lane; the detail is its first line capped at 300 chars unless `full`. `queued` (the attempt that never launched)
+ * adds why the batch stopped before it.
+ */
+export function recoveryEvidence({ code, attempt, outcome, resultCode, detail, full = false, queued = 0, cause = "", recoveryMax = 0 }) {
+  const how = attempt ? `Recovery pass for \`${code}\` (attempt ${attempt}) did not merge` : "The lane did not merge";
+  const d = String(detail ?? "").trim();
+  const shown = full ? d : d.split("\n")[0].slice(0, 300);
+  const head = `${how}: it ended \`${outcome ?? "needs-human"}\`${resultCode ? ` (\`${resultCode}\`)` : ""}${shown ? `: ${shown}` : ""}`;
+  return queued ? `${head}\n\nRecovery attempt ${queued}/${recoveryMax || queued} for \`${code}\` was queued, but the batch stopped (${cause}) before it launched. The issue stays \`needs-human\`.`
+    : `${head}. The issue stays \`needs-human\`.`;
+}
 const usable = (md) => sanitizeMd(md).replace(/\s+/g, " ").length >= 20;
 
 /** Text of the `### heading` section (up to the next heading), or "". */

package/bin/lean/testmap.mjs

@@ -59,6 +59,23 @@ export function selectCommands(map, files) {
   return out;
 }
 
+/**
+ * #4315: the pre-PR checks are the learned commands (in order) plus each map-selected command they lack; compared
+ * whitespace-collapsed, so the map can only add checks, never remove one. `source`: "learned" when the map added
+ * nothing, "test-map" when there were no learned commands, else "test-map+learned".
+ * @returns {{commands:string[], source:string, added:number}}
+ */
+export function mergeChecks(selected, learned) {
+  const norm = (c) => String(c ?? "").trim().replace(/\s+/g, " ");
+  const commands = [], seen = new Set();
+  const add = (c) => { const t = String(c ?? "").trim(), k = norm(t); if (!k || seen.has(k)) return false; seen.add(k); commands.push(t); return true; };
+  for (const c of Array.isArray(learned) ? learned : []) add(c);
+  const base = commands.length;
+  let added = 0;
+  for (const c of Array.isArray(selected) ? selected : []) if (add(c)) added++;
+  return { commands, added, source: !added ? "learned" : base ? "test-map+learned" : "test-map" };
+}
+
 /** The path of the first repo-facts file under `dirs` that exists, or null; never throws. */
 export async function factsPath(dirs, exists) {
   if (typeof exists !== "function") return null;