forgedock 1.35.0 → 1.37.0

package/bin/engine.mjs

@@ -506,12 +506,14 @@ export async function runIssue(opts) {
   // declaration or an untrusted body proceeds. An unreadable body/dependency fails closed.
   {
     let dep = null;
-    try { dep = await openDependency(issue, io); } catch (e) {
+    try { dep = await openDependency(issue, io, { lane }); } catch (e) {
       dep = { unreadable: true, detail: `issue ${issue} **Depends on** check failed: ${e?.message || e}` };
     }
     if (dep?.unreadable) {
       return { terminalReason: "dependency-unreadable", code: OUTCOME_CODES.DEPENDENCY_UNREADABLE, detail: dep.detail };
     }
+    // #4686: an open dependency whose PR is already on this lane is satisfied; name the merge commit.
+    for (const x of dep?.satisfied ?? []) emitProgress({ event: "dependency_satisfied", detail: `#${x.issue} merged into ${lane} by PR #${x.pr} (merge commit ${x.sha.slice(0, 12)})` });
     if (dep?.open?.length) {
       return {
         terminalReason: "dependency-open",

package/bin/experiment.mjs

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4629: live A/B experiments. forge.yaml `experiment:` section (flat keys, the parser has one nesting level):
+ *   id: light-vs-full          arms: light,full         ratio: 1,1 (weights, default equal)
+ *   metrics: usd_median,wall_p50_ms,first_pass_rate,needs_human_rate (default all)
+ *   targets: light.usd_median<=1.2xfull,light.first_pass_rate>=0.8   min_n: 10
+ * The arm is a hash of (id, issue), so a re-run or resume keeps its arm. Pure; the stats report is bin/stats/experiment.mjs.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseForgeYaml } from "./forge-utils.mjs";
+
+export const EXPERIMENT_METRICS = ["usd_median", "wall_p50_ms", "first_pass_rate", "needs_human_rate"];
+export const BENCH_SCHEMA = "forge.bench.v1";
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TARGET = /^([A-Za-z0-9][A-Za-z0-9._-]*)\.([a-z_0-9]+)(<=|>=)(\d+(?:\.\d+)?)(?:x([A-Za-z0-9][A-Za-z0-9._-]*))?$/;
+const list = (v) => String(v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+
+/** Parsed declaration {id, arms, ratio, metrics, targets, minN}, or null when absent or invalid. */
+export function parseExperiment(sec, { defaultMinN = 10 } = {}) {
+  if (!sec || typeof sec !== "object") return null;
+  const id = String(sec.id ?? "").trim(), arms = list(sec.arms);
+  if (!NAME.test(id) || arms.length < 2 || new Set(arms).size !== arms.length || !arms.every((a) => NAME.test(a))) return null;
+  const ratio = sec.ratio == null || sec.ratio === "" ? arms.map(() => 1) : list(sec.ratio).map((x) => (/^[1-9]\d*$/.test(x) ? Number(x) : NaN));
+  if (ratio.length !== arms.length || ratio.some(Number.isNaN)) return null;
+  const metrics = sec.metrics ? list(sec.metrics) : [...EXPERIMENT_METRICS];
+  if (!metrics.length || metrics.some((m) => !EXPERIMENT_METRICS.includes(m))) return null;
+  const targets = [];
+  for (const t of list(sec.targets)) {
+    const m = TARGET.exec(t);
+    if (!m || !arms.includes(m[1]) || !metrics.includes(m[2]) || (m[5] && !arms.includes(m[5]))) return null;
+    targets.push({ arm: m[1], metric: m[2], op: m[3], limit: Number(m[4]), vs: m[5] ?? null, text: t });
+  }
+  const mn = String(sec.min_n ?? "").trim();
+  if (mn && !/^\d+$/.test(mn)) return null;
+  return { id, arms, ratio, metrics, targets, minN: mn ? Number(mn) : defaultMinN };
+}
+
+/** forge.yaml `experiment:` of `cwd`, or null. */
+export function readExperiment(cwd = process.cwd()) {
+  try { return parseExperiment(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.experiment); } catch { return null; }
+}
+
+/** Deterministic arm of an issue: sha1(id:issue) mod the ratio total, walked over the arms in declared order. */
+export function assignArm(exp, issue) {
+  const total = exp.ratio.reduce((a, b) => a + b, 0);
+  let pick = createHash("sha1").update(`${exp.id}:${issue}`).digest().readUInt32BE(0) % total;
+  for (let i = 0; i < exp.arms.length; i++) { if (pick < exp.ratio[i]) return exp.arms[i]; pick -= exp.ratio[i]; }
+  return exp.arms[0];
+}
+
+/** The shared result record of the bench harness, the eval gate and `stats --experiment`: targets are {pass: true|false|null, value, limit}. */
+export const benchRecord = ({ source, arms = {}, targets = {} }) => ({ schema: BENCH_SCHEMA, source, arms, targets });

package/bin/forgedock.mjs

@@ -86,6 +86,8 @@ import {
   CYAN,
 } from "./tui.mjs";
 import { buildMinimalForgeYaml } from "./init-detect.mjs";
+import { checkContext, refreshContextFlow } from "./review-context.mjs";
+import { botTokenStatus } from "./bot-token-status.mjs";
 import {
   parseNameStatusDiff,
   classifyCommandChanges,
@@ -234,7 +236,7 @@ const SCRIPTS_DIR = join(FORGE_HOME, "scripts");
 // --minimal is init-only. Subcommands with their own flag parsing (run,
 // run-issue, demo) receive restArgs — everything after the command token.
 const rawArgs = process.argv.slice(2);
-const FLAGS = new Set(["--fast", "--manual", "--verbose", "--minimal", "--extras"]);
+const FLAGS = new Set(["--fast", "--manual", "--verbose", "--minimal", "--extras", "--refresh-context"]);
 const flags = rawArgs.filter((a) => FLAGS.has(a));
 // --global is stripped from positionals/restArgs for backward compatibility
 // with existing invocations, but is otherwise a no-op — see the install-mode
@@ -1042,6 +1044,13 @@ function ensureToolStateIgnored(c) {
 
 async function initFlow(c) {
   const outputPath = join(c.cwd, "forge.yaml");
+  if (flags.includes("--refresh-context")) {
+    return refreshContextFlow({
+      cwd: c.cwd,
+      out: c.stdout,
+      deps: { interactive: process.stdin.isTTY === true, confirm, backup: backupExisting, write: atomicWriteFile },
+    });
+  }
   const hasExisting = existsSync(outputPath);
   if (hasExisting && process.stdin.isTTY !== true) {
     const dim = (s) => (c.mode === "none" ? s : `\x1b[2m${s}\x1b[22m`);
@@ -2704,6 +2713,15 @@ async function doctor(fix = false) {
             );
           }
 
+          try {
+            const ctxCheck = checkContext({ configPath: forgeYamlPath, root: process.cwd(), repo: forgeOwner && forgeRepo ? `${forgeOwner}/${forgeRepo}` : "" });
+            if (ctxCheck.stale) {
+              warn("review context", `REVIEW_CONTEXT_STALE: ${ctxCheck.reasons.map((r) => r.detail).join("; ")}. Run: npx forgedock init --refresh-context`);
+            } else if (ctxCheck.advisory) {
+              warn("review context", `REVIEW_CONTEXT_STALE: generated ${ctxCheck.generated_at}, ${ctxCheck.merged_since} PRs merged since (limit ${ctxCheck.max_merged_prs}). Run: npx forgedock init --refresh-context`);
+            }
+          } catch { /* advisory check: never fail doctor */ }
+
           const defaultMatch = content.match(/^\s+default:\s+"([^"]*)"/m);
           const stagingMatch = content.match(/^\s+staging:\s+"([^"]*)"/m);
           if (
@@ -3243,14 +3261,20 @@ async function doctor(fix = false) {
   }
 
   // ── Check 12: GitHub App / bot token status ─────────────────────────────────
-  // Informational only — never a hard failure. Installing the ForgeDock GitHub
+  // Informational without a refresh stamp (#4662: with one, a stale or expiring token fails). Installing the ForgeDock GitHub
   // App registers it against the account/org but does not, by itself, mint a
   // bot token: that requires the app's private key, which only the app owner
   // holds. Pipeline gh calls always use whatever `gh auth` context is active
   // locally (personal token unless the operator manually configured a bot
   // token) — this check exists so that state is surfaced instead of silent.
   // See docs/CONFIG.md "GitHub App Install" and forge#1890.
-  {
+  const botTok = botTokenStatus(); // #4662: lifetime from the refresh stamp; no stamp means no refresher is installed
+  if (botTok.configured) {
+    const min = (ms) => Math.round(ms / 60000);
+    const detail = botTok.remainingMs != null ? `${min(botTok.remainingMs)} min left, refreshed ${min(botTok.ageMs)} min ago (${botTok.refreshedAt})` : botTok.reason;
+    if (botTok.ok) pass("GitHub App / bot token", detail);
+    else fail(`GitHub App / bot token: ${botTok.reason} (${detail})`, "run scripts/refresh-bot-token.sh and install the timer: docs/CONFIG.md \"Bot token refresh\"");
+  } else {
     warn(
       "GitHub App / bot token",
       "pipeline commands use your active `gh auth` (personal token, unless you've manually configured a bot token). Installing the GitHub App alone does not create one — see docs/CONFIG.md \"GitHub App Install\".",
@@ -3277,6 +3301,19 @@ async function doctor(fix = false) {
     }
   }
 
+  // ── Check 14: Router/schedd restarts (#4673) ───────────────────────────────
+  // A restart in the last hour usually means an OOM killer or SIGTERM took the coordinator and dropped in-flight lanes. Warn only.
+  {
+    try {
+      const { restartCheck } = await import("./pool/health.mjs");
+      for (const unit of ["computeshare-router", "forgedock-schedd"]) {
+        const r = restartCheck({ unit });
+        if (r.status === "warn") warn(`Restarts: ${unit}`, r.detail);
+        else if (r.status === "pass") pass(`Restarts: ${unit}`, r.detail);
+      }
+    } catch { /* no systemd here: nothing to report */ }
+  }
+
   // ── Summary ────────────────────────────────────────────────────────────────
   console.log("");
   if (fix && fixesApplied > 0) {
@@ -3314,12 +3351,16 @@ function help() {
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
     ["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 plan validate --live [--repo owner/repo] [--json]", "Re-run the bootstrap dependency-order rules on live GitHub state: each cross-milestone Depends-on edge is ok, held or invalid (exit 1 on invalid)"],
     ["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> [N...] | --set-parallel <id> K | --add <id> N... | --cancel <id> | --hold <id> N... | --release <id> N...", "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), or hold/release single issues of a batch (a held issue is not admitted until released or named by --resume)"],
+    ["npx forgedock orchestrate --resume <id> [N...] | --set-parallel <id> K | --add <id> N... | --requeue <id> N... [--reason \"...\"] | --cancel <id> | --hold <id> N... | --release <id> N... | --show-env <id> | --set-env <id> KEY=VAL | --unset-env <id> KEY", "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, requeue a terminal issue (and the dependents skipped behind it) after an operator decision (refused while it is labelled needs-human or closed; a finished batch is reopened), or stop one batch without stopping schedd (running lanes torn down with their work saved, the rest held for --resume), or hold/release single issues of a batch (a held issue is not admitted until released or named by --resume), or print (secrets redacted), set or unset a batch's pinned lane env (applies to newly launched lanes)"],
     ["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 milestone train <slug...> [--parallel-milestones N] | --resume <id> | --insert <id> <slug> [--before s|--after s] | --show <id>", "Unattended multi-milestone train: one durable state file (order, active set, lifecycle), typed STOP reasons, resumable; never edits forge.yaml"],
+    ["npx forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]", "Fix guards: list the FORGE:GUARD records (test files + protected hunks of merged fixes) covering a path, or build them for already-merged lean lanes"],
     ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
+    ["npx forgedock decisions list [--stale] [--refresh]", "List anchored decisions (FORGE:DECISION); --stale shows those with an anchor missing on the base"],
     ["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"],
     ["npx forgedock pool router [install] | enroll [--cpus N --mem GB] | status | upgrade [agent] | remove <agent>", "Built-in remote compute pool: run the router (foreground, or install it as a user service), print the one-time install command for a host, list agents, upgrade or remove them"],
@@ -3350,6 +3391,7 @@ function help() {
     ["--manual", "Plain text prompts instead of the review screen (init)"],
     ["--verbose", "Show detection sources for every field (init)"],
     ["--minimal", "Generate a minimal forge.yaml with required sections only (init)"],
+    ["--refresh-context", "Regenerate review.context/tech_stack from manifests and show a diff for approval (init)"],
     ["--version, -v", "Print the installed version and check for updates"],
   ];
 
@@ -3903,7 +3945,7 @@ async function watch() {
 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", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "pool", "check", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4060,6 +4102,12 @@ switch (command) {
   case "run":
     await run();
     break;
+  case "plan": {
+    // #4659: bootstrap-validate's dependency rules on live GitHub state
+    const { runLive } = await import("../scripts/plan-validate-live.mjs");
+    exitCode = await runLive(restArgs);
+    break;
+  }
   case "bootstrap": {
     // #4177: headless /bootstrap; --plan runs scripts/bootstrap-create.mjs directly (no LLM), a re-run resumes.
     const { runBootstrap } = await import("./bootstrap.mjs");
@@ -4136,6 +4184,17 @@ switch (command) {
     }
     break;
   }
+  case "decisions": {
+    // #4695: anchored decisions of the local index
+    const { decisionsFromCli } = await import("./engine-cli.mjs");
+    try {
+      await decisionsFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    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");
@@ -4199,6 +4258,50 @@ switch (command) {
     }
     break;
   }
+  case "milestone-sync": {
+    // On-demand milestone branch sync (#4663): PR + auto-merge under protected branches, one debounced sync PR.
+    const { milestoneSyncFromCli } = await import("./engine-cli.mjs");
+    try {
+      exitCode = await milestoneSyncFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
+  case "milestone": {
+    // Native unattended milestone train (#4658): `forgedock milestone train <slug...>`.
+    const { trainFromCli } = await import("./engine-cli.mjs");
+    try {
+      if (restArgs[0] !== "train") throw new Error("usage: forgedock milestone train <slug...> [--parallel-milestones N] | --resume <id> | --insert <id> <slug> | --show <id>");
+      const result = await trainFromCli(restArgs.slice(1));
+      if (result && !result.ok) exitCode = 1;
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
+  case "guards": {
+    // Fix guards (#4692): `forgedock guards list [--path p]` | `guards backfill --since <date>`.
+    const { guardsFromCli } = await import("./engine-cli.mjs");
+    try { exitCode = await guardsFromCli(restArgs); } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
+  case "integration": {
+    // Milestone integration runs (#4667): `forgedock integration run` for cron or a scheduled workflow.
+    const { integrationFromCli } = await import("./engine-cli.mjs");
+    try {
+      exitCode = await integrationFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "probe": {
     const { probeFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/hooks/reread-nudge.mjs

@@ -9,6 +9,8 @@
  * #4580: the same script is also a PreToolUse guard on Read: a full-file Read (no offset/limit) of a path already read
  * REREAD_MIN-1 times whose mtime is unchanged since its last read is denied with a reason that points at notes or a line
  * range. Ranged reads and Bash never deny, and any error allows. A changed mtime resets the path's count.
+ * #4622: the guard counts only full-file Reads ({path: count} in <session_id>.full.json), so ranged Reads and Bash samples never
+ * make a first full Read look like a re-read; the nudge still counts every read.
  * State: {path: count} in <tmpdir>/forgedock-reread/<session_id>.json plus {path: mtimeMs} in <session_id>.mtime.json (per-run caches).
  */
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -44,7 +46,13 @@ export const stateFile = (sessionId, dir = join(tmpdir(), "forgedock-reread")) =
 const mtimeOf = (p) => { try { return statSync(p).mtimeMs; } catch { return null; } };
 const loadJson = (file) => { try { const v = JSON.parse(readFileSync(file, "utf8")); return v && typeof v === "object" ? v : {}; } catch { return {}; } };
 
-/** Pure core of the guard: the deny reason for a payload, or null. `mtimeNow(path)` is the file's current mtime. */
+/** Paths a payload reads whole: a Read with no offset/limit (what the guard counts, #4622). */
+export function fullReads(payload) {
+  const inp = payload?.tool_input ?? {};
+  return payload?.tool_name === "Read" && inp.offset == null && inp.limit == null ? payloadReads(payload) : [];
+}
+
+/** Pure core of the guard: the deny reason for a payload, or null. `counts` are full-read counts; `mtimeNow(path)` is the file's current mtime. */
 export function guardFor(payload, counts = {}, mtimes = {}, mtimeNow = mtimeOf) {
   const inp = payload?.tool_input ?? {};
   if (payload?.tool_name !== "Read" || inp.offset != null || inp.limit != null) return null;
@@ -64,20 +72,23 @@ export function main(input, { dir } = {}) {
     if (!payload?.session_id) return "";
     if (!payloadReads(payload).length) return "";
     const file = stateFile(payload.session_id, dir), mfile = file.replace(/\.json$/, ".mtime.json");
-    const counts = loadJson(file), mtimes = loadJson(mfile);
+    const ffile = file.replace(/\.json$/, ".full.json");
+    const counts = loadJson(file), mtimes = loadJson(mfile), full = loadJson(ffile);
     if (payload.hook_event_name === "PreToolUse") {
-      const reason = guardFor(payload, counts, mtimes);
+      const reason = guardFor(payload, full, mtimes);
       return reason ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } })}\n` : "";
     }
     for (const p of payloadReads(payload)) {
       const now = mtimeOf(p);
-      if (now != null && mtimes[p] !== now) delete counts[p]; // the file changed (or is new): earlier reads no longer count
+      if (now != null && mtimes[p] !== now) { delete counts[p]; delete full[p]; } // the file changed (or is new): earlier reads no longer count
       if (now != null) mtimes[p] = now;
     }
+    for (const p of fullReads(payload)) full[p] = (full[p] ?? 0) + 1;
     const r = nudgeFor(payload, counts);
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(r.counts));
     writeFileSync(mfile, JSON.stringify(mtimes));
+    writeFileSync(ffile, JSON.stringify(full));
     return r.message ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: r.message } })}\n` : "";
   } catch {
     return "";

package/bin/labels.json

@@ -69,11 +69,31 @@
     "color": "E4E669",
     "description": "Pipeline stalled — requires human intervention. Managed by ForgeDock."
   },
+  {
+    "name": "needs-human:external",
+    "color": "E4E669",
+    "description": "Waiting on an external prerequisite (credential, account, sign-off). Comment names the owner and unblock condition. Managed by ForgeDock."
+  },
+  {
+    "name": "parked",
+    "color": "FBCA04",
+    "description": "Mechanical park on a terminal code; per-code labels are parked:<code>. Managed by ForgeDock."
+  },
+  {
+    "name": "remediation-queue",
+    "color": "FBCA04",
+    "description": "Parked issue awaiting /work-on:remediate. Managed by ForgeDock."
+  },
   {
     "name": "workflow:engine-error",
     "color": "B60205",
     "description": "Pipeline stalled — engine/tool failure (not a genuine human-judgment block). Managed by ForgeDock."
   },
+  {
+    "name": "awaiting-due",
+    "color": "C5DEF5",
+    "description": "Post-deploy follow-up parked until its due date; re-queued by the engine. Managed by ForgeDock."
+  },
   {
     "name": "awaiting-promotion",
     "color": "C5DEF5",
@@ -183,5 +203,35 @@
     "name": "performance",
     "color": "F9D0C4",
     "description": "Performance optimization or regression. Managed by ForgeDock."
+  },
+  {
+    "name": "integration-red",
+    "color": "D93F0B",
+    "description": "Scheduled full-suite integration run on a milestone branch is red. Managed by ForgeDock."
+  },
+  {
+    "name": "followup:engineering",
+    "color": "BFD4F2",
+    "description": "Deferred buildable engineering work. Managed by ForgeDock."
+  },
+  {
+    "name": "followup:post-deploy",
+    "color": "BFD4F2",
+    "description": "Deferred post-deploy checks. Managed by ForgeDock."
+  },
+  {
+    "name": "followup:external",
+    "color": "BFD4F2",
+    "description": "Deferred items blocked on something outside the repo (credentials, third parties). Managed by ForgeDock."
+  },
+  {
+    "name": "followup:ops",
+    "color": "BFD4F2",
+    "description": "Deferred ops work (drills, runbooks). Managed by ForgeDock."
+  },
+  {
+    "name": "external-prerequisite",
+    "color": "E99695",
+    "description": "Follow-up that waits on an external prerequisite. Managed by ForgeDock."
   }
 ]

package/bin/lean/batch.mjs

@@ -6,6 +6,7 @@
  * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
  * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K),
  * `add` (issues added to the batch by `--add`, #4408: a cumulative JSON set the runner re-reads every pass),
+ * `requeue` (`--requeue`, #4550: a cumulative JSON list of `{issue, reason, by, at}` the runner applies once each, moving a terminal issue back to pending),
  * `hold` (issues held by `--hold`, #4592: a cumulative JSON set; the runner admits none of them until `--release` or a `--resume` names them),
  * `cancel` (`{at, reason}` written by `--cancel`, #4376: the runner stops admitting and stops its local lanes; a resume clears it),
  * `lanes/<issue>.{json,log}` (each lane's result and output) and `report.json` (the final rows and printed report, written
@@ -69,6 +70,16 @@ const readAdded = (file) => {
   return Array.isArray(v) ? [...new Set(v.filter((n) => Number.isSafeInteger(n) && n > 0))].sort((a, b) => a - b) : [];
 };
 
+/** `outcome`s `--requeue` may move back to pending (#4550). */
+export const REQUEUABLE = (outcome) => ["needs-human", "invalid", "skipped", "ci-pending", "budget-exceeded"].includes(outcome) || /^dependency-/.test(String(outcome));
+/** Key of one requeue entry; the runner records the applied keys in state.json `requeueApplied`. */
+export const requeueKey = (e) => `${e.issue}@${e.at}`;
+
+const readRequeueFile = (file) => {
+  const v = readJson(file);
+  return Array.isArray(v) ? v.filter((e) => e && Number.isSafeInteger(e.issue) && e.issue > 0 && typeof e.at === "string") : [];
+};
+
 /** The positive integers among `list` (numbers, `7`, `#7`). */
 const ints = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN)).filter((n) => Number.isSafeInteger(n) && n > 0);
 
@@ -88,7 +99,7 @@ export function openBatch(root, id) {
   if (!ID_RE.test(String(id ?? ""))) throw new Error(`invalid batch id ${JSON.stringify(id)}`);
   const dir = join(root, id);
   const f = (name) => join(dir, name);
-  return {
+  const self = {
     id, dir,
     exists: () => existsSync(f("plan.json")),
     readPlan: () => readJson(f("plan.json")),
@@ -111,19 +122,53 @@ export function openBatch(root, id) {
      * `order`, in the file or earlier in `list`: skipped `already in batch`. @returns {{added:number[], skipped:Array<{issue, reason}>}}
      */
     addIssues: (list) => {
-      const have = new Set([...(readJson(f("state.json"))?.order ?? []), ...readAdded(f("add"))]);
-      const added = [], skipped = [];
+      const st = readJson(f("state.json")) ?? {};
+      const have = new Set([...(st.order ?? []), ...readAdded(f("add"))]);
+      const added = [], skipped = [], requeued = [];
       for (const x of Array.isArray(list) ? list : []) {
         const n = typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN;
         if (!Number.isSafeInteger(n) || n < 1) { skipped.push({ issue: x, reason: "not an integer" }); continue; }
+        // #4687: an issue skipped in the batch (a dependency ended) is re-queued, not refused; any other row is "already in batch"
+        if (have.has(n) && st.results?.[n]?.outcome === "skipped" && !requeued.includes(n) && self.requeue([n], { reason: "--add", by: "operator" }).requeued.length) { requeued.push(n); continue; }
         if (have.has(n)) { skipped.push({ issue: n, reason: "already in batch" }); continue; }
         have.add(n); added.push(n);
       }
       if (added.length) writeAtomic(f("add"), JSON.stringify([...new Set([...readAdded(f("add")), ...added])].sort((a, b) => a - b)) + "\n");
-      return { added, skipped };
+      return { added, skipped, requeued };
+    },
+    /**
+     * `--requeue` (#4550): record that each issue returns to pending. Refused: not a positive integer, not in the batch's
+     * `order`, no terminal result yet (`not terminal`), or already requeued and not yet applied. The needs-human label and
+     * closed checks need GitHub and live in the CLI. @returns {{requeued:number[], refused:Array<{issue, reason}>}}
+     */
+    requeue: (list, { reason = "operator decision", by = "operator" } = {}) => {
+      const st = readJson(f("state.json")) ?? {};
+      const order = new Set(st.order ?? []), applied = new Set(st.requeueApplied ?? []);
+      const entries = readRequeueFile(f("requeue"));
+      const pend = new Set(entries.filter((e) => !applied.has(requeueKey(e))).map((e) => e.issue));
+      const requeued = [], refused = [];
+      for (const x of Array.isArray(list) ? list : []) {
+        const n = typeof x === "number" ? x : typeof x === "string" && /^#?\d+$/.test(x.trim()) ? parseInt(x.trim().replace("#", ""), 10) : NaN;
+        if (!Number.isSafeInteger(n) || n < 1) refused.push({ issue: x, reason: "not an integer" });
+        else if (!order.has(n)) refused.push({ issue: n, reason: "not in batch" });
+        else if (pend.has(n)) refused.push({ issue: n, reason: "already requeued" });
+        else if (!REQUEUABLE(st.results?.[n]?.outcome)) refused.push({ issue: n, reason: "not terminal" });
+        else { pend.add(n); requeued.push(n); }
+      }
+      if (requeued.length) {
+        const at = new Date().toISOString();
+        writeAtomic(f("requeue"), JSON.stringify([...entries, ...requeued.map((issue) => ({ issue, reason: String(reason), by: String(by), at }))]) + "\n");
+      }
+      return { requeued, refused };
     },
+    /** Every `--requeue` entry, in order; [] when missing or invalid. */
+    readRequeued: () => readRequeueFile(f("requeue")),
+    /** Entries the runner has not applied yet (a finished or unhosted batch with a pending requeue). */
+    unrunRequeues: () => { const done = new Set(readJson(f("state.json"))?.requeueApplied ?? []); return readRequeueFile(f("requeue")).filter((e) => !done.has(requeueKey(e))); },
     /** Issues held by `--hold` (#4592): the `hold` file, sorted unique positive integers; [] when missing or invalid. */
     readHeld: () => readAdded(f("hold")),
+    /** #4656: gates waiting on issues (`gates` file: [{ name, waitsOn: [n...], since? }], written by the ship/settle pre-flight); [] when missing or invalid. */
+    readGates: () => { const v = readJson(f("gates")); return Array.isArray(v) ? v.filter((g) => g && typeof g.name === "string" && Array.isArray(g.waitsOn)) : []; },
     /** Merge the positive integers of `list` into the `hold` file. @returns {number[]} the issues newly held */
     holdIssues: (list) => {
       const have = new Set(readAdded(f("hold")));
@@ -138,8 +183,8 @@ export function openBatch(root, id) {
       if (freed.length) writeAtomic(f("hold"), JSON.stringify([...have].filter((n) => !freed.includes(n)).sort((a, b) => a - b)) + "\n");
       return freed;
     },
-    /** `--cancel` (#4376): `{at, reason}` in the `cancel` file; the runner re-reads it every pass. */
-    requestCancel: ({ reason = "operator" } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason) }) + "\n"),
+    /** `--cancel` (#4376): `{at, reason, stopRemote?}` in the `cancel` file; the runner re-reads it every pass. `stopRemote` (#4612) also asks remote lanes to stop at their checkpoint. */
+    requestCancel: ({ reason = "operator", stopRemote = false } = {}) => writeAtomic(f("cancel"), JSON.stringify({ at: new Date().toISOString(), reason: String(reason), ...(stopRemote === true ? { stopRemote: true } : {}) }) + "\n"),
     /** The cancel record, or null when missing or invalid. */
     readCancel: () => { const v = readJson(f("cancel")); return v && typeof v === "object" && !Array.isArray(v) && typeof v.at === "string" ? v : null; },
     clearCancel: () => rmSync(f("cancel"), { force: true }),
@@ -157,6 +202,7 @@ export function openBatch(root, id) {
     resultFile: (n) => f(join("lanes", `${n}.json`)),
     logFile: (n) => f(join("lanes", `${n}.log`)),
   };
+  return self;
 }
 
 /** True when `pid` is alive and (where /proc exists) its command line names `marker`, so a reused pid is not adopted. */