forgedock 1.24.4 → 1.25.0

package/bin/lean/orchestrate.mjs

@@ -1,68 +1,268 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Thin orchestrate: run core work-on for several issues with bounded concurrency, honouring `**Depends on**: #X`
+ * Thin orchestrate: run core work-on for several issues with bounded concurrency, honouring `Depends on` / `Blocked by`
  * among the given issues (wait for the dependency to merge; skip when it ends anywhere but merged/invalid).
+ * A `dependency-open` run is requeued behind its dependencies, pulling an out-of-set one into the batch; a
+ * `decomposed` run adds its sub-issues and its dependents wait on them instead (#4124).
  * No investigation, synthesis or agent spawning. `runOne(issue)` and `readBody(issue)` are injected.
+ * Optional `prefilter(issue, lane)` (#4123) runs in the lane slot before `runOne`: when it closed the issue, no lane starts.
+ * Optional `resolveLane(issue)` (#4125) works out each issue's own lane (milestone branch or staging): an issue whose
+ * lane is refused ends `lane-refused` without a run, and a dependency edge between two lanes goes to `onCrossLane`.
+ *
+ * Durable batch runner (#4121): with a `store` every transition is persisted, so a restarted dispatcher continues the
+ * batch; lanes it launched that are still alive are re-attached through `adopt(issue, rec)` instead of relaunched.
+ * `deferred` is a scheduling fact, not an end: each typed code is requeued with its retry-at (`deferPolicy`), a usage
+ * limit holds all admissions until its reset, and non-host deferrals stop after `maxDeferrals`. An `engine-error` is
+ * relaunched once; `breaker` ({errors, window_min}) stops admissions after a burst and lets running lanes finish, the
+ * rest stay pending (outcome `held`) for a resume. `getParallel()` is read on every pass, so K can change live.
  */
-const DEP_RE = /^\*\*Depends on\*\*:[ \t]*#(\d+)\b/gm;
+import { parseDependsOn } from "../engine/phases.mjs";
+
 // A dependency that finished like this no longer blocks its dependents.
 const SATISFIED = new Set(["merged", "invalid"]);
+// Times one issue may be requeued behind a dependency before its dependency-open row is final.
+export const MAX_REQUEUES = 2;
+// Non-host deferrals (anything but host.busy) one issue may take before its deferred row is final.
+export const DEFAULT_MAX_DEFERRALS = 3;
+// Relaunches of an issue whose lane ended engine-error.
+export const ENGINE_ERROR_RELAUNCHES = 1;
+export const HOST_BUSY_RETRY_S = 60;
+export const RATE_LIMIT_FALLBACK_S = 15 * 60;
+export const DEFER_BACKOFF_S = 120;
+export const DEFER_BACKOFF_MAX_S = 30 * 60;
+// A dependency-open whose dependencies already finished satisfied (GitHub not yet closed): wait before relaunching.
+export const DEP_REQUEUE_DELAY_S = 60;
 
+/** Declared dependencies of an issue body; the same parser as the engine's admission (`openDependency`). */
 export function parseDeps(body, issue) {
-  return [...new Set([...String(body ?? "").replace(/\r\n/g, "\n").matchAll(DEP_RE)].map((m) => Number(m[1])))].filter((n) => n > 0 && n !== issue);
+  return parseDependsOn(body, issue);
+}
+
+const posNum = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : null; };
+
+/**
+ * When to run a `deferred` issue again. `deferrals` counts this issue's earlier non-host deferrals.
+ * @returns {{delayMs:number, host?:true, hold?:true} | {capped:true}}
+ */
+export function deferPolicy(r, { now, deferrals = 0, maxDeferrals = DEFAULT_MAX_DEFERRALS }) {
+  const code = r?.code ?? null;
+  if (code === "host.busy") return { delayMs: (posNum(r?.retryInSeconds) ?? HOST_BUSY_RETRY_S) * 1000, host: true };
+  const k = deferrals + 1;
+  if (k > maxDeferrals) return { capped: true };
+  if (code === "rate_limited") {
+    const at = posNum(r?.resetAtEpochMs) && r.resetAtEpochMs > now ? r.resetAtEpochMs : now + (posNum(r?.retryInSeconds) ?? RATE_LIMIT_FALLBACK_S) * 1000;
+    return { delayMs: at - now, hold: true };
+  }
+  if (posNum(r?.retryInSeconds)) return { delayMs: r.retryInSeconds * 1000 };
+  // lease-held: "leased by X until <ISO>"
+  const until = /\buntil (\d{4}-\d\d-\d\dT[\d:.]+Z)/.exec(String(r?.detail ?? ""))?.[1];
+  const at = until ? Date.parse(until) : NaN;
+  if (Number.isFinite(at) && at > now) return { delayMs: Math.min(at - now + 5000, DEFER_BACKOFF_MAX_S * 1000) };
+  return { delayMs: Math.min(DEFER_BACKOFF_S * 2 ** (k - 1), DEFER_BACKOFF_MAX_S) * 1000 };
 }
 
+const cancellableSleep = (ms, signal) => new Promise((res) => {
+  const t = setTimeout(res, ms);
+  signal?.addEventListener("abort", () => { clearTimeout(t); res(); }, { once: true });
+});
+
+const toObj = (m) => Object.fromEntries([...m].map(([k, v]) => [String(k), v]));
+const toMap = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [Number(k), v]));
+
 /**
  * @returns {Promise<Array<{issue:number, outcome:string, pr:?number, cost_usd:number, minutes:number, detail?:string}>>}
  */
-export async function orchestrate({ issues, parallel = 3, runOne, readBody, now = () => Date.now(), onUpdate = () => {} }) {
-  const set = new Set(issues);
-  const deps = new Map();
-  for (const n of issues) {
+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 }) {
+  const saved = store?.load?.() ?? null;
+  const order = saved ? [...saved.order] : [];
+  const set = new Set(order);
+  const deps = toMap(saved?.deps); // issue -> declared dependencies (any issue); only those in `set` are edges
+  const lanes = toMap(saved?.lanes); // issue -> resolveLane result
+  const crossSeen = new Set(saved?.crossSeen ?? []);
+  const results = toMap(saved?.results); // issue -> final row
+  const running = new Map(); // issue -> promise
+  const runRecs = toMap(saved?.running); // issue -> {startedAt, lane, pid?}: persisted so a restart can adopt the lane
+  const pending = [...(saved?.pending ?? [])];
+  const notBefore = toMap(saved?.notBefore);
+  const requeues = toMap(saved?.requeues);
+  const deferrals = toMap(saved?.deferrals);
+  const engineErrors = toMap(saved?.engineErrors);
+  const checked = toMap(saved?.prefilter); // issue -> pre-filter result
+  let errorTimes = [...(saved?.errorTimes ?? [])];
+  let holdUntil = saved?.holdUntil ?? null;
+  let tripped = saved?.breaker ?? null;
+
+  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, holdUntil, breaker: tripped });
+  };
+  const update = (row) => { store?.log?.(row); onUpdate(row); };
+  const readDeps = async (n) => {
     let body = "";
     try { body = await readBody(n); } catch { /* unreadable: no ordering info, work-on's own check still applies */ }
-    deps.set(n, parseDeps(body, n).filter((d) => set.has(d)));
-  }
-  const results = new Map(); // issue -> row
-  const running = new Map(); // issue -> promise
-  const pending = [...new Set(issues)];
+    deps.set(n, parseDeps(body, n));
+    if (resolveLane) { let l; try { l = await resolveLane(n); } catch (e) { l = { ok: false, code: "lane.unresolved", detail: e?.message ?? String(e) }; } lanes.set(n, l); }
+  };
+  const edges = (n) => (deps.get(n) ?? []).filter((d) => set.has(d));
+  // A milestone issue waiting on a staging fix (or the reverse) never sees that fix on its own base: surface the edge.
+  const noteCrossLane = () => {
+    for (const n of order) for (const d of edges(n)) {
+      const a = lanes.get(n), b = lanes.get(d), key = `${n}<${d}`;
+      if (!a?.ok || !b?.ok || a.lane === b.lane || crossSeen.has(key)) continue;
+      crossSeen.add(key);
+      onCrossLane({ issue: n, lane: a.lane, dependency: d, dependencyLane: b.lane });
+    }
+  };
+  const addIssues = async (ns) => {
+    const fresh = ns.filter((d) => !set.has(d));
+    for (const d of fresh) { set.add(d); order.push(d); }
+    for (const d of fresh) { await readDeps(d); pending.push(d); }
+    noteCrossLane();
+  };
+  // New issues (a fresh batch, or extra issues passed to a resume) join the queue.
+  for (const n of issues) if (!set.has(n)) { set.add(n); order.push(n); pending.push(n); }
+  for (const n of order) if (!deps.has(n)) await readDeps(n);
+  noteCrossLane();
+  save();
+
+  const skip = (n, detail) => { results.set(n, { issue: n, outcome: "skipped", pr: null, cost_usd: 0, minutes: 0, detail }); update(results.get(n)); };
+  const requeue = (n, delayMs) => { pending.push(n); if (delayMs > 0) notBefore.set(n, now() + delayMs); else notBefore.delete(n); };
+  const noteEngineError = () => {
+    if (!breaker) return;
+    const t = now(), windowMs = breaker.window_min * 60000;
+    errorTimes = [...errorTimes.filter((x) => t - x < windowMs), t];
+    if (!tripped && errorTimes.length >= breaker.errors) {
+      tripped = { at: t, detail: `circuit breaker: ${errorTimes.length} engine-errors within ${breaker.window_min} min; admissions stopped` };
+      update({ issue: null, outcome: "breaker", detail: tripped.detail });
+    }
+  };
 
-  const skip = (n, detail) => { results.set(n, { issue: n, outcome: "skipped", pr: null, cost_usd: 0, minutes: 0, detail }); onUpdate(results.get(n)); };
+  // 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 } : {}) };
+    const depList = (Array.isArray(r?.dependencies) ? r.dependencies : []).filter((d) => Number.isSafeInteger(d) && d > 0 && d !== n);
+    const subs = (Array.isArray(r?.subissues) ? r.subissues : []).filter((d) => Number.isSafeInteger(d) && d > 0 && d !== n);
+    const done = () => { running.delete(n); runRecs.delete(n); };
+    if (row.outcome === "dependency-open" && depList.length && (requeues.get(n) ?? 0) < MAX_REQUEUES) {
+      // A scheduling fact, not a failure: add the edge, pull the dependency in, and run this issue again after it.
+      requeues.set(n, (requeues.get(n) ?? 0) + 1);
+      deps.set(n, [...new Set([...(deps.get(n) ?? []), ...depList])]);
+      await addIssues(depList);
+      // 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();
+      update({ ...row, detail: `requeued behind ${depList.map((d) => `#${d}`).join(", ")}` });
+      return;
+    }
+    if (row.outcome === "deferred") {
+      const pol = deferPolicy(r, { now: now(), deferrals: deferrals.get(n) ?? 0, maxDeferrals });
+      if (!pol.capped) {
+        if (!pol.host) deferrals.set(n, (deferrals.get(n) ?? 0) + 1);
+        if (pol.hold) holdUntil = Math.max(holdUntil ?? 0, now() + pol.delayMs);
+        requeue(n, pol.delayMs); done(); save();
+        update({ ...row, detail: `requeued in ${Math.round(pol.delayMs / 1000)}s${pol.hold ? " (admissions held)" : ""}: ${r?.code ?? "deferred"}${r?.detail ? ` ${r.detail}` : ""}` });
+        return;
+      }
+      row.detail = `gave up after ${deferrals.get(n) ?? 0} deferrals: ${r?.detail ?? r?.code ?? ""}`;
+    }
+    if (row.outcome === "engine-error") {
+      noteEngineError();
+      if ((engineErrors.get(n) ?? 0) < ENGINE_ERROR_RELAUNCHES) {
+        engineErrors.set(n, (engineErrors.get(n) ?? 0) + 1);
+        requeue(n, 0); done(); save();
+        update({ ...row, detail: `relaunching once: ${row.detail ?? ""}` });
+        return;
+      }
+    }
+    if (row.outcome === "decomposed" && subs.length) {
+      await addIssues(subs);
+      for (const [m, ds] of deps) if (ds.includes(n)) deps.set(m, [...new Set(ds.flatMap((d) => (d === n ? subs : [d])))]);
+      noteCrossLane();
+    }
+    results.set(n, row); done(); save(); update(row);
+  };
+
+  const track = (n, p) => { running.set(n, p.catch((e) => settle(n, { terminalReason: "engine-error", detail: e?.message ?? String(e) }, runRecs.get(n), null))); };
   const start = (n) => {
-    const t0 = now();
-    const p = (async () => {
+    const ln = lanes.get(n);
+    if (ln && !ln.ok) { // settled synchronously: nothing runs, no lease, no comment
+      const row = { issue: n, outcome: "lane-refused", pr: null, cost_usd: 0, minutes: 0, detail: `${ln.code}: ${ln.detail}`, code: ln.code };
+      results.set(n, row); save(); update(row);
+      return;
+    }
+    const lane = ln?.lane;
+    const rec = { startedAt: now(), ...(lane ? { lane } : {}) };
+    runRecs.set(n, rec); notBefore.delete(n); save();
+    track(n, (async () => {
+      // Pre-filter once per issue (a requeued issue is not re-checked); fail-open: an error means a normal lane.
+      if (prefilter && !checked.has(n)) { let pf = null; try { pf = await prefilter(n, lane); } catch { pf = null; } checked.set(n, pf); save(); }
+      const pf = checked.get(n) ?? null;
       let r;
-      try { r = await runOne(n); } catch (e) { r = { terminalReason: "engine-error", detail: e?.message ?? String(e) }; }
-      const row = { issue: n, outcome: r?.terminalReason ?? "engine-error", pr: r?.pr ?? null, cost_usd: r?.cost_usd ?? 0, minutes: Math.round((now() - t0) / 6000) / 10, detail: r?.detail };
-      results.set(n, row); running.delete(n); onUpdate(row);
-    })();
-    running.set(n, p);
+      if (pf?.closed) r = { terminalReason: "invalid", cost_usd: 0, detail: `pre-filter: ${pf.detail}` };
+      else {
+        try { r = await runOne(n, lane, { onStart: (info) => { Object.assign(rec, info ?? {}); save(); } }); }
+        catch (e) { r = { terminalReason: "engine-error", detail: e?.message ?? String(e) }; }
+      }
+      await settle(n, r, rec, pf);
+    })());
   };
 
+  // Lanes launched by an earlier dispatcher: re-attach to the live ones, queue the rest again (no result was recorded).
+  for (const [n, rec] of [...runRecs]) {
+    let p = null;
+    if (adopt && rec?.pid) { try { p = await adopt(n, rec); } catch { p = null; } }
+    if (p) track(n, Promise.resolve(p).then((r) => settle(n, r, rec, checked.get(n) ?? null)));
+    else { runRecs.delete(n); if (!pending.includes(n) && !results.has(n)) pending.unshift(n); }
+  }
+  save();
+
+  const K = () => { let k = null; try { k = getParallel?.(); } catch { k = null; } return Number.isInteger(k) && k >= 1 ? k : parallel; };
   while (pending.length || running.size) {
     // Resolve skips first: a dependency that finished unsatisfied (or never can) skips its dependents.
     for (let i = pending.length - 1; i >= 0; i--) {
       const n = pending[i];
-      const bad = deps.get(n).find((d) => results.has(d) && !SATISFIED.has(results.get(d).outcome));
+      if (results.has(n)) { pending.splice(i, 1); continue; }
+      const bad = edges(n).find((d) => results.has(d) && !SATISFIED.has(results.get(d).outcome));
       if (bad !== undefined) { pending.splice(i, 1); skip(n, `dependency #${bad} ended ${results.get(bad).outcome}`); }
     }
-    for (let i = 0; i < pending.length && running.size < parallel;) {
-      const n = pending[i];
-      if (deps.get(n).every((d) => results.has(d) && SATISFIED.has(results.get(d).outcome))) { pending.splice(i, 1); start(n); }
-      else i++;
+    const t = now();
+    if (holdUntil && t >= holdUntil) { holdUntil = null; save(); }
+    let started = 0;
+    if (!tripped && !holdUntil) {
+      for (let i = 0; i < pending.length && running.size < K();) {
+        const n = pending[i];
+        if ((notBefore.get(n) ?? 0) <= t && edges(n).every((d) => results.has(d) && SATISFIED.has(results.get(d).outcome))) { pending.splice(i, 1); start(n); started++; }
+        else i++;
+      }
     }
-    if (running.size) await Promise.race(running.values());
-    else if (pending.length) { // nothing runnable and nothing running: a dependency cycle
+    if (tripped && !running.size) break; // breaker: let running lanes finish, keep the rest pending for a resume
+    // Wake for a delayed issue, the end of a usage-limit hold, or (with a live K) a poll.
+    const waits = pending.map((n) => notBefore.get(n) ?? 0).filter((x) => x > t);
+    if (holdUntil) waits.push(holdUntil);
+    let wake = waits.length ? Math.max(0, Math.min(...waits) - t) : null;
+    if (getParallel && pending.length) wake = Math.min(wake ?? pollMs, pollMs);
+    if (tripped) wake = null;
+    if (running.size) {
+      if (wake === null) await Promise.race(running.values());
+      else { const ac = new AbortController(); await Promise.race([...running.values(), sleep(wake, ac.signal)]); ac.abort(); }
+    } else if (started) continue; // only lane-refused rows settled (synchronously): re-resolve skips first
+    else if (pending.length && waits.length) await sleep(Math.max(0, Math.min(...waits) - t));
+    else if (pending.length) { // nothing runnable, nothing running, nothing waiting on time: a dependency cycle
       for (const n of pending.splice(0)) skip(n, "dependency cycle");
+      save();
     }
   }
-  return issues.filter((n, i) => issues.indexOf(n) === i).map((n) => results.get(n));
+  save();
+  return order.map((n) => results.get(n) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: tripped?.detail ?? "not run" });
 }
 
 export function formatTable(rows) {
   const head = ["issue", "outcome", "PR", "cost", "min"];
-  const body = rows.map((r) => [`#${r.issue}`, r.outcome + (r.outcome === "skipped" && r.detail ? ` (${r.detail})` : ""), r.pr ? `#${r.pr}` : "-", `$${(r.cost_usd ?? 0).toFixed(2)}`, String(r.minutes ?? 0)]);
+  const body = rows.map((r) => [`#${r.issue}`, r.outcome + (["skipped", "held"].includes(r.outcome) && r.detail ? ` (${r.detail})` : r.prefilter?.closed ? " (pre-filter)" : ""), r.pr ? `#${r.pr}` : "-", `$${(r.cost_usd ?? 0).toFixed(2)}`, String(r.minutes ?? 0)]);
   const w = head.map((h, i) => Math.max(h.length, ...body.map((b) => b[i].length)));
   const line = (c) => c.map((x, i) => x.padEnd(w[i])).join("  ").trimEnd();
   return [line(head), line(w.map((n) => "-".repeat(n))), ...body.map(line)].join("\n");

package/bin/lean/prefilter.mjs

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * 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
+ *   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 { PREFILTER_SYSTEM, prefilterPrompt, parsePrefilterVerdict } from "./prompts.mjs";
+
+export const DEFAULT_PREFILTER_MODEL = "claude-haiku-5-5";
+export const PREFILTER_MARKER = "FORGE:PREFILTER";
+/** Spend avoided per pre-filter close when the batch has no full-lane invalid run to average (#4123: ~$13 / 21 lanes). */
+export const DEFAULT_AVOIDED_USD = 0.62;
+
+const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** `Fixes #N`, `closes owner/repo#N`, `resolved: #N`, or a lean-style title/subject ending `(#N)`. */
+export function claimsFix(text, n) {
+  const s = String(text ?? "");
+  return new RegExp(`\\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\b:?\\s+(?:[\\w.-]+/[\\w.-]+)?#${n}(?!\\d)`, "i").test(s)
+    || new RegExp(`\\(#${n}\\)\\s*$`, "m").test(s);
+}
+
+const RUN_URL_RE = /https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/actions\/runs\/(\d+)/;
+const CI_FAIL_RE = /\b(?:fail(?:s|ed|ing|ure)?|broken|red)\b/i;
+/** The failing Actions run of an auto-filed CI-failure issue: failure wording plus a run link in the title or body. */
+export function ciFailureRun(iss) {
+  const text = `${iss.title ?? ""}\n${iss.body ?? ""}`;
+  const m = RUN_URL_RE.exec(text);
+  return m && CI_FAIL_RE.test(text) ? { repo: m[1], id: Number(m[2]) } : null;
+}
+
+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, " ");
+  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[]}>}
+ */
+export async function collectSignals({ iss, repo, lane, io, cwd }) {
+  const n = iss.number;
+  const sig = { prs: [], commits: [], ci: null, missingPaths: [], namedPaths: [] };
+  try {
+    const found = JSON.parse(String(await io.gh(["search", "prs", `#${n}`, "--repo", repo, "--merged", "--json", "number,title,body,url", "--limit", "20"])) || "[]");
+    sig.prs = found.filter((p) => claimsFix(p.title, n) || claimsFix(p.body, n));
+  } catch { /* search unavailable: no PR signal */ }
+  try {
+    const log = String(await io.git(["log", `origin/${lane}`, "--max-count=50", "-E", `--grep=#${n}([^0-9]|$)`, "--format=%H%x09%s"], { cwd }));
+    sig.commits = log.split("\n").map((l) => l.split("\t")).filter(([h, s]) => h && s && !/^Merge /.test(s) && claimsFix(s, n)).map(([sha, subject]) => ({ sha, subject }));
+  } catch { /* no lane ref: no commit signal */ }
+  const run = ciFailureRun(iss);
+  if (run && run.repo.toLowerCase() === repo.toLowerCase()) {
+    try {
+      const failed = JSON.parse(String(await io.gh(["api", `repos/${repo}/actions/runs/${run.id}`])));
+      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 ?? "" };
+      }
+    } catch { /* run unreadable: no CI signal */ }
+  }
+  sig.namedPaths = namedPaths(iss.body);
+  if (sig.namedPaths.length) {
+    const missing = [];
+    for (const p of sig.namedPaths.slice(0, 20)) {
+      try { await io.git(["cat-file", "-e", `origin/${lane}:${p}`], { cwd }); } catch { missing.push(p); }
+    }
+    if (missing.length === Math.min(sig.namedPaths.length, 20)) sig.missingPaths = missing; // all gone: the code moved or was removed
+  }
+  return sig;
+}
+
+/**
+ * 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 }) {
+  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"])));
+    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) {
+      let st = null;
+      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 close = async (kind, body, detail) => {
+      if (!dryRun) {
+        await io.gh(["issue", "comment", String(issue), "-R", repo, "--body", capComment(`<!-- ${PREFILTER_MARKER} -->\n<!-- FORGE:VALIDATE -->\n${body}`)]);
+        await io.gh(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
+        try { await io.transitionLabel?.(issue, "invalid"); } catch { /* labels are best effort */ }
+      }
+      return { ...out, closed: !dryRun, kind, 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" };
+    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}` };
+    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` }; }
+    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` };
+    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})`);
+  } catch (e) {
+    return { ...out, detail: `pre-filter error (${String(e?.message ?? e).slice(0, 120)}): lane` };
+  }
+}
+
+/** 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 } : {}) });
+}
+
+/** One report line: how many the pre-filter checked, flagged and closed, what validation cost, and the spend avoided. */
+export function formatPrefilterSummary(rows) {
+  const pf = rows.filter((r) => r?.prefilter);
+  if (!pf.length) return "";
+  const closed = pf.filter((r) => r.prefilter.closed);
+  const lanes = rows.filter((r) => r && !r.prefilter?.closed && r.outcome === "invalid" && (r.cost_usd ?? 0) > 0);
+  const per = lanes.length ? lanes.reduce((a, r) => a + r.cost_usd, 0) / lanes.length : DEFAULT_AVOIDED_USD;
+  const spent = pf.reduce((a, r) => a + (r.prefilter.cost_usd ?? 0), 0);
+  const ci = closed.filter((r) => r.prefilter.kind === "ci-green").length;
+  return `pre-filter: ${pf.length} checked, ${pf.filter((r) => r.prefilter.candidate).length} candidate(s), ${closed.length} closed without a lane (${ci} CI green, ${closed.length - ci} validated); validation $${spent.toFixed(2)}, spend avoided ~$${Math.max(0, closed.length * per - spent).toFixed(2)} (${lanes.length ? "batch invalid-lane average" : "default"} $${per.toFixed(2)}/lane)`;
+}