forgedock 1.29.1 → 1.30.0

package/bin/lean/orchestrate.mjs

@@ -59,7 +59,9 @@
  * `maxAttempts`) under the same admission as any lane, so its dependents stay queued. Only a final lane relabels needs-human
  * itself; a non-final attempt that ends needs-human/ci-pending without a successor is relabelled here, once (#4302). A recovery
  * still queued when the batch exits (breaker, budget, hold, or a resume that does not relaunch it) is relabelled once with the
- * full persisted lane reason (#4315).
+ * full persisted lane reason (#4315); also when the loop throws, and through `onExit(fn)` (the caller's signal handler
+ * awaits `fn(cause)`), each once (#4318). `relabelNeedsHuman` may return `false`/"failed" (not recorded, a resume retries)
+ * or "skipped" (closed or leased issue: recorded); any other result counts as relabelled.
  * A merged recovery row carries `recovered: <code>`; any other end is final with `recovery` evidence. Human codes (`builder.blocked`) are never recovered. Every operational decision the runner takes
  * (recovery, engine-error relaunch, dependency requeue, sub-issues added) goes to `decide({issue, what, why, alternative})`,
  * fire-and-forget: the runner never waits on it.
@@ -160,7 +162,7 @@ const toMap = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [Number(k),
 export async function orchestrate({ issues, parallel = 3, runOne, readBody, prefilter = null, resolveLane = null, now = () => Date.now(), onUpdate = () => {}, onCrossLane = () => {},
   store = null, adopt = null, getParallel = null, breaker = null, maxDeferrals = DEFAULT_MAX_DEFERRALS, sleep = cancellableSleep, pollMs = 5000,
   classify = null, maintenance = null, limits = null, identity = () => "default", batchId = null, drift = null, sched = null, priorityOf = null, remote = null, beforeAdmit = null,
-  recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null }) {
+  recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null, onExit = null }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
   const set = new Set(order);
@@ -349,6 +351,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?.precheckMs) ? { precheck_ms: r.precheckMs } : {}), ...(Number.isInteger(r?.precheckDeferred) && r.precheckDeferred > 0 ? { precheck_deferred: r.precheckDeferred } : {}), // #4331
       ...(rec?.placement ? { placement: rec.placement } : {}) };
     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);
@@ -408,7 +411,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     }
     // #4267: a recovery pass ends here; a recoverable row under the attempt cap is requeued as a recovery lane.
     const prior = recovering.get(n) ?? null;
-    const evidence = () => recoveryEvidence({ code: prior.code, attempt: prior.attempt, outcome: row.outcome, resultCode: row.code, detail: row.detail });
+    // #4318: the full persisted lane reason (capped by the comment writer), not its first 300 chars
+    const evidence = () => recoveryEvidence({ code: prior.code, attempt: prior.attempt, outcome: row.outcome, resultCode: row.code, detail: row.detail, full: true });
     if (prior) {
       recovering.delete(n);
       // #4298: the row reports the whole issue: earlier attempts' cost and minutes are summed into the recovery's.
@@ -511,95 +515,110 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   }
   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];
-      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}`); }
+  const heldDetail = (n) => tripped?.detail ?? (driftHeld.has(n) ? `drift: ${driftHeld.get(n)} flagged` : budgetStop ? `execution budget: ${budgetStop}` : budgetHeld ? "maintenance share" : "not run");
+  // #4315: a recovery queued but never launched (the batch stopped: breaker, budget, hold; or a resume that did not relaunch a
+  // lost run) left the issue without needs-human, since a non-final attempt does not relabel. Relabel it once, with the full reason.
+  // #4318: also on a throw out of the loop and on a signal (`onExit`); `cause` overrides the held reason. Runs once per process.
+  let exitRelabel = null;
+  const relabelQueued = (cause = null) => (exitRelabel ??= (async () => {
+    for (const [n, q] of recovering) {
+      if (running.has(n) || results.has(n) || relabelled.has(n) || typeof relabelNeedsHuman !== "function") continue;
+      const why = cause ?? (heldDetail(n) === "not run" ? "batch stopped" : heldDetail(n));
+      const evidence = recoveryEvidence({ code: q.code, attempt: q.prev_attempt, outcome: q.outcome, resultCode: q.result_code, detail: q.detail, full: true,
+        queued: q.attempt, cause: why, recoveryMax });
+      let res;
+      try { res = await relabelNeedsHuman({ issue: n, evidence }); } catch { res = "failed"; }
+      if (res !== false && res !== "failed") relabelled.add(n); // a failed label add is retried by a resume
     }
-    const t = now();
-    const holdUntil = heldUntil();
-    let started = 0;
-    driftHeld.clear();
-    const isReady = (n) => {
-      if (!((notBefore.get(n) ?? 0) <= t && edges(n).every((d) => results.has(d) && SATISFIED.has(results.get(d).outcome)))) return false;
-      if (!drift?.holds) return true;
-      let pkg = null;
-      try { pkg = drift.holds(n, { body: bodies.get(n) ?? "", lane: lanes.get(n)?.lane ?? null }); } catch { pkg = null; }
-      if (pkg) driftHeld.set(n, pkg);
-      return !pkg;
-    };
-    budgetHeld = false;
-    // #4183: a hook (owned-resource GC near the host ceiling) before lanes are admitted; its errors never stop the batch.
-    if (beforeAdmit && !tripped && !holdUntil && running.size < K() && pending.some(isReady)) { try { await beforeAdmit(); } catch { /* ignored */ } }
-    budgetStop = null;
-    const wanted = new Set(); // issues that stay offered in the host registry after this pass
-    if (!tripped && !holdUntil && budget) {
-      while (running.size < K()) {
-        const ready = pending.filter(isReady);
-        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;
-        pending.splice(pending.indexOf(n), 1);
-        if (lanes.get(n)?.ok !== false) { dispatch.started++; if (clsOf(classes, n).maintenance) dispatch.maint++; }
-        start(n); started++;
+    save();
+  })());
+  if (typeof onExit === "function") { try { onExit(relabelQueued); } catch { /* best effort */ } }
+
+  const K = () => { let k = null; try { k = getParallel?.(); } catch { k = null; } return Number.isInteger(k) && k >= 1 ? k : parallel; };
+  try {
+    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];
+        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}`); }
       }
-    } else if (!tripped && !holdUntil && reg) {
-      // Priority first, pending order within a priority; the free per-batch K is offered so the host queue keeps FIFO.
-      const ready = pending.filter(isReady).map((n, i) => [n, i]).sort((a, b) => prioOf(a[0]) - prioOf(b[0]) || a[1] - b[1]).map(([n]) => n);
-      const want = ready.filter((n) => lanes.get(n)?.ok !== false && !isRemote(n)).slice(0, Math.max(0, K() - running.size));
-      offerFresh(want);
-      for (const n of want) wanted.add(n);
-      for (const n of ready) {
-        if (running.size >= K() || !grant(n, wanted)) break;
-        pending.splice(pending.indexOf(n), 1); start(n); started++;
+      const t = now();
+      const holdUntil = heldUntil();
+      let started = 0;
+      driftHeld.clear();
+      const isReady = (n) => {
+        if (!((notBefore.get(n) ?? 0) <= t && edges(n).every((d) => results.has(d) && SATISFIED.has(results.get(d).outcome)))) return false;
+        if (!drift?.holds) return true;
+        let pkg = null;
+        try { pkg = drift.holds(n, { body: bodies.get(n) ?? "", lane: lanes.get(n)?.lane ?? null }); } catch { pkg = null; }
+        if (pkg) driftHeld.set(n, pkg);
+        return !pkg;
+      };
+      budgetHeld = false;
+      // #4183: a hook (owned-resource GC near the host ceiling) before lanes are admitted; its errors never stop the batch.
+      if (beforeAdmit && !tripped && !holdUntil && running.size < K() && pending.some(isReady)) { try { await beforeAdmit(); } catch { /* ignored */ } }
+      budgetStop = null;
+      const wanted = new Set(); // issues that stay offered in the host registry after this pass
+      if (!tripped && !holdUntil && budget) {
+        while (running.size < K()) {
+          const ready = pending.filter(isReady);
+          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;
+          pending.splice(pending.indexOf(n), 1);
+          if (lanes.get(n)?.ok !== false) { dispatch.started++; if (clsOf(classes, n).maintenance) dispatch.maint++; }
+          start(n); started++;
+        }
+      } else if (!tripped && !holdUntil && reg) {
+        // Priority first, pending order within a priority; the free per-batch K is offered so the host queue keeps FIFO.
+        const ready = pending.filter(isReady).map((n, i) => [n, i]).sort((a, b) => prioOf(a[0]) - prioOf(b[0]) || a[1] - b[1]).map(([n]) => n);
+        const want = ready.filter((n) => lanes.get(n)?.ok !== false && !isRemote(n)).slice(0, Math.max(0, K() - running.size));
+        offerFresh(want);
+        for (const n of want) wanted.add(n);
+        for (const n of ready) {
+          if (running.size >= K() || !grant(n, wanted)) break;
+          pending.splice(pending.indexOf(n), 1); start(n); started++;
+        }
+      } else if (!tripped && !holdUntil) {
+        for (let i = 0; i < pending.length && running.size < K();) {
+          const n = pending[i];
+          if (isReady(n) && grant(n, new Set())) { pending.splice(i, 1); start(n); started++; }
+          else i++;
+        }
       }
-    } else if (!tripped && !holdUntil) {
-      for (let i = 0; i < pending.length && running.size < K();) {
-        const n = pending[i];
-        if (isReady(n) && grant(n, new Set())) { pending.splice(i, 1); start(n); started++; }
-        else i++;
+      if (reg) withdrawExcept(wanted);
+      if (tripped && !running.size) break; // breaker: let running lanes finish, keep the rest pending for a resume
+      if (budgetStop && !running.size) break; // execution budget (stop): the same, the rest end held
+      // 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 (offered.size && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // a slot another batch frees
+      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 && offered.size) await sleep(wake); // waiting for a host slot
+      else if (pending.length && waits.length) await sleep(Math.max(0, Math.min(...waits) - t));
+      else if (pending.length && budgetHeld) break; // maintenance the budget does not admit now: held for a later batch
+      else if (pending.length && driftHeld.size) break; // held by a drift flag (block_dispatch): pending for a later batch
+      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();
       }
     }
-    if (reg) withdrawExcept(wanted);
-    if (tripped && !running.size) break; // breaker: let running lanes finish, keep the rest pending for a resume
-    if (budgetStop && !running.size) break; // execution budget (stop): the same, the rest end held
-    // 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 (offered.size && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // a slot another batch frees
-    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 && offered.size) await sleep(wake); // waiting for a host slot
-    else if (pending.length && waits.length) await sleep(Math.max(0, Math.min(...waits) - t));
-    else if (pending.length && budgetHeld) break; // maintenance the budget does not admit now: held for a later batch
-    else if (pending.length && driftHeld.size) break; // held by a drift flag (block_dispatch): pending for a later batch
-    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();
-    }
+  } catch (e) {
+    // #4318: an exception out of the loop still relabels the queued recoveries before it propagates
+    try { await relabelQueued(`batch failed: ${firstLine(e?.message ?? e)}`); } catch { /* best effort */ }
+    throw e;
   }
   if (reg) withdrawExcept(new Set());
-  const heldDetail = (n) => tripped?.detail ?? (driftHeld.has(n) ? `drift: ${driftHeld.get(n)} flagged` : budgetStop ? `execution budget: ${budgetStop}` : budgetHeld ? "maintenance share" : "not run");
-  // #4315: a recovery queued but never launched (the batch stopped: breaker, budget, hold; or a resume that did not relaunch a
-  // lost run) left the issue without needs-human, since a non-final attempt does not relabel. Relabel it once, with the full reason.
-  for (const [n, q] of recovering) {
-    if (running.has(n) || results.has(n) || relabelled.has(n) || typeof relabelNeedsHuman !== "function") continue;
-    const cause = heldDetail(n) === "not run" ? "batch stopped" : heldDetail(n);
-    const evidence = recoveryEvidence({ code: q.code, attempt: q.prev_attempt, outcome: q.outcome, resultCode: q.result_code, detail: q.detail, full: true,
-      queued: q.attempt, cause, recoveryMax });
-    try { await relabelNeedsHuman({ issue: n, evidence }); } catch { /* best effort */ }
-    relabelled.add(n);
-  }
+  await relabelQueued();
   save();
   return order.map((n) => results.get(n) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: heldDetail(n),
     ...(recovering.has(n) ? { recovery: { code: recovering.get(n).code, attempts: recoveries.get(n) ?? recovering.get(n).attempt, outcome: recovering.get(n).outcome ?? "needs-human",

package/bin/lean/precheck.mjs

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Pre-PR declared check commands (#4240), one round (#4331): the commands run concurrently up to the host worker cap
+ * (the caller holds one heavy-step slot for the whole round), each timed, inside one total budget. A command that never
+ * started before the budget ran out, or that the budget cut short, is left to CI (`deferred-to-ci`), never a failure.
+ * Repo-agnostic: commands are opaque `bash -c` strings run through the injected `run`.
+ */
+
+/** rc of a command killed by its timeout (effects.mjs runCheckCommand). */
+const TIMEOUT_RC = 124;
+
+/**
+ * @param {{commands:string[], parallelism?:number, budgetMs:number, perCommandMs:number, now?:() => number,
+ *   run:(a:{command:string, timeoutMs:number}) => Promise<{rc:number, output?:string}>}} p
+ * @returns {Promise<{results:{command:string, rc:number, output:string, ms:number}[], deferred:string[], ms:number}>}
+ *   results in input order (commands that ran and were not cut by the budget); deferred in input order
+ */
+export async function runChecks({ commands, parallelism = 1, budgetMs, perCommandMs, now = () => Date.now(), run }) {
+  const list = Array.isArray(commands) ? commands : [];
+  const workers = Math.max(1, Math.floor(Number(parallelism)) || 1);
+  const start = now(), deadline = start + (Number(budgetMs) > 0 ? Number(budgetMs) : 0);
+  const per = Number(perCommandMs) > 0 ? Number(perCommandMs) : Infinity;
+  const slots = new Array(list.length).fill(null);
+  let next = 0;
+  async function worker() {
+    while (next < list.length) {
+      const i = next++, command = list[i], left = deadline - now();
+      if (left <= 0) { slots[i] = { deferred: true }; continue; }
+      const timeoutMs = Math.min(per, left), t = now();
+      let r;
+      try { r = await run({ command, timeoutMs }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+      const rc = Number.isInteger(r?.rc) ? r.rc : 1;
+      // the budget, not the command's own timeout, cut it short: CI runs it
+      if (rc === TIMEOUT_RC && timeoutMs < per) { slots[i] = { deferred: true }; continue; }
+      slots[i] = { command, rc, output: String(r?.output ?? ""), ms: Math.max(0, now() - t) };
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(workers, list.length) }, worker));
+  const results = [], deferred = [];
+  slots.forEach((s, i) => { if (s?.deferred) deferred.push(list[i]); else if (s) results.push(s); });
+  return { results, deferred, ms: Math.max(0, now() - start) };
+}
+
+/**
+ * #4331 batch-report line: pre-PR check wall time summed over the rows' `precheck_ms`, and the commands deferred to CI
+ * (`precheck_deferred`). Null when no lane ran pre-PR checks.
+ */
+export function formatPrecheckSummary(rows) {
+  const ran = (rows ?? []).filter((r) => Number.isFinite(r?.precheck_ms) && r.precheck_ms >= 0);
+  if (!ran.length) return null;
+  const ms = ran.reduce((a, r) => a + r.precheck_ms, 0);
+  const deferred = ran.reduce((a, r) => a + (Number.isInteger(r.precheck_deferred) ? r.precheck_deferred : 0), 0);
+  return `precheck: ${(ms / 60000).toFixed(1)}m total over ${ran.length} lane${ran.length === 1 ? "" : "s"}${deferred ? `, ${deferred} deferred to CI` : ""}`;
+}

package/bin/lean/precheck.test.mjs

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { runChecks, formatPrecheckSummary } from "./precheck.mjs";
+import { readPrecheckBudget } from "../engine-cli.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+
+/** A fake run: each call takes `cost[command]` ms of the shared clock (default 1000) and returns rc[command] (default 0). */
+function harness({ cost = {}, rc = {} } = {}) {
+  const h = { t: 0, live: 0, peak: 0, calls: [] };
+  h.now = () => h.t;
+  h.run = async ({ command, timeoutMs }) => {
+    h.calls.push([command, timeoutMs]); h.peak = Math.max(h.peak, ++h.live);
+    await new Promise((r) => setImmediate(r));
+    const c = cost[command] ?? 1000;
+    h.t += Math.min(c, timeoutMs); h.live--;
+    return c > timeoutMs ? { rc: 124, output: "timed out" } : { rc: rc[command] ?? 0, output: `${command} out` };
+  };
+  return h;
+}
+
+describe("runChecks (#4331)", () => {
+  it("runs up to `parallelism` commands at once and returns results in input order with ms", async () => {
+    const h = harness();
+    const r = await runChecks({ commands: ["a", "b", "c", "d", "e"], parallelism: 3, budgetMs: 600000, perCommandMs: 300000, now: h.now, run: h.run });
+    assert.equal(h.peak, 3);
+    assert.deepEqual(r.results.map((x) => x.command), ["a", "b", "c", "d", "e"]);
+    assert.ok(r.results.every((x) => x.rc === 0 && Number.isFinite(x.ms) && x.ms >= 0));
+    assert.deepEqual(r.deferred, []);
+    assert.ok(r.ms > 0);
+  });
+
+  it("parallelism 1 is serial; 0, NaN or missing fall back to 1", async () => {
+    for (const p of [1, 0, NaN, undefined, "x"]) {
+      const h = harness();
+      await runChecks({ commands: ["a", "b", "c"], parallelism: p, budgetMs: 600000, perCommandMs: 300000, now: h.now, run: h.run });
+      assert.equal(h.peak, 1, String(p));
+    }
+  });
+
+  it("past the budget the remaining commands are deferred to CI, not failed; a running one gets what is left", async () => {
+    const h = harness();
+    const r = await runChecks({ commands: ["a", "b", "c"], parallelism: 1, budgetMs: 1500, perCommandMs: 300000, now: h.now, run: h.run });
+    assert.deepEqual(h.calls, [["a", 1500], ["b", 500]]);
+    assert.deepEqual(r.results.map((x) => [x.command, x.rc]), [["a", 0]], "b was cut by the budget (rc 124): deferred, not a failure");
+    assert.deepEqual(r.deferred, ["b", "c"]);
+  });
+
+  it("a command's own timeout (not the budget) stays a failure; a throw is rc 127", async () => {
+    const h = harness({ cost: { slow: 5000 } });
+    const r = await runChecks({ commands: ["slow", "boom", "bad"], parallelism: 2, budgetMs: 600000, perCommandMs: 2000, now: h.now,
+      run: (a) => (a.command === "boom" ? Promise.reject(new Error("spawn failed")) : a.command === "bad" ? Promise.resolve({ rc: 2, output: "lint" }) : h.run(a)) });
+    assert.deepEqual(r.results.map((x) => [x.command, x.rc]), [["slow", 124], ["boom", 127], ["bad", 2]]);
+    assert.match(r.results[1].output, /spawn failed/);
+    assert.deepEqual(r.deferred, []);
+  });
+
+  it("no commands: nothing runs", async () => {
+    let n = 0;
+    const r = await runChecks({ commands: [], parallelism: 4, budgetMs: 1000, perCommandMs: 1000, now: () => 0, run: async () => { n++; return { rc: 0 }; } });
+    assert.deepEqual([n, r.results, r.deferred, r.ms], [0, [], [], 0]);
+  });
+});
+
+describe("formatPrecheckSummary (#4331)", () => {
+  it("sums precheck_ms over the lanes that ran checks and counts deferrals; null when none did", () => {
+    assert.equal(formatPrecheckSummary([{ precheck_ms: 90000 }, { precheck_ms: 30000, precheck_deferred: 2 }, { issue: 3 }]), "precheck: 2.0m total over 2 lanes, 2 deferred to CI");
+    assert.equal(formatPrecheckSummary([{ precheck_ms: 6000 }]), "precheck: 0.1m total over 1 lane");
+    assert.equal(formatPrecheckSummary([{ issue: 1 }]), null);
+    assert.equal(formatPrecheckSummary(undefined), null);
+  });
+  it("orchestrate rows carry the lane's precheckMs/precheckDeferred as precheck_ms/precheck_deferred for the report line", async () => {
+    const rows = await orchestrate({ issues: [1, 2, 3], parallel: 1, readBody: async () => "",
+      runOne: async (n) => ({ terminalReason: "merged", ...({ 1: { precheckMs: 90000, precheckDeferred: 1 }, 2: { precheckMs: 30000, precheckDeferred: 0 } })[n] }) });
+    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");
+  });
+});
+
+describe("readPrecheckBudget: forge.yaml lean.precheck.max_minutes (#4331)", () => {
+  const withYaml = (text, fn) => { const d = tmpDir("precheck-"); writeFileSync(join(d, "forge.yaml"), text); return fn(d); };
+  it("reads the nested block and the flat key; invalid or absent is undefined", () => {
+    assert.equal(withYaml("lean:\n  precheck:\n    max_minutes: 7\n", readPrecheckBudget), 7);
+    assert.equal(withYaml("lean:\n  precheck_max_minutes: 15\n  repro_test: off\n", readPrecheckBudget), 15);
+    for (const bad of ["0", "-1", "abc", "121"]) assert.equal(withYaml(`lean:\n  precheck_max_minutes: ${bad}\n`, readPrecheckBudget), undefined, bad);
+    assert.equal(withYaml("verify:\n  mode: local\n", readPrecheckBudget), undefined);
+    assert.equal(readPrecheckBudget(tmpDir("precheck-")), undefined);
+  });
+});

package/bin/lean/prefilter.mjs

@@ -54,9 +54,20 @@ const isMarked = (c) => String(c?.body ?? "").trimStart().startsWith(`<!-- ${PRE
  * CONTRIBUTOR, never `[bot]`) plus the token's own user (`gh api user`; an App installation token cannot read it).
  */
 export async function ownLogins(gh) {
+  return (await resolveOwnLogins(gh)).logins;
+}
+/**
+ * #4318: {logins, resolved}. When `gh api user` fails (an App installation token), the App's own slug from `gh api app`
+ * (a differently named App); `resolved` is false when neither lookup answered, so the batch memo may ask once more.
+ */
+export async function resolveOwnLogins(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];
+  let resolved = false;
+  try { const me = bareLogin(await gh(["api", "user", "--jq", ".login"])); if (me) { out.add(me); resolved = true; } } catch { /* installation token */ }
+  if (!resolved) {
+    try { const slug = bareLogin(await gh(["api", "app", "--jq", ".slug"])); if (slug) { out.add(slug); resolved = true; } } catch { /* the App slug only */ }
+  }
+  return { logins: [...out], resolved };
 }
 /**
  * #4305: why one green run is no proof for this issue, without an API call: flaky wording or a `flaky` label, or an
@@ -195,8 +206,14 @@ 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) {
-  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)));
+  // #4315: one identity lookup per batch, and only when a marker comment needs it; #4318: an unresolved one is retried once
+  let own = null, tries = 0;
+  const selfLogins = opts.selfLogins ?? (() => (own ??= (async () => {
+    tries++;
+    const r = await resolveOwnLogins(opts.io.gh);
+    if (!r.resolved && tries < 2) own = null;
+    return r.logins;
+  })()));
   return (issue, lane) => prefilterIssue({ ...opts, selfLogins, issue, ...(lane ? { lane } : {}) });
 }
 

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, flakyReason, makePrefilter, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
+import { prefilterIssue, flakyReason, makePrefilter, ownLogins, resolveOwnLogins, 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";
@@ -315,3 +315,26 @@ describe("orchestrate with the pre-filter (#4123)", () => {
     assert.ok(logs.some((s) => /^#12 → lane-refused \(lane\.default_branch/.test(s)));
   });
 });
+
+describe("#4318: the engine's own identity under an installation token or a differently named App", () => {
+  it("ownLogins falls back to the App slug from `gh api app` when `gh api user` fails", async () => {
+    const gh = async (a) => { if (a[1] === "user") throw new Error("Resource not accessible by integration"); if (a[1] === "app") return "Other-Forge\n"; return ""; };
+    assert.deepEqual((await resolveOwnLogins(gh)), { logins: ["rapiercraft-forgedock", "other-forge"], resolved: true });
+    assert.deepEqual(await ownLogins(gh), ["rapiercraft-forgedock", "other-forge"]);
+    const both = async () => { throw new Error("401"); };
+    assert.deepEqual(await resolveOwnLogins(both), { logins: ["rapiercraft-forgedock"], resolved: false });
+  });
+  it("an unresolved lookup is retried once in the batch, then the App-slug-only set is kept", async () => {
+    const link = "Run: https://github.com/o/r/actions/runs/500";
+    const real = { author: { login: "Other-Forge" }, authorAssociation: "CONTRIBUTOR", body: "<!-- FORGE:PREFILTER -->\n## Pre-filter" };
+    const w = world({ issues: { 34: { title: "shell-compat failed on staging", body: `Workflow failed.\n${link}`, comments: [real] } },
+      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" }] } });
+    let lookups = 0; const g0 = w.io.gh;
+    w.io.gh = async (a) => (a[0] === "api" && (a[1] === "user" || a[1] === "app") ? (lookups++, (() => { throw new Error("401"); })()) : g0(a));
+    const run = makePrefilter({ repo: "o/r", cwd: "/repo", io: w.io });
+    await run(34, "staging"); await run(34, "staging"); await run(34, "staging");
+    assert.equal(lookups, 4, "user + app, twice: one retry, then cached");
+  });
+});

package/bin/lean/preflight.mjs

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4328: freeze-time preflight of a contract's validate commands. Pure: derives the host tools a command needs
+ * (each segment's bare executable, Python modules a bare python imports via -c/-m, Node packages `node -e` code imports)
+ * and a read-only bash probe for each. The engine runs the probes (lean.mjs) before the implement session, so a validate
+ * command the host cannot run is corrected in the plan instead of found after the build (#4323 env.tool_missing).
+ */
+import { builtinModules } from "node:module";
+
+export const PREFLIGHT_CAP = 20;
+const KIND_NAME = { command: "command", "python-module": "Python module", "node-module": "Node package" };
+const PY_RE = /^python(\d+(\.\d+)?)?$/;
+const PY_ARG_FLAGS = new Set(["-W", "-X", "-Q"]);
+const sq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Quote-aware split of a bash command into segments (on &&, ||, |, ;, newline) of unquoted words; `$(...)` stays one word. */
+export function shellSegments(command) {
+  const segs = [];
+  let words = [], word = "", has = false, q = null, depth = 0;
+  const endWord = () => { if (has) words.push(word); word = ""; has = false; };
+  const endSeg = () => { endWord(); if (words.length) segs.push(words); words = []; };
+  const s = String(command ?? "");
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (q === "'") { if (ch === "'") q = null; else word += ch; continue; }
+    if (ch === "\\" && i + 1 < s.length) { word += s[++i]; has = true; continue; }
+    if (q === '"') { if (ch === '"') q = null; else word += ch; continue; }
+    if (depth) { word += ch; if (ch === "(") depth++; else if (ch === ")") depth--; continue; }
+    if (ch === "'" || ch === '"') { q = ch; has = true; continue; }
+    if (ch === "$" && s[i + 1] === "(") { word += "$("; i++; depth = 1; has = true; continue; }
+    if (ch === " " || ch === "\t") { endWord(); continue; }
+    if (ch === "\n" || ch === ";" || ch === "|" || ch === "&") { if (ch === "&" && s[i + 1] !== "&") { endWord(); continue; } endSeg(); if (s[i + 1] === ch) i++; continue; }
+    if ((ch === "(" || ch === ")" || ch === "{" || ch === "}") && !has) continue;
+    word += ch; has = true;
+  }
+  endSeg();
+  return segs;
+}
+
+/** Top-level module names a Python `-c` program imports (absolute imports only). */
+export function pythonImports(code) {
+  const out = [];
+  for (const line of String(code ?? "").split(/[;\n]/)) {
+    const imp = /^\s*import\s+(.+)$/.exec(line), from = /^\s*from\s+([\w.]+)\s+import\b/.exec(line);
+    if (imp) for (const part of imp[1].split(",")) { const m = /^\s*([A-Za-z_]\w*)/.exec(part); if (m) out.push(m[1]); }
+    else if (from && !from[1].startsWith(".")) out.push(from[1].split(".")[0]);
+  }
+  for (const m of String(code ?? "").matchAll(/(?:__import__|import_module)\(\s*['"]([A-Za-z_][\w.]*)['"]/g)) out.push(m[1].split(".")[0]);
+  return [...new Set(out)].filter((x) => x !== "__future__");
+}
+
+/** Package names (bare specifiers, cut to the package) a `node -e` program imports; builtins, node:, relative and absolute are not packages. */
+export function nodeImports(code) {
+  const specs = [], c = String(code ?? "");
+  for (const re of [/\brequire\(\s*['"]([^'"]+)['"]\s*\)/g, /\bimport\s*\(\s*['"]([^'"]+)['"]/g, /\bfrom\s*['"]([^'"]+)['"]/g, /(?:^|[;\n])\s*import\s*['"]([^'"]+)['"]/g]) for (const m of c.matchAll(re)) specs.push(m[1]);
+  const out = [];
+  for (const spec of specs) {
+    if (/^(\.|\/|node:|file:|data:)/.test(spec)) continue;
+    const parts = spec.split("/"), pkg = spec.startsWith("@") ? (parts.length > 1 ? parts.slice(0, 2).join("/") : null) : parts[0];
+    if (pkg && !builtinModules.includes(pkg)) out.push(pkg);
+  }
+  return [...new Set(out)];
+}
+
+const PY_PROBE = "import importlib.util,sys;sys.exit(0 if importlib.util.find_spec(sys.argv[1]) else 3)";
+const NODE_PROBE = "const m=require('module'),p=require('path'),f=require('fs'),n=process.argv[1];if(m.builtinModules.includes(n))process.exit(0);for(let d=process.cwd();;){if(f.existsSync(p.join(d,'node_modules',n,'package.json')))process.exit(0);const u=p.dirname(d);if(u===d)process.exit(3);d=u}";
+
+/** The program text and modules of one python/node segment's arguments. */
+function moduleNeeds(exe, args) {
+  if (PY_RE.test(exe)) {
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a === "-c") return pythonImports(args[i + 1]);
+      if (a.startsWith("-c") && a.length > 2) return pythonImports(a.slice(2));
+      if (a === "-m") return args[i + 1] ? [args[i + 1].split(".")[0]] : [];
+      if (a.startsWith("-m") && a.length > 2) return [a.slice(2).split(".")[0]];
+      if (PY_ARG_FLAGS.has(a)) { i++; continue; }
+      if (!a.startsWith("-")) return [];
+    }
+    return [];
+  }
+  if (exe === "node") {
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (["-e", "--eval", "-p", "--print"].includes(a)) return nodeImports(args[i + 1]);
+      const eq = /^--(?:eval|print)=(.*)$/s.exec(a);
+      if (eq) return nodeImports(eq[1]);
+      if (!a.startsWith("-")) return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * The probes for `contract.validate[]`: {probes: [{ids, tool, kind, interp, needs, probe}], dropped}. `needs` is the command
+ * probe (tool) a module probe depends on: skip the module probe when its interpreter is missing. A name `repoHas(name)` holds
+ * or a deliverable's change text names (the change adds it) is not probed; paths and `$...` words are never probed.
+ */
+export function preflightProbes(contract, { repoHas = () => false, cap = PREFLIGHT_CAP } = {}) {
+  const changes = (Array.isArray(contract?.deliverables) ? contract.deliverables : []).map((d) => String(d?.change ?? "")).join("\n");
+  const named = (name) => new RegExp(`(^|[^\\w@/.-])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w/-])`).test(changes);
+  const skip = (name) => !name || name.includes("/") && !name.startsWith("@") || name.startsWith("$") || repoHas(name) || named(name);
+  const byKey = new Map();
+  const add = (id, kind, tool, interp = null) => {
+    const key = `${kind}|${tool}|${interp ?? ""}`;
+    const p = byKey.get(key);
+    if (p) { if (!p.ids.includes(id)) p.ids.push(id); return; }
+    const probe = kind === "command" ? `command -v -- ${sq(tool)} >/dev/null 2>&1`
+      : kind === "python-module" ? `${sq(interp)} -c ${sq(PY_PROBE)} ${sq(tool)} >/dev/null 2>&1`
+      : `node -e ${sq(NODE_PROBE)} ${sq(tool)} >/dev/null 2>&1`;
+    byKey.set(key, { ids: [id], tool, kind, interp, needs: kind === "command" ? null : interp, probe });
+  };
+  for (const v of Array.isArray(contract?.validate) ? contract.validate : []) {
+    if (!v?.id || typeof v.command !== "string") continue;
+    for (const seg of shellSegments(v.command)) {
+      let i = 0;
+      while (i < seg.length && (/^[A-Za-z_]\w*=/.test(seg[i]) || ["!", "time", "exec", "command", "env"].includes(seg[i]))) i++;
+      const exe = seg[i];
+      if (!exe || exe.includes("/") || exe.startsWith("$") || exe.startsWith("-")) continue;
+      if (!skip(exe)) add(v.id, "command", exe);
+      const kind = exe === "node" ? "node-module" : "python-module";
+      for (const mod of moduleNeeds(exe, seg.slice(i + 1))) if (!skip(mod)) add(v.id, kind, mod, exe);
+    }
+  }
+  const all = [...byKey.values()];
+  return { probes: all.slice(0, cap), dropped: Math.max(0, all.length - cap) };
+}
+
+/** One contract problem per missed probe: names the validate ids and the tool, and how to fix the plan (never a global install). */
+export function preflightProblems(misses) {
+  return (misses ?? []).map((m) => `${m.ids.join(", ")}: needs ${KIND_NAME[m.kind] ?? m.kind} '${m.tool}'${m.interp ? ` (for ${m.interp})` : ""}, which this host lacks, so the validate command cannot run here; run the check through the repo's own toolchain (its virtualenv, lockfile-pinned runner or package scripts) or use a check that does not need it, never a global install`);
+}