forgedock 1.42.0 → 1.43.0

package/bin/lean/schedd.test.mjs

@@ -8,11 +8,11 @@ import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { openBatch, isLaneAlive, listBatches, SECRET_ENV } from "./batch.mjs";
-import { startDaemon, scheddPaths, connectDaemon, request, SCHEDD_SCRIPT, mergeEnv, batchEnv, droppedEnv, sanitizePath, redactEnv, exitOnSignals } from "./schedd.mjs";
+import { startDaemon, scheddPaths, connectDaemon, request, unitState, SCHEDD_SCRIPT, mergeEnv, batchEnv, droppedEnv, sanitizePath, redactEnv, exitOnSignals } from "./schedd.mjs";
 import { schedDir } from "./sched.mjs";
 import { readHeartbeat } from "./schedd-health.mjs";
 import { formatTable, orchestrate } from "./orchestrate.mjs";
-import { orchestrateFromCli } from "../engine-cli.mjs";
+import { orchestrateFromCli, scheddFromCli } from "../engine-cli.mjs";
 
 // #4503: this process, and the env its clients submit for their lanes, never resolve the host's `~/.forge/sched`.
 process.env.FORGEDOCK_SCHED_DIR = tmpDir("schedd-home-");
@@ -637,6 +637,96 @@ describe("schedd due timer (#4627)", () => {
   });
 });
 
+// #4775: a client never races a systemd-managed daemon; a stalled daemon is visible and bounded.
+describe("schedd under load and restart (#4775)", () => {
+  const noSleep = () => Promise.resolve();
+  it("connectDaemon never spawns while the unit is active or activating, and starts an installed stopped unit instead of spawning", async () => {
+    for (const state of ["active", "activating", "reloading"]) {
+      let spawned = 0;
+      await assert.rejects(connectDaemon({ dir: tmpDir("schedd-unit-"), waitMs: 0, sleep: noSleep, spawnDaemon: () => { spawned++; }, unit: () => state, start: () => { spawned++; } }), /did not start/);
+      assert.equal(spawned, 0, `${state}: nothing is started`);
+    }
+    const calls = [];
+    await assert.rejects(connectDaemon({ dir: tmpDir("schedd-unit-"), waitMs: 0, sleep: noSleep, spawnDaemon: () => calls.push("spawn"), unit: () => "inactive", start: () => calls.push("unit") }), /did not start/);
+    assert.deepEqual(calls, ["unit"]);
+  });
+
+  it("connectDaemon spawns the daemon itself only when no unit is installed; spawnDaemon:null starts nothing", async () => {
+    const calls = [];
+    await assert.rejects(connectDaemon({ dir: tmpDir("schedd-unit-"), waitMs: 0, sleep: noSleep, spawnDaemon: () => calls.push("spawn"), unit: () => null, start: () => calls.push("unit") }), /did not start/);
+    assert.deepEqual(calls, ["spawn"]);
+    await assert.rejects(connectDaemon({ dir: tmpDir("schedd-unit-"), spawnDaemon: null, unit: () => { throw new Error("not consulted"); } }), { code: "ENOENT" });
+  });
+
+  it("unitState reads the systemctl state (also from a non-zero exit) and is null without a unit file", () => {
+    assert.equal(unitState({ exists: () => false }), null);
+    assert.equal(unitState({ exists: () => true, run: () => "activating\n" }), "activating");
+    assert.equal(unitState({ exists: () => true, run: () => { throw Object.assign(new Error("exit 3"), { stdout: "inactive\n" }); } }), "inactive");
+    assert.equal(unitState({ exists: () => true, run: () => { throw Object.assign(new Error("none"), { code: "ENOENT" }); } }), null);
+  });
+
+  it("request(timeoutMs) rejects a daemon that never answers instead of hanging", async () => {
+    const dir = tmpDir("schedd-mute-"), sock = scheddPaths(dir).sock;
+    const server = (await import("node:net")).createServer(() => { /* accepts, never answers */ });
+    await new Promise((r) => server.listen(sock, r));
+    try {
+      const c = await connectDaemon({ dir, spawnDaemon: null });
+      await assert.rejects(request(c, { op: "status" }, undefined, { timeoutMs: 80 }), { code: "schedd.timeout" });
+    } finally { server.close(); }
+  });
+
+  it("status reports per-batch last-progress age and pending adds, including an unhosted batch with un-admitted adds", async () => {
+    const root = tmpDir("schedd-st-b-"), dir = tmpDir("schedd-st-");
+    const mk = (id, files) => { mkdirSync(join(root, id), { recursive: true }); writeFileSync(join(root, id, "plan.json"), JSON.stringify({ daemon: true })); for (const [n, t] of Object.entries(files)) writeFileSync(join(root, id, n), t); };
+    mk("b-stuck", { "state.json": JSON.stringify({ order: [1] }), add: "[7,8]" });
+    mk("b-quiet", { "state.json": JSON.stringify({ order: [1] }) });
+    const d = await startDaemon({ dir, root, runBatch: async () => ({}), resumeOnStart: false, log: () => {} });
+    try {
+      const st = await request(await connectDaemon({ dir, spawnDaemon: null }), { op: "status" });
+      assert.equal(st.batches.length, 1, "a quiet unhosted batch is not listed");
+      const [b] = st.batches;
+      assert.equal(b.id, "b-stuck");
+      assert.equal(b.running, false);
+      assert.deepEqual(b.pendingAdds, [7, 8]);
+      assert.ok(b.lastProgressAgeSec >= 0 && b.lastProgressAgeSec < 60);
+    } finally { await d.close(); }
+  });
+
+  it("a batch whose start stalls does not block another batch's request, and the stalled request answers an error", async () => {
+    const root = tmpDir("schedd-stall-b-"), dir = tmpDir("schedd-stall-");
+    for (const id of ["b-hung", "b-ok"]) { mkdirSync(join(root, id), { recursive: true }); writeFileSync(join(root, id, "plan.json"), JSON.stringify({ daemon: true })); writeFileSync(join(root, id, "state.json"), JSON.stringify({ order: [1] })); }
+    const d = await startDaemon({ dir, root, resumeOnStart: false, admitMs: 150, log: () => {},
+      runBatch: ({ argv, sink }) => (argv[1] === "b-hung" ? new Promise(() => {}) : Promise.resolve().then(() => { sink.batch({ id: argv[1], dir: join(root, argv[1]) }); return {}; })) });
+    try {
+      const ask = async (id) => request(await connectDaemon({ dir, spawnDaemon: null }), { op: "attach", id }).catch((e) => e);
+      const hung = ask("b-hung");
+      const ok = await ask("b-ok");
+      assert.notEqual(ok instanceof Error && /did not start/.test(ok.message), true, "the healthy batch is served");
+      const e = await hung;
+      assert.match(e.message, /did not start within 150 ms/);
+    } finally { await d.close(); }
+  });
+
+  it("the unit stands by while another daemon holds the lock instead of exiting 0 (no Restart=always loop)", async () => {
+    const dir = tmpDir("schedd-sb-"), root = tmpDir("schedd-sb-b-");
+    const owner = spawn(process.execPath, ["-e", "setTimeout(() => {}, 60000)"], { stdio: "ignore" });
+    const gone = new Promise((r) => owner.on("exit", r));
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(scheddPaths(dir).lock, String(owner.pid)); // a live daemon of another process
+    const slept = [];
+    process.env.FORGEDOCK_SCHEDD_IDLE_MS = "100"; // the successor daemon exits when idle, so the call returns
+    process.env.FORGEDOCK_BATCH_DIR = root;
+    try {
+      const r = await Promise.race([
+        scheddFromCli([], { scheddDir: dir, standby: true, standbyMs: 1, sleep: async () => { slept.push(1); if (slept.length === 3) { owner.kill("SIGKILL"); await gone; } }, processOn: () => {}, exit: () => {}, batchDeps: {}, due: null }),
+        new Promise((res) => setTimeout(() => res("timeout"), 5000)),
+      ]);
+      assert.ok(slept.length >= 3, "waited for the owner before retrying");
+      assert.notEqual(r, "timeout");
+    } finally { delete process.env.FORGEDOCK_SCHEDD_IDLE_MS; delete process.env.FORGEDOCK_BATCH_DIR; owner.kill("SIGKILL"); }
+  });
+});
+
 describe("#4762 win32 socket path", () => {
   it("win32 derives a stable per-dir named pipe; other platforms keep the unix socket file", () => {
     const a = scheddPaths("/tmp/a", "win32"), b = scheddPaths("/tmp/b", "win32");

package/bin/lean/toolstate.mjs

@@ -51,14 +51,30 @@ export async function unstageToolState(git) {
   return stray.length ? (await git(["diff", "--cached", "--name-only"])).trim() !== "" : staged.length > 0;
 }
 
+const REQUIREMENTS_EXPORT = /^requirements([-_.][\w.-]+)?\.txt$/;
+
+/**
+ * #4959: `requirements*.txt` files the branch added to a Poetry/uv project (pyproject [tool.poetry], or poetry.lock / uv.lock at
+ * the base) that the base does not track and the contract does not list (`keep`): an export generated to run local tests.
+ */
+export async function strayGenerated(git, ref, added, keep = []) {
+  const cands = added.filter((p) => REQUIREMENTS_EXPORT.test(base(p)) && !keep.includes(p));
+  if (!cands.length) return [];
+  const tracked = zlist(await git(["ls-tree", "-r", "--name-only", "-z", ref]));
+  const managed = tracked.some((f) => /(^|\/)(poetry|uv)\.lock$/.test(f))
+    || (await Promise.all(tracked.filter((f) => /(^|\/)pyproject\.toml$/.test(f)).map((f) => git(["show", `${ref}:${f}`]).catch(() => "")))).some((t) => /^\[tool\.poetry[\].]/m.test(String(t)));
+  return managed ? cands : [];
+}
+
 /**
  * Remove from the index (and commit) the deny-listed files this branch added against `base`. Returns the removed paths ([]
- * when the branch is clean). Never throws: a failure leaves the branch as it was and the push proceeds.
+ * when the branch is clean). `keep`: contract deliverable paths, never removed as generated files. Never throws: a failure
+ * leaves the branch as it was and the push proceeds.
  */
-export async function untrackToolState({ git, base: ref, ev = () => {} }) {
+export async function untrackToolState({ git, base: ref, ev = () => {}, keep = [] }) {
   try {
     const added = zlist(await git(["diff", "--diff-filter=A", "--name-only", "-z", `${ref}...HEAD`]));
-    const stray = await strayPaths(git, added);
+    const stray = [...await strayPaths(git, added), ...await strayGenerated(git, ref, added, keep)];
     if (!stray.length) return [];
     await git(["rm", "--cached", "-r", "-q", "--ignore-unmatch", "--", ...stray]);
     await git(["commit", "--no-verify", "-m", "chore: untrack lane tool state (#4590)", "-m", stray.slice(0, 20).join("\n")]);

package/bin/lean/toolstate.test.mjs

@@ -112,3 +112,25 @@ describe("lane scratch is untracked and cleared (#4880)", () => {
     assert.equal(execFileSync("git", ["ls-files", ".forge-lean"], { cwd: root, encoding: "utf8" }).trim(), "");
   });
 });
+
+describe("generated requirements.txt is untracked in a Poetry project (#4959)", () => {
+  const lane = (poetry, files) => {
+    const d = tmpDir("toolstate-poetry-");
+    sh(d, "init", "-q", "-b", "main"); sh(d, "config", "user.email", "t@t"); sh(d, "config", "user.name", "t");
+    put(d, "pyproject.toml", poetry ? "[tool.poetry]\nname = \"x\"\n" : "[project]\nname = \"x\"\n");
+    sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "base"); sh(d, "checkout", "-q", "-b", "lane");
+    for (const f of files) put(d, f);
+    sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "lane");
+    return d;
+  };
+  it("drops an added requirements.txt, keeps product files and contract-listed ones", async () => {
+    const d = lane(true, ["services/worker/requirements.txt", "services/worker/app.py", "services/api/requirements.txt"]);
+    const removed = await untrackToolState({ git: gitIn(d), base: "main", keep: ["services/api/requirements.txt"] });
+    assert.deepEqual(removed, ["services/worker/requirements.txt"]);
+    assert.deepEqual(sh(d, "diff", "--name-only", "main...HEAD").trim().split("\n"), ["services/api/requirements.txt", "services/worker/app.py"]);
+  });
+  it("a non-Poetry project is untouched", async () => {
+    const d = lane(false, ["requirements.txt"]);
+    assert.deepEqual(await untrackToolState({ git: gitIn(d), base: "main" }), []);
+  });
+});

package/bin/lean/verify.mjs

@@ -60,7 +60,15 @@ export function parseVerify(sec = {}) {
   const flaky = [...new Set(rawFlaky.map((x) => String(x ?? "").trim().replace(/^(["'])(.*)\1$/s, "$2").trim()).filter(Boolean))];
   const duplicateExports = str(s.duplicate_exports).toLowerCase() !== "false";
   const invariants = [...new Set((Array.isArray(s.invariants) ? s.invariants : []).map((x) => String(x ?? "").trim()).filter(Boolean))];
-  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, e2e: parseE2e(s) };
+  // #4792: guard_command maps an extension (`.py` or `py`) to a test-file command template; read by engine-cli readYamlMap; the key is omitted when empty so unconfigured repos parse as before
+  const guardCommand = {};
+  if (s.guard_command && typeof s.guard_command === "object" && !Array.isArray(s.guard_command)) {
+    for (const [k, v] of Object.entries(s.guard_command)) {
+      const ext = String(k).trim().toLowerCase().replace(/^\.?/, "."), cmd = str(v);
+      if (ext.length > 1 && cmd) guardCommand[ext] = cmd;
+    }
+  }
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, ...(Object.keys(guardCommand).length ? { guardCommand } : {}), e2e: parseE2e(s) };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);

package/bin/lean/verify.test.mjs

@@ -22,6 +22,10 @@ function fake(o = {}) {
 }
 
 describe("verify-by-CI config (#4167)", () => {
+  it("parseVerify normalises guard_command extensions and drops empty values (#4792)", () => {
+    assert.deepEqual(parseVerify({ guard_command: { PY: " scripts/pytest {path} ", ".js": "", "": "x" } }).guardCommand, { ".py": "scripts/pytest {path}" });
+    assert.equal("guardCommand" in parseVerify({ guard_command: "nope" }), false);
+  });
   it("parseVerify defaults to local and rejects invalid values", () => {
     assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, precheckTotalSeconds: 600, checkRun: false, checks: null, postMerge: null, flaky: [], duplicateExports: true, invariants: [], e2e: parseE2e({}) });
     const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });

package/commands/orchestrate.md

@@ -103,10 +103,10 @@ remaining maintenance once no feature is pending; otherwise the rest ends `held
   `forgedock orchestrate --set-parallel <id> K`. Issues filed while a batch runs join it with
   `forgedock orchestrate --add <id> N...` (or `--resume <id> N...`), under its K and DAG; never start a second batch
   for them. After a decision (a `FORGE:DECISION` posted and `needs-human` removed), a blocked issue that already ended in the batch
-  (`needs-human`, `invalid`, `skipped`, `dependency-*`, `ci-pending`) returns to it with
+  (`needs-human`, `invalid`, `skipped`, `dependency-*`, `ci-pending`, `deferred`) returns to it with
   `forgedock orchestrate --requeue <id> N... --reason "..."` (refused while it is labelled `needs-human` or closed; skipped dependents
   return to pending with it; a finished batch is reopened); `--add` on a `skipped` issue re-queues it (other ended issues still report `already in batch`). A dependency-skipped issue shows as `waiting on #X` while the batch runs (the blocker is re-checked each pass; merged or closed re-admits it, closed as not planned keeps it skipped) and ends `skipped` only if the blocker never resolved. Its pre-filter still closes already-fixed ones. The runner requeues `deferred` lanes by code (host busy and a full sandbox pool after their
-  retry-in, uncapped, a usage limit holds admissions for that account (backend identity) until the reset, across every batch on
+  retry-in, uncapped, a usage limit holds admissions for that account (backend identity) until the reset, never capped, across every batch on
   the host; `forgedock limits show|clear <id>|--all` lists or drops holds; transient merge/push/idle failures back off; other
   deferrals stop after `orchestration.max_deferrals`), relaunches an `engine-error` once, and stops admitting after
   `orchestration.breaker` engine-errors (`errors` within `window_min`; held issues continue on `--resume`). Lanes are

package/docs/CONFIG.md

@@ -439,8 +439,11 @@ orchestration:
 | `breaker.errors` / `breaker.window_min` | integer | No | `forgedock orchestrate` circuit breaker (#4121): after `errors` engine-errors within `window_min` minutes the batch stops admitting lanes, lets running lanes finish, and keeps the rest pending for `--resume`. `errors: 0` turns it off. Default: 3 in 30 |
 | `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held, gh unavailable) before its row is final. `host.busy` and `sandbox.capacity` (sandbox pool full) deferrals are not capped. Default: 3 |
 | `blocked_label` | string | No | `forgedock orchestrate` (#4773): an open issue carrying this label is admitted to the batch but not dispatched; removing the label releases it on the next scheduler pass. A `Blocked by #N` / `Depends on #N` line in the body of a trusted author (OWNER, MEMBER, COLLABORATOR or a bot) is a DAG edge to #N, and `--add` prints the edges it created. Empty turns the label off. Default: `blocked` |
+| `auto_add_children` | string | No | `forgedock orchestrate` (#4965): which children a running batch adds by itself. `off` (no auto-adds; a decomposed lane's sub-issues stay out too), `decomposed` (a decomposed lane's sub-issues join, as before), `epic` (also the open children of every batch issue and of each `--epic N`, found by a `**Parent**: #P` line, the `parent` field or GitHub sub-issues, including children filed after the batch started) or `all`. Children labelled `needs-human` and children another live batch of the repo still holds are not added. Each pass that adds posts one batch decision and one `added` row listing the children and edges. `forgedock orchestrate --auto-children <mode>` overrides it per batch and `--resume` keeps it. Default: `decomposed` |
+| `auto_add_children_poll_s` | integer | No | Seconds between child scans for `epic`/`all` (one `gh issue list` per scan). Default: `120` |
 | `global_parallel` | integer | No | `forgedock orchestrate` (#4191): host-wide cap on running lanes across every batch and repo on the host, enforced through the host lane registry (`~/.forge/sched/`, or `FORGEDOCK_SCHED_DIR`). A freed slot goes to the highest-priority queued issue (`priority:P<n>` / `P<n>` labels, unlabelled P2); within a priority, slots are shared across repos by weight (#4193: `forgedock sched weight <owner/repo> N`, `--clear` resets; default equal, FIFO inside a repo), and priority always dominates weights; running lanes are never preempted and `--parallel` K still bounds each batch. `forgedock sched cap N` overrides it live for the whole host (`--clear` reverts); `forgedock sched show` lists the weights, slots and the queue. Default: unset (no global cap) |
 | `recovery.max_attempts` | integer | No | `forgedock orchestrate` in-batch recovery (#4267): how many recovery lanes the batch launches per issue for a `needs-human` with a mechanical code (`ci.red`, `base.conflict`, `ci-pending` on a conflicting PR, `contract.invalid` after a mid-run issue edit, `builder.block_untyped`). A recovery lane (`run-issue --recover <code>`) removes `needs-human`, posts a `FORGE:DECISION`, resumes the open PR and re-queues the issue with its dependents. If it ends anything but `merged`, the issue is labelled `needs-human` again with a recovery-evidence `FORGE:NEEDS_HUMAN` comment. Human codes are never recovered. Flat form: `recovery_max_attempts`. Default: 1; `0` disables in-batch recovery (a mechanical `needs-human` is final, as before). |
+| `recovery.mechanical_max_attempts` | integer | No | `forgedock orchestrate` (#4725): the separate recovery budget of mechanical `needs-human` rows (`env.*`, `base.conflict`, a conflicting PR); never below `recovery.max_attempts`. Flat form: `recovery_mechanical_max_attempts`. Default: 2, so with the default config such a row gets 2 recovery lanes, not 1. |
 | `base_sync.enabled` | boolean | No | `forgedock orchestrate` parked-PR base sync (#4525): every 10 min while the batch runs, an open PR of a `needs-human` row is merged with its moved base in a throwaway worktree. A clean merge, or one whose only conflicts are hunks where both sides purely added lines in a `union_globs` file, is pushed as a plain merge commit (never forced). Any other conflict is aborted, the branch left alone, and its paths are posted once per base sha as a `FORGE:DECISION` on the issue. Sequence/`_journal.json` files are never resolved here. Flat form: `base_sync_enabled`. Default: `true`; `false` opts out. |
 | `base_sync.union_globs` | string | No | Comma-separated globs (`*` within a segment, `**` across; no `/` matches the file name anywhere) of well-known append-only files (registries, changelogs) whose two-sided line additions the base sync keeps both of. Flat form: `base_sync_union_globs`. Default: none (every conflict is reported). |
 | `cascade.policy` | string | No | `all` \| `balanced` \| `conservative`. Default: `balanced` |
@@ -455,7 +458,7 @@ orchestration:
 | `cascade.convergence_window` | positive integer | No | Consecutive ratio observations at or above 1.0 before warning. Default: 3 |
 | `cascade.amplification_breaker` | `on` \| `off` | No | Pause P3-and-below cascade admission while the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units. Counts all cascade findings (not only same-lineage); P1/P2 unaffected; independent of `cascade.policy`, so `policy: all` does not disable it. Paused P3s route to bounded P3 batches. Default: `on`. Opt out with `off` (boolean `false` is accepted as `off`, `true` as `on`). |
 
-**Upgrade note — in-batch recovery is on by default** (1.29.0): without `orchestration.recovery.max_attempts`, `forgedock orchestrate` launches one recovery lane per issue for a mechanical `needs-human` before reporting it. To keep the previous behavior (every `needs-human` final), set `orchestration.recovery.max_attempts: 0`.
+**Upgrade note — in-batch recovery is on by default** (1.29.0): without `orchestration.recovery.max_attempts`, `forgedock orchestrate` launches one recovery lane per issue for a mechanical `needs-human` before reporting it. To keep the previous behavior (every `needs-human` final), set `orchestration.recovery.max_attempts: 0`. The budget of mechanical rows (`env.*`, `base.conflict`, conflicting PR) is `orchestration.recovery.mechanical_max_attempts` (default 2, #4725); set it to `0` as well to turn those off.
 
 **Upgrade note — `cascade.amplification_breaker` is on by default**: existing configs that do not set this key now get the breaker automatically. During a batch, once the findings-spawned / merged-units ratio stays at or above 1.0 for `convergence_window` units (it can trip at exactly 1.0 over 3 units), P3-and-below cascade admission pauses; paused P3s are routed to bounded P3 batches rather than dispatched individually. P1/P2 are unaffected. To keep the previous behavior, set `orchestration.cascade.amplification_breaker: off` (or `false`). See [RELEASE-NOTES.md](RELEASE-NOTES.md) for the release that introduced this default.
 
@@ -602,7 +605,7 @@ engine:
 | `cli_max_minutes` | number | No | Absolute ceiling for a core builder session (code `cli.timeout`), replacing the fixed 60-minute kill. A session that keeps making progress is never idle-killed. Default 180. On either kill, uncommitted work is committed as `wip(forge): checkpoint after <reason>` and the lane branch is pushed (with the push retry), the builder retries once from the checkpoint, and a second kill ends `deferred`; a rerun resumes from the branch. |
 | `turn_budget_s` / `turn_budget_m` / `turn_budget_l` | number | No | Core implement turn budget per lane size (#4392). Size comes from a `size:S|M|L` issue label, else the frozen contract's distinct deliverable paths (S ≤ 2, M ≤ 5, else L). The build call and its context/timeout restarts share the budget; at the limit the session is stopped, checkpointed, and one fresh wrap-up session of max(5, budget/5) turns either finishes or writes `status: budget-exceeded` with a digest. A stop or overrun ends with the non-human `budget-exceeded` reason and code `budget.exceeded` (no `needs-human` label, forge#4505), which `forgedock orchestrate` recovers once (continue from the checkpoint or split); a batch that does not recover it labels it `needs-human` once. Lane results carry `turns: {size, budget, build, total, exceeded}`, and the batch report prints `turns by size`. Defaults 25 / 60 / 100; 0 disables that size. An L lane's budget scales with the contract: +10 turns per distinct deliverable path above 5 (capped at +2x `turn_budget_l`), and a `budget.exceeded` recovery of an L lane gets a further +50% of `turn_budget_l` (#4587). |
 | `lane_limits` | map | No | Cap each core lane's whole process tree (#4115, #4690), under `pipeline:` or `engine:`: `tasks_max` (default `1024`; `0`/`off` disables), `memory_max` (for example `3G`) and `cpu_quota` (for example `150%`). Where `systemd-run --user --scope` works (probed once) every lane's builder CLI is spawned as `systemd-run --user --scope -q --unit=forgedock-lane-... -p TasksMax=... -p MemoryMax=... -p CPUQuota=... -- claude ...` by default. `memory_max` has no default: lanes get no `MemoryMax` unless it is set (`off` also disables; #4740). A lane that hits `TasksMax` or `MemoryMax` is stopped and ends `needs-human` with `env.lane_limit` (not an engine-error, so the breaker ignores it). Where scopes are unavailable the run logs one line saying lanes are uncapped and the limits are ignored. Write it nested or flat (`lane_limits_tasks_max`, `lane_limits_memory_max`, `lane_limits_cpu_quota`). While a builder runs the engine polls host load and memory every 15 s against the `admission` thresholds: over them it SIGSTOPs the lane's process group, under them SIGCONT, and never pauses longer than 10 minutes. |
-| `admission` | map | No | Host-resource admission for the core work-on (#4105), checked before the lease, worktree or any GitHub call. When a check fails the run ends `deferred` (code `host.busy`, exit 75) with a last line such as `issue #N → deferred (host busy: mem 1.2G < 2G; retry in 60s)`; no lease is taken and nothing is posted. Keys: `enabled` (default `true`; `false` disables admission), `min_free_mem_mb` (default 2048; `MemAvailable` from `/proc/meminfo`, else `os.freemem()`), `min_free_tmp_mb` (default 1024; free space of the run TMPDIR filesystem, `~/.forge/tmp`, and of `/tmp`, via `statfs`), `max_load_per_core` (default 4; 1-minute load average divided by cores). Write it nested (`engine:` then `admission:` with the keys indented) or flat as `admission_enabled`, `admission_min_free_mem_mb`, `admission_min_free_tmp_mb`, `admission_max_load_per_core`; the parser reads one nested level into `engine`. `/orchestrate` requeues a host-busy lane and lowers K by 1 for 5 minutes. |
+| `admission` | map | No | Host-resource admission for the core work-on (#4105), checked before the lease, worktree or any GitHub call. When a check fails the run ends `deferred` (code `host.busy`, exit 75) with a last line such as `issue #N → deferred (host busy: mem 1.2G < 2G; retry in 60s)`; no lease is taken and nothing is posted. Keys: `enabled` (default `true`; `false` disables admission), `min_free_mem_mb` (default 2048; `MemAvailable` from `/proc/meminfo`, else `os.freemem()`), `min_free_tmp_mb` (default 1024; free space of the run TMPDIR filesystem, `~/.forge/tmp`, and of `/tmp`, via `statfs`), `max_load_per_core` (default 4; 1-minute load average divided by cores), `lane_cpu_reservation` (default 1) and `lane_mem_mb` (default 2048). The last two feed the live local lane cap (#4777), on by default: `min(--parallel / global_parallel, max(1, min(floor(cores / lane_cpu_reservation), floor((MemAvailable - min_free_mem_mb) / lane_mem_mb))))`, re-probed at every admission attempt, so `--parallel 12` on a 4-core / 8 GB host runs fewer concurrent local lanes. Remote sandbox lanes are exempt; `enabled: false` removes the cap. The cap reads the `forge.yaml` of the batch's repo, also when the batch runs under the schedd daemon. Write it nested (`engine:` then `admission:` with the keys indented) or flat as `admission_enabled`, `admission_min_free_mem_mb`, `admission_min_free_tmp_mb`, `admission_max_load_per_core`; the parser reads one nested level into `engine`. `/orchestrate` requeues a host-busy lane and lowers K by 1 for 5 minutes. |
 | `merge_wait` | string | No | Core work-on merge gate. `required` (default): wait only for the status checks the base branch requires: the union of classic branch protection (`gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`, contexts and checks) and repository rulesets (`gh api repos/{o}/{r}/rules/branches/{base}`, `required_status_checks` rules); with neither (404 or empty) merge right after review PASS. A merge rejected by base branch policy (PR `MERGEABLE` but `BLOCKED`) is waited on and retried within the CI budget, then left `ci-pending`; it is never base-synced and never `base.conflict`. A failing required check is `needs-human`; a pending one is polled with backoff and never `needs-human`. `all`: wait for every check (`scripts/wait-ci-green.sh`). `none`: merge right after review. Always `--match-head-commit` at the reviewed head. The policy used is recorded in the `FORGE:WORK-ON` comment. |
 | `context_pack` | string | No | Context pack (#4275). Before the plan call the core compiles the issue's GitHub/git neighbourhood into a small, budgeted pack: linked issues and PRs (parent, `Depends on`, body links, same-repo cross-references, siblings), prior attempts, merged PRs on the issue's files that were reverted or whose decisions/findings name a symbol from the issue, structured `FORGE:FACTS` records of earlier lanes on the issue's files (rejected approaches with why, hot spots, decisions, conventions, baselines; #4401), and repo-fact file pointers (found in the lane worktree or, for untracked caches, the main checkout; #4400). `shadow` (default): the pack is compiled, posted on the issue as a collapsed `FORGE:CONTEXT` comment and logged as a `CONTEXT_PACK` event; the builder prompt is unchanged. `on`: it is also appended to the plan prompt as hints. `off`: nothing is gathered, posted or logged. `ab` (#4444): the A/B experiment. Each issue gets a stable arm, `on` or `shadow`, from a hash of `repo#issue`, logged as that mode with `context_ab: true`; the default stays `shadow`. The pack never enters the text contract quotes are checked against. Values read from linked issues' `FORGE:STATE` are kept only when they are outcome codes. Compare with `forgedock stats --context-ab` (per lane type and mode: first-pass yield, turns and cache-read per merge, rework rate, and recovery lanes' implement attempt against the first run on the same issue). Unless `off`, a resumed or recovery lane also gets a bounded resume digest of its last run in the builder prompt (end reason, validate results per command, deliver requirements, files changed; logged as `RESUME_DIGEST`; #4400), whatever the mode. |
 | `context_pack_sources` | string | No | Comma list of the pack sources to use: `graph`, `attempts`, `pitfalls`, `ledger`, `facts` (earlier lanes' `FORGE:FACTS` on the issue's files plus repo-fact file pointers). Default: all five. |
@@ -880,6 +883,8 @@ verify:
   duplicate_exports: false      # optional; turn off the same-app duplicate-export check (default true)
   invariants:                   # optional block list; repo-wide check commands that always run before the PR
     - pnpm check:registry
+  guard_command:                # optional; per-extension command for the guard gate's base test files
+    ".py": "scripts/pytest {path}"
   e2e: auto                     # optional e2e merge gate: auto (default) | always | never
   e2e_label: full-ci            # PR label that makes the repo's CI run e2e (label path)
   e2e_checks: "e2e"             # check names of the e2e jobs the label path waits on
@@ -900,6 +905,7 @@ verify:
 | `precheck_total_seconds` | integer | No | Total budget of one round of pre-PR check commands (1–7200, default 600; it was 1800 before 1.30.0). `lean.precheck.max_minutes` takes precedence. Commands not started within the budget are deferred to CI, not failed. |
 | `checks` | string | No | Comma-separated check names that gate CI verification without `workflow` (forge#4387). Overrides the required-check set; other checks are reported, not gating. |
 | `invariants` | list | No | Block list of cheap repo-wide check commands (#4585), e.g. the suites that list every table, export, key or namespace (cross-tenant registry, export and purge coverage, i18n status, boundary tests). They run in the pre-PR check round in every verify mode, whichever tests the test map selected: never scoped away by `.forge/test-map.json`, deduplicated against the learned commands, and subject to the same round budget and per-command timeout. A failure goes to the builder in the precheck fix round like a failed declared check. The plan and implement prompts also carry an invariants checklist built from the list (a new table, export or key must join every registry that enumerates its kind). `forgedock check` and the light lane run them too. Absent: nothing changes. |
+| `guard_command` | map | No | Guard gate (#4693) test-file command per extension (#4792), e.g. `".py": "scripts/pytest {path}"` for a repo whose tests need a managed environment. Consulted before the contract's validate commands and the hard-coded `node --test` / `python -m pytest -q` fallbacks. `{path}` is replaced by the repo-relative path of the guard's base copy (`<name>__guardbase.<ext>`); a template without `{path}` gets it appended. Runs from the worktree root. Keys may be written with or without the leading dot. Absent: unchanged. |
 | `check_run` | boolean | No | Default `false` (no Checks API call, behaviour unchanged). `true`: after each push of a reviewed head (PR open, base-sync, merge-time fix round) the engine posts one completed `forgedock/verify` check run on that head (forge#4270), `success` iff every deterministic gate the lane already ran passed: declared check commands, undeclared package edges, docs freshness, contract scope, validate ids, requirement status, hotspot growth, amendments. The output carries each gate's id, pass/fail and evidence as JSON; the run log records a `VERIFY` event. Report only: ForgeDock never makes it required and never waits on it (it is ignored by its own CI waits); requiring it is the repository's branch-protection choice. Creating check runs needs a token that may (a GitHub App with `checks: write`); a Checks API failure is logged as an anomaly and never fails the lane. |
 | `post_merge` | string | No | Command run in the lane worktree on the merged tree after each base-sync merge, before the push (forge#4406). Default: the typecheck rows of the lane's change-scoped checks (`bin/lean/checks.mjs`), in `local` and `hybrid` mode only; `ci` mode runs no host typecheck unless `post_merge` is set. A failure resumes the builder with the output, up to `max_rounds` rounds, and the fixed head is re-reviewed; still failing is a trajectory anomaly and CI stays the gate. |
 | `duplicate_exports` | boolean | No | Default `true`: at hand-off and after each base-sync merge, names the lane newly exports that another non-test module of the same app or package (nearest `package.json`/`pyproject.toml`/`setup.py`/`go.mod`/`Cargo.toml`) already declares go back to the builder once ("rename or reuse", both paths); one left over is an anomaly (forge#4406). Re-exports, default exports and names 3+ other modules declare (framework conventions) are ignored. `false` turns the check off. |

package/docs/RELEASE-NOTES.md

@@ -7,6 +7,9 @@ Operator-facing notes for behavior changes that need action or awareness. Newest
 - **New command** `forgedock selftest [--static] | --live [--repo <owner/sandbox>] [--pr N]`. It runs a live contract harness against a disposable sandbox repo, plus a static check of every `gh --json` field list. See [SELFTEST.md](SELFTEST.md).
 - **Opt-in nightly run:** `selftest.nightly_interval_hours` makes the schedd daemon start a detached live selftest on that schedule and file one issue on failure. Restart schedd after upgrading to pick it up.
 - **Gate-marker check ignored:** the `Check for FORGE gate markers` check is no longer read as a CI failure by `review-staging`, `/review-pr-staging` or `/deploy-pr`. It only echoes the latest gate marker, so after a GATE_FAILURE it blocked its own GATE_PASS (#4941).
+- **`blocked` label now holds issues (#4773):** `orchestration.blocked_label` defaults to `blocked`. After upgrading, an open issue in a batch that carries a label named `blocked` is admitted but not dispatched until the label is removed. If you use `blocked` for another meaning, set `blocked_label: ""` (turns it off) or another label name. See [CONFIG.md](CONFIG.md#orchestration-optional) and `forge.yaml.example`.
+- **Host lane cap is on by default (#4777):** local lanes are bounded by cores and free memory (`engine.lane_cpu_reservation`, `engine.lane_mem_mb`), so `--parallel 12` on a small host runs fewer concurrent local lanes. Remote sandbox lanes are exempt; `admission: enabled: false` removes the cap.
+- **Mechanical recovery budget is 2 (#4725):** `orchestration.recovery.mechanical_max_attempts` defaults to 2 while `recovery.max_attempts` stays 1, so `env.*`, `base.conflict` and conflicting-PR rows get 2 recovery lanes.
 
 ### Live selftest gates the staging->main release review (when a sandbox repo is set)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/file-deferred-followups.sh

@@ -374,6 +374,7 @@ file_class() {
   {
     printf '## Problem\n\n'
     printf 'Deferred from #%s: the items below were declared out of scope in its contract and are tracked here, in one issue per class (%s), instead of surfacing later as review findings.\n\n' "$PARENT" "$CLS"
+    printf '**Parent**: #%s\n\n' "$PARENT"
     if [ "$CLS" = "external" ]; then
       printf 'External prerequisite of #%s: these items wait on something outside the repo (credentials, an account, a third party).' "$PARENT"
       [ -n "${FORGE_EXTERNAL_PREREQ:-}" ] && printf ' Linked prerequisite: #%s.' "${FORGE_EXTERNAL_PREREQ#\#}"

package/scripts/file-deferred-followups.test.sh

@@ -331,5 +331,12 @@ printf -- 'x/y.sh\towner: [bucket:owner] spend\t\tpost-deploy\n' > "$T/ow.tsv"
 bash "$S" --parent 10 --repo o/r --items "$T/ow.tsv" >/dev/null 2>&1
 check "owner bucket never lands in post-deploy, even when the row says so" "grep -q 'FORGE:DEFERRED_CLASS: external' '$T/created.901.body' && ! grep -q POSTDEPLOY_ROLLUP '$T/created.901.body'"
 
+# a parent that is itself an open follow-up and is the issue the lane closes: a NEW follow-up links it, its body is never edited
+reset
+printf '{"number":20,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"## Acceptance Criteria\\n\\n- [ ] `R1: old`\\n<!-- FORGE:DEFERRED_FROM: #10 -->"}\n' > "$T/issue.20.json"
+printf -- '-\tdefer: later\t\t\tR2: wire `pd.py` in\n' > "$T/fu.tsv"
+OUT=$(bash "$S" --parent 20 --repo o/r --items "$T/fu.tsv"); RC=$?
+check "follow-up parent: new follow-up issue, parent body unchanged" "[ $RC -eq 0 ] && [ \$(grep -c '^issue create' '$GH_LOG') -eq 1 ] && ! grep -q '^issue edit 20' '$GH_LOG' && [ ! -e '$ISSUE_BODY.edited' ] && grep -q '^\*\*Parent\*\*: #20\$' '$T/created.901.body' && grep -q 'FORGE:DEFERRED_FROM: #20' '$T/created.901.body' && printf '%s\n' \"\$OUT\" | grep -q '^R2: wire pd.py in.901\$'"
+
 echo "passed=$PASS failed=$FAIL"
 [ "$FAIL" -eq 0 ]

package/scripts/review-pr-staging-scope.test.sh

@@ -235,7 +235,7 @@ OUT9=$(credit9 "$H"); N9=$(printf '%s' "${OUT9#*|}" | wc -w)
 # spec text guards: the resolver is reused, never copied; carried record accepted; the unchanged cross-PR and merge-resolution paths are still present
 grep -q 'review-delta.sh' "$PRE" && grep -q 'REVIEW-CARRIED' "$PRE" && ok || bad "review-staging-pre.sh must call review-delta.sh and accept the REVIEW-CARRIED record"
 if grep -qE 'merge-base --is-ancestor.*REVIEWED_SHA_STALE|diff_shape\(\)' "$SPEC" "$PRE"; then bad "spec must not carry a second copy of the resolver logic"; else ok; fi
-grep -qF 'printf '"'"'%s\n'"'"' "$_FILES" | sort -u | sed "s|^|$pr |" >> "$_PF"' "$PRE" && grep -qF 'git diff-tree --no-commit-id --name-only -r --cc "$c"' "$PRE" && ok || bad "CROSS_PR_FILES accumulation and --cc merge scoping must stay intact"
+grep -qF 'printf '"'"'%s\n'"'"' "$_FILES" | sort -u | sed "s|^|$pr |" > "$_D/pf"' "$PRE" && grep -qF 'cat "$_W/$pr/pf" >> "$_PF"' "$PRE" && grep -qF 'git diff-tree --no-commit-id --name-only -r --cc "$c"' "$PRE" && ok || bad "CROSS_PR_FILES accumulation and --cc merge scoping must stay intact"
 [ "$(grep -c '# FENCE_BOOTSTRAP$' "$SPEC" | head -1)" -ge 3 ] && ok || bad "FENCE_BOOTSTRAP stubs must remain"
 # an unresolvable helper fails the fence closed (exit 1), never an unsourced bootstrap
 OUT8=$( ( unset FORGEDOCK_HOME FORGE_HOME FORGE_ROOT CLAUDE_PLUGIN_ROOT CLAUDE_CONFIG_DIR CODEX_HOME FORGE_SOURCED_ROOT FORGEDOCK_MARKETPLACE; export HOME="$TMP/nohome"; cd "$TMP" && bash -c "$(cat "$TMP/boot.sh"); echo reached" ) 2>&1 )
@@ -305,8 +305,8 @@ OUT11=$(scope11 "28668 5 6")
 [ "$(printf '%s\n' "$OUT11" | head -1)" = "scoped 1" ] && ok || bad "an issue number in the bundle list must be skipped, not fall open (got '$OUT11')"
 case "$OUT11" in *"#28668 is an issue"*) ok ;; *) bad "0B.1 must announce the skipped issue (got '$OUT11')" ;; esac
 OUT11=$(scope11 "5 77")
-[ "$(printf '%s\n' "$OUT11" | head -1 | cut -d' ' -f1)" = "full" ] && ok || bad "a genuine read failure must still fall open (got '$OUT11')"
-case "$OUT11" in *"fell open at bundle PR #77"*"not a confirmed issue"*) ok ;; *) bad "a fall-open must print the PR and reason (got '$OUT11')" ;; esac
+[ "$(printf '%s\n' "$OUT11" | head -1)" = "scoped 1" ] && ok || bad "a genuine read failure on one PR must degrade that PR only and keep scope (got '$OUT11')"
+case "$OUT11" in *"scope degraded for PR #77"*"not a confirmed issue"*) ok ;; *) bad "a degraded PR must print the PR and reason (got '$OUT11')" ;; esac
 else echo "review-pr-staging-scope.test.sh: git missing, delta section skipped"; fi
 echo "review-pr-staging-scope.test.sh: passed=$PASS failed=$FAILN"
 [ "$FAILN" -eq 0 ]

package/scripts/review-prepare.sh

@@ -601,6 +601,7 @@ if [ "$REVIEW_MODE" != "BASE_SYNC_ONLY" ]; then
             echo "Domain files (${domain}): ${files:-none}"
         else echo "Code index not available — agent will use grep exploration"; fi
     }
+    echo "review-prepare: code index phase done; building per-domain diff slices" >&2
     IDX_AUTH=$(build_index_slice auth); IDX_BILLING=$(build_index_slice billing); IDX_DATABASE=$(build_index_slice database)
     IDX_API=$(build_index_slice api); IDX_FRONTEND=$(build_index_slice frontend); IDX_INFRA=$(build_index_slice infrastructure)
 
@@ -639,6 +640,7 @@ if [ "$REVIEW_MODE" != "BASE_SYNC_ONLY" ]; then
         printf '%s' "$paths" > "$TMP_DIR/slice-paths" || { echo "review-prepare: cannot write $TMP_DIR/slice-paths" >&2; exit 2; }
         SLICES_JSON=$(printf '%s' "$SLICES_JSON" | jq -c --arg d "$dom" --arg df "$df" --rawfile p "$TMP_DIR/slice-paths" '. + {($d): {paths: ($p | split("\n") | map(select(length > 0))), diff_file: $df}}')
     }
+    echo "review-prepare: slicing the diff ($(printf '%s\n' "$SLICE_FILES_SRC" | sed '/^$/d' | wc -l | tr -d ' ') file(s))" >&2
     slice security ALL ALL
     slice auth '^diff --git.*/(auth|session|jwt|oauth|permission|middleware|login|token)' "auth|session|login|logout|jwt|oauth|token|user|permission|middleware"
     slice billing '^diff --git.*/(billing|payment|credit|pricing|stripe|subscription|invoice|charge|refund)' "billing|credit|payment|charge|refund|subscription|pricing|tier"
@@ -649,6 +651,7 @@ if [ "$REVIEW_MODE" != "BASE_SYNC_ONLY" ]; then
     slice infra '^diff --git.*/(docker|nginx|infra|\.github|deploy|ci|traefik|k8s|helm)' "docker|nginx|traefik|\.github|Makefile|deploy|infra"
     slice scraper '^diff --git.*/(scrape|scraper|stealth|browser_pool|headless|anti_bot|captcha|crawl)' "scrape|crawler|stealth|browser.*pool|headless|anti.bot|detection.*keyword|captcha"
     slice spec-cli '^diff --git a/(commands|bin)/' "^(commands|bin)/"
+    echo "review-prepare: diff slices done" >&2
 fi
 
 # --- emit ---

package/scripts/review-staging-pre.sh

@@ -14,7 +14,8 @@
 #           gh read blocks (TYPE=gate-read-failure, never waived by an override): no GATE_PASS without real reads (forge#4470).
 #   scope   0B.1: writes DIR/<N>_scope.env (printf %q, read by 7A), DIR/<N>_bundle-pr-files.txt and DIR/<N>_scope.json
 #           {scope_mode, reviewed_pr_count, reviewed_commits, unreviewed_commits, unreviewed_files, cross_pr_files,
-#           deploy_wiring_files}; prints the one-line SCOPE_MODE summary. Every failed read widens scope to full.
+#           deploy_wiring_files, degraded_prs}; prints the one-line SCOPE_MODE summary. Per-PR reads run FORGE_SCOPE_PARALLELISM (default 8) at a time
+#           and retry; a PR whose read still fails is degraded (its commits stay unreviewed) and the rest stay scoped. Global failures widen to full.
 # Exit: 2 on a usage error.
 #
 # The `# BEGIN <name>` ... `# END <name>` blocks below are byte-identical copies of the spec's blocks ({GH_REPO} -> $GH_REPO);
@@ -106,7 +107,11 @@ MERGE_PRS=$(git log origin/$DEFAULT_BRANCH..origin/$STAGING_BRANCH --merges --on
 # Merge-subject numbers are PRs by construction; an unclassifiable number is kept (fail open: it may be a PR). forge#4127
 # BEGIN bundle-pr-kind
 # Prints "pr" or "issue" for issue number ${2} in repo ${1}; prints nothing and returns 1 when the read fails or is malformed.
-bundle_pr_kind() { local k; k=$(gh_retry gh api "repos/${1}/issues/${2}" --jq 'if .pull_request then "pr" else "issue" end' 2>/dev/null) || return 1; case "$k" in pr|issue) printf '%s' "$k" ;; *) return 1 ;; esac; }
+# A number's kind never changes, so a successful answer is cached under the run scratch dir ($_SD/gh-cache): a rerun after a killed run skips the read (#4960).
+bundle_pr_kind() { local k c="${_SD:-${FORGE_SCRATCHPAD:-}}"; [ -z "$c" ] || c="$c/gh-cache/kind-$(printf '%s' "${1}" | tr '/' '_')-${2}"
+  [ -z "$c" ] || ! [ -f "$c" ] || { k=$(cat "$c" 2>/dev/null); case "$k" in pr|issue) printf '%s' "$k"; return 0 ;; esac; }
+  k=$(gh_retry gh api "repos/${1}/issues/${2}" --jq 'if .pull_request then "pr" else "issue" end' 2>/dev/null) || return 1; case "$k" in pr|issue) ;; *) return 1 ;; esac
+  [ -z "$c" ] || { mkdir -p "$(dirname "$c")" 2>/dev/null && printf '%s' "$k" > "$c" 2>/dev/null; }; printf '%s' "$k"; }
 # END bundle-pr-kind
 SUBJECT_PRS=""; SKIPPED_ISSUES=""
 for n in $BUNDLE_PRS; do
@@ -332,49 +337,89 @@ bundle_delta_credit() {
 # END bundle-delta-credit
 # BEGIN bundle-pr-kind
 # Prints "pr" or "issue" for issue number ${2} in repo ${1}; prints nothing and returns 1 when the read fails or is malformed.
-bundle_pr_kind() { local k; k=$(gh_retry gh api "repos/${1}/issues/${2}" --jq 'if .pull_request then "pr" else "issue" end' 2>/dev/null) || return 1; case "$k" in pr|issue) printf '%s' "$k" ;; *) return 1 ;; esac; }
+# A number's kind never changes, so a successful answer is cached under the run scratch dir ($_SD/gh-cache): a rerun after a killed run skips the read (#4960).
+bundle_pr_kind() { local k c="${_SD:-${FORGE_SCRATCHPAD:-}}"; [ -z "$c" ] || c="$c/gh-cache/kind-$(printf '%s' "${1}" | tr '/' '_')-${2}"
+  [ -z "$c" ] || ! [ -f "$c" ] || { k=$(cat "$c" 2>/dev/null); case "$k" in pr|issue) printf '%s' "$k"; return 0 ;; esac; }
+  k=$(gh_retry gh api "repos/${1}/issues/${2}" --jq 'if .pull_request then "pr" else "issue" end' 2>/dev/null) || return 1; case "$k" in pr|issue) ;; *) return 1 ;; esac
+  [ -z "$c" ] || { mkdir -p "$(dirname "$c")" 2>/dev/null && printf '%s' "$k" > "$c" 2>/dev/null; }; printf '%s' "$k"; }
 # END bundle-pr-kind
 # BEGIN bundle-scope-loop
-_WHY=""
+_WHY=""; DEGRADED_PRS=""
+# scope_one_pr PR DIR: every read for one bundle PR, run in its own subshell. Writes DIR/status ("ok", "issue" or "degraded <why>") and, for ok,
+# DIR/pf (the "<pr> <file>" lines), DIR/reviewed (0|1), DIR/commits, DIR/merges. A failed read is retried (gh_retry) and then degrades THIS PR only:
+# it is credited no commits, so they stay UNREVIEWED and are reviewed (widening, never narrowing); it never changes the bundle's scope mode (#4960).
+scope_one_pr() {
+  pr="$1"; _D="$2"
+  _degrade() { printf 'degraded %s\n' "$1" > "$_D/status"; }
+  # A number 0A could not classify may be an issue (subjects cite issues): a confirmed issue is skipped (forge#4127).
+  _J=$(gh_retry gh pr view "$pr" -R $GH_REPO --json headRefOid,mergeCommit,commits,state,baseRefName,labels 2>/dev/null) || {
+    if [ "$(bundle_pr_kind "$GH_REPO" "$pr")" = issue ]; then echo issue > "$_D/status"; else _degrade "gh pr view failed and #$pr is not a confirmed issue"; fi
+    return 0; }
+  _HEAD=$(printf '%s' "$_J" | jq -r '.headRefOid') || { _degrade "unreadable pr view output"; return 0; }
+  # a malformed head id would make the sha match accept any comment (fail open): this PR gets no credit
+  case "$_HEAD" in *[!0-9a-f]*|"") _degrade "malformed head id"; return 0 ;; esac
+  [ "${#_HEAD}" -eq 40 ] || [ "${#_HEAD}" -eq 64 ] || { _degrade "malformed head id"; return 0; }
+  _HEAD7=$(printf '%s' "$_HEAD" | cut -c1-7)
+  # Capture each gh read into a variable FIRST and test its own exit status: in a pipeline `||` only sees the last stage (no pipefail),
+  # so a failed gh read piped into another command would silently look like "no comments" / "no files".
+  _CM=$(gh_retry gh api --paginate "repos/$GH_REPO/issues/$pr/comments" 2>/dev/null) || { _degrade "comments read failed"; return 0; }
+  _FILES=$(gh_retry gh pr diff "$pr" -R $GH_REPO --name-only 2>/dev/null) || { _degrade "file list read failed"; return 0; }
+  # Reviewed = trusted FORGE:REVIEW_ROUTE (a real review mode) whose sha is the PR's FINAL head, plus at least one review-agent comment
+  # carrying the full-length `Reviewed-SHA: <head>` line and a findings block (same predicate as review-pr.md Phase 5; a 7-char substring or a comment with no findings block never counts), and no degraded/blocked review marker. A PR pushed to after its review has a stale sha: the exact-head gate gives it no credit, and only the delta branch below (shared resolver `scripts/review-delta.sh`) may credit the commits an earlier trusted complete panel covered or a trusted `FORGE:REVIEW-CARRIED` base sync carried; everything else stays UNREVIEWED.
+  _ROUTE=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW_ROUTE mode=(?!spec-evolution-blocked)[^ ]+ spec=review-pr.md sha=${_HEAD7} -->") || { _degrade "marker count failed"; return 0; }
+  _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { _degrade "marker count failed"; return 0; }
+  _DEGRADED=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:(REVIEW_DEGRADED|REVIEW_BLOCKED)") || { _degrade "marker count failed"; return 0; }
+  case "$_ROUTE$_AGENT$_DEGRADED" in ''|*[!0-9]*) _degrade "malformed marker count"; return 0 ;; esac
+  _NC=$(printf '%s' "$_J" | jq '.commits|length') || { _degrade "unreadable commit list"; return 0; }
+  _ALLC=$(printf '%s' "$_J" | jq -r '[.commits[].oid, .mergeCommit.oid // empty] | join(" ")') || { _degrade "unreadable commit list"; return 0; }
+  _MERGEC=$(printf '%s' "$_J" | jq -r '.mergeCommit.oid // empty') || { _degrade "unreadable commit list"; return 0; }
+  _REV=0; _COMMITS=""; _MERGES=""
+  if [ "$_ROUTE" -ge 1 ] && [ "$_AGENT" -ge 1 ] && [ "$_DEGRADED" -eq 0 ] && [ "$_NC" -lt 100 ]; then
+    _REV=1; _COMMITS="$_ALLC"; _MERGES="$_MERGEC"
+  elif [ "$_DEGRADED" -eq 0 ] && [ "$_NC" -lt 100 ]; then
+    # Stale head: the exact-head gate failed, so ask the shared resolver how much of the PR an earlier trusted complete panel covered. Additive only: it can move commits out of UNREVIEWED, never into it.
+    bundle_delta_credit
+    if [ "$DELTA_FULL" -eq 1 ]; then _REV=1; _COMMITS="$_ALLC"; _MERGES="$_MERGEC"
+    elif [ -n "$DELTA_COMMITS" ]; then _COMMITS="$DELTA_COMMITS"   # the PR's merge commit is not credited: it contains the post-review commits
+    fi
+  fi
+  printf '%s\n' "$_REV" > "$_D/reviewed"; printf '%s' "$_COMMITS" > "$_D/commits"; printf '%s' "$_MERGES" > "$_D/merges"
+  printf '%s\n' "$_FILES" | sort -u | sed "s|^|$pr |" > "$_D/pf"
+  echo ok > "$_D/status"
+}
 if [ -n "$TRUSTED_SCRIPT" ] && [ -n "${ALL_PR_NUMBERS:-}" ] && [ -n "${PR_NUMBER:-}" ] && [ -n "${GH_REPO:-}" ]; then
   SCOPE_MODE=scoped
-  for pr in $ALL_PR_NUMBERS; do
-    # A number 0A could not classify may be an issue (subjects cite issues): a confirmed issue is skipped, only a genuine read failure falls open (forge#4127).
-    _J=$(gh pr view "$pr" -R $GH_REPO --json headRefOid,mergeCommit,commits,state,baseRefName,labels 2>/dev/null) || {
-      if [ "$(bundle_pr_kind "$GH_REPO" "$pr")" = issue ]; then echo "0B.1: #$pr is an issue, not a bundle PR: skipped"; continue; fi
-      _WHY="gh pr view failed and #$pr is not a confirmed issue"; SCOPE_MODE=full; break; }
-    _HEAD=$(printf '%s' "$_J" | jq -r '.headRefOid')
-    case "$_HEAD" in *[!0-9a-f]*|"") SCOPE_MODE=full; break ;; esac   # a malformed head id would make the sha match accept any comment (fail open): review everything
-    [ "${#_HEAD}" -eq 40 ] || [ "${#_HEAD}" -eq 64 ] || { SCOPE_MODE=full; break; }
-    _HEAD7=$(printf '%s' "$_HEAD" | cut -c1-7)
-    # Capture each gh read into a variable FIRST and test its own exit status: in a pipeline `||` only sees the last stage (no pipefail),
-    # so a failed gh read piped into another command would silently look like "no comments" / "no files".
-    _CM=$(gh api --paginate "repos/$GH_REPO/issues/$pr/comments" 2>/dev/null) || { SCOPE_MODE=full; break; }
-    _FILES=$(gh pr diff "$pr" -R $GH_REPO --name-only 2>/dev/null) || { SCOPE_MODE=full; break; }
-    # Reviewed = trusted FORGE:REVIEW_ROUTE (a real review mode) whose sha is the PR's FINAL head, plus at least one review-agent comment
-    # carrying the full-length `Reviewed-SHA: <head>` line and a findings block (same predicate as review-pr.md Phase 5; a 7-char substring or a comment with no findings block never counts), and no degraded/blocked review marker. A PR pushed to after its review has a stale sha: the exact-head gate gives it no credit, and only the delta branch below (shared resolver `scripts/review-delta.sh`) may credit the commits an earlier trusted complete panel covered or a trusted `FORGE:REVIEW-CARRIED` base sync carried; everything else stays UNREVIEWED.
-    _ROUTE=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:REVIEW_ROUTE mode=(?!spec-evolution-blocked)[^ ]+ spec=review-pr.md sha=${_HEAD7} -->") || { SCOPE_MODE=full; break; }
-    _AGENT=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${_HEAD}(\\r?\\n|$)") || { SCOPE_MODE=full; break; }
-    _DEGRADED=$(printf '%s' "$_CM" | bash "$TRUSTED_SCRIPT" count "^<!-- FORGE:(REVIEW_DEGRADED|REVIEW_BLOCKED)") || { SCOPE_MODE=full; break; }
-    case "$_ROUTE$_AGENT$_DEGRADED" in ''|*[!0-9]*) SCOPE_MODE=full; break ;; esac
-    if [ "$_ROUTE" -ge 1 ] && [ "$_AGENT" -ge 1 ] && [ "$_DEGRADED" -eq 0 ] && [ "$(printf '%s' "$_J" | jq '.commits|length')" -lt 100 ]; then
-      REVIEWED_PR_COUNT=$((REVIEWED_PR_COUNT+1))
-      REVIEWED_COMMITS="$REVIEWED_COMMITS $(printf '%s' "$_J" | jq -r '[.commits[].oid, .mergeCommit.oid // empty] | join(" ")')"
-      REVIEWED_MERGES="$REVIEWED_MERGES $(printf '%s' "$_J" | jq -r '.mergeCommit.oid // empty')"
-    elif [ "$_DEGRADED" -eq 0 ] && [ "$(printf '%s' "$_J" | jq '.commits|length')" -lt 100 ]; then
-      # Stale head: the exact-head gate failed, so ask the shared resolver how much of the PR an earlier trusted complete panel covered. Additive only: it can move commits out of UNREVIEWED, never into it.
-      bundle_delta_credit
-      if [ "$DELTA_FULL" -eq 1 ]; then
-        REVIEWED_PR_COUNT=$((REVIEWED_PR_COUNT+1))
-        REVIEWED_COMMITS="$REVIEWED_COMMITS $(printf '%s' "$_J" | jq -r '[.commits[].oid, .mergeCommit.oid // empty] | join(" ")')"
-        REVIEWED_MERGES="$REVIEWED_MERGES $(printf '%s' "$_J" | jq -r '.mergeCommit.oid // empty')"
-      elif [ -n "$DELTA_COMMITS" ]; then
-        REVIEWED_COMMITS="$REVIEWED_COMMITS$DELTA_COMMITS"   # the PR's merge commit is not credited: it contains the post-review commits
-      fi
-    fi
-    printf '%s\n' "$_FILES" | sort -u | sed "s|^|$pr |" >> "$_PF"
-  done
-  [ "$SCOPE_MODE" = scoped ] || echo "SCOPE_MODE=full: scoping fell open at bundle PR #$pr (${_WHY:-a gh read or marker count failed or returned malformed data})"
+  _W=$(mktemp -d "$_SD/scope-work.XXXXXX") || { SCOPE_MODE=full; _WHY="cannot create a scratch dir under $_SD"; }
+  if [ "$SCOPE_MODE" = scoped ]; then
+    _P="${FORGE_SCOPE_PARALLELISM:-8}"; case "$_P" in ''|*[!0-9]*|0) _P=8 ;; esac
+    _TOT=$(echo $ALL_PR_NUMBERS | wc -w | tr -d ' '); _N=0; _ACTIVE=0; _NEXT=25
+    echo "0B.1: reading $_TOT bundle PR(s), $_P at a time" >&2
+    for pr in $ALL_PR_NUMBERS; do
+      mkdir -p "$_W/$pr"
+      ( scope_one_pr "$pr" "$_W/$pr" ) &
+      _ACTIVE=$((_ACTIVE+1)); _N=$((_N+1))
+      if [ "$_ACTIVE" -ge "$_P" ]; then wait; _ACTIVE=0; fi
+      if [ "$_N" -ge "$_NEXT" ]; then echo "0B.1: $_N/$_TOT PR(s) dispatched" >&2; _NEXT=$((_NEXT+25)); fi
+    done
+    wait
+    echo "0B.1: all $_TOT PR read(s) done; merging" >&2
+    for pr in $ALL_PR_NUMBERS; do
+      _S=$(cat "$_W/$pr/status" 2>/dev/null) || _S=""   # a subshell that died leaves no status: degrade this PR
+      case "$_S" in
+        ok)
+          REVIEWED_PR_COUNT=$((REVIEWED_PR_COUNT + $(cat "$_W/$pr/reviewed")))
+          REVIEWED_COMMITS="$REVIEWED_COMMITS $(cat "$_W/$pr/commits")"
+          REVIEWED_MERGES="$REVIEWED_MERGES $(cat "$_W/$pr/merges")"
+          cat "$_W/$pr/pf" >> "$_PF" ;;
+        issue) echo "0B.1: #$pr is an issue, not a bundle PR: skipped" ;;
+        *) _WHY="${_S#degraded }"; [ -n "$_S" ] || _WHY="scope read of #$pr produced no result"
+           DEGRADED_PRS="$DEGRADED_PRS $pr"
+           echo "0B.1: scope degraded for PR #$pr ($_WHY): its commits stay UNREVIEWED; scope stays scoped for the rest" ;;
+      esac
+    done
+    rm -rf "$_W"
+  fi
+  [ "$SCOPE_MODE" = scoped ] || echo "SCOPE_MODE=full: scoping fell open (${_WHY:-a scope read failed})"
 fi
 # END bundle-scope-loop
 if [ "$SCOPE_MODE" = "scoped" ]; then
@@ -415,7 +460,7 @@ _jw() { printf '%s\n' "${1:-}" | tr ' ' '\n' | sed '/^$/d' | jq -R . | jq -s .;
 _jn() { printf '%s\n' "${1:-}" | sed '/^$/d' | jq -R . | jq -s .; }
 jq -n --arg mode "$SCOPE_MODE" --argjson n "${REVIEWED_PR_COUNT:-0}" \
   --argjson rc "$(_jw "$REVIEWED_COMMITS")" --argjson uc "$(_jw "$UNREVIEWED_COMMITS")" \
-  --argjson uf "$(_jn "${UNREVIEWED_FILES:-}")" --argjson cf "$(_jn "${CROSS_PR_FILES:-}")" --argjson dw "$(_jn "${DEPLOY_WIRING_FILES:-}")" \
-  '{scope_mode: $mode, reviewed_pr_count: $n, reviewed_commits: $rc, unreviewed_commits: $uc, unreviewed_files: $uf, cross_pr_files: $cf, deploy_wiring_files: $dw}' \
+  --argjson uf "$(_jn "${UNREVIEWED_FILES:-}")" --argjson cf "$(_jn "${CROSS_PR_FILES:-}")" --argjson dw "$(_jn "${DEPLOY_WIRING_FILES:-}")" --argjson dp "$(_jw "$DEGRADED_PRS" | jq -c "map(tonumber)")" \
+  '{scope_mode: $mode, reviewed_pr_count: $n, reviewed_commits: $rc, unreviewed_commits: $uc, unreviewed_files: $uf, cross_pr_files: $cf, deploy_wiring_files: $dw, degraded_prs: $dp}' \
   > "$_SD/${PR_NUMBER}_scope.json" || { echo "review-staging-pre: could not write ${PR_NUMBER}_scope.json" >&2; exit 1; }
 exit 0