forgedock 1.31.0 → 1.32.1

package/bin/lean/orchestrate.mjs

@@ -14,7 +14,9 @@
  * 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.
+ * batch; lanes it launched that are still alive are re-attached through `adopt(issue, rec, {onLive})` instead of relaunched.
+ * A seam calls `onLive()` before it waits on a live lane (#4504); an adopt that resolves first is settled (or requeued on null)
+ * before scheduling, so a live lane does not hold up the others.
  * `deferred` is a scheduling fact, not an end: each typed code is requeued with its retry-at (`deferPolicy`), a usage
  * limit holds admissions for that account until its reset, and non-host deferrals stop after `maxDeferrals`.
  * Usage-limit holds (#4190) are keyed by backend identity in `limits` (the host store, shared by every batch on the
@@ -41,6 +43,13 @@
  * `priorities`) ranks it host-wide, and the batch's ready issues are tried in priority order. Ready issues it cannot
  * start yet stay offered in the registry (polled every `pollMs`) and are withdrawn once no longer ready; a settled lane
  * releases its slot, an adopted one re-records it.
+ * Per-issue lock (#4481), on with `sched.exclusive` (registry entries ask `exclusive: true`): when another batch holds a live slot for the same repo and issue (`tryAcquire` `conflict`, or
+ * `registry.holder` for a lane placed remote), the issue is not started: it is retried after `pollMs` with one `deferred`
+ * row naming that batch (no deferral count, no breaker), and admission goes on with the next ready issue.
+ *
+ * Dispatch check (#4481), off unless `dispatchCheck(issue)` is passed: it runs before EVERY lane start (first and
+ * requeued, unlike the once-per-issue pre-filter) and returns null (run) or `{outcome: "merged", pr}` / `{outcome:
+ * "invalid"}` for an issue already closed or whose PR merged; the row ends with that outcome and no lane starts. Fail-open.
  *
  * Remote lanes (#4253), off unless `remote: {max, isRemote(issue)}` is passed (execution.mjs): a lane `isRemote` places
  * in a sandbox takes no host registry slot; it starts only while fewer than `max` remote lanes of this batch run (the
@@ -217,7 +226,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   store = null, adopt = null, getParallel = null, getAdded = 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,
   recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null, onExit = null, issueLabels = null, getCancelled = null, stopLane = null,
-  estimate = null, starveMs = DEFAULT_STARVE_MS, signal = null }) {
+  estimate = null, starveMs = DEFAULT_STARVE_MS, signal = null, dispatchCheck = null }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
   const set = new Set(order);
@@ -380,7 +389,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     return ready.map((n) => ({ n, p: prioOf(n), b: heads.has(n) || starved(n) ? 0 : 1, s: starved(n) ? enqueued.get(n) : 0, w: weight(n), i: idx.get(n) ?? 0 }))
       .sort((a, b) => a.p - b.p || a.b - b.b || a.s - b.s || b.w - a.w || a.i - b.i).map((x) => x.n);
   };
-  const entryOf = (n) => ({ key: keyOf(n), batch: sched?.batch ?? batchId ?? null, repo: sched?.repo ?? null, issue: n, priority: prioOf(n) });
+  const entryOf = (n) => ({ key: keyOf(n), batch: sched?.batch ?? batchId ?? null, repo: sched?.repo ?? null, issue: n, priority: prioOf(n), ...(sched?.exclusive ? { exclusive: true } : {}) });
   const releaseSlot = (n) => { if (reg && slotted.delete(n)) reg.release(keyOf(n)); };
   const offerFresh = (ns) => { const fresh = ns.filter((n) => !offered.has(n)); if (!fresh.length) return; reg.offer(fresh.map(entryOf)); for (const n of fresh) offered.add(n); };
   const withdrawExcept = (keep) => {
@@ -407,10 +416,28 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     if (budgetHit === null) update({ issue: null, outcome: "budget", detail: `execution budget reached: ${reason}; ${remote?.onBudget === "local" || remote?.fallbackLocal ? "remaining lanes run locally" : "no further remote lanes admitted"}` });
     budgetHit = reason;
   };
+  // #4481: another batch runs a lane for `n` now: retry after a poll, one row (and decision) per other batch.
+  const busyNoted = new Map(); // issue -> the other batch last reported
+  const busy = (n, other, wanted) => {
+    const delayMs = Math.max(pollMs, 1);
+    notBefore.set(n, now() + delayMs); offered.delete(n); wanted.delete(n);
+    if (busyNoted.get(n) !== other) {
+      busyNoted.set(n, other); save();
+      decided({ issue: n, what: `deferred: batch ${other} runs a lane for #${n}`, why: "one lane per issue on the host (two batches include it)", alternative: "run a second lane on the same branch" });
+      update({ issue: n, outcome: "deferred", pr: null, cost_usd: 0, minutes: 0, detail: `#${n} has a live lane in batch ${other}; retried in ${Math.round(delayMs / 1000)}s` });
+    }
+    return "busy";
+  };
   // A host slot for `n` (a lane-refused issue runs nothing and needs none); refused: `n` stays queued in the registry.
+  // true: start it; false: no capacity now; "busy" (#4481): another batch runs `n`, try the next issue.
   const grant = (n, wanted) => {
     if (lanes.get(n)?.ok === false) return true;
     let p = placeOf(n);
+    if (p?.where === "remote" && reg?.holder) {
+      let other = null;
+      try { other = reg.holder(entryOf(n)) ?? null; } catch { other = null; }
+      if (other !== null) return busy(n, other, wanted);
+    }
     if (p?.where === "remote") {
       const adm = admitRemote();
       if (adm.ok) {
@@ -426,6 +453,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     }
     if (!reg) { if (p) placed.set(n, p); return true; }
     const r = reg.tryAcquire(keyOf(n), entryOf(n), sched.cap);
+    if (!r?.ok && r?.conflict != null) return busy(n, r.conflict, wanted);
     if (!r?.ok) { offered.add(n); wanted.add(n); return false; }
     offered.delete(n); slotted.add(n);
     if (p) placed.set(n, p);
@@ -452,6 +480,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     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 } : {}),
+      ...(Number.isFinite(r?.wall_ms) ? { wall_ms: r.wall_ms } : {}), ...(Number.isFinite(r?.model_ms) ? { model_ms: r.model_ms } : {}), // #4451
       ...(Number.isFinite(r?.precheckMs) ? { precheck_ms: r.precheckMs } : {}), ...(Number.isInteger(r?.precheckDeferred) && r.precheckDeferred > 0 ? { precheck_deferred: r.precheckDeferred } : {}), // #4331
       ...(typeof r?.firstPass === "boolean" ? { first_pass: r.firstPass } : {}), // #4362
       ...(r?.turns && typeof r.turns === "object" ? { turns: r.turns } : {}), // #4392
@@ -604,17 +633,24 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     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);
-    heads.delete(n); enqueued.delete(n);
+    heads.delete(n); enqueued.delete(n); busyNoted.delete(n);
     const rec = { startedAt: now(), ...(lane ? { lane } : {}), ...(remoteRun.has(n) ? { remote: true } : {}), ...(pl ? { placement: pl } : {}) };
     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;
+      // #4481: every start re-checks GitHub: a closed issue or a merged PR ends the row without a lane (fail-open).
+      let gone = null;
+      if (dispatchCheck && !cancelled && !pf?.closed && !pf?.parked) {
+        try { gone = (await dispatchCheck(n)) ?? null; } catch { gone = null; }
+        if (!["merged", "invalid"].includes(gone?.outcome)) gone = null;
+      }
       if (halted) return; // #4454: stopped before launch; no pid, so a resume queues it again
       let r;
       if (cancelled) r = { terminalReason: "deferred", code: "run.interrupted", cost_usd: 0, detail: "cancelled before launch" }; // #4376
       else if (pf?.closed) r = { terminalReason: "invalid", cost_usd: 0, detail: `pre-filter: ${pf.detail}` };
+      else if (gone) r = { terminalReason: gone.outcome, pr: Number.isInteger(gone.pr) ? gone.pr : null, cost_usd: 0, detail: `skipped at dispatch: ${gone.detail ?? gone.outcome}` };
       // #4389: a parked post-deploy follow-up starts no lane; it ends awaiting-promotion|awaiting-precondition, re-checked next batch.
       else if (pf?.parked) r = { terminalReason: pf.kind, cost_usd: 0, detail: `pre-filter: ${pf.detail}` };
       else {
@@ -632,15 +668,34 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   };
 
   // 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 || rec?.handle)) { try { p = await adopt(n, rec); } catch { p = null; } }
-    if (p && rec.remote) { remoteRun.add(n); track(n, Promise.resolve(p).then((r) => settle(n, r, rec, checked.get(n) ?? null))); }
-    else if (p) {
-      if (reg) { reg.adoptSlot(keyOf(n), { ...entryOf(n), lanePid: rec.pid }); slotted.add(n); }
-      track(n, Promise.resolve(p).then((r) => settle(n, r, rec, checked.get(n) ?? null)));
+  // #4504: every adopt starts at once and races its `onLive` signal, so a live lane never holds up the others: one that
+  // already ended is settled from its result (or requeued without one) before scheduling; a live one is awaited in the background.
+  const requeueLost = (n) => { runRecs.delete(n); if (!pending.includes(n) && !results.has(n)) { pending.unshift(n); enqueued.set(n, now()); } };
+  const adopting = [...runRecs].map(([n, rec]) => {
+    if (!adopt || !(rec?.pid || rec?.handle)) return { n, rec, live: false, p: Promise.resolve(null) };
+    let onLive;
+    const isLive = new Promise((r) => { onLive = () => r(true); });
+    const p = Promise.resolve().then(() => adopt(n, rec, { onLive })).catch(() => null);
+    return { n, rec, p, first: Promise.race([p.then(() => false), isLive]) };
+  });
+  for (const a of adopting) a.live = a.first ? await a.first : false;
+  for (const { n, rec, p, live } of adopting) {
+    if (live) {
+      if (rec.remote) remoteRun.add(n);
+      else if (reg) { reg.adoptSlot(keyOf(n), { ...entryOf(n), lanePid: rec.pid }); slotted.add(n); }
+      track(n, p.then((r) => {
+        if (r) return settle(n, r, rec, checked.get(n) ?? null);
+        if (halted) return; // #4454: kept for the next resume
+        running.delete(n); releaseSlot(n); remoteRun.delete(n); requeueLost(n); save(); // ended without a result after all
+      }));
+      continue;
     }
-    else { runRecs.delete(n); if (!pending.includes(n) && !results.has(n)) { pending.unshift(n); enqueued.set(n, now()); } }
+    const r = await p;
+    if (!r) { requeueLost(n); continue; }
+    if (rec.remote) remoteRun.add(n);
+    else if (reg) { reg.adoptSlot(keyOf(n), { ...entryOf(n), lanePid: rec.pid }); slotted.add(n); } // released by the settle
+    track(n, Promise.resolve(r).then((x) => settle(n, x, rec, checked.get(n) ?? null)));
+    await running.get(n); // settled before scheduling
   }
   // A resume re-derives each unfinished issue's lane from its current milestone (#4153): a re-milestone takes effect.
   if (saved && resolveLane) {
@@ -766,7 +821,9 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
           const n = pickNext(ready, { classes, share: budget.share, whenIdle: budget.whenIdle, started: dispatch.started, maint: dispatch.maint,
             featuresPending: pending.some((p) => !clsOf(classes, p).maintenance) });
           if (n === null) { budgetHeld = ready.length > 0; break; }
-          if (!grant(n, wanted)) break;
+          const g = grant(n, wanted);
+          if (g === "busy") continue; // #4481: not ready any more this pass (notBefore), so `ready` drops it
+          if (!g) break;
           pending.splice(pending.indexOf(n), 1);
           if (lanes.get(n)?.ok !== false) { dispatch.started++; if (clsOf(classes, n).maintenance) dispatch.maint++; }
           start(n); started++;
@@ -778,13 +835,16 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
         offerFresh(want);
         for (const n of want) wanted.add(n);
         for (const n of ready) {
-          if (running.size >= K() || !grant(n, wanted)) break;
+          if (running.size >= K()) break;
+          const g = grant(n, wanted);
+          if (g === "busy") continue; // #4481
+          if (!g) break;
           pending.splice(pending.indexOf(n), 1); start(n); started++;
         }
       } else if (!tripped && !cancelled && !holdUntil) {
         for (const n of rank(pending.filter(isReady))) {
           if (running.size >= K()) break;
-          if (grant(n, new Set())) { pending.splice(pending.indexOf(n), 1); start(n); started++; }
+          if (grant(n, new Set()) === true) { pending.splice(pending.indexOf(n), 1); start(n); started++; }
         }
       }
       if (reg) withdrawExcept(wanted);

package/bin/lean/precheck.test.mjs

@@ -118,6 +118,11 @@ describe("formatPrecheckSummary (#4331)", () => {
     assert.deepEqual(rows.map((r) => [r.issue, r.precheck_ms, r.precheck_deferred]), [[1, 90000, 1], [2, 30000, undefined], [3, undefined, undefined]]);
     assert.equal(formatPrecheckSummary(rows), "precheck: 2.0m total over 2 lanes, 1 deferred to CI");
   });
+  it("#4451: orchestrate rows carry the lane's wall_ms and model_ms, so wall vs model time can be measured", async () => {
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, readBody: async () => "",
+      runOne: async (n) => ({ terminalReason: "merged", ...({ 1: { wall_ms: 90000, model_ms: 60000 } })[n] }) });
+    assert.deepEqual(rows.map((r) => [r.issue, r.wall_ms, r.model_ms]), [[1, 90000, 60000], [2, undefined, undefined]]);
+  });
   it("#4362: orchestrate rows carry the lane's firstPass as first_pass for the batch first-pass line", async () => {
     const rows = await orchestrate({ issues: [1, 2, 3], parallel: 1, readBody: async () => "",
       runOne: async (n) => ({ terminalReason: "merged", ...({ 1: { firstPass: true }, 2: { firstPass: false } })[n] }) });

package/bin/lean/prefilter.mjs

@@ -12,7 +12,9 @@
  * ALREADY-FIXED/INVALID verdict with evidence closes the issue; everything else, and every error, goes to the normal lane.
  * Post-deploy gate (#4389), with `defaultBranch`: a `FORGE:DEFERRED_FROM: #P` follow-up whose checklist items are all
  * post-deploy is parked (`parked: true`, label `awaiting-promotion`, no lane) while a merge SHA of #P is not an ancestor
- * of origin/<default>, or while forge.yaml `post_deploy.precondition_cmd` exits 1. Anything unresolvable fails open.
+ * of origin/<default>, or while forge.yaml `post_deploy.precondition_cmd` exits 1. With `post_deploy.min_age` (#4425) it also
+ * stays parked (`awaiting-min-age`) until that long (or the longest window an item's why states) after the fix landed on
+ * the default branch. Anything unresolvable fails open.
  * All effects are injected (gh, git, runner, transitionLabel, projector?, execCode?) so it is unit-testable.
  */
 import { execFile } from "node:child_process";
@@ -196,12 +198,52 @@ function execCode(cmd, args, opts) {
     try { execFile(cmd, args, opts, (err) => res(err ? (typeof err.code === "number" ? err.code : -1) : 0)); } catch { res(-1); }
   });
 }
+// #4425: post_deploy.min_age soak window. Deterministic: a strict duration parse, and git for the landing time.
+const UNIT_MS = { m: 60e3, h: 3600e3, d: 86400e3, w: 604800e3 };
+/** forge.yaml `post_deploy.min_age` ("30m", "24h", "7d", "2w"; a bare number is minutes, so "0" is allowed) -> ms, or null. */
+export function parseMinAge(s) {
+  if (s == null) return null;
+  const m = /^(\d+(?:\.\d+)?)\s*([mhdw]?)$/i.exec(String(s).trim());
+  return m ? Math.round(Number(m[1]) * UNIT_MS[(m[2] || "m").toLowerCase()]) : null;
+}
+const WINDOW_RE = /\b(\d+(?:\.\d+)?)\s*(h|hrs?|hours?|d|days?|w|wks?|weeks?)\b/gi;
+const POST_DEPLOY_ITEM_RE = /^`[^`]*`\s+(?:\*\*known-flaw\*\*\s+)?[—-]+\s*post-deploy:(.*)$/;
+/** Per post-deploy checklist item: the largest duration its why states (ms), or null when it states none. */
+export function itemWindowsMs(body) {
+  return noComments(String(body ?? ""), " ").split("\n").map((l) => CHECK_RE.exec(l)?.[1]).filter((x) => x != null)
+    .map((t) => POST_DEPLOY_ITEM_RE.exec(t)).filter(Boolean).map((m) => {
+      const ms = [...m[1].matchAll(WINDOW_RE)].map((w) => Number(w[1]) * UNIT_MS[w[2][0].toLowerCase()]);
+      return ms.length ? Math.round(Math.max(...ms)) : null;
+    });
+}
+/**
+ * Unix seconds when `sha` reached origin/<def>: the oldest first-parent commit of <def> that descends from it (the merge
+ * that brought it in), or the SHA's own commit time when it is on the mainline itself. Null on any git error.
+ */
+export async function landedAt({ sha, def, io, cwd }) {
+  try {
+    // --first-parent with --ancestry-path drops merges that brought the SHA in through a second parent (git 2.55): two walks
+    const range = `${sha}..origin/${def}`;
+    const below = new Set(String(await io.git(["rev-list", "--ancestry-path", range], { cwd })).trim().split(/\s+/).filter(Boolean));
+    const chain = String(await io.git(["log", "--first-parent", "--format=%H %P %ct", range], { cwd })).trim().split("\n").map((l) => l.trim().split(/\s+/));
+    const oldest = chain.filter((c) => below.has(c[0])).at(-1);
+    let own = !oldest;
+    if (!own) {
+      const full = /^[0-9a-f]{40}$/i.test(sha) ? sha : String(await io.git(["rev-parse", `${sha}^{commit}`], { cwd })).trim();
+      own = oldest[1]?.toLowerCase() === full.toLowerCase();
+    }
+    const ct = own ? String(await io.git(["log", "-1", "--format=%ct", sha], { cwd })).trim() : oldest.at(-1);
+    return /^\d+$/.test(ct) ? Number(ct) : null;
+  } catch { return null; }
+}
+const fmtAge = (ms) => (ms % UNIT_MS.d === 0 && ms ? `${ms / UNIT_MS.d}d` : ms % UNIT_MS.h === 0 && ms ? `${ms / UNIT_MS.h}h` : `${Math.round(ms / UNIT_MS.m)}m`);
 /**
  * #4389: never throws, no model call. `defaultBranch` is a name or an (async) function resolving it (and fetching it).
- * @returns {Promise<{state:"not-applicable"|"unresolved"|"awaiting-promotion"|"awaiting-precondition"|"ready", parent:?number, shas:string[], default?:string, detail:string}>}
+ * #4425: `minAge` (ms, opt-in) parks `awaiting-min-age` until max(item window ?? minAge) after the fix landed on <default>.
+ * @returns {Promise<{state:"not-applicable"|"unresolved"|"awaiting-promotion"|"awaiting-min-age"|"awaiting-precondition"|"ready", parent:?number, shas:string[], default?:string, eligibleAt?:string, detail:string}>}
  * Fail-open: no merge SHA, a git answer other than yes/no, an unknown default branch or a hook error give "unresolved".
  */
-export async function postDeployGate({ iss, repo, lane, defaultBranch, cwd, io, preconditionCmd = null }) {
+export async function postDeployGate({ iss, repo, lane, defaultBranch, cwd, io, preconditionCmd = null, minAge = null, now = null }) {
   const parent = deferredFrom(iss?.body);
   const res = (state, detail, extra = {}) => ({ state, parent, shas: [], detail, ...extra });
   if (!parent || !postDeployOnly(iss.body)) return res("not-applicable", "");
@@ -218,6 +260,20 @@ export async function postDeployGate({ iss, repo, lane, defaultBranch, cwd, io,
       if (!on) off.push(sha);
     }
     if (off.length) return res("awaiting-promotion", `fix ${off.map((s) => s.slice(0, 12)).join(", ")} of #${parent} is not on ${def}${lane ? ` (lane ${lane})` : ""}`, { shas, default: def });
+    if (minAge != null) {
+      const required = Math.max(0, ...itemWindowsMs(iss.body).map((w) => w ?? minAge));
+      let landed = 0;
+      for (const sha of shas) {
+        const t = await landedAt({ sha, def, io, cwd });
+        if (t == null) return res("unresolved", `landing time of ${sha.slice(0, 12)} on ${def} unknown`, { shas, default: def });
+        landed = Math.max(landed, t);
+      }
+      const at = now ?? io.now?.() ?? Date.now(), until = landed * 1000 + required;
+      if (at < until) {
+        const eligibleAt = new Date(until).toISOString();
+        return res("awaiting-min-age", `fix of #${parent} on ${def} since ${new Date(landed * 1000).toISOString()}; min age ${fmtAge(required)} until ${eligibleAt}`, { shas, default: def, eligibleAt });
+      }
+    }
     if (preconditionCmd) {
       const code = await (io.execCode ?? execCode)("sh", ["-c", preconditionCmd, "precondition", String(iss.number)],
         { cwd, timeout: 60000, env: { ...process.env, FORGE_ISSUE: String(iss.number) } });
@@ -252,12 +308,12 @@ async function markParked({ issue, repo, io, had, gate }) {
     } catch { /* the comment and the report still show it */ }
   }
   if (had) return;
-  const what = gate.state === "awaiting-promotion" ? "awaiting promotion" : "awaiting its post-deploy precondition";
+  const what = gate.state === "awaiting-promotion" ? "awaiting promotion" : gate.state === "awaiting-min-age" ? "awaiting its post-deploy soak window" : "awaiting its post-deploy precondition";
   const body = `<!-- ${PRECONDITION_MARKER} -->\n## Parked: ${what}\n${sanitizeMd(gate.detail)}.\n\nEvery item here is a post-deploy check, so no lane was started. The next orchestrate or triage run checks again and launches this issue once the precondition holds.`;
   try { await io.gh(["issue", "comment", String(issue), "-R", repo, "--body", capComment(body)]); } catch { /* the label still shows it */ }
 }
 
-/** #4389 batch-report lines: one `awaiting promotion:` line (and one `awaiting precondition:` line) for the parked rows, or "". */
+/** #4389 batch-report lines: one `awaiting promotion:` line (and one `awaiting min age:` / `awaiting precondition:` line) for the parked rows, or "". */
 export function formatParkedLine(rows) {
   const parked = (rows ?? []).filter((r) => r?.prefilter?.parked);
   const uniq = (xs) => [...new Set(xs.filter(Boolean))];
@@ -267,6 +323,11 @@ export function formatParkedLine(rows) {
     const lanes = uniq(promo.map((r) => r.prefilter.lane)), defs = uniq(promo.map((r) => r.prefilter.default));
     out.push(`awaiting promotion: ${promo.map((r) => `#${r.issue}`).join(" ")} (fixes on ${lanes.join(", ") || "the lane"}, not on ${defs.join(", ") || "the default branch"})`);
   }
+  const soak = parked.filter((r) => r.prefilter.kind === "awaiting-min-age"); // #4425
+  if (soak.length) {
+    const defs = uniq(soak.map((r) => r.prefilter.default));
+    out.push(`awaiting min age: ${soak.map((r) => `#${r.issue}`).join(" ")} (fix on ${defs.join(", ") || "the default branch"}, soak window not elapsed)`);
+  }
   const pre = parked.filter((r) => r.prefilter.kind === "awaiting-precondition");
   if (pre.length) out.push(`awaiting precondition: ${pre.map((r) => `#${r.issue}`).join(" ")} (post_deploy.precondition_cmd not ready)`);
   return out.join("\n");
@@ -276,7 +337,7 @@ export function formatParkedLine(rows) {
  * 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, selfLogins = null, defaultBranch = null, preconditionCmd = null }) {
+export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAULT_PREFILTER_MODEL, dryRun = false, agentId = null, maxMinutes = 5, selfLogins = null, defaultBranch = null, preconditionCmd = null, minAge = 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,comments"])));
@@ -292,9 +353,9 @@ export async function prefilterIssue({ issue, repo, lane, cwd, io, model = DEFAU
       if (st?.lease && st.lease.until > Date.now() && st.lease.by !== agentId) return { ...out, detail: `leased by ${st.lease.by}` };
     }
     if (gated) {
-      const gate = await postDeployGate({ iss, repo, lane, defaultBranch, cwd, io, preconditionCmd });
+      const gate = await postDeployGate({ iss, repo, lane, defaultBranch, cwd, io, preconditionCmd, minAge });
       const had = names.includes(AWAITING_PROMOTION_LABEL);
-      if (gate.state === "awaiting-promotion" || gate.state === "awaiting-precondition") {
+      if (["awaiting-promotion", "awaiting-min-age", "awaiting-precondition"].includes(gate.state)) {
         if (!dryRun) await markParked({ issue, repo, io, had, gate });
         return { ...out, parked: true, kind: gate.state, parent: gate.parent, lane, default: gate.default, detail: gate.detail };
       }

package/bin/lean/prefilter.test.mjs

@@ -2,10 +2,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { prefilterIssue, flakyReason, makePrefilter, postDeployGate, postDeployOnly, deferredFrom, formatParkedLine, lazyDefaultBranch, ownLogins, resolveOwnLogins, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, isTrustedIssueComment, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
+import { prefilterIssue, flakyReason, makePrefilter, postDeployGate, postDeployOnly, deferredFrom, formatParkedLine, lazyDefaultBranch, ownLogins, resolveOwnLogins, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, isTrustedIssueComment, DEFAULT_PREFILTER_MODEL, parseMinAge, itemWindowsMs, landedAt } from "./prefilter.mjs";
+import { writeFileSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
 import { parsePrefilterVerdict, prefilterPrompt } from "./prompts.mjs";
 import { orchestrate, formatTable, formatOutcomeLists } from "./orchestrate.mjs";
-import { triageFromCli } from "../engine-cli.mjs";
+import { triageFromCli, readPostDeployMinAge } from "../engine-cli.mjs";
 
 const fence = (o) => "```json\n" + JSON.stringify(o) + "\n```";
 
@@ -477,6 +481,109 @@ describe("post-deploy precondition gate (#4389)", () => {
   });
 });
 
+describe("post_deploy.min_age soak window (#4425)", () => {
+  const MERGE = "a".repeat(40), PROMO = "b".repeat(40), MAIN = "c".repeat(40);
+  const H = 3600, LANDED = 1_800_000_000; // unix seconds of the promotion merge
+  const item = (id, why) => `- [ ] \`${id}: a health row exists\` — post-deploy: ${why}`;
+  const followup = (items) => `## Acceptance Criteria\n\n${items.join("\n")}\n\n<!-- FORGE:DEFERRED_FROM: #40 -->\n`;
+  const parentPr = [{ number: 90, title: "fix(x): health row (#40)", body: "", mergeCommit: { oid: MERGE } }];
+  // the parent fix reached main through promotion merge PROMO (first parent MAIN) at LANDED
+  const soakWorld = (o = {}) => {
+    const w = world({ mergedPrs: parentPr, ancestry: { [MERGE]: 0 }, ...o });
+    const git = w.io.git;
+    w.io.git = async (a, opts) => {
+      if (a[0] === "log" && a[1] === "--first-parent") { w.gitCalls.push(a); return o.walk ?? `${"d".repeat(40)} ${PROMO} ${LANDED + 9 * H}\n${PROMO} ${MAIN} ${MERGE} ${LANDED}\n${MAIN} ${"e".repeat(40)} ${LANDED - H}\n`; }
+      if (a[0] === "rev-list") { w.gitCalls.push(a); return o.below ?? `${"d".repeat(40)}\n${PROMO}\n`; }
+      if (a[0] === "log" && a[1] === "-1") { w.gitCalls.push(a); return String(LANDED - 5 * H); }
+      return git(a, opts);
+    };
+    return w;
+  };
+  const gate = (w, body, extra = {}) => postDeployGate({ iss: { number: 41, body }, repo: "o/r", lane: "staging", defaultBranch: "main", cwd: "/repo", io: w.io, ...extra });
+
+  it("parses min_age and the windows each post-deploy item's why states (largest wins, none -> null)", () => {
+    assert.equal(parseMinAge("24h"), 24 * H * 1000); assert.equal(parseMinAge("7d"), 7 * 24 * H * 1000); assert.equal(parseMinAge("2w"), 14 * 24 * H * 1000);
+    assert.equal(parseMinAge("30m"), 30 * 60e3); assert.equal(parseMinAge("0"), 0); assert.equal(parseMinAge(90), 90 * 60e3);
+    assert.equal(parseMinAge("soon"), null); assert.equal(parseMinAge(null), null);
+    assert.deepEqual(itemWindowsMs(followup([item("R1", "after 24h of traffic, then 7 days of retention"), item("R2", "only in prod")])), [7 * 24 * H * 1000, null]);
+  });
+
+  it("landedAt: the promotion merge time, or the SHA's own time when it is on the mainline", async () => {
+    const w = soakWorld();
+    assert.equal(await landedAt({ sha: MERGE, def: "main", io: w.io, cwd: "/repo" }), LANDED);
+    assert.deepEqual(w.gitCalls.slice(0, 2), [["rev-list", "--ancestry-path", `${MERGE}..origin/main`], ["log", "--first-parent", "--format=%H %P %ct", `${MERGE}..origin/main`]]);
+    const own = soakWorld({ walk: `${PROMO} ${MERGE} ${LANDED}\n`, below: `${PROMO}\n` });
+    assert.equal(await landedAt({ sha: MERGE, def: "main", io: own.io, cwd: "/repo" }), LANDED - 5 * H);
+    const tip = soakWorld({ walk: "", below: "" });
+    assert.equal(await landedAt({ sha: MERGE, def: "main", io: tip.io, cwd: "/repo" }), LANDED - 5 * H);
+  });
+
+  it("landedAt on a real repo: the promotion merge that brought a staging fix in through its second parent", async () => {
+    const d = tmpDir("landed-");
+    const run = (args, t) => execFileSync("git", args, { cwd: d, encoding: "utf8", env: { ...process.env, GIT_AUTHOR_DATE: `@${t} +0000`, GIT_COMMITTER_DATE: `@${t} +0000`,
+      GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" } }).trim();
+    run(["init", "-q", "-b", "main"], 1);
+    run(["commit", "-q", "--allow-empty", "-m", "base"], LANDED - 10 * H);
+    run(["checkout", "-q", "-b", "staging"], 1);
+    run(["commit", "-q", "--allow-empty", "-m", "fix"], LANDED - 8 * H);
+    const fix = run(["rev-parse", "HEAD"], 1);
+    run(["checkout", "-q", "main"], 1);
+    run(["commit", "-q", "--allow-empty", "-m", "hotfix on main"], LANDED - 2 * H);
+    run(["merge", "-q", "--no-ff", "-m", "promote", "staging"], LANDED);
+    run(["commit", "-q", "--allow-empty", "-m", "later"], LANDED + 5 * H);
+    run(["update-ref", "refs/remotes/origin/main", "HEAD"], 1);
+    const io = { git: async (a, o) => run(a, 1) + "\n" };
+    assert.equal(await landedAt({ sha: fix, def: "main", io, cwd: d }), LANDED);
+    assert.equal(await landedAt({ sha: fix.slice(0, 12), def: "main", io, cwd: d }), LANDED);
+    assert.equal(await landedAt({ sha: run(["rev-parse", "HEAD~1^1"], 1), def: "main", io, cwd: d }), LANDED - 2 * H); // on the mainline itself
+    assert.equal(await landedAt({ sha: "f".repeat(40), def: "main", io, cwd: d }), null);
+  });
+
+  it("parks awaiting-min-age until max(item window ?? min_age) after landing, then is ready", async () => {
+    const body = followup([item("R1", "wait 7d of production data"), item("R2", "only in prod")]);
+    const g = await gate(soakWorld(), body, { minAge: parseMinAge("24h"), now: (LANDED + 48 * H) * 1000 });
+    assert.equal(g.state, "awaiting-min-age");
+    assert.equal(g.eligibleAt, new Date((LANDED + 7 * 24 * H) * 1000).toISOString());
+    assert.match(g.detail, /^fix of #40 on main since .*; min age 7d until /);
+    // no stated window: the min_age floor applies
+    const short = followup([item("R2", "only in prod")]);
+    assert.equal((await gate(soakWorld(), short, { minAge: parseMinAge("24h"), now: (LANDED + 23 * H) * 1000 })).state, "awaiting-min-age");
+    assert.equal((await gate(soakWorld(), short, { minAge: parseMinAge("24h"), now: (LANDED + 25 * H) * 1000 })).state, "ready");
+    assert.equal((await gate(soakWorld(), body, { minAge: 0, now: (LANDED + 8 * 24 * H) * 1000 })).state, "ready");
+  });
+
+  it("unset min_age changes nothing (no landing-time git calls); an unknown landing time fails open", async () => {
+    const w = soakWorld();
+    assert.equal((await gate(w, followup([item("R1", "wait 7d")]))).state, "ready");
+    assert.ok(!w.gitCalls.some((a) => a[0] === "log" || a[0] === "rev-list"));
+    const broken = soakWorld();
+    const git = broken.io.git;
+    broken.io.git = async (a, o) => { if (a[0] === "rev-list") throw Object.assign(new Error("bad"), { code: 128 }); return git(a, o); };
+    const g = await gate(broken, followup([item("R1", "wait 7d")]), { minAge: 0 });
+    assert.equal(g.state, "unresolved"); assert.match(g.detail, /landing time of aaaaaaaaaaaa on main unknown/);
+  });
+
+  it("prefilterIssue parks it with the awaiting-promotion label, one comment, and an 'awaiting min age:' report line", async () => {
+    const w = soakWorld({ issues: { 41: { body: followup([item("R1", "wait 7d")]) } } });
+    w.io.now = () => (LANDED + H) * 1000;
+    const r = await pf(w, 41, { defaultBranch: "main", minAge: parseMinAge("24h") });
+    assert.equal(r.parked, true); assert.equal(r.kind, "awaiting-min-age"); assert.equal(r.cost_usd, 0);
+    assert.deepEqual(w.edits, [[41, "--add-label", "awaiting-promotion"]]);
+    assert.equal(w.comments.length, 1); assert.match(w.comments[0][1], /Parked: awaiting its post-deploy soak window/);
+    assert.equal(formatParkedLine([{ issue: 41, prefilter: r }, { issue: 42, prefilter: { parked: true, kind: "awaiting-promotion", lane: "staging", default: "main" } }]),
+      "awaiting promotion: #42 (fixes on staging, not on main)\nawaiting min age: #41 (fix on main, soak window not elapsed)");
+  });
+
+  it("readPostDeployMinAge reads forge.yaml post_deploy.min_age; absent or invalid -> null", async () => {
+    const d = tmpDir("minage-");
+    assert.equal(await readPostDeployMinAge(d), null);
+    writeFileSync(join(d, "forge.yaml"), "post_deploy:\n  min_age: \"24h\"\n");
+    assert.equal(await readPostDeployMinAge(d), 24 * H * 1000);
+    writeFileSync(join(d, "forge.yaml"), "post_deploy:\n  min_age: later\n");
+    assert.equal(await readPostDeployMinAge(d), null);
+  });
+});
+
 describe("#4467: isTrustedIssueComment", () => {
   it("trusts the App in gh issue view and REST shapes and trusted associations; not other contributors", () => {
     assert.equal(isTrustedIssueComment({ author: { login: "rapiercraft-forgedock" }, authorAssociation: "CONTRIBUTOR" }), true);

package/bin/lean/prompts.mjs

@@ -24,6 +24,9 @@ export const FORGEDOCK_CLI = fileURLToPath(new URL("../forgedock.mjs", import.me
 const HOST_RULES = `Host rules (many lanes share this machine): run only targeted tests (specific files or -k filters), never the full suite. Never create extra checkouts, copies or base clones of the repo; compare with git show or git diff origin/<base>. Never install browsers. Keep scratch files under $TMPDIR. Cap verification workers at $FORGE_HOST_PARALLELISM when set: turbo --concurrency, vitest/jest --maxWorkers, playwright --workers, node --test --test-concurrency (eslint via turbo). For any typecheck, lint or test you run, first run \`node ${CHECKS_CLI} --base origin/<base>\` after your edits and run the scoped commands it prints instead of the full tsc/eslint/test scripts (it widens itself when impact is unknown: lockfile, tsconfig, CI config); once they pass, rerun it with --publish to share the incremental caches. Lint changed packages only, never dependents (turbo ...[base], nx affected). node_modules/.venv may be hardlinked read-only from a shared cache: after changing a lockfile, or when an install fails with EACCES, delete that dir first (rm -rf is safe), then install; never chmod or edit files inside it.
 Quiet output (tool results are re-read every later turn): run tests quietly (-q or a dot/summary reporter); on failure read \`tail -40\` plus the failing test ids (grep FAILED / not ok / FAIL), never the whole log. Send output over 8 KB to a $TMPDIR file; tail or grep it. Issue independent read-only calls (reads, greps, git log/blame, gh) in the same turn or one shell call. Read each file's ranges once (sed -n a,bp or Read offset/limit, never a whole large file) and keep notes; don't re-read it.`;
 
+/** #4450: the host-rules block of the builder prompts (toolchain, sparse and repo-facts lines included), reused by the light-lane prompt. */
+export const hostRules = ({ toolchain = null, sparse = null, facts = null } = {}) => `${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}`;
+
 /** Verify-by-CI (#4167): in ci/hybrid mode the engine runs the repo's CI on GitHub runners; the host runs only light checks. */
 const LIGHT = "run only formatters and linters on the files you changed";
 const VERIFY_RUN = { ci: `${LIGHT} (no type-checks, test suites or test containers)`, hybrid: "run the targeted validate commands" };

package/bin/lean/retry.mjs

@@ -5,7 +5,9 @@
 export const PUSH_TRANSIENT_RE = /remote unpack failed|index-pack failed|RPC failed|unexpected disconnect|early EOF|the remote end hung up|HTTP\/?\s?5\d\d|returned error: 5\d\d|\b50[0234]\b|internal server error|bad gateway|service unavailable|gateway time-?out|connection (?:reset|timed out|refused)|timed out|could not resolve host|broken pipe|ETIMEDOUT|ECONNRESET|temporarily unavailable|\[remote rejected\][^\n]*\(failed\)|unable to write file|unable to create temporary object|unpacker error|failed to write object/i;
 export const PUSH_PERMANENT_RE = /protected branch|GH006|GH013|repository rule violations|permission (?:denied|to .* denied)|denied to|\b403\b|authentication failed|not allowed|hook declined|pre-receive hook declined|\[rejected\]|non-fast-forward|fetch first/i;
 export const GH_TRANSIENT_RE = /HTTP 5\d\d|\b50[0234]\b|secondary rate limit|rate limit exceeded|abuse detection|something went wrong|internal server error|bad gateway|service unavailable|ETIMEDOUT|ECONNRESET|connection reset|timed out|\bEOF\b|temporarily unavailable/i;
-export const MERGE_TRANSIENT_RE = new RegExp(`${GH_TRANSIENT_RE.source}|base branch was modified|head branch was modified|mergeability.*unknown|try again`, "i");
+/** #4507: gh failing to parse its own input: a torn HTTP cache entry (JSON) or a half-written config (YAML). */
+export const GH_PARSE_RE = /invalid character .{0,40}looking for|unexpected end of JSON input|cannot unmarshal|yaml: line \d+|yaml: unmarshal/i;
+export const MERGE_TRANSIENT_RE = new RegExp(`${GH_TRANSIENT_RE.source}|${GH_PARSE_RE.source}|base branch was modified|head branch was modified|mergeability.*unknown|try again`, "i");
 export const MERGE_CONFLICT_RE = /not mergeable|merge conflict|conflict/i;
 
 export const errText = (e) => `${e?.stderr ?? ""}\n${e?.message ?? ""}\n${e?.stdout ?? ""}`;
@@ -29,3 +31,15 @@ export async function retrying(fn, { transient, permanent = null, attempts = 4,
   last.transientExhausted = true;
   throw last;
 }
+
+/**
+ * #4507: run `call(env)` with the lane's gh cache env; on a gh parse error (corrupt cache) reset the cache and run it
+ * once more. Without a cache it still retries once. Any other error is rethrown unchanged.
+ */
+export async function ghCacheRetry(call, cache) {
+  try { return await call(cache?.env?.()); } catch (e) {
+    if (!GH_PARSE_RE.test(errText(e))) throw e;
+    try { await cache?.reset?.(); } catch { /* retry on the old dir */ }
+    return await call(cache?.env?.());
+  }
+}

package/bin/lean/sched.mjs

@@ -17,6 +17,9 @@
  * (`forgedock sched cap N`), else the caller's forge.yaml `orchestration.global_parallel`, else none. Fail-open: an
  * unreadable registry or a lock not taken within `lockWaitMs` grants (`fallback: true`), since a stuck registry would
  * stall every batch on the host.
+ * Per-issue lock (#4481), asked for per request with `exclusive: true` in the entry (not stored; the batch runner sets it):
+ * such a key is never granted while a live slot of another batch holds the same (non-null) repo and issue, so two batches that both include issue N (a resumed batch and a new one) never run two lanes for N at once;
+ * `tryAcquire` answers `{ok:false, conflict:<batch>}` and drops the key from the queue (it would hold a grant rank).
  */
 import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
@@ -50,6 +53,14 @@ const posInt = (k) => (Number.isInteger(k) && k >= 1 ? k : null);
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 const byRank = ([ka, a], [kb, b]) => (a.priority - b.priority) || (a.seq - b.seq) || (ka < kb ? -1 : ka > kb ? 1 : 0);
 const groupOf = (k, e) => e?.repo ?? e?.batch ?? k;
+/** #4481: the batch of another live slot running the same repo and issue as an `exclusive` `entry`, or null (no repo: never). */
+const holderOf = (s, key, entry) => {
+  if (entry?.exclusive !== true || !entry.repo || entry.issue == null) return null;
+  for (const [k, e] of Object.entries(s.slots)) {
+    if (k !== key && e?.repo === entry.repo && e?.issue === entry.issue && (e.batch ?? null) !== (entry.batch ?? null)) return e.batch ?? k;
+  }
+  return null;
+};
 
 /**
  * Queue entries `[key, entry]` in grant order: priority ascending, then a weighted fair share across repos within each
@@ -88,7 +99,7 @@ export function grantOrder(s) {
 
 /**
  * Handle on the registry. `pid` is this dispatcher; `alive(pid)` is the liveness probe (injected in tests).
- * @returns {{dir, tryAcquire, offer, withdraw, release, setLanePid, adoptSlot, cap, setCap, weights, setWeight, list}}
+ * @returns {{dir, tryAcquire, holder, offer, withdraw, release, setLanePid, adoptSlot, cap, setCap, weights, setWeight, list}}
  */
 export function openSched(dir = schedDir(), { now = () => Date.now(), pid = process.pid, alive = pidAlive, lockWaitMs = LOCK_WAIT_MS } = {}) {
   const file = join(dir, "registry.json"), lockFile = join(dir, "registry.lock");
@@ -167,6 +178,8 @@ export function openSched(dir = schedDir(), { now = () => Date.now(), pid = proc
       try {
         return mutate((s) => {
           if (s.slots[key]) return { ok: true };
+          const holder = holderOf(s, key, entry);
+          if (holder !== null) { delete s.queue[key]; return { ok: false, conflict: holder, reason: `#${entry.issue} has a live lane in batch ${holder}` }; }
           enqueue(s, key, entry);
           const cap = effCap(s, callerCap);
           if (cap !== null) {
@@ -182,6 +195,8 @@ export function openSched(dir = schedDir(), { now = () => Date.now(), pid = proc
         });
       } catch (e) { return { ok: true, fallback: true, reason: e?.message ?? String(e) }; }
     },
+    /** #4481: the other batch holding a live slot for `{repo, issue}` (not `batch`), or null; null on any error. */
+    holder: (entry = {}) => { try { return mutate((s) => holderOf(s, null, entry)); } catch { return null; } },
     /** Queue entries `[{key, batch, repo, issue, priority}]` (their FIFO position is kept on a re-offer). */
     offer: (entries) => { try { mutate((s) => { for (const e of entries) enqueue(s, e.key, e); }); } catch { /* fail-open */ } },
     withdraw: (keys) => { if (!keys.length) return; try { mutate((s) => { for (const k of keys) delete s.queue[k]; }); } catch { /* fail-open */ } },

package/bin/lean/sched.test.mjs

@@ -434,3 +434,51 @@ describe("longest-first admission (#4409)", () => {
     assert.equal(estCalls, 0);
   });
 });
+
+describe("#4481: one lane per repo and issue across batches", () => {
+  it("the registry refuses a second batch's key for a live repo+issue slot, names the batch and drops it from the queue", () => {
+    const { handle, live } = world();
+    const a = handle(201), b = handle(202);
+    assert.equal(a.tryAcquire("A#5", { batch: "A", repo: "o/r", issue: 5, exclusive: true }, 4).ok, true);
+    const r = b.tryAcquire("B#5", { batch: "B", repo: "o/r", issue: 5, exclusive: true }, 4);
+    assert.deepEqual([r.ok, r.conflict], [false, "A"]);
+    assert.match(r.reason, /#5 has a live lane in batch A/);
+    assert.deepEqual(b.list().queue, [], "a refused key holds no grant rank");
+    assert.equal(b.holder({ batch: "B", repo: "o/r", issue: 5, exclusive: true }), "A");
+    assert.equal(a.holder({ batch: "A", repo: "o/r", issue: 5, exclusive: true }), null, "its own batch is no conflict");
+    assert.equal(b.tryAcquire("B#6", { batch: "B", repo: "o/r", issue: 6, exclusive: true }, 4).ok, true, "another issue");
+    assert.equal(b.tryAcquire("C#5", { batch: "C", repo: "o/other", issue: 5, exclusive: true }, 4).ok, true, "another repo");
+    assert.equal(b.tryAcquire("D#5", { batch: "D", repo: null, issue: 5, exclusive: true }, 4).ok, true, "no repo: unchanged");
+    assert.equal(a.tryAcquire("A#5", { batch: "A", repo: "o/r", issue: 5, exclusive: true }, 4).ok, true, "a granted key stays granted");
+    assert.equal(b.tryAcquire("E#5", { batch: "E", repo: "o/r", issue: 5 }, null).ok, true, "not exclusive: unchanged");
+    b.release("E#5");
+    live.delete(201); // A's dispatcher dies with no lane: its slot is reclaimed
+    assert.equal(b.tryAcquire("B#5", { batch: "B", repo: "o/r", issue: 5, exclusive: true }, 4).ok, true);
+  });
+
+  it("two batches that both include issue N never run two lanes for N; the second defers naming the first and runs its other issues", async () => {
+    const { handle } = world();
+    const regA = handle(301), regB = handle(302);
+    const active = new Map(), maxActive = new Map(), ranB = [];
+    let releaseA;
+    const gateA = new Promise((r) => { releaseA = r; });
+    const lane = (n) => { active.set(n, (active.get(n) ?? 0) + 1); maxActive.set(n, Math.max(maxActive.get(n) ?? 0, active.get(n))); };
+    const pA = orchestrate({ issues: [5], readBody: async () => "", pollMs: 2, batchId: "bA", sched: { registry: regA, batch: "bA", repo: "o/r", cap: null, exclusive: true },
+      runOne: async (n) => { lane(n); await gateA; active.set(n, active.get(n) - 1); return { terminalReason: "merged", cost_usd: 0 }; } });
+    await until(() => active.get(5) === 1, "batch A's lane");
+    const rowsB = [];
+    const pB = orchestrate({ issues: [5, 6], readBody: async () => "", pollMs: 2, batchId: "bB", sched: { registry: regB, batch: "bB", repo: "o/r", cap: null, exclusive: true },
+      onUpdate: (r) => rowsB.push(r),
+      runOne: async (n) => { lane(n); ranB.push(n); active.set(n, active.get(n) - 1); return { terminalReason: "merged", cost_usd: 0 }; } });
+    await until(() => ranB.includes(6), "batch B's other issue");
+    const deferred = rowsB.filter((r) => r.issue === 5 && r.outcome === "deferred");
+    assert.equal(deferred.length, 1, "one row per other batch");
+    assert.match(deferred[0].detail, /live lane in batch bA/);
+    assert.ok(!ranB.includes(5), "no second lane while batch A runs #5");
+    releaseA();
+    await pA;
+    const done = await pB;
+    assert.deepEqual(done.map((r) => [r.issue, r.outcome]).sort(), [[5, "merged"], [6, "merged"]]);
+    assert.equal(maxActive.get(5), 1);
+  });
+});