forgedock 1.30.0 → 1.32.0

package/bin/engine.mjs

@@ -9,6 +9,13 @@ import { execFileSync } from "node:child_process";
 import { createHash, scryptSync } from "node:crypto";
 import { hostname as osHostname, homedir } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog, scopeEvents } from "./engine/runlog.mjs";
+
+/** #4432: the issue's run log in `dir`, keyed by repo + issue (legacy `<issue>.jsonl` when `repo` is null). */
+const makeRunLog = (dir, issue, repo) => ({
+  append: (e) => appendEvent(dir, issue, e, { repo }),
+  read: () => readLog(dir, issue, { repo }),
+  rewrite: (events) => rewriteLog(dir, issue, events, { repo }),
+});
 import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postCycleMarker, nextCycleNumber, newestCycle, cycleResetProvable, remediationHeadStale, decompositionRevoked, openDependency, reopenRevokedDecomposition } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
@@ -431,7 +438,7 @@ export async function runIssue(opts) {
   // event and forwards it to the telemetry hook (#3834 owns the FORGE:TELEMETRY writer), which can
   // never fail the run.
   const emitOutcome = async (rec) => {
-    appendEvent(dir, issue, rec);
+    runLog.append(rec);
     try { await emitTelemetry?.({ ...rec, issue }); } catch { /* telemetry never fails a run */ }
   };
 
@@ -443,11 +450,23 @@ export async function runIssue(opts) {
   // #4125: no silent lane default; the caller (run-issue --lane) names it, and the CLI refuses the default branch.
   if (typeof lane !== "string" || !lane.trim()) throw new Error("runIssue: lane is required (staging or milestone/<slug>); there is no default");
 
+  // forge#3824: hoisted so RUN_START can carry the repo; #4432: resolved before the first run-log read, which is keyed by it (lazy, memoised; null when unresolved).
+  let repoPromise = null;
+  const resolveRepo = () => (repoPromise ??= (async () => {
+    if (repo) return String(repo).trim();
+    try {
+      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+      return String(out || "").trim() || null;
+    } catch { return null; }
+  })());
+  // #4432: the run log is keyed by repo + issue (issue numbers are per repo); an unresolved repo keeps the legacy name.
+  const runLog = makeRunLog(dir, issue, await resolveRepo().catch(() => null));
+
   const projector = makeProjector(io);
 
   // 1. Load + reconcile (GitHub wins).
   // #4109: only this (full) path's own events: core-path commits and terminals in the shared log are never replayed here.
-  const local = scopeEvents(readLog(dir, issue)).length ? deriveState(readLog(dir, issue)) : null;
+  const local = scopeEvents(runLog.read()).length ? deriveState(runLog.read()) : null;
   let remote = await projector.readState(issue);
   let { state, action } = reconcileState(local, remote);
   const leaseHeld = (r) => !!(r?.lease && r.lease.until > now() && r.lease.by !== agentId &&
@@ -515,28 +534,19 @@ export async function runIssue(opts) {
       };
     }
   }
-  // forge#3824: hoisted so RUN_START can carry the repo (lazy, memoised; null when unresolved).
-  let repoPromise = null;
-  const resolveRepo = () => (repoPromise ??= (async () => {
-    if (repo) return String(repo).trim();
-    try {
-      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
-      return String(out || "").trim() || null;
-    } catch { return null; }
-  })());
 
   const runMeta = async () => ({ version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo: await resolveRepo().catch(() => null) });
   if (!state) {
     state = freshState(issue, lane);
-    appendEvent(dir, issue, { event: "RUN_START", issue, run: state.run, lane, ...(await runMeta()) });
+    runLog.append({ event: "RUN_START", issue, run: state.run, lane, ...(await runMeta()) });
   } else if (action === "hydrate") {
     // GitHub is ahead of (or the only source of) local state. Rebuild the
     // local run-log to match the remote compact index so downstream
     // `deriveState(readLog(...))` calls stay consistent — otherwise the
     // post-commit re-derive below would fold over an empty/stale local log
     // and regress committed/issue/v (C2).
-    rewriteLog(dir, issue, eventsFromIndex(state, await runMeta()));
-    state = deriveState(readLog(dir, issue));
+    runLog.rewrite(eventsFromIndex(state, await runMeta()));
+    state = deriveState(runLog.read());
     // forge#3931: the index does not carry the cycle, so a hydrated log always starts at cycle 0. When a
     // trusted FORGE:CYCLE exists, cycle-scoped progress (or a needs-human/phase-complete/engine-error terminal)
     // belongs to an older cycle ONLY when provably so (cycleResetProvable: terminal index, issue OPEN, no needs-human/remediating label, no open PR): reset via the existing RUN_NEXT_CYCLE event so build runs again instead of
@@ -547,8 +557,8 @@ export async function runIssue(opts) {
       let cyc = 0;
       try { cyc = await newestCycle(issue, io); } catch { cyc = 0; }
       if (cyc > 0) {
-        appendEvent(dir, issue, { event: "RUN_NEXT_CYCLE", issue });
-        state = deriveState(readLog(dir, issue));
+        runLog.append({ event: "RUN_NEXT_CYCLE", issue });
+        state = deriveState(runLog.read());
       }
     }
   }
@@ -630,7 +640,7 @@ export async function runIssue(opts) {
     // forge#3657: publish the cycle boundary on GitHub BEFORE the log flips, so
     // build's reconcilers never re-adopt cycle-1 evidence. Fail closed.
     if (state.terminalReason === "phase-complete") {
-      const localCycles = readLog(dir, issue).filter((e) => e.event === "RUN_NEXT_CYCLE").length;
+      const localCycles = runLog.read().filter((e) => e.event === "RUN_NEXT_CYCLE").length;
       try { await postCycleMarker(issue, await nextCycleNumber(issue, localCycles, io), io); } catch {
         return {
           terminalReason: "not-retryable",
@@ -638,12 +648,12 @@ export async function runIssue(opts) {
         };
       }
     }
-    appendEvent(dir, issue, {
+    runLog.append({
       event: state.terminalReason === "phase-complete" ? "RUN_NEXT_CYCLE" : "RUN_REOPEN",
       issue,
       ...(reopenUncommit ? { uncommit: reopenUncommit } : {}),
     });
-    state = deriveState(readLog(dir, issue));
+    state = deriveState(runLog.read());
     reopened = true;
   }
   // forge#2239: claim the lease unconditionally here — before the phase loop
@@ -882,7 +892,7 @@ export async function runIssue(opts) {
         for (;;) {
         for (;;) {
           try {
-            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry, sleep });
+            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, runLog, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry, sleep });
             break;
           } catch (e) {
             const resetAtMs = e.resetAtEpochMs;
@@ -904,7 +914,7 @@ export async function runIssue(opts) {
             // hasn't committed yet, so a resumed run correctly re-enters
             // pickPhase at this same phase regardless of whether this event
             // was ever written.
-            appendEvent(dir, issue, {
+            runLog.append({
               event: "PHASE_RATE_LIMITED", phase: phase.id,
               resetAt: hasResetEpoch ? resetAtMs : null, resetAtDisplay: e.resetAt || null, waitMs,
               backendId: backendIdentity({ backend, env: process.env }),
@@ -1051,7 +1061,7 @@ export async function runIssue(opts) {
     const commitReason = blockedReason ?? outcome.terminalReason ?? null;
     // forge#3833: the handoff/blocked cause, persisted on the commit event like the reason.
     const commitCode = commitReason ? normalizeCode(outcome.code ?? codeForTerminalReason(commitReason)) : null;
-    appendEvent(dir, issue, {
+    runLog.append({
       event: "PHASE_COMMIT", phase: phase.id, outputs: commitOutputs,
       // forge#3696: `usage` is cumulative over every attempt of the phase; the last attempt's alone is `last_attempt_usage`.
       usage: outcome.usage ?? null, last_attempt_usage: outcome.last_attempt_usage ?? null,
@@ -1061,7 +1071,7 @@ export async function runIssue(opts) {
       backend: outcome.backend ?? null,
       ...(commitReason ? { terminalReason: commitReason, code: commitCode } : {}),
     });
-    state = deriveState(readLog(dir, issue));
+    state = deriveState(runLog.read());
     const terminalReason = blockedReason ?? outcome.terminalReason;
     if (terminalReason) state.terminalReason = terminalReason;
     await projector.writeState(issue, { ...state, lease: { by: agentId, until: now() + leaseTtlMs } });
@@ -1129,14 +1139,14 @@ export async function runIssue(opts) {
     const repoName = await resolveRepo();
     if (typeof io.waitCiGreen !== "function" || pr == null || !repoName) return {};
     const budgetMs = ciPendingMaxMinutes * 60000;
-    const open = readLog(dir, issue).filter((ev) => ev.event === "CI_PENDING_WAIT" && ev.pr === pr).pop();
+    const open = runLog.read().filter((ev) => ev.event === "CI_PENDING_WAIT" && ev.pr === pr).pop();
     const startedAt = open && open.state === "start" && Number.isFinite(open.startedAt) ? open.startedAt : now();
-    if (!(open && open.state === "start")) appendEvent(dir, issue, { event: "CI_PENDING_WAIT", state: "start", pr, startedAt });
+    if (!(open && open.state === "start")) runLog.append({ event: "CI_PENDING_WAIT", state: "start", pr, startedAt });
     let slept = 0, polls = 0, rateLimitSleeps = 0, pollIndex = 0;
     const spentMs = () => Math.max(now() - startedAt, slept);
     const report = async (result) => {
       const minutes = Math.round(spentMs() / 600) / 100;
-      appendEvent(dir, issue, { event: "CI_PENDING_WAIT", state: "end", pr, startedAt, minutes_waited: minutes, result, polls, rate_limit_sleeps: rateLimitSleeps });
+      runLog.append({ event: "CI_PENDING_WAIT", state: "end", pr, startedAt, minutes_waited: minutes, result, polls, rate_limit_sleeps: rateLimitSleeps });
       try { await emitTelemetry?.({ event: "CI_PENDING_WAIT", phase: phaseId, issue, pr, minutes_waited: minutes, result, polls, rate_limit_sleeps: rateLimitSleeps }); } catch { /* telemetry never fails a run */ }
       return minutes;
     };
@@ -1181,14 +1191,14 @@ export async function runIssue(opts) {
   async function terminate(s, reason, detail, code) {
     // forge#3833: absent -> the reason's own code; unknown -> `unclassified` with the raw text kept in `detail`.
     const outcomeCode = code == null ? codeForTerminalReason(reason) : normalizeCode(code);
-    appendEvent(dir, issue, { event: "RUN_TERMINAL", reason, code: outcomeCode,
+    runLog.append({ event: "RUN_TERMINAL", reason, code: outcomeCode,
       ...(outcomeCode === UNCLASSIFIED && detail ? { detail } : {}) });
     // forge#3835: forward the terminal record to the telemetry seam (best-effort, never fails the run).
     try { await emitTelemetry?.({ event: "RUN_TERMINAL", reason, code: outcomeCode, issue }); } catch { /* telemetry never fails a run */ }
     // The terminal write must always land; only the lease field is preserved when another live
     // agent holds it. A failed read falls back to clearing (a lost terminal write would strand the issue).
     const foreign = await foreignLiveLease();
-    const final = { ...deriveState(readLog(dir, issue)), terminal: true, terminalReason: reason, outcomeCode, lease: foreign ?? null };
+    const final = { ...deriveState(runLog.read()), terminal: true, terminalReason: reason, outcomeCode, lease: foreign ?? null };
     await projector.writeState(issue, final);
     // forge#3566: the terminal projection must not leave a stranded `workflow:remediating`
     // next to the terminal label. Best-effort: runs after the terminal write and never throws.
@@ -1237,7 +1247,7 @@ export function cleanupRunTmpdir(issue, { cwd = process.cwd(), env = process.env
 export const INFRA_SPAWN_BACKOFF_MS = Object.freeze([10_000, 30_000, 60_000]);
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = ctx;
+  const { io, runner, dir, issue, runLog, commandsDir, maxAttempts, backend, model, resolveRepo, agentId, emitTelemetry, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = ctx;
   // forge#3499: build the phase's full argument set ONCE, up front. Every
   // work-on phase sub-skill stops with BLOCKED when a required flag is absent,
   // so an incomplete/invalid set is a deterministic engine failure — fail
@@ -1249,7 +1259,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
   } catch (e) {
     if (e?.code !== "PHASE_ARGS_INVALID") throw e;
     const detail = `phase ${phase.id} args unresolved: ${e.message}`;
-    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt: 0, reason: detail, code: OUTCOME_CODES.ENGINE_ERROR, maxAttempts });
+    runLog.append({ event: "PHASE_FAILED", phase: phase.id, attempt: 0, reason: detail, code: OUTCOME_CODES.ENGINE_ERROR, maxAttempts });
     return { status: "blocked", detail, reason: "engine-error", code: OUTCOME_CODES.ENGINE_ERROR, usage: null };
   }
   // forge#2261: true only if EVERY attempt failed by the runner itself
@@ -1288,7 +1298,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
       cost_usd: extra?.cost_usd ?? null, model: extra?.model ?? null, turns: extra?.turns ?? null,
       backend: extra?.backend ?? null,
     };
-    appendEvent(dir, issue, rec);
+    runLog.append(rec);
     try { await emitTelemetry?.({ ...rec, issue }); } catch { /* telemetry never fails a phase */ }
   };
   // forge#4021: transient CLI spawn failures (ETIMEDOUT/EAGAIN/ENOMEM at spawn) retry on their own bounded
@@ -1296,7 +1306,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
   // so a CLI that merely runs long cannot loop forever.
   let infraRetries = 0;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    appendEvent(dir, issue, { event: "PHASE_START", phase: phase.id, attempt });
+    runLog.append({ event: "PHASE_START", phase: phase.id, attempt });
     let result;
     const t0 = performance.now();
     try {
@@ -1332,7 +1342,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
       if (e.code === "CLI_MAX_TURNS") {
         addUsage(e.usage);
         await recordAttempt(attempt, e.usage, t0, { turns: e.numTurns });
-        appendEvent(dir, issue, {
+        runLog.append({
           event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts,
           turns: e.numTurns ?? null, usage: e.usage ?? null,
         });
@@ -1342,13 +1352,13 @@ async function runPhaseWithRetry(phase, state, ctx) {
       // failure, so rethrow fail-fast and let runIssue end it as a retryable `engine-error` (never needs-human).
       if (isDiskQuotaError(e)) {
         await recordAttempt(attempt, null, t0, null);
-        appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts });
+        runLog.append({ event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts });
         throw e;
       }
       // Transient spawn class: e.code === "CLI_SPAWN_TRANSIENT" (see isTransientSpawnError); retried with infra backoff.
       if (isTransientSpawnError(e) && infraRetries < INFRA_SPAWN_BACKOFF_MS.length) {
         await recordAttempt(attempt, null, t0, null);
-        appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts, infraRetry: infraRetries + 1 });
+        runLog.append({ event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts, infraRetry: infraRetries + 1 });
         await sleep(INFRA_SPAWN_BACKOFF_MS[infraRetries++]);
         attempt--;
         continue;
@@ -1363,7 +1373,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
       const killUsage = e.code === "CLI_TIMEOUT" ? e.usage ?? null : null;
       if (killUsage) addUsage(killUsage);
       await recordAttempt(attempt, killUsage, t0, null);
-      appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts, ...(killUsage ? { usage: killUsage } : {}) });
+      runLog.append({ event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message, code: codeForRunnerError(e), maxAttempts, ...(killUsage ? { usage: killUsage } : {}) });
       lastCode = OUTCOME_CODES.ENGINE_ERROR;
       continue;
     }
@@ -1377,7 +1387,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
     await recordAttempt(attempt, lastUsage, t0, { cost_usd: result?.costUsd ?? null, model: lastModel, turns: lastTurns, backend: lastBackend });
     const outcome = await phase.detectOutcome(state, io, result);
     if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: cumulativeUsage, last_attempt_usage: lastUsage, model: lastModel, turns: lastTurns, backend: lastBackend };
-    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, code: normalizeCode(outcome.code), maxAttempts, usage: lastUsage, model: lastModel, turns: lastTurns });
+    runLog.append({ event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, code: normalizeCode(outcome.code), maxAttempts, usage: lastUsage, model: lastModel, turns: lastTurns });
     // forge#2176: a phase's detectOutcome can mark a failure as a known,
     // state-derived fixed point — re-running the phase's runner is
     // guaranteed to reproduce the identical failure (e.g. the build phase's

package/bin/forgedock.mjs

@@ -3289,8 +3289,10 @@ function help() {
     ["npx forgedock bootstrap <idea|docs> [--dry-run] [--spike <path>] | --plan <plan.json> [--dry-run]", "Headless /bootstrap: idea to orchestrate-ready backlog (--dry-run previews milestones, titles, DAG and estimated agent cost without GitHub writes); --plan validates and creates (or previews) a plan, and re-running resumes from GitHub"],
     ["npx forgedock run-issue <issue> [--lane <lane>] [--lane-override] [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline; the lane comes from the issue: milestone → milestone/<slug>, else staging; --lane is an assertion, never the default branch) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering; each issue on its own lane, cross-lane dependencies reported"],
-    ["npx forgedock orchestrate --resume <id> | --set-parallel <id> K", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), or change its concurrency live"],
+    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --cancel <id>", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), change its concurrency live, add issues to a running (or held) batch under its K and DAG, or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume)"],
     ["npx forgedock triage <issue...> [--lane L] [--dry-run]", "Already-fixed pre-filter: close issues a merged PR or green CI already resolved; print the rest"],
+    ["npx forgedock probe [issue...] [--dry-run]", "Run declared acceptance probes for closed issues whose fix is on the default branch; a fail reopens the issue"],
+    ["npx forgedock check [--base REF] [--json]", "Run the lane's frozen validate commands and change-scoped pre-PR checks locally in this worktree, as the engine will (no GitHub, no Actions)"],
     ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
     ["npx forgedock sched show | cap <N>|--clear | weight <owner/repo> <N>|--clear", "Show the host lane registry, set the host-wide lane cap shared by orchestrate batches, or set a repo's share of slots within a priority (default equal)"],
     ["npx forgedock schedd [status]", "Host scheduler daemon hosting every orchestrate batch (auto-spawned by orchestrate; run in the foreground for a systemd-user unit); status shows its pid and batches"],
@@ -3301,6 +3303,9 @@ function help() {
     ["npx forgedock config migrate [dir]", "Backfill missing optional sections into an existing forge.yaml (idempotent)"],
     ["npx forgedock watch [--repo owner/repo]", "Live per-agent orchestration view (Ctrl+C to exit)"],
     ["npx forgedock report [--days 30] [--md] [--json]", "30-day pipeline impact receipts for your repo"],
+    ["npx forgedock review-staging [<PR>] [--thorough] [--json]", "Staging->main review pre-dispatch: route marker, open-finding gate, scope, prepare, roster; writes one reviewer brief per domain"],
+    ["npx forgedock review-staging [<PR>] --finalize --test-gate-output <file>", "Staging->main review post-dispatch: delivery, test-gate verdict, extract/classify/file-prepare; prints the findings to file"],
+    ["npx forgedock review-staging [<PR>] --summary [--filed <N>]...", "Staging->main review Phase 8: verdict and summary comment with the FORGE:GATE_PASS / FORGE:GATE_FAILURE marker"],
     ["npx forgedock stats [--since <ver|date>] [--repo owner/repo] [--json] [--refresh]", "Version-over-version cost/time/flow/review/gate report from GitHub telemetry (no model)"],
     ["npx forgedock doctor", "Check installation health"],
     ["npx forgedock doctor --fix", "Auto-fix deterministic issues (symlinks, hook, labels, legacy block) and reclaim ForgeDock-owned leftovers (forge.yaml hygiene TTLs)"],
@@ -3868,10 +3873,10 @@ async function watch() {
 // The journey-routed commands render their own branded marks (hero/compact);
 // splash() would double-brand them. Engine-surface commands, help, and
 // unknown-command output keep the logo.
-const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
+const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "probe", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "check", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4081,6 +4086,12 @@ switch (command) {
     }
     break;
   }
+  case "review-staging": {
+    // #4358: deterministic staging->main review pre-dispatch; writes one reviewer brief per roster domain.
+    const { reviewStagingFromCli } = await import("./review-staging.mjs");
+    exitCode = await reviewStagingFromCli(restArgs);
+    break;
+  }
   case "gc": {
     // Reaper (#4180): dry-run report by default; --apply reclaims only ForgeDock-owned resources (ledger, label, lane naming, own tmp).
     const { runGc } = await import("./gc.mjs");
@@ -4098,6 +4109,17 @@ switch (command) {
     }
     break;
   }
+  case "check": {
+    // #4364: the builder's in-session run of the engine's validate and pre-PR checks; local only
+    const { checkFromCli } = await import("./engine-cli.mjs");
+    try {
+      exitCode = (await checkFromCli(restArgs)).exitCode;
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = err.exitCode ?? 1;
+    }
+    break;
+  }
   case "limits": {
     const { limitsFromCli } = await import("./engine-cli.mjs");
     try {
@@ -4139,6 +4161,16 @@ switch (command) {
     }
     break;
   }
+  case "probe": {
+    const { probeFromCli } = await import("./engine-cli.mjs");
+    try {
+      await probeFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "resume-stalled": {
     const { resumeStalledFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/gc.mjs

@@ -223,7 +223,7 @@ export async function planGc({ probes, scopes = new Set(GC_SCOPES), olderThanMs
       const sameHost = j.host === P.host;
       // A live owner on this host is a running lane, even past `expires` (long CI waits refresh it only on register).
       const stale = sameHost ? !(Number.isSafeInteger(j.pid) && P.alive(j.pid)) : Number(j.expires) < now;
-      ledgers.push({ path, batch: j.batch, lane: j.lane, stale });
+      ledgers.push({ path, batch: j.batch, lane: j.lane, repo: j.repo ?? null, stale });
       for (const r of j.resources) {
         const type = TYPE_OF_KIND[r.kind];
         if (!type) continue;
@@ -343,6 +343,9 @@ export async function planGc({ probes, scopes = new Set(GC_SCOPES), olderThanMs
         const id = local ? name : `origin/${name}`;
         if (seen.has(`branch:${id}`) || liveIds.has(`branch:${name}`)) continue;
         const it = { type: "branch", id, branch: name, local, sizeBytes: null, ageMs: age(Number(ts) * 1000), owned: true, action: "report", reason: "" };
+        // #4361: a tracking ref is not origin. Missing on origin = a stale ref, pruned locally (no push, no gh lookups).
+        if (!local && originHeads === null) { it.reason = "cannot verify origin"; add(it); continue; }
+        if (!local && !originHeads.has(name)) { it.gone = true; it.action = "reclaim"; it.reason = "already gone on origin (stale tracking ref)"; add(it); continue; }
         const why = await branchBlock(name, { local });
         if (why) it.reason = why;
         else if (!(it.ageMs >= ttl("branch"))) it.reason = "younger than TTL";
@@ -355,6 +358,12 @@ export async function planGc({ probes, scopes = new Set(GC_SCOPES), olderThanMs
       }
     };
     await scan("refs/heads/", true);
+    // #4361: one ls-remote is the truth about origin; the local tracking refs may hold hundreds of long-deleted branches.
+    let originHeads = null;
+    try {
+      originHeads = new Set();
+      for (const l of String(await git(["ls-remote", "--heads", "origin"])).split("\n")) { const r = l.split("\t")[1]?.trim(); if (r?.startsWith("refs/heads/")) originHeads.add(r.slice(11)); }
+    } catch (e) { originHeads = null; notes.push(`git ls-remote origin failed: ${errText(e)}`); }
     await scan("refs/remotes/origin/", false);
   }
 
@@ -449,14 +458,23 @@ const SANDBOX_TEARDOWN = {
 };
 const defaultSandboxTeardown = (P) => async (provider, handle) => (SANDBOX_TEARDOWN[provider] ? SANDBOX_TEARDOWN[provider](P, handle) : false);
 
-/** Reclaim every owned item marked "reclaim"; release ledger entries that were reclaimed. Never touches anything else. */
-export async function applyGc(plan, probes) {
+/** Remote branch deletes per `git push` (#4361): one round trip per chunk, not per branch. */
+export const GC_PUSH_CHUNK = 50;
+
+/**
+ * Reclaim every owned item marked "reclaim"; release ledger entries that were reclaimed. Never touches anything else.
+ * With a `deadline` (#4361) items not started by then are returned in `deferred` for a later run.
+ */
+export async function applyGc(plan, probes, { deadline = null, now = () => Date.now() } = {}) {
   const P = probes, fs = P.fs ?? nodeFs;
-  const reclaimed = [], failed = [];
+  const reclaimed = [], failed = [], deferred = [], remote = [];
   const git = (args) => P.git(args, { cwd: P.cwd });
+  const late = () => deadline != null && now() >= deadline;
   let prune = false;
   for (const it of plan.items) {
     if (!(it.owned === true && it.action === "reclaim")) continue;
+    if (it.type === "branch" && !it.local) { remote.push(it); continue; }
+    if (late()) { deferred.push(it); continue; }
     try {
       switch (it.type) {
         case "container": await P.docker(["rm", "-f", it.id]); break;
@@ -481,24 +499,37 @@ export async function applyGc(plan, probes) {
           break;
         case "branch":
           if (it.gone) break;
-          if (it.local) await git(["branch", "-D", it.branch]);
-          else await git(["push", "origin", "--delete", it.branch]);
+          await git(["branch", "-D", it.branch]);
           break;
         default: throw new Error(`unknown type ${it.type}`);
       }
       reclaimed.push(it);
       if (it.ledger) {
         const l = plan.ledgers.find((x) => x.path === it.ledger);
-        if (l) { const led = makeLedger({ root: dirname(dirname(l.path)), batch: l.batch, lane: l.lane, fs }); if (led.path === l.path) led.release(it.kind, it.value); }
+        if (l) { const led = makeLedger({ root: dirname(dirname(l.path)), batch: l.batch, lane: l.lane, repo: l.repo, fs }); if (led.path === l.path) led.release(it.kind, it.value); }
       }
     } catch (e) { failed.push({ ...it, error: errText(e) }); }
   }
+  // #4361: stale tracking refs are pruned locally; branches still on origin are deleted GC_PUSH_CHUNK per push. A failed
+  // chunk is retried one branch at a time so each failure stays attributed to its branch.
+  const flush = async (items, cmd) => {
+    for (let i = 0; i < items.length; i += GC_PUSH_CHUNK) {
+      const chunk = items.slice(i, i + GC_PUSH_CHUNK);
+      if (late()) { deferred.push(...chunk); continue; }
+      try { await git(cmd(chunk)); reclaimed.push(...chunk); continue; } catch { /* retry singly */ }
+      for (const it of chunk) {
+        try { await git(cmd([it])); reclaimed.push(it); } catch (e) { failed.push({ ...it, error: errText(e) }); }
+      }
+    }
+  };
+  await flush(remote.filter((it) => it.gone), (c) => ["branch", "-r", "-d", ...c.map((it) => `origin/${it.branch}`)]);
+  await flush(remote.filter((it) => !it.gone), (c) => ["push", "origin", "--delete", ...c.map((it) => it.branch)]);
   if (prune) { try { await git(["worktree", "prune"]); } catch { /* best effort */ } }
   for (const l of plan.ledgers.filter((x) => x.stale)) {
-    const led = makeLedger({ root: dirname(dirname(l.path)), batch: l.batch, lane: l.lane, fs });
+    const led = makeLedger({ root: dirname(dirname(l.path)), batch: l.batch, lane: l.lane, repo: l.repo, fs }); // #4432: repo-keyed file name
     if (led.path === l.path && led.read() && led.entries().length === 0) led.remove();
   }
-  return { reclaimed, failed };
+  return { reclaimed, failed, deferred };
 }
 
 const fmtSize = (b) => (b == null ? "?" : b >= 1073741824 ? `${(b / 1073741824).toFixed(1)}G` : b >= 1048576 ? `${(b / 1048576).toFixed(1)}M` : b >= 1024 ? `${Math.round(b / 1024)}K` : `${b}B`);
@@ -521,7 +552,7 @@ export function formatGcReport(plan, { applied = null } = {}) {
   for (const n of plan.notes) L.push(`  note: ${n}`);
   for (const f of applied?.failed ?? []) L.push(`  failed: ${f.type} ${f.id}: ${f.error}`);
   const n = plan.items.filter((i) => i.owned && i.action === "reclaim").length;
-  L.push(applied ? `gc: reclaimed ${applied.reclaimed.length} of ${n} item(s)` : `gc: ${n} item(s) reclaimable; run with --apply to reclaim`);
+  L.push(applied ? `gc: reclaimed ${applied.reclaimed.length} of ${n} item(s)${applied.deferred?.length ? `, ${applied.deferred.length} deferred` : ""}` : `gc: ${n} item(s) reclaimable; run with --apply to reclaim`);
   return L.join("\n") + "\n";
 }
 
@@ -541,18 +572,20 @@ export async function runGc(argv = [], { probes, hygiene = null, now = Date.now(
 
 /**
  * Plan + apply with forge.yaml hygiene settings (orchestrate preflight/admission GC, #4183). Never throws: a failure
- * becomes a note. Returns {plan, applied, reclaimed, bytes}.
+ * becomes a note. With `budgetMs` (#4361) apply stops at the deadline; the rest is counted in `deferred` for the next run.
+ * Returns {plan, applied, reclaimed, deferred, bytes}.
  */
-export async function runOwnedGc({ probes, hygiene = HYGIENE_DEFAULTS, scopes = new Set(GC_SCOPES), now = Date.now() } = {}) {
-  let plan = null, applied = { reclaimed: [], failed: [] };
+export async function runOwnedGc({ probes, hygiene = HYGIENE_DEFAULTS, scopes = new Set(GC_SCOPES), now = Date.now(), budgetMs = null, clock = () => Date.now() } = {}) {
+  let plan = null, applied = { reclaimed: [], failed: [], deferred: [] };
+  const deadline = Number.isFinite(budgetMs) ? clock() + budgetMs : null;
   try {
     plan = await planGc({ probes, scopes, ttlMs: hygieneTtls(hygiene), deleteMergedBranches: hygiene.delete_merged_branches !== false, now });
-    applied = await applyGc(plan, probes);
+    applied = await applyGc(plan, probes, { deadline, now: clock });
   } catch (e) {
     plan = plan ?? { items: [], summary: {}, notes: [], ledgers: [], scopes: [...scopes], olderThanMs: LEDGER_TTL_MS };
     plan.notes.push(`gc failed: ${errText(e)}`);
   }
-  return { plan, applied, reclaimed: applied.reclaimed.length, bytes: applied.reclaimed.reduce((s, i) => s + (i.sizeBytes ?? 0), 0) };
+  return { plan, applied, reclaimed: applied.reclaimed.length, deferred: applied.deferred?.length ?? 0, bytes: applied.reclaimed.reduce((s, i) => s + (i.sizeBytes ?? 0), 0) };
 }
 
 /**
@@ -569,10 +602,10 @@ export function hygieneCheck(plan, { applied = null, ttlMs = plan?.ttlMs ?? hygi
   const reclaimable = items.filter((i) => i.owned && i.action === "reclaim").length;
   const stale = items.filter((i) => !i.owned && i.ageMs != null && i.ageMs >= (ttlMs?.[i.type] ?? LEDGER_TTL_MS)).length;
   const bits = [`owned: ${parts.length ? parts.join(", ") : "none"}`];
-  if (applied) bits.push(`reclaimed ${applied.reclaimed.length} of ${reclaimable}${applied.failed.length ? ` (${applied.failed.length} failed)` : ""}`);
+  if (applied) bits.push(`reclaimed ${applied.reclaimed.length} of ${reclaimable}${applied.failed.length ? ` (${applied.failed.length} failed)` : ""}${applied.deferred?.length ? ` (${applied.deferred.length} deferred)` : ""}`);
   else bits.push(`${reclaimable} reclaimable`);
   if (stale) bits.push(`${stale} unowned stale (report only)`);
-  const pending = applied ? applied.failed.length : reclaimable;
+  const pending = applied ? applied.failed.length + (applied.deferred?.length ?? 0) : reclaimable;
   const status = pending > 0 || stale > 0 ? "warn" : "pass";
   let detail = bits.join("; ");
   if (!applied && reclaimable > 0) detail += ". Run: npx forgedock doctor --fix  (or: npx forgedock gc --apply)";

package/bin/hooks/reread-nudge.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Re-read nudge (#4456): a Claude CLI PostToolUse hook the lean engine passes to builder sessions with `--settings`
+ * (bin/lean/effects.mjs rereadNudgeFlags). It counts reads per path for one session, using the #4410 telemetry's
+ * definition of a read (toolstats readPaths), and on exactly the REREAD_MIN-th read of a path it returns an
+ * `additionalContext` system reminder. Advisory only: it always exits 0 and an error produces no output.
+ * State: {path: count} in <tmpdir>/forgedock-reread/<session_id>.json (a per-run cache).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readPaths, REREAD_MIN } from "../lean/toolstats.mjs";
+
+/** Paths one hook payload reads, resolved against the payload cwd so `sed -n … a.js` and Read `/abs/a.js` agree. */
+export function payloadReads(payload) {
+  const inp = payload?.tool_input ?? {};
+  const path = inp.file_path ?? inp.path;
+  const u = { name: payload?.tool_name ?? null, path: typeof path === "string" ? path : null, cmd: typeof inp.command === "string" ? inp.command : null };
+  const cwd = typeof payload?.cwd === "string" && payload.cwd ? payload.cwd : null;
+  return [...new Set(readPaths(u).map((p) => (cwd ? resolve(cwd, p) : p)))];
+}
+
+/** Pure core: counts after this payload and the reminder to emit (null when no path just reached REREAD_MIN). */
+export function nudgeFor(payload, counts = {}) {
+  const next = { ...counts }, hot = [];
+  for (const p of payloadReads(payload)) {
+    next[p] = (next[p] ?? 0) + 1;
+    if (next[p] === REREAD_MIN) hot.push(p);
+  }
+  const message = hot.length ? `${hot.join(", ")} ${hot.length > 1 ? "have" : "has"} now been read ${REREAD_MIN} times in this session: `
+    + "use your notes or the excerpt already in context; if you need a different part, read only that line range." : null;
+  return { counts: next, message };
+}
+
+export const stateFile = (sessionId, dir = join(tmpdir(), "forgedock-reread")) =>
+  join(dir, `${String(sessionId).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "session"}.json`);
+
+/** One hook call: stdin JSON in, the hookSpecificOutput line (or nothing) out. Fails open. */
+export function main(input, { dir } = {}) {
+  try {
+    const payload = JSON.parse(input);
+    if (!payload?.session_id) return "";
+    if (!payloadReads(payload).length) return "";
+    const file = stateFile(payload.session_id, dir);
+    let counts = {};
+    try { counts = JSON.parse(readFileSync(file, "utf8")) ?? {}; } catch { /* first read of this session */ }
+    const r = nudgeFor(payload, counts);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(r.counts));
+    return r.message ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: r.message } })}\n` : "";
+  } catch {
+    return "";
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+  process.stdin.on("end", () => { process.stdout.write(main(input)); process.exitCode = 0; });
+  process.stdin.on("error", () => { process.exitCode = 0; });
+}

package/bin/labels.json

@@ -74,6 +74,11 @@
     "color": "B60205",
     "description": "Pipeline stalled — engine/tool failure (not a genuine human-judgment block). Managed by ForgeDock."
   },
+  {
+    "name": "awaiting-promotion",
+    "color": "C5DEF5",
+    "description": "Post-deploy follow-up parked until its parent fix reaches the default branch. Managed by ForgeDock."
+  },
   {
     "name": "blocked-on-human-merge",
     "color": "006B75",