forgedock 1.34.0 → 1.36.0

package/bin/lean/orchestrate.mjs

@@ -7,6 +7,7 @@
  * `decomposed` run adds its sub-issues and its dependents wait on them instead (#4124). A dependency that is parked
  * (ended needs-human in this batch, or an out-of-set issue labelled needs-human per `issueLabels(n)`) is never pulled in:
  * the issue ends `skipped` (`dependency #N needs-human`) and its dependents with it (#4387).
+ * A skipped dependent whose blocker later closes or merges outside its lane is re-admitted (#4595, needs `dispatchCheck`).
  * No investigation, synthesis or agent spawning. `runOne(issue)` and `readBody(issue)` are injected.
  * Optional `prefilter(issue, lane)` (#4123) runs in the lane slot before `runOne`: when it closed the issue, no lane starts.
  * When it parked the issue (#4389, `parked: true`), no lane starts either and the row ends with the parked kind.
@@ -28,6 +29,8 @@
  * `getAdded()` (#4408, `forgedock orchestrate --add`) is read on every pass too: issues it returns that are not in the batch
  * join it through `addIssues` (the still-pending issues' `Depends on` are re-read first, so edges hold both ways), with one
  * batch decision and one `added` row; while it is set, lanes running with an empty queue still wake every `pollMs`.
+ * `getHeld()` (#4592, `--hold`/`--release`) is read on every pass: the issues it returns are never admitted (a running lane is not stopped);
+ * when only held issues (and their dependents) remain and nothing runs, the batch ends with them `held` ("held by operator"), and a `--resume <id> <issue...>` naming them (or `--release`) re-admits them.
  *
  * Maintenance budget (#4197), off unless `maintenance: {share, whenIdle}` is passed: `classify(issue)` gives each issue
  * `{maintenance, priority}` (persisted as `classes`) and admission follows `pickNext`: P0/P1 features, then a maintenance
@@ -101,9 +104,11 @@ import { recoveryEvidence } from "./render.mjs";
 import { renderAlerts } from "../stats/render.mjs";
 import { formatParkedLine, postDeployOnly } from "./prefilter.mjs";
 import { laneSize, SIZES } from "./budget.mjs";
+import { requeueKey, REQUEUABLE } from "./batch.mjs";
 
 // A dependency that finished like this no longer blocks its dependents.
 const SATISFIED = new Set(["merged", "invalid"]);
+const WATCH_EVERY_MS = 60_000; // #4595
 // Times one issue may be requeued behind a dependency before its dependency-open row is final.
 export const MAX_REQUEUES = 2;
 // Deferrals other than a busy resource (UNCAPPED_DEFERRALS) one issue may take before its deferred row is final.
@@ -230,9 +235,9 @@ const toMap = (o) => new Map(Object.entries(o ?? {}).map(([k, v]) => [Number(k),
  * @returns {Promise<Array<{issue:number, outcome:string, pr:?number, cost_usd:number, minutes:number, detail?:string}>>}
  */
 export async function orchestrate({ issues, parallel = 3, runOne, readBody, prefilter = null, resolveLane = null, now = () => Date.now(), onUpdate = () => {}, onCrossLane = () => {},
-  store = null, adopt = null, getParallel = null, getAdded = null, breaker = null, maxDeferrals = DEFAULT_MAX_DEFERRALS, sleep = cancellableSleep, pollMs = 5000,
+  store = null, adopt = null, getParallel = null, getAdded = null, getRequeued = 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,
+  recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null, onExit = null, issueLabels = null, getCancelled = null, getHeld = null, stopLane = null,
   estimate = null, starveMs = DEFAULT_STARVE_MS, signal = null, dispatchCheck = null, syncParked = null, syncEveryMs = DEFAULT_SYNC_EVERY_MS }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
@@ -257,6 +262,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   const holds = limits ?? memoryLimits(now);
   const heldUntil = () => { try { const id = identity(); const u = holds.holdUntil(id); return Number.isFinite(u) && u > now() ? u : null; } catch { return null; } };
   let tripped = saved?.breaker ?? null;
+  let opHeld = new Set(); // #4592: operator-held issues this pass (the batch `hold` file is the authority)
+  const opHeldHit = new Set(); // held issues that were pending this pass
   // #4376: operator cancel (the batch `cancel` file through `getCancelled`); persisted, but the file stays the authority.
   let cancelled = getCancelled ? (saved?.cancelled ?? null) : null;
   const budget = maintenance && Number(maintenance.share) > 0 ? { share: Number(maintenance.share), whenIdle: !!maintenance.whenIdle } : null;
@@ -295,6 +302,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   const recoveryMax = Number.isInteger(recovery?.maxAttempts) && recovery.maxAttempts > 0 ? recovery.maxAttempts : 0;
   const recoveries = toMap(saved?.recoveries); // issue -> recovery lanes launched (#4267)
   const recovering = toMap(saved?.recovering); // issue -> {code, attempt, detail, outcome, ...} of the recovery lane queued or running
+  const requeueApplied = new Set(saved?.requeueApplied ?? []); // #4550: `--requeue` entries already applied (batch `requeue` file)
+  const requeuedInfo = toMap(saved?.requeued); // #4550: issue -> {reason, by, at, prior: [earlier rows]}
   const relabelled = new Set(saved?.relabelled ?? []); // #4315: queued recoveries relabelled needs-human when a batch stopped
   // #4267: decisions are recorded, never awaited: a failing or slow recorder cannot block the batch.
   const decided = (d) => { try { Promise.resolve(decide?.(d)).catch(() => {}); } catch { /* best effort */ } };
@@ -308,6 +317,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       prefilter: toObj(checked), errorTimes, breaker: tripped, ...(budget ? { classes: toObj(classes), dispatch: { ...dispatch } } : {}),
       ...(reg ? { priorities: toObj(priorities) } : {}), ...(sandboxUse.size ? { sandbox: toObj(sandboxUse) } : {}),
       ...(recoveries.size || recovering.size ? { recoveries: toObj(recoveries), recovering: toObj(recovering) } : {}),
+      ...(requeueApplied.size ? { requeueApplied: [...requeueApplied], requeued: toObj(requeuedInfo) } : {}),
       ...(relabelled.size ? { relabelled: [...relabelled] } : {}), ...(cancelled ? { cancelled } : {}),
       ...(estimate ? { estimates: toObj(estimates), enqueued: toObj(enqueued) } : {}), ...(heads.size ? { heads: [...heads] } : {}) });
   };
@@ -736,7 +746,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   }
   save();
 
-  const heldDetail = (n) => cancelled ? "cancelled by operator" : tripped?.detail ?? (driftHeld.has(n) ? `drift: ${driftHeld.get(n)} flagged` : budgetStop ? `execution budget: ${budgetStop}` : budgetHeld ? "maintenance share" : "not run");
+  const heldDetail = (n) => cancelled ? "cancelled by operator" : opHeld.has(n) ? "held by operator" : 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.
@@ -776,13 +786,67 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     update({ issue: null, outcome: "added", detail: list });
     return fresh.length;
   };
-  // #4376: one SIGTERM per running local lane (their teardown saves the work); remote lanes run to their result.
+  // #4550: `--requeue` entries (batch `requeue` file) not applied yet: a terminal issue and the dependents skipped behind it
+  // return to pending, the prior rows kept in history; edges stay, so a dependent still waits for the issue to merge.
+  const drainRequeues = async () => {
+    if (!getRequeued) return 0;
+    let got = [];
+    try { got = getRequeued() ?? []; } catch { got = []; }
+    const fresh = (Array.isArray(got) ? got : []).filter((e) => Number.isSafeInteger(e?.issue) && !requeueApplied.has(requeueKey(e)));
+    let n = 0;
+    for (const e of fresh) {
+      requeueApplied.add(requeueKey(e));
+      const row = results.get(e.issue);
+      if (!row || !REQUEUABLE(row.outcome) || running.has(e.issue)) continue;
+      const moved = [e.issue], priors = new Map([[e.issue, row]]);
+      results.delete(e.issue);
+      for (let i = 0; i < moved.length; i++) { // dependents skipped behind a requeued issue (fixpoint)
+        for (const [m, r] of [...results]) {
+          if (r?.outcome !== "skipped" || Number(/^dependency #(\d+)/.exec(r.detail ?? "")?.[1]) !== moved[i]) continue;
+          priors.set(m, r); results.delete(m); moved.push(m);
+        }
+      }
+      for (const m of moved) {
+        for (const x of [requeues, deferrals, engineErrors, recoveries, recovering]) x.delete(m);
+        relabelled.delete(m);
+        if (m === e.issue) requeuedInfo.set(m, { reason: e.reason, by: e.by, at: e.at, prior: [...(requeuedInfo.get(m)?.prior ?? []), priors.get(m)] });
+        if (!pending.includes(m)) requeue(m, 0);
+      }
+      save();
+      const list = moved.filter((m) => m !== e.issue).map((m) => `#${m}`);
+      decided({ issue: e.issue, what: `requeued by ${e.by ?? "operator"} (forgedock orchestrate --requeue); prior outcome ${row.outcome}${list.length ? `; dependents back to pending: ${list.join(", ")}` : ""}`,
+        why: e.reason || "operator decision", alternative: "start a second batch" });
+      update({ issue: e.issue, outcome: "requeued", detail: `${e.reason || "operator decision"} (was ${row.outcome})` });
+      n++;
+    }
+    if (fresh.length) save();
+    return n;
+  };
+  // #4376: one SIGTERM per running local lane (their teardown saves the work); remote lanes run to their result unless the cancel carries `stopRemote` (#4612).
   const stopSent = new Set();
   function stop(n, rec) {
-    if (!stopLane || rec?.remote || stopSent.has(n)) return;
+    if (!stopLane || (rec?.remote && cancelled?.stopRemote !== true) || stopSent.has(n)) return; // #4612: remote lanes only when the cancel asked for it
     stopSent.add(n);
     try { Promise.resolve(stopLane(n, rec)).catch(() => {}); } catch { /* best effort */ }
   }
+  // #4592: re-read the hold set; one decision and one row when it changes.
+  const refreshHeld = () => {
+    if (!getHeld) return;
+    let got = [];
+    try { got = getHeld() ?? []; } catch { got = opHeld.size ? [...opHeld] : []; }
+    const next = new Set((Array.isArray(got) ? got : []).filter((n) => Number.isSafeInteger(n) && n > 0));
+    const fmt = (ns) => ns.map((n) => `#${n}`).join(", ");
+    const held = [...next].filter((n) => !opHeld.has(n)), freed = [...opHeld].filter((n) => !next.has(n));
+    opHeld = next;
+    if (held.length) {
+      decided({ issue: null, what: `held ${fmt(held)} (forgedock orchestrate --hold)`, why: "operator request", alternative: "cancel the batch" });
+      update({ issue: null, outcome: "hold", detail: fmt(held) });
+    }
+    if (freed.length) {
+      decided({ issue: null, what: `released ${fmt(freed)} (forgedock orchestrate --release)`, why: "operator request", alternative: "resume the batch" });
+      update({ issue: null, outcome: "release", detail: fmt(freed) });
+    }
+  };
   const checkCancel = () => {
     if (!getCancelled) return;
     let c = null;
@@ -811,25 +875,72 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     halted = true;
     return Object.assign(new Error("batch stopped: schedd shutting down"), { code: "batch.stopped" });
   };
+  // #4595: a skipped row whose blocker (`dependency #B ...`) was finished outside the lane is re-admitted: B is re-checked
+  // through `dispatchCheck` (at most every WATCH_EVERY_MS, and once before the batch would end); fail-open.
+  let lastWatch = null;
+  const readmitted = new Set(); // "n:b": re-admit n on blocker b once; a lane that re-skips on b stays skipped
+  const blockerOf = (n) => { const r = results.get(n); const m = r?.outcome === "skipped" ? /^dependency #(\d+) /.exec(r.detail ?? "") : null; return m ? Number(m[1]) : null; };
+  const watchable = () => !!dispatchCheck && [...results.keys()].some((n) => blockerOf(n) !== null);
+  const watchBlockers = async (final) => {
+    if (!watchable() || cancelled || tripped) return;
+    const t0 = now();
+    if (!final && lastWatch !== null && t0 - lastWatch < WATCH_EVERY_MS) return;
+    lastWatch = t0;
+    const resolved = new Set();
+    const roots = new Set([...results.keys()].filter((n) => !readmitted.has(`${n}:${blockerOf(n)}`)).map(blockerOf).filter((b) => b !== null && blockerOf(b) === null));
+    for (const b of roots) {
+      let g = null;
+      try { g = (await dispatchCheck(b)) ?? null; } catch { g = null; }
+      if (!g || !SATISFIED.has(g.outcome)) continue;
+      resolved.add(b);
+      const row = results.get(b);
+      if (row) { results.set(b, { ...row, outcome: g.outcome, pr: Number.isInteger(g.pr) ? g.pr : row.pr, detail: g.detail ?? row.detail }); update(results.get(b)); }
+    }
+    const back = new Set();
+    for (let grew = true; grew;) {
+      grew = false;
+      for (const n of results.keys()) {
+        const b = blockerOf(n);
+        if (b !== null && !back.has(n) && !readmitted.has(`${n}:${b}`) && (resolved.has(b) || back.has(b))) { back.add(n); grew = true; }
+      }
+    }
+    for (const n of back) {
+      const b = blockerOf(n);
+      readmitted.add(`${n}:${b}`);
+      results.delete(n);
+      pending.push(n);
+      decided({ issue: n, what: `re-admitted: dependency #${b} merged or closed after this issue was skipped`, why: "the blocker was finished outside this batch lane",
+        alternative: "leave it skipped until the next batch" });
+    }
+    if (back.size) save();
+  };
   const K = () => { let k = null; try { k = getParallel?.(); } catch { k = null; } return Number.isInteger(k) && k >= 1 ? k : parallel; };
   try {
     for (;;) {
       if (signal?.aborted) throw halt();
       await drainAdds();
+      await drainRequeues();
       checkCancel();
+      await watchBlockers(!pending.length && !running.size);
       if (!pending.length && !running.size) break;
       // 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}`); }
+      for (let again = true; again;) { // #4595: to a fixpoint, so a chain's tail is skipped on its blocker, not as a "cycle"
+        again = false;
+        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}`); again = true; }
+        }
       }
       const t = now();
       const holdUntil = heldUntil();
       let started = 0;
       driftHeld.clear();
+      opHeldHit.clear();
+      refreshHeld();
       const isReady = (n) => {
+        if (opHeld.has(n)) { opHeldHit.add(n); return false; }
         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;
@@ -898,10 +1009,12 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       if (holdUntil) waits.push(holdUntil);
       let wake = waits.length ? Math.max(0, Math.min(...waits) - t) : null;
       if (holdUntil && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // #4446: a cleared hold (forgedock limits clear) admits on the next poll
-      if (getParallel && pending.length) wake = Math.min(wake ?? pollMs, pollMs);
+      if ((getParallel || getHeld) && 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 (getAdded && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4408: an add while only lanes run
+      if ((getAdded || getRequeued) && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4408/#4550: an add or requeue while only lanes run
+      if (getHeld && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4592: a release while only lanes run
       if (syncParked && running.size && parkedPrs().length) wake = Math.min(wake ?? syncEveryMs, Math.max(0, syncEveryMs - (t - (lastParkedSync ?? t)))); // #4525
+      if (running.size && watchable()) wake = Math.min(wake ?? WATCH_EVERY_MS, WATCH_EVERY_MS); // #4595: re-check the blockers of skipped rows
       if (tripped) wake = null;
       if (getCancelled && running.size && !cancelled) wake = Math.min(wake ?? pollMs, pollMs); // #4376: notice a cancel while lanes run
       if (running.size) {
@@ -911,6 +1024,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       else if (pending.length && offered.size) await nap(wake); // waiting for a host slot
       else if (pending.length && waits.length) await nap(Math.min(wake, getCancelled ? pollMs : Infinity)); // wake is poll-capped by a hold or a live K; #4454: nap wakes on a stop
       else if (pending.length && budgetHeld) { if (await drainAdds()) continue; break; } // maintenance the budget does not admit now: held for a later batch
+      else if (pending.length && opHeldHit.size && !pending.some((n) => !opHeldHit.has(n) && isReady(n))) { if (await drainAdds()) continue; break; } // #4592: held by the operator: pending for a --resume
       else if (pending.length && driftHeld.size) { if (await drainAdds()) continue; 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");
@@ -925,7 +1039,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   if (reg) withdrawExcept(new Set());
   await relabelQueued();
   save();
-  return order.map((n) => results.get(n) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: heldDetail(n),
+  const withRequeue = (r) => (r && requeuedInfo.has(r.issue) ? { ...r, requeued: { reason: requeuedInfo.get(r.issue).reason, by: requeuedInfo.get(r.issue).by, prior: requeuedInfo.get(r.issue).prior.map((p) => ({ outcome: p.outcome, detail: p.detail ?? null, pr: p.pr ?? null })) } } : r);
+  return order.map((n) => withRequeue(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",
       ...(recovering.get(n).result_code ? { result_code: recovering.get(n).result_code } : {}), detail: firstLine(recovering.get(n).detail ?? recovering.get(n).code) } } : {}) });
 }
@@ -954,6 +1069,8 @@ export const OUTCOME_LINE_MAX = 200;
 export function formatOutcomeLists(rows) {
   const out = [];
   const one = (x) => String(x ?? "").split("\n")[0].slice(0, OUTCOME_LINE_MAX);
+  const requeued = (rows ?? []).filter((r) => r?.requeued); // #4550: operator --requeue after a decision; the row is the latest outcome
+  if (requeued.length) out.push(`requeued: ${requeued.map((r) => `#${r.issue} (${one(r.requeued.reason)})`).join(" ")}`);
   const rec = (rows ?? []).filter((r) => r?.recovered);
   if (rec.length) out.push(`recovered: ${rec.map((r) => `#${r.issue} (${r.recovered})`).join(" ")}`);
   for (const r of rows ?? []) {

package/bin/lean/postdeploy-check.mjs

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Named post-deploy checks (#4626). A post-deploy requirement names a check id (`[check:<id>]` in its follow-up item);
+ * the command lives in the checks file on the default branch, `.forge/post-deploy-checks.json`:
+ *   { "<id>": { "run": "sh command", "pass": "exit 0 | /regex/flags", "timeout": 120 } }   (a bare string is `run`)
+ * and is read with `git show origin/<default>:<file>`: reviewed default-branch code, never an issue body or comment
+ * (#4468). When the #4389 gate reports a follow-up ready, `measureFollowup` runs every item's check (no model call, the
+ * probe runner's minimal env): all pass -> a FORGE:PROBE record and the follow-up closes; a fail -> the record, and the
+ * parent reopens with the output. An item without a runnable check is `awaiting-measurement`: no lane, ever.
+ */
+import { noComments } from "./render.mjs";
+import { MAX_TIMEOUT_S, OUTPUT_TAIL, PROBE_MARKER, probeEnv, probeResultOf, readProbeConfig, runProbe } from "./probe.mjs";
+import { parseMinAge } from "./prefilter.mjs";
+
+export const CHECKS_FILE = ".forge/post-deploy-checks.json";
+export const CHECK_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const AWAITING_MEASUREMENT_LABEL = "awaiting-measurement";
+export const MONITORING_LABEL = "post-deploy-monitoring";
+export const DEFAULT_EVERY_MS = 6 * 3600e3;
+const ITEM_RE = /^\s*[-*]\s+\[[ xX]\]\s+(.*)$/;
+const CHECK_TOKEN_RE = /^`[^`]*`\s+(?:\*\*known-flaw\*\*\s+)?[—-]+\s*post-deploy:\s*\[check:\s*([^\]\s]*)\s*\]/;
+
+/**
+ * The checks file's runnable entries `{id: {run, pass, timeoutS, forMs?, everyMs?}}`; malformed input or entries are dropped.
+ * `for` (a window such as "7d") makes the check windowed (#4627); `every` (default 6h) is its cadence and needs a `for`.
+ */
+export function parseChecks(text) {
+  let j;
+  try { j = JSON.parse(String(text ?? "")); } catch { return {}; }
+  if (!j || typeof j !== "object" || Array.isArray(j)) return {};
+  const out = {};
+  for (const [id, v] of Object.entries(j)) {
+    const spec = typeof v === "string" ? { run: v } : v;
+    if (!CHECK_ID_RE.test(id) || !spec || typeof spec.run !== "string" || !spec.run.trim()) continue;
+    let pass = { kind: "exit" };
+    const p = String(spec.pass ?? "").trim();
+    if (p && !/^exit\s+0$/i.test(p)) {
+      const r = /^\/(.+)\/([a-z]*)$/.exec(p);
+      try { if (!r) continue; new RegExp(r[1], r[2]); } catch { continue; }
+      pass = { kind: "regex", re: r[1], flags: r[2] };
+    }
+    const t = spec.timeout == null ? null : Number(spec.timeout);
+    if (t != null && !(Number.isFinite(t) && t > 0)) continue;
+    const win = spec.for == null ? null : parseMinAge(spec.for);
+    const cad = spec.every == null ? null : parseMinAge(spec.every);
+    if ((spec.for != null && !win) || (spec.every != null && !cad) || (spec.every != null && spec.for == null)) continue;
+    out[id] = { run: spec.run.trim(), pass, timeoutS: t == null ? null : Math.min(Math.floor(t) || 1, MAX_TIMEOUT_S), ...(win ? { forMs: win, everyMs: cad ?? DEFAULT_EVERY_MS } : {}) };
+  }
+  return out;
+}
+
+/** Per checklist item of a follow-up body: its `[check:<id>]` id, or null when it names none (or a malformed one). */
+export function itemCheckIds(body) {
+  return noComments(String(body ?? ""), " ").split("\n").map((l) => ITEM_RE.exec(l)?.[1]).filter((t) => t != null)
+    .map((t) => { const m = CHECK_TOKEN_RE.exec(t); return m && CHECK_ID_RE.test(m[1]) ? m[1] : null; });
+}
+
+/** The checks file at each git ref (`git show <ref>:<file>`); a missing file or ref contributes nothing. */
+export async function checksAt(git, refs, cwd) {
+  const out = {};
+  for (const ref of refs) {
+    try { Object.assign(out, parseChecks(String(await git(["show", `${ref}:${CHECKS_FILE}`], { cwd })))); } catch { /* no file at this ref */ }
+  }
+  return out;
+}
+
+const fenced = (s) => { const f = "`".repeat(Math.max(3, ...[...String(s).matchAll(/`+/g)].map((m) => m[0].length + 1))); return `${f}\n${String(s).trim() || "(no output)"}\n${f}`; };
+
+/** Run each distinct check id with the probe runner (minimal env, timeout, masked output): `[{id, result, exit, ms, output}]`. */
+export async function runNamedChecks({ ids, checks, cwd, config, env, spawn }) {
+  const rows = [];
+  for (const id of [...new Set(ids)]) {
+    const r = await runProbe(checks[id], { cwd, env: probeEnv(config.env, env), mask: config.env.map((k) => env[k]), timeoutS: config.timeoutS, ...(spawn ? { spawn } : {}) });
+    rows.push({ id, ...r });
+  }
+  return rows;
+}
+
+/** The windowed-monitoring fields of a FORGE:PROBE record body (`at`, `window_until`, `every_ms`, `regression`, ...), or null. */
+export function monitorRecord(body) {
+  const base = probeResultOf(body);
+  if (!base) return null;
+  const line = String(body).split("\n").find((l) => /^\s*`?\{.*"result"/.test(l));
+  try {
+    const j = JSON.parse(line.trim().replace(/^`|`$/g, ""));
+    const at = Date.parse(j.at), until = Date.parse(j.window_until);
+    return Number.isFinite(at) ? { ...base, at, defaultSha: j.default_sha ?? null, everyMs: Number(j.every_ms) || DEFAULT_EVERY_MS, until: Number.isFinite(until) ? until : null, regression: j.regression ?? null } : null;
+  } catch { return null; }
+}
+
+/** The post-deploy-monitoring label, created on first use; best effort. */
+export async function addMonitoringLabel({ io, repo, issue }) {
+  const edit = () => io.gh(["issue", "edit", String(issue), "-R", repo, "--add-label", MONITORING_LABEL]);
+  try { await edit(); } catch {
+    try { await io.gh(["label", "create", MONITORING_LABEL, "-R", repo, "--force", "--color", "C5DEF5", "--description", "Post-deploy follow-up whose windowed check re-runs on later releases. Managed by ForgeDock."]); await edit(); } catch { /* the record still shows it */ }
+  }
+}
+
+/**
+ * Measure a ready post-deploy follow-up. Never runs a command that is not in the default branch's checks file.
+ * @returns {Promise<{state:"awaiting-measurement"|"pass"|"fail"|"recorded-fail"|"dry-run"|"monitoring", detail:string}>}
+ * When every item's check declares a window (#4627) a pass records the release and the window end and the follow-up stays
+ * open (`monitoring`); `sweepDue` (postdeploy-monitor.mjs) re-runs it.
+ */
+export async function measureFollowup({ iss, repo, parent, def, shas = [], cwd, io, dryRun = false, isTrusted = () => false, config = readProbeConfig(cwd), env = process.env, spawn, now = () => Date.now() }) {
+  const ids = itemCheckIds(iss.body);
+  const checks = await checksAt(io.git, [`origin/${def}`], cwd);
+  const missing = ids.filter((id) => !id || !checks[id]);
+  if (!ids.length || missing.length) return { state: "awaiting-measurement", detail: `no runnable check on ${def} for ${ids.length ? `${missing.map((m) => m ?? "an item without a check id").join(", ")}` : "any item"} (${CHECKS_FILE})` };
+  const fix = [...shas].sort().join(",");
+  const prior = (iss.comments ?? []).filter((c) => isTrusted(c)).map((c) => probeResultOf(c?.body)).filter(Boolean).reverse().find((p) => p.fix === fix);
+  if (prior?.result === "fail") return { state: "recorded-fail", detail: `check failed for ${fix.slice(0, 12)} (FORGE:PROBE); waiting for a new fix of #${parent}` };
+  const windowed = ids.every((id) => checks[id].forMs);
+  const monitored = (iss.comments ?? []).filter((c) => isTrusted(c)).map((c) => monitorRecord(c?.body)).filter(Boolean).find((p) => p.fix === fix && p.result === "pass" && p.until);
+  if (windowed && monitored) return { state: "monitoring", detail: `windowed checks ${[...new Set(ids)].join(", ")} monitored until ${new Date(monitored.until).toISOString()}` };
+  if (dryRun) return { state: "dry-run", detail: `checks ${[...new Set(ids)].join(", ")} not run (dry run)` };
+  let defaultSha = null;
+  try { defaultSha = String(await io.git(["rev-parse", `origin/${def}`], { cwd })).trim() || null; } catch { /* recorded as null */ }
+  const rows = [];
+  if (prior?.result !== "pass") {
+    rows.push(...await runNamedChecks({ ids, checks, cwd, config, env, spawn }));
+    const ok = rows.every((r) => r.result === "pass");
+    const at = now();
+    const win = windowed && ok ? { at: new Date(at).toISOString(), window_until: new Date(at + Math.max(...ids.map((id) => checks[id].forMs))).toISOString(), every_ms: Math.min(...ids.map((id) => checks[id].everyMs)) } : {};
+    const body = [
+      `<!-- ${PROBE_MARKER} -->`, `## Post-deploy check: ${ok ? "pass" : "fail"}`,
+      JSON.stringify({ fix, default_sha: defaultSha, result: ok ? "pass" : "fail", ...win, checks: rows.map((r) => ({ id: r.id, result: r.result, exit: r.exit, ms: r.ms })) }), "",
+      `Ran after the fix of #${parent} reached \`${def}\`; commands come from \`${CHECKS_FILE}\` on \`${def}\`.${ok ? (win.at ? ` Monitored until \`${win.window_until}\`, re-run on later releases.` : " The follow-up is closed.") : " The parent is reopened."}`,
+      ...rows.filter((r) => r.result === "fail").flatMap((r) => ["", `**${r.id}** (exit ${r.exit ?? "timeout"})`, fenced(r.output)]),
+    ].join("\n").slice(0, OUTPUT_TAIL * 4);
+    await io.gh(["issue", "comment", String(iss.number), "-R", repo, "--body", body]);
+    if (!ok) {
+      const bad = rows.filter((r) => r.result === "fail");
+      let note = "";
+      try { await io.gh(["issue", "reopen", String(parent), "-R", repo]); } catch (e) { note = ` (reopen failed: ${String(e?.message ?? e).slice(0, 120)})`; }
+      try {
+        await io.gh(["issue", "comment", String(parent), "-R", repo, "--body", `Post-deploy check ${bad.map((r) => `\`${r.id}\``).join(", ")} failed for the fix on \`${def}\` (follow-up #${iss.number}); reopened.\n\n${bad.map((r) => fenced(r.output)).join("\n\n")}`.slice(0, OUTPUT_TAIL * 4)]);
+      } catch { /* the follow-up comment carries the output */ }
+      return { state: "fail", detail: `check ${bad.map((r) => r.id).join(", ")} failed; #${parent} reopened${note}` };
+    }
+  }
+  if (windowed) {
+    await addMonitoringLabel({ io, repo, issue: iss.number });
+    return { state: "monitoring", detail: `checks ${[...new Set(ids)].join(", ")} passed; monitored on later releases` };
+  }
+  await io.gh(["issue", "close", String(iss.number), "-R", repo, "--reason", "completed"]);
+  return { state: "pass", detail: `checks ${[...new Set(ids)].join(", ")} passed` };
+}

package/bin/lean/postdeploy-check.test.mjs

@@ -0,0 +1,146 @@
+// 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 { parseChecks, itemCheckIds, measureFollowup, monitorRecord, CHECK_ID_RE } from "./postdeploy-check.mjs";
+import { postDeployOnly } from "./prefilter.mjs";
+import { validateContract, applyAmendments, precheck, followupItems } from "./conformance.mjs";
+import { PROBE_MARKER } from "./probe.mjs";
+
+const item = (id, why) => `- [ ] \`${id}: some quote here\` — post-deploy: ${why}`;
+const body = (items) => `## Acceptance Criteria\n\n${items.join("\n")}\n\n<!-- FORGE:DEFERRED_FROM: #40 -->\n`;
+const CHECKS = JSON.stringify({ smoke: { run: "echo ok", timeout: 5 }, bad: "echo nope", "bad id!": "x", rx: { run: "echo up", pass: "/up/" }, norun: {} });
+
+function world({ file = CHECKS, spawn } = {}) {
+  const w = { gh: [], git: [], spawned: [] };
+  w.io = {
+    gh: async (a) => { w.gh.push(a); return ""; },
+    git: async (a) => { w.git.push(a); if (a[0] === "show") { if (file == null) throw new Error("missing"); return file; } return "deadbeef\n"; },
+  };
+  w.spawn = async (o) => { w.spawned.push(o.run); return spawn ? spawn(o) : { code: o.run === "echo nope" ? 1 : 0, stdout: o.run === "echo nope" ? "boom" : "ok", stderr: "" }; };
+  return w;
+}
+const run = (w, bodyText, extra = {}) => measureFollowup({ iss: { number: 41, body: bodyText, comments: [] }, repo: "o/r", parent: 40, def: "main", shas: ["abc"], cwd: "/repo", io: w.io, config: { env: [], timeoutS: 5 }, env: {}, spawn: w.spawn, ...extra });
+
+describe("post-deploy named checks (#4626)", () => {
+  it("parses the checks file; malformed entries are dropped", () => {
+    const c = parseChecks(CHECKS);
+    assert.deepEqual(Object.keys(c).sort(), ["bad", "rx", "smoke"]);
+    assert.equal(c.smoke.timeoutS, 5); assert.equal(c.rx.pass.kind, "regex");
+    assert.deepEqual(parseChecks("not json"), {});
+    assert.ok(CHECK_ID_RE.test("login-smoke") && !CHECK_ID_RE.test("Bad Id"));
+  });
+
+  it("postDeployOnly still matches items with and without a [check:id] token", () => {
+    assert.ok(postDeployOnly(body([item("R1", "[check:smoke] soak"), item("R2", "only in prod")])));
+  });
+  it("extracts [check:id] per item; an item without one yields null", () => {
+    assert.deepEqual(itemCheckIds(body([item("R1", "[check:smoke] soak"), item("R2", "only in prod")])), ["smoke", null]);
+  });
+
+  it("pass: runs the default-branch command, records FORGE:PROBE, closes the follow-up, no reopen", async () => {
+    const w = world();
+    const r = await run(w, body([item("R1", "[check:smoke] x")]));
+    assert.equal(r.state, "pass");
+    assert.deepEqual(w.spawned, ["echo ok"]);
+    assert.ok(w.git.some((a) => a.join(" ") === "show origin/main:.forge/post-deploy-checks.json"));
+    const cm = w.gh.find((a) => a[1] === "comment");
+    assert.match(cm[cm.indexOf("--body") + 1], new RegExp(PROBE_MARKER));
+    assert.ok(w.gh.some((a) => a[1] === "close" && a[2] === "41"));
+    assert.ok(!w.gh.some((a) => a[1] === "reopen"));
+  });
+
+  it("fail: reopens the parent with the output and does not close", async () => {
+    const w = world();
+    const r = await run(w, body([item("R1", "[check:bad] x")]));
+    assert.equal(r.state, "fail");
+    assert.ok(w.gh.some((a) => a[1] === "reopen" && a[2] === "40"));
+    assert.ok(w.gh.some((a) => a[1] === "comment" && a[2] === "40" && a[a.indexOf("--body") + 1].includes("boom")));
+    assert.ok(!w.gh.some((a) => a[1] === "close"));
+  });
+
+  it("no runnable check: awaiting-measurement, nothing runs, no model call", async () => {
+    for (const [file, b] of [[CHECKS, body([item("R1", "[check:ghost] x")])], [null, body([item("R1", "[check:smoke] x")])], [CHECKS, body([item("R1", "x"), item("R2", "[check:smoke] y")])]]) {
+      const w = world({ file });
+      assert.equal((await run(w, b)).state, "awaiting-measurement");
+      assert.deepEqual(w.spawned, []); assert.deepEqual(w.gh, []);
+    }
+  });
+
+  it("a command declared in the issue body never runs", async () => {
+    const w = world();
+    const b = body([item("R1", "[check:ghost] x")]) + "\n```forge-probe\nrun: rm -rf /\n```\n";
+    assert.equal((await run(w, b)).state, "awaiting-measurement");
+    assert.deepEqual(w.spawned, []);
+  });
+
+  it("migration: the six open follow-up shapes (no check id) all park awaiting-measurement", async () => {
+    for (const n of [4415, 4421, 4438, 4488, 4495, 4498]) {
+      const w = world();
+      const r = await run(w, body([item(`R${n % 7}`, "only checkable after the next deploy")]));
+      assert.equal(r.state, "awaiting-measurement", `#${n}`);
+      assert.deepEqual(w.spawned, []);
+    }
+  });
+
+  it("a recorded fail for the same fix is not re-run", async () => {
+    const w = world();
+    const c = { body: `<!-- ${PROBE_MARKER} -->\n${JSON.stringify({ fix: "abc", result: "fail" })}` };
+    const r = await run(w, body([item("R1", "[check:smoke] x")]), { iss: { number: 41, body: body([item("R1", "[check:smoke] x")]), comments: [c] }, isTrusted: () => true });
+    assert.equal(r.state, "recorded-fail"); assert.deepEqual(w.spawned, []);
+  });
+
+  it("contract: post-deploy needs a check id; amendment too; precheck rejects an unknown id; followup item names it", () => {
+    const Q = "The deploy-time health row must exist after promotion.";
+    const c = { requirements: [{ id: "R1", quote: Q, disposition: "post-deploy", why: "w" }], deliverables: [], preserve: [], validate: [{ id: "V1", command: "true" }] };
+    assert.ok(validateContract(c, Q).problems.some((p) => /needs a check id/.test(p)));
+    assert.ok(!validateContract({ ...c, requirements: [{ ...c.requirements[0], check: "smoke" }] }, Q).problems.some((p) => /check id/.test(p)));
+    const frozen = { ...c, requirements: [{ id: "R1", quote: Q, disposition: "deliver" }] };
+    assert.ok(applyAmendments(frozen, [{ kind: "post-deploy", requirement: "R1", why: "w" }], Q).problems.some((p) => /check id/.test(p)));
+    const ok = applyAmendments(frozen, [{ kind: "post-deploy", requirement: "R1", why: "w", check: "smoke" }], Q);
+    assert.equal(ok.contract.requirements[0].check, "smoke");
+    const pc = precheck({ contract: { ...c, requirements: [{ ...c.requirements[0], check: "ghost" }] }, result: { requirements: [] }, changedFiles: [], checkIds: new Set(["smoke"]) });
+    assert.ok(pc.failures.some((f) => f.kind === "check_unknown"));
+    assert.match(followupItems([{ ...c.requirements[0], check: "smoke" }])[0].why, /^post-deploy: \[check:smoke\] w/);
+  });
+});
+
+describe("windowed post-deploy checks (#4627)", () => {
+  const WIN = JSON.stringify({ soak: { run: "echo ok", for: "7d", every: "6h" }, soakd: { run: "echo ok", for: "2d" }, noFor: { run: "echo ok", every: "6h" }, badFor: { run: "echo ok", for: "soon" }, zero: { run: "echo ok", for: "0" }, plain: "echo ok" });
+  const NOW = Date.parse("2026-10-26T00:00:00Z");
+  it("parses for/every; every defaults to 6h; every without for or a bad duration drops the entry", () => {
+    const c = parseChecks(WIN);
+    assert.deepEqual(Object.keys(c).sort(), ["plain", "soak", "soakd"]);
+    assert.equal(c.soak.forMs, 7 * 86400e3); assert.equal(c.soak.everyMs, 6 * 3600e3);
+    assert.equal(c.soakd.everyMs, 6 * 3600e3);
+    assert.equal(c.plain.forMs, undefined);
+  });
+  it("first pass records the release and window, labels, and keeps the follow-up open", async () => {
+    const w = world({ file: WIN });
+    const r = await run(w, body([item("R1", "[check:soak] x")]), { now: () => NOW });
+    assert.equal(r.state, "monitoring");
+    assert.ok(!w.gh.some((a) => a[1] === "close") && !w.gh.some((a) => a[1] === "reopen"));
+    assert.ok(w.gh.some((a) => a[1] === "edit" && a.includes("post-deploy-monitoring")));
+    const cm = w.gh.find((a) => a[1] === "comment");
+    const rec = monitorRecord(cm[cm.indexOf("--body") + 1]);
+    assert.equal(rec.result, "pass"); assert.equal(rec.until, NOW + 7 * 86400e3); assert.equal(rec.everyMs, 6 * 3600e3); assert.equal(rec.defaultSha, "deadbeef");
+  });
+  it("a recorded windowed pass is not re-measured by the pre-filter path", async () => {
+    const w = world({ file: WIN });
+    const rec = { body: `<!-- ${PROBE_MARKER} -->\n${JSON.stringify({ fix: "abc", result: "pass", at: new Date(NOW).toISOString(), window_until: new Date(NOW + 1e9).toISOString() })}` };
+    const b = body([item("R1", "[check:soak] x")]);
+    const r = await run(w, b, { iss: { number: 41, body: b, comments: [rec] }, isTrusted: () => true });
+    assert.equal(r.state, "monitoring"); assert.deepEqual(w.spawned, []);
+  });
+  it("a non-windowed check still closes on pass (part 1 unchanged)", async () => {
+    const w = world({ file: WIN });
+    assert.equal((await run(w, body([item("R1", "[check:plain] x")]))).state, "pass");
+    assert.ok(w.gh.some((a) => a[1] === "close"));
+  });
+  it("a first-run fail of a windowed check reopens the parent as before", async () => {
+    const w = world({ file: JSON.stringify({ soak: { run: "echo nope", for: "7d" } }), spawn: () => ({ code: 1, stdout: "boom", stderr: "" }) });
+    assert.equal((await run(w, body([item("R1", "[check:soak] x")]))).state, "fail");
+    assert.ok(w.gh.some((a) => a[1] === "reopen" && a[2] === "40"));
+  });
+});
+