forgedock 1.41.0 → 1.43.0

package/docs/CONFIG.md

@@ -58,6 +58,7 @@ If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pi
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`execution`](#execution-optional) | No | `forgedock orchestrate`: run lanes in sandboxes instead of host processes (`mode: local\|remote\|hybrid`, `max_remote`) |
 | [`verify`](#verify-optional) | No | Core work-on: run lane verification on CI runners instead of the host (`mode: local\|ci\|hybrid`) |
+| [`selftest`](#selftest-optional) | No | `forgedock selftest --live`: the disposable sandbox repo and fixture language of the live contract harness |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
 | [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
 
@@ -438,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` |
@@ -454,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.
 
@@ -601,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. |
@@ -658,6 +662,27 @@ prod_watch:
 
 ---
 
+## `selftest` (OPTIONAL)
+
+Settings for `forgedock selftest --live` (see [SELFTEST.md](SELFTEST.md)): a harness that drives the real `gh`, git and `orchestrate` against a disposable sandbox repo, and the `FORGE:SELFTEST` result the staging->main review requires.
+
+```yaml
+selftest:
+  sandbox_repo: acme/forgedock-sandbox   # disposable repo; the harness creates and closes issues, PRs and branches in it
+  fixture: node                          # node (default) | python
+  nightly_interval_hours: 24             # opt-in: schedd runs `selftest --live` this often (default off)
+```
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `sandbox_repo` | string | No | `owner/repo` the live harness runs in. `--repo` overrides it; with neither the command stops. Never point it at a real project. Setting it also turns on the release gate: `forgedock review-staging` then requires a passing `FORGE:SELFTEST` marker for the release PR head; unset, the gate is skipped. |
+| `fixture` | string | No | Toolchain of the two trivial fixture issues: `node` (default) or `python`. `--lang` overrides it. |
+| `nightly_interval_hours` | number | No | Off when unset or 0. When positive, the schedd daemon (host, never GitHub Actions) starts a detached `selftest --live` against `sandbox_repo` once this many hours have passed since the last run of that repo. On failure, including a run that cannot start, it files or edits one issue naming the failed step, in the repo schedd resolves for its working directory. See [SELFTEST.md](SELFTEST.md#nightly-run). |
+
+**Commands that use this section**: `forgedock selftest`, `forgedock review-staging` (release gate, only when `sandbox_repo` is set)
+
+---
+
 ## `issue_watch` (OPTIONAL)
 
 Named, scoped, capped watches for `forgedock issue-watch` (see [ISSUE-WATCH.md](ISSUE-WATCH.md)). Write `issue_watch:`, then `watches:`, then one block per watch name. The release keys need `mode: release` and at least a `threshold` or `immediate`.
@@ -858,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
@@ -878,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

@@ -2,6 +2,19 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Unreleased: `forgedock selftest`, opt-in release gate and nightly run; gate-marker check ignored
+
+- **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)
+
+When forge.yaml sets `selftest.sandbox_repo`, `forgedock review-staging` stops with `REVIEW_RESULT: status: BLOCKED` unless the staging->main PR carries a `FORGE:SELFTEST result=pass` comment for its current head commit (a missing, failing, malformed or stale marker refuses). Run `forgedock selftest --live --repo <owner/sandbox> --pr <N>` (sandbox repo or `selftest.sandbox_repo` in forge.yaml, see [CONFIG.md](CONFIG.md#selftest-optional)) after the last push to the release PR; it posts the marker. Without `selftest.sandbox_repo` the gate is skipped (the CLI prints `SELFTEST: skipped` on stderr), so repos without a sandbox are not blocked. Details: [SELFTEST.md](SELFTEST.md).
+
 ## v1.30.0: environment failures are recoverable, scoped pre-PR checks, decomposed parents can close
 
 - **New recoverable codes.** A validate command the host cannot run (missing interpreter, module or executable) ends `env.tool_missing`, and a repro test the harness could not run on head ends `env.repro_unrunnable`. Both were terminal `conformance.unimplemented` before. The batch runner recovers them like `ci.red` (see docs/OUTCOME-CODES.md).

package/docs/SELFTEST.md

@@ -0,0 +1,34 @@
+# Selftest
+
+The engine's unit tests mock `gh`, git and the pool transport, so defects such as #4859 (`authorAssociation` is not a gh field), #4860 (issue body wiped to `FORGE:STATE`), #4817 and #4818 passed CI. `forgedock selftest` checks the real binaries.
+
+```
+forgedock selftest --static
+forgedock selftest --live [--repo <owner/sandbox>] [--lang node|python] [--pr <staging->main PR>]
+```
+
+`--live` also runs the static check. The sandbox repo comes from `--repo` or `selftest.sandbox_repo` in forge.yaml ([CONFIG.md](CONFIG.md#selftest-optional)). Run it on the host or the pool, not in GitHub Actions. The exit code is non-zero and the output names the failed step.
+
+## Static check
+
+Every literal `gh issue|pr view|list --json a,b` field list in non-test `bin/**/*.mjs` must be a subset of the `JSON FIELDS` of `gh <cmd> --help` on this host. A violation is reported as `file:line`.
+
+## Live steps
+
+1. **create**: the fixture base files, then issues A and B (B has `**Depends on**: #A`), each a trivial change with a test that fails on the old code.
+2. **add**: `orchestrate A --parallel 2`, then `orchestrate --add <id> B`; B must be added (not skipped or unreadable) and wait on A in the DAG.
+3. **body**: after the add, after the resume and while waiting, each issue body must still contain its creation text (`FORGE:STATE` ignored).
+4. **resume**: the orchestrate client is killed and `--resume`d; the live lane of A must be re-adopted, not launched again.
+5. **merge**: both lanes merge; the PRs are `MERGED`, the issues closed with `workflow:merged`, and A merged before B.
+6. **remote**: with `execution.mode` `remote` or `hybrid`, one lane runs remotely; the sandbox engine version must equal the CLI version and the lane must authenticate. Skipped (noted) when no pool is configured.
+7. **cleanup**: always runs, even after a failure: the orchestrate client is stopped; the issues, PRs and branches are closed or deleted.
+
+The first failing step stops the run.
+
+## Release gate
+
+With `--pr N`, the PR head is read before the run (from `--release-repo`, else the current repo), and the result is posted on the PR as `<!-- FORGE:SELFTEST result=pass|fail sha=<head> step=<failed step|none> -->`. When forge.yaml sets `selftest.sandbox_repo`, `forgedock review-staging` reads the newest marker and refuses (`REVIEW_RESULT: status: BLOCKED`, nothing reviewed) unless it is a pass for the PR's current head. Only markers from trusted commenters count (maintainer association, a GitHub App bot, or `FORGE_TRAIL_TRUSTED_LOGINS`), and only when the marker leads the comment. A push after the selftest makes the marker stale: re-run it. The harness refuses a sandbox repo that is the project repo (forge.yaml `project`) or the release repo. Without `selftest.sandbox_repo` the gate is skipped and the CLI prints `SELFTEST: skipped` on stderr.
+
+## Nightly run
+
+Off by default. Set `selftest.nightly_interval_hours` (see [CONFIG.md](CONFIG.md#selftest-optional)) and the schedd daemon starts `selftest --live --nightly-report <repo>` on the host, as a detached process, once that many hours have passed since that repo's last run (last run time cached per repo in `selftest-nightly-<owner>_<repo>.json` under the sched dir). The daemon never runs the harness itself, so a long run never holds its other sweeps. It never runs on GitHub Actions. A failing run, including one that cannot start (for example no `selftest.sandbox_repo`, step `config`) or a harness crash, files one issue titled `selftest --live failed at step <step> (nightly)` carrying `<!-- FORGE:SELFTEST_NIGHTLY -->`; the next failure edits that open issue instead of filing another. A passing run writes nothing. The issue lives in the repo schedd resolves for the working directory, and the sandbox repo must be set by `selftest.sandbox_repo`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.41.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

package/scripts/review-staging-pre.test.sh

@@ -162,7 +162,48 @@ grep -q '^SCOPE_MODE=scoped$' "$TMP/sd/9_scope.env" && grep -q '^5 a.js$' "$TMP/
 case "$OUT" in *"SCOPE_MODE=scoped reviewed_prs=1"*) ok ;; *) bad "scope must print the one-line summary" ;; esac
 newfix scopefail
 run scope --repo o/r --default main --staging staging --pr 9 --prs-file "$TMP/prs" --sd "$TMP/sd" >/dev/null 2>&1
-[ "$(jq -r .scope_mode "$TMP/sd/9_scope.json" 2>/dev/null)" = full ] && ok || bad "a failed gh pr view must widen scope to full"
+J="$TMP/sd/9_scope.json"
+[ "$(jq -r .scope_mode "$J" 2>/dev/null)" = scoped ] && jq -e '.degraded_prs == [5] and .reviewed_pr_count == 0' "$J" >/dev/null 2>&1 && ok || bad "a failed gh pr view must degrade only that PR (scoped, degraded_prs [5]; got $(jq -c . "$J" 2>/dev/null))"
+
+# (6) #4960: one PR's reads fail permanently, the others stay credited and scoped
+newfix onefail; H6=${FEAT:0:7}
+for n in 5 6; do
+  jq -n --arg h "$FEAT" --arg m "$MERGE" '{headRefOid:$h,mergeCommit:{oid:$m},commits:[{oid:$h}],state:"MERGED",baseRefName:"staging",labels:[]}' > "$FIX/pr-$n.json"
+  printf '%s.js\n' "f$n" > "$FIX/files-$n"
+  jq -n --arg r "<!-- FORGE:REVIEW_ROUTE mode=single-pr spec=review-pr.md sha=$H6 -->" \
+    --arg g "$(printf '<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: %s\n\n<!-- REVIEW-FINDINGS-START -->\n<!-- REVIEW-FINDINGS-END -->' "$FEAT")" \
+    '[{body:$r,author_association:"NONE",user:{type:"Bot",login:"b"}},{body:$g,author_association:"NONE",user:{type:"Bot",login:"b"}}]' > "$FIX/comments-$n.json"
+done
+rm -f "$FIX/files-6"   # `gh pr diff 6` fails on every attempt
+printf '5\n6\n' > "$TMP/prs56"
+OUT=$(run scope --repo o/r --default main --staging staging --pr 9 --prs-file "$TMP/prs56" --sd "$TMP/sd" 2>&1)
+J="$TMP/sd/9_scope.json"
+[ "$(jq -r .scope_mode "$J" 2>/dev/null)" = scoped ] && jq -e '.degraded_prs == [6] and .reviewed_pr_count == 1' "$J" >/dev/null 2>&1 && ok || bad "one failed PR must leave the other scoped and credited (got $(jq -c . "$J" 2>/dev/null); $OUT)"
+case "$OUT" in *"scope degraded for PR #6"*) ok ;; *) bad "the degraded PR must be named (got $OUT)" ;; esac
+case "$OUT" in *"fell open"*) bad "must not fall open on one failed PR" ;; *) ok ;; esac
+grep -q '^5 f5.js$' "$TMP/sd/9_bundle-pr-files.txt" && ! grep -q '^6 ' "$TMP/sd/9_bundle-pr-files.txt" && ok || bad "files of the healthy PR kept, none for the degraded PR"
+
+# (7) #4960: a synthetic 300-PR bundle completes quickly, in parallel, with progress output
+newfix bigbundle
+seq 1000 1299 > "$TMP/prs300"
+for n in $(seq 1000 1299); do
+  jq -n --arg h "$FEAT" --arg m "$MERGE" '{headRefOid:$h,mergeCommit:{oid:$m},commits:[{oid:$h}],state:"MERGED",baseRefName:"staging",labels:[]}' > "$FIX/pr-$n.json"
+  printf 'f%s.js\n' "$n" > "$FIX/files-$n"
+done
+T0=$SECONDS
+OUT=$(FORGE_SCOPE_PARALLELISM=8 run scope --repo o/r --default main --staging staging --pr 9 --prs-file "$TMP/prs300" --sd "$TMP/sd" 2>&1); RC=$?
+EL=$((SECONDS-T0))
+J="$TMP/sd/9_scope.json"
+[ "$RC" -eq 0 ] && [ "$(jq -r .scope_mode "$J" 2>/dev/null)" = scoped ] && [ "$(grep -c '^[0-9]* f' "$TMP/sd/9_bundle-pr-files.txt")" -eq 300 ] && ok || bad "300-PR scope must finish scoped with 300 file rows (rc $RC)"
+[ "$EL" -lt 300 ] && ok || bad "300-PR scope took ${EL}s (limit 300s)"
+case "$OUT" in *"250/300"*) ok ;; *) bad "progress output expected for a long scope (got $(printf '%s' "$OUT" | head -3))" ;; esac
+
+# (8) #4960: a PR/issue kind lookup is cached in the scratch dir, so a rerun makes no gh call for it
+newfix kindcache; echo 1 > "$FIX/issue-77"
+K1=$(cd "$TMP/work" && _SD="$TMP/kc" bash -c 'FORGE_GH_RETRY_SLEEP=0; . <(awk "/^# BEGIN gh-retry\$/{f=1;next} /^# END gh-retry\$/{f=0} f" "$1"); . <(awk "/^# BEGIN bundle-pr-kind\$/{f=1;n++;next} /^# END bundle-pr-kind\$/{f=0} f&&n==1" "$1"); bundle_pr_kind o/r 77' _ "$PRE")
+rm -f "$FIX/issue-77"
+K2=$(cd "$TMP/work" && _SD="$TMP/kc" bash -c 'FORGE_GH_RETRY_SLEEP=0; . <(awk "/^# BEGIN gh-retry\$/{f=1;next} /^# END gh-retry\$/{f=0} f" "$1"); . <(awk "/^# BEGIN bundle-pr-kind\$/{f=1;n++;next} /^# END bundle-pr-kind\$/{f=0} f&&n==1" "$1"); bundle_pr_kind o/r 77' _ "$PRE")
+[ "$K1" = issue ] && [ "$K2" = issue ] && ok || bad "kind lookup must be answered from the cache on rerun (got '$K1' '$K2')"
 
 echo "review-staging-pre.test.sh: passed=$PASS failed=$FAILN"
 [ "$FAILN" -eq 0 ]