forgedock 1.30.0 → 1.32.0

package/bin/lean/precheck.test.mjs

@@ -5,7 +5,9 @@ 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 { formatFirstPassSummary } from "./fixround.mjs";
+import { runChecks, formatPrecheckSummary, planPrecheck, selfCheck, selfCheckState, formatCheckTable, worktreeFingerprint, quietFailure } from "./precheck.mjs";
+import { execFileSync } from "node:child_process";
 import { readPrecheckBudget } from "../engine-cli.mjs";
 import { orchestrate } from "./orchestrate.mjs";
 
@@ -66,6 +68,43 @@ describe("runChecks (#4331)", () => {
   });
 });
 
+describe("runChecks (#4344)", () => {
+  /** A fake heavy semaphore: counts live slots, their peak and releases; `wait` ms of the shared clock per acquire. */
+  const sem = (h, wait = 0) => { const s = { live: 0, peak: 0, acquired: 0, released: 0 };
+    s.acquire = async () => { s.acquired++; s.peak = Math.max(s.peak, ++s.live); h.t += wait; return { release: () => { s.live--; s.released++; } }; }; return s; };
+
+  it("#4344 divides the worker budget across concurrent commands and takes one heavy slot per running command", async () => {
+    for (const [n, cmds, share, peak] of [[8, ["a", "b", "c", "d", "e", "f", "g", "h"], 1, 8], [8, ["a", "b"], 4, 2], [6, ["a", "b", "c", "d"], 1, 4], [5, ["a", "b"], 2, 2], [4, ["a"], 4, 1]]) {
+      const h = harness(), s = sem(h), seen = [];
+      await runChecks({ commands: cmds, parallelism: n, budgetMs: 600000, perCommandMs: 300000, now: h.now, acquire: s.acquire, run: (a) => { seen.push(a.workers); return h.run(a); } });
+      assert.ok(seen.every((w) => w === share), `N=${n} k=${cmds.length}: ${seen}`);
+      assert.ok(share * h.peak <= n, `round total ${share * h.peak} workers > N=${n}`);
+      assert.deepEqual([s.peak, s.acquired, s.released, s.live], [peak, cmds.length, cmds.length, 0], `N=${n} slots`);
+    }
+  });
+
+  it("#4344 FORGE_HOST_PARALLELISM=1: one command at a time, one worker, one slot", async () => {
+    const h = harness(), s = sem(h), seen = [];
+    await runChecks({ commands: ["a", "b", "c"], parallelism: 1, budgetMs: 600000, perCommandMs: 300000, now: h.now, acquire: s.acquire, run: (a) => { seen.push(a.workers); return h.run(a); } });
+    assert.deepEqual([h.peak, s.peak, seen], [1, 1, [1, 1, 1]]);
+  });
+
+  it("#4344 the slot wait counts against the budget: a command whose wait exhausts it is deferred, its slot released", async () => {
+    const h = harness(), s = sem(h, 1000);
+    const r = await runChecks({ commands: ["a", "b"], parallelism: 1, budgetMs: 2500, perCommandMs: 300000, now: h.now, acquire: s.acquire, run: h.run });
+    assert.deepEqual(h.calls, [["a", 1500]]);
+    assert.deepEqual([r.results.map((x) => x.command), r.deferred], [["a"], ["b"]]);
+    assert.deepEqual([s.acquired, s.released], [2, 2]);
+  });
+
+  it("#4344 a throwing acquire runs the command ungated; a throwing release is ignored", async () => {
+    const h = harness();
+    const r1 = await runChecks({ commands: ["a"], parallelism: 2, budgetMs: 600000, perCommandMs: 300000, now: h.now, acquire: async () => { throw new Error("registry"); }, run: h.run });
+    const r2 = await runChecks({ commands: ["b"], parallelism: 2, budgetMs: 600000, perCommandMs: 300000, now: h.now, acquire: async () => ({ release: () => { throw new Error("x"); } }), run: h.run });
+    assert.deepEqual([...r1.results, ...r2.results].map((x) => [x.command, x.rc]), [["a", 0], ["b", 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");
@@ -79,6 +118,17 @@ 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] }) });
+    assert.deepEqual(rows.map((r) => [r.issue, r.first_pass]), [[1, true], [2, false], [3, undefined]]);
+    assert.equal(formatFirstPassSummary(rows), "first-pass: 50% (1/2 lanes that reached the build)");
+  });
 });
 
 describe("readPrecheckBudget: forge.yaml lean.precheck.max_minutes (#4331)", () => {
@@ -91,3 +141,70 @@ describe("readPrecheckBudget: forge.yaml lean.precheck.max_minutes (#4331)", ()
     assert.equal(readPrecheckBudget(tmpDir("precheck-")), undefined);
   });
 });
+
+describe("forgedock check core (#4364)", () => {
+  const MAP = { version: 1, entries: [{ globs: ["src/**"], command: "npm test", cwd: "." }, { globs: ["docs/**"], command: "make docs", cwd: "." }] };
+
+  it("planPrecheck: the engine's selection and budget rule (max_minutes wins, else precheck_total_seconds, else 600 s)", () => {
+    const p = planPrecheck({ testMap: MAP, files: ["src/a.js"], learned: [" make lint ", "", "make docs"], verify: { precheckTotalSeconds: 120, precheckTimeoutSeconds: 30 } });
+    assert.deepEqual(p.commands, ["make lint", "npm test"]); assert.deepEqual(p.dropped, ["make docs"]);
+    assert.equal(p.selected, 1); assert.equal(p.budgetMs, 120000); assert.equal(p.perCommandMs, 30000);
+    assert.equal(planPrecheck({ learned: ["x"], maxMinutes: 2, verify: { precheckTotalSeconds: 999 } }).budgetMs, 120000);
+    assert.equal(planPrecheck({ learned: ["x"], maxMinutes: 3, verify: {} }).budgetMs, 180000);
+    assert.deepEqual(planPrecheck({ learned: ["x"], verify: {} }), { commands: ["x"], added: 0, dropped: [], source: "learned", selected: 0, budgetMs: 600000, perCommandMs: 300000 });
+  });
+
+  it("selfCheck runs validates then pre-PR commands; ok only when every run exits 0; ci mode leaves validates to CI", async () => {
+    const h = harness({ rc: { "make lint": 2 } });
+    const contract = { validate: [{ id: "V1", command: "node --test a" }, { id: "V2", command: " " }] };
+    const plan = { mode: "local", commands: ["npm test", "make lint"], budgetMs: 600000, perCommandMs: 300000 };
+    const r = await selfCheck({ contract, plan, now: h.now, run: h.run });
+    assert.deepEqual(h.calls.map((c) => c[0]), ["node --test a", "npm test", "make lint"]);
+    assert.deepEqual(r.validate.map((x) => [x.id, x.rc]), [["V1", 0]]); assert.deepEqual(r.commands.map((x) => x.rc), [0, 2]); assert.equal(r.ok, false);
+    const h2 = harness();
+    const r2 = await selfCheck({ contract, plan: { ...plan, mode: "ci" }, now: h2.now, run: h2.run });
+    assert.deepEqual(h2.calls.map((c) => c[0]), ["npm test", "make lint"]); assert.deepEqual(r2.validate, [{ id: "V1", command: "node --test a", status: "ci" }]); assert.equal(r2.ok, true);
+    const h3 = harness({ cost: { "npm test": 5000 } });
+    const r3 = await selfCheck({ contract: {}, plan: { commands: ["npm test", "make lint"], budgetMs: 4000, perCommandMs: 300000 }, now: h3.now, run: h3.run });
+    assert.deepEqual(r3.deferred, ["npm test", "make lint"]); assert.equal(r3.ok, true, "deferred to CI is not a failure, as in the engine");
+  });
+
+  it("selfCheckState and formatCheckTable", () => {
+    assert.equal(selfCheckState(null, "f"), "skipped"); assert.equal(selfCheckState({ fingerprint: "g", ok: true }, "f"), "stale");
+    assert.equal(selfCheckState({ fingerprint: "f", ok: false }, "f"), "red"); assert.equal(selfCheckState({ fingerprint: "f", ok: true }, "f"), "green");
+    const t = formatCheckTable({ ok: false, validate: [{ id: "V1", command: "v", rc: 0, ms: 1200 }], commands: [{ command: "make lint", rc: 2, ms: 10, output: `${"x".repeat(5000)}TAIL` }], deferred: ["slow"] }, 1000);
+    assert.match(t, /^PASS +1\.2s {2}V1 v$/m); assert.match(t, /^FAIL exit 2 .* make lint$/m); assert.match(t, /^DEFERRED .* slow$/m);
+    assert.match(t, /--- make lint \(exit 2\)\n…x+TAIL/); assert.ok(t.length < 1400, "failure output capped"); assert.match(t, /check: FAIL \(1 failing\)$/);
+  });
+
+  it("#4390 quietFailure: last 40 lines, failing ids across ecosystems, log pointer; short output unchanged", () => {
+    const out = ["FAILED tests/test_x.py::test_a - assert 1 == 2", "not ok 3 - parses dates", " FAIL  src/a.test.ts > adds", "--- FAIL: TestSum (0.00s)", "test parser::empty ... FAILED", "  ✕ renders header (5 ms)",
+      ...Array.from({ length: 100 }, (_, i) => `line ${i}`)].join("\n");
+    const q = quietFailure(out, { logPath: ".forge-lean/logs/check-V1.log" });
+    assert.match(q, /^…line 60\n/); assert.match(q, /line 99\nfailing tests:\n/);
+    for (const id of ["FAILED tests/test_x.py::test_a", "not ok 3 - parses dates", "FAIL  src/a.test.ts > adds", "--- FAIL: TestSum", "test parser::empty ... FAILED", "✕ renders header"]) assert.ok(q.includes(`  ${id}`), id);
+    assert.match(q, /\nfull log: \.forge-lean\/logs\/check-V1\.log$/);
+    assert.equal(quietFailure("ok\nall good\n"), "ok\nall good");
+    assert.equal(quietFailure(""), "(no output)");
+    assert.equal(quietFailure("x".repeat(50), { maxChars: 10 }), `…${"x".repeat(10)}`);
+  });
+
+  it("worktreeFingerprint: the same content committed or not is the same tree; an edit or new file changes it; .forge-lean is ignored", async () => {
+    const dir = tmpDir("selfcheck-fp-");
+    const env = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.invalid", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.invalid", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+    const g = (a) => execFileSync("git", a, { cwd: dir, encoding: "utf8", env });
+    g(["init", "-q", "-b", "main"]); writeFileSync(join(dir, "a.js"), "1\n"); writeFileSync(join(dir, "gone.js"), "x\n"); g(["add", "-A"]); g(["commit", "-q", "-m", "base"]);
+    g(["branch", "base"]);
+    const fp = () => worktreeFingerprint({ git: async (a) => g(a), base: "base" });
+    const clean = await fp();
+    writeFileSync(join(dir, "a.js"), "2\n"); writeFileSync(join(dir, "new.js"), "n\n"); g(["rm", "-q", "gone.js"]);
+    const dirty = await fp(); assert.notEqual(dirty, clean);
+    execFileSync("mkdir", ["-p", join(dir, ".forge-lean")]); writeFileSync(join(dir, ".forge-lean", "result.json"), "{}");
+    g(["add", "-A"]); g(["reset", "-q", "--", ".forge-lean"]);
+    writeFileSync(join(dir, ".git", "info", "exclude"), ".forge-lean/\n");
+    g(["commit", "-q", "-m", "work"]);
+    assert.equal(await fp(), dirty, "committing the checked tree does not make the check stale");
+    writeFileSync(join(dir, "a.js"), "3\n");
+    assert.notEqual(await fp(), dirty);
+  });
+});

package/bin/lean/prefilter.mjs

@@ -10,12 +10,19 @@
  *   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.
+ * 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. 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";
 import { capComment, sanitizeMd, noComments } from "./render.mjs";
 import { PREFILTER_SYSTEM, prefilterPrompt, parsePrefilterVerdict } from "./prompts.mjs";
 import { isTrustedComment } from "../engine/phases.mjs";
 import { APP_SLUG } from "../init-repo.mjs";
+import { probeResultOf } from "./probe.mjs";
 
 export const DEFAULT_PREFILTER_MODEL = "claude-haiku-5-5";
 export const PREFILTER_MARKER = "FORGE:PREFILTER";
@@ -78,11 +85,15 @@ export function flakyReason(iss, own = [bareLogin(APP_SLUG)]) {
   if (FLAKY_RE.test(`${iss.title ?? ""}\n${noComments(String(iss.body ?? ""), " ")}`)) return { reason: "flaky", why: "issue says the failure is intermittent" };
   if ((iss.labels ?? []).some((l) => String(l?.name ?? l).toLowerCase() === "flaky")) return { reason: "flaky", why: "flaky label" };
   const mine = new Set((own ?? []).map(bareLogin));
+  // #4399: the latest pipeline FORGE:PROBE result is a fail: the fix did not hold in production, so no already-fixed close
+  const probe = (iss.comments ?? []).filter((c) => probeResultOf(c?.body) && (trusted(c) || mine.has(bareLogin(loginOf(c))))).at(-1);
+  if (probe && probeResultOf(probe.body).result === "fail") return { reason: "probe-failed", why: "acceptance probe failed after promotion" };
   if ((iss.comments ?? []).some((c) => isMarked(c) && (trusted(c) || mine.has(bareLogin(loginOf(c)))))) return { reason: "reopened", why: "reopened after a pre-filter close" };
   return null;
 }
 /** The own logins, looked up only when an otherwise-untrusted marker comment needs them (no call for most issues). */
-const ownFor = async (iss, resolve) => ((iss.comments ?? []).some((c) => isMarked(c) && !trusted(c)) ? resolve() : undefined);
+const ownFor = async (iss, resolve) => ((iss.comments ?? []).some((c) => (isMarked(c) || probeResultOf(c?.body)) && !trusted(c)) ? resolve() : undefined);
+const selfResolver = (selfLogins, gh) => (typeof selfLogins === "function" ? selfLogins : selfLogins ? async () => selfLogins : () => ownLogins(gh));
 
 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. */
@@ -115,7 +126,7 @@ export async function collectSignals({ iss, repo, lane, io, cwd, selfLogins = nu
         const sha = latest.head_sha ?? "";
         // #4305: a workflow that failed and passed at the same SHA is flaky; the lookup is any branch (PR run vs push)
         // and only made when the issue itself gave no reason. An unreadable lookup throws: no CI signal.
-        const own = await ownFor(iss, typeof selfLogins === "function" ? selfLogins : selfLogins ? async () => selfLogins : () => ownLogins(io.gh));
+        const own = await ownFor(iss, selfResolver(selfLogins, io.gh));
         let skip = flakyReason(iss, own);
         const same = { reason: "same-sha", why: `failed and passed at ${sha.slice(0, 12)}` };
         if (!skip && sha && failed.head_sha === sha) skip = same;
@@ -139,21 +150,225 @@ export async function collectSignals({ iss, repo, lane, io, cwd, selfLogins = nu
   return sig;
 }
 
+// #4389: post-deploy precondition gate. A follow-up filed by scripts/file-deferred-followups.sh whose items are all
+// post-deploy checks cannot be done before its parent's fix is on the default branch: a git fact, so no lane learns it.
+export const PRECONDITION_MARKER = "FORGE:PRECONDITION";
+export const AWAITING_PROMOTION_LABEL = "awaiting-promotion";
+const DEFERRED_FROM_RE = /<!--\s*FORGE:DEFERRED_FROM:\s*#(\d+)\s*-->/;
+/** The parent #P of a deferred follow-up (`<!-- FORGE:DEFERRED_FROM: #P -->`), or null. */
+export function deferredFrom(body) {
+  const m = DEFERRED_FROM_RE.exec(String(body ?? ""));
+  return m ? Number(m[1]) : null;
+}
+const CHECK_RE = /^\s*[-*]\s+\[[ xX]\]\s+(.*)$/;
+/** True when the body has checklist items and every one is a ``- [ ] `R#: …` — post-deploy: why`` line (conformance followupItems). */
+export function postDeployOnly(body) {
+  const items = noComments(String(body ?? ""), " ").split("\n").map((l) => CHECK_RE.exec(l)?.[1]).filter((x) => x != null);
+  return items.length > 0 && items.every((t) => /^`[^`]*`\s+(?:\*\*known-flaw\*\*\s+)?[—-]+\s*post-deploy:/.test(t));
+}
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+/**
+ * #4467: an issue comment the engine may trust, in REST shape (`user.type`) or `gh issue view` shape (`author.login`,
+ * `authorAssociation`): what isTrustedComment trusts, or the ForgeDock App, which `gh issue view` reports as a bare
+ * `rapiercraft-forgedock` CONTRIBUTOR with no type and no `[bot]` suffix (#4315).
+ */
+export const isTrustedIssueComment = (c) => Boolean(c) && (trusted(c) || bareLogin(loginOf(c)) === bareLogin(APP_SLUG));
+/** Merge commits of the merged PRs that claim to fix #parent; else the `merged at <sha>` of its trusted FORGE:TRAJECTORY. */
+export async function parentMergeShas({ parent, repo, io }) {
+  const shas = new Set();
+  try {
+    const prs = JSON.parse(String(await io.gh(["pr", "list", "-R", repo, "--state", "merged", "--search", `#${parent}`, "--json", "number,title,body,mergeCommit", "--limit", "20"])) || "[]");
+    for (const p of prs) if ((claimsFix(p.title, parent) || claimsFix(p.body, parent)) && SHA_RE.test(p.mergeCommit?.oid ?? "")) shas.add(p.mergeCommit.oid);
+  } catch { /* unreadable: try the trajectory */ }
+  if (!shas.size) {
+    try {
+      const v = JSON.parse(String(await io.gh(["issue", "view", String(parent), "-R", repo, "--json", "comments"])));
+      for (const c of v.comments ?? []) {
+        const b = String(c?.body ?? "");
+        const m = b.includes("FORGE:TRAJECTORY") && isTrustedIssueComment(c) ? /merged at `?([0-9a-f]{7,40})\b/i.exec(b) : null;
+        if (m) shas.add(m[1]);
+      }
+    } catch { /* unreadable: no SHA */ }
+  }
+  return [...shas];
+}
+/** Default `io.execCode`: the exit code of an argv-only child (-1 when it could not run or timed out). */
+function execCode(cmd, args, opts) {
+  return new Promise((res) => {
+    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).
+ * #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, 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", "");
+  try {
+    const def = typeof defaultBranch === "function" ? await defaultBranch() : defaultBranch;
+    if (!def) return res("unresolved", "default branch unknown");
+    const shas = await parentMergeShas({ parent, repo, io });
+    if (!shas.length) return res("unresolved", `no merge SHA found for #${parent}`);
+    const off = [];
+    for (const sha of shas) {
+      let on;
+      try { await io.git(["merge-base", "--is-ancestor", sha, `origin/${def}`], { cwd }); on = true; } catch (e) { on = e?.code === 1 ? false : null; }
+      if (on === null) return res("unresolved", `${sha.slice(0, 12)} unknown to git`, { shas, default: def });
+      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) } });
+      if (code === 1) return res("awaiting-precondition", `fix of #${parent} is on ${def}; post_deploy.precondition_cmd says not ready`, { shas, default: def });
+      if (code !== 0) return res("unresolved", `post_deploy.precondition_cmd exited ${code}`, { shas, default: def });
+    }
+    return res("ready", `fix of #${parent} is on ${def}`, { shas, default: def });
+  } catch (e) {
+    return res("unresolved", `gate error (${String(e?.message ?? e).slice(0, 120)})`);
+  }
+}
+/**
+ * #4389: the default branch for the gate, resolved and fetched once, only when a gated issue asks: forge.yaml
+ * `branches.default`, else GitHub's default branch. Null when neither answers (the gate then fails open).
+ */
+export function lazyDefaultBranch({ io, repo, cwd, configured = null }) {
+  let p = null;
+  return () => (p ??= (async () => {
+    let name = configured;
+    if (!name) { try { name = String(await io.gh(["repo", "view", repo, "--json", "defaultBranchRef", "-q", ".defaultBranchRef.name"])).trim() || null; } catch { name = null; } }
+    if (name) { try { await io.git(["fetch", "origin", name], { cwd }); } catch { /* offline: use the local ref */ } }
+    return name;
+  })());
+}
+/** #4389: label and explain a parked issue once (the comment only when the label was not there yet); best effort. */
+async function markParked({ issue, repo, io, had, gate }) {
+  const edit = () => io.gh(["issue", "edit", String(issue), "-R", repo, "--add-label", AWAITING_PROMOTION_LABEL]);
+  try { await edit(); } catch {
+    try {
+      await io.gh(["label", "create", AWAITING_PROMOTION_LABEL, "-R", repo, "--force", "--color", "C5DEF5", "--description", "Post-deploy follow-up parked until its parent fix reaches the default branch. Managed by ForgeDock."]);
+      await edit();
+    } catch { /* the comment and the report still show it */ }
+  }
+  if (had) return;
+  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 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))];
+  const out = [];
+  const promo = parked.filter((r) => r.prefilter.kind === "awaiting-promotion");
+  if (promo.length) {
+    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");
+}
+
 /**
  * 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 }) {
+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"])));
     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" };
+    const names = (iss.labels ?? []).map((l) => l?.name ?? l);
+    const labelled = names.some((l) => ["needs-human", "workflow:merged"].includes(l));
+    // #4389: a post-deploy follow-up is gated even when an earlier lane escalated it (needs-human); nothing else changes.
+    const gated = !!defaultBranch && !names.includes("workflow:merged") && deferredFrom(iss.body) != null && postDeployOnly(iss.body);
+    if (labelled && !gated) 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}` };
     }
+    if (gated) {
+      const gate = await postDeployGate({ iss, repo, lane, defaultBranch, cwd, io, preconditionCmd, minAge });
+      const had = names.includes(AWAITING_PROMOTION_LABEL);
+      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 };
+      }
+      if (gate.state === "ready" && had && !dryRun) {
+        try { await io.gh(["issue", "edit", String(issue), "-R", repo, "--remove-label", AWAITING_PROMOTION_LABEL]); } catch { /* best effort */ }
+      }
+      if (labelled) return { ...out, detail: `labelled, left to the lane (post-deploy gate: ${gate.state}${gate.detail ? `, ${gate.detail}` : ""})` };
+    }
+    // #4399: an issue reopened by a failed acceptance probe goes to a lane, never back to an already-fixed close
+    if ((iss.comments ?? []).some((c) => probeResultOf(c?.body)?.result === "fail")
+      && flakyReason({ comments: iss.comments }, await ownFor(iss, selfResolver(selfLogins, io.gh)))?.reason === "probe-failed") {
+      return { ...out, detail: "acceptance probe failed after promotion (FORGE:PROBE): no already-fixed close; lane" };
+    }
     const sig = await collectSignals({ iss, repo, lane, io, cwd, selfLogins });
     const close = async (kind, body, detail) => {
       let note = "";