@codedology/code-forge 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,48 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-10-04
+
+### Changed
+
+- Docs: README "What's new in 0.5" (with the bench numbers), the 0.5 config keys marked, how to install a tagged release
+  before it is on npm (getting-started), and how maintainers update their own install after a release (releasing).
+
+## [0.5.0] — 2026-10-04
+
+### Added
+
+- Per-provider session limit `review.provider_concurrency` (defaults anthropic 4, openai 2, xai 2) and rate-limit
+  backoff: a rate-limited session waits about 2 s, then about 6 s (±30 %), before retrying the same step, instead of
+  retrying at once. New in-process keyed locks and semaphores (`src/util/locks.mjs`) prepare parallel review.
+- Parallel review in the worker: `review.parallel_tickets` (1–16, default 3) review tickets run at once, oldest first.
+  The same file is never reviewed twice at once; a block's budget row and its one L3 rung are taken under a block lock;
+  a crashed ticket never stops the others; on stop, running tickets finish. `run reload` can change the pool size. `1`
+  keeps the serial behaviour.
+- `code-forge doctor` shows a `review concurrency` row (tickets at once and provider slots); maintainers can measure the
+  pool with `npm run bench:review` (6 fake 2 s reviews: about 12 s at 1, about 4 s at 3).
+
+### Changed
+
+- Skill: a plan that passed `plan check` is shown to the owner for approval in the harness's plan mode (Claude Code:
+  EnterPlanMode → plan file → ExitPlanMode); no block is dispatched before that approval.
+- `budget.usd` holds when sessions start together: each session reserves its estimated cost under one lock (after taking
+  its provider slot) and releases it when its row is written or it fails. A refusal caused by running sessions says how
+  much they hold and this session's estimate; a session whose estimate alone is above the budget says so.
+- `code-forge review` enqueues every file first, then waits on all of them together under ONE deadline for the whole run
+  (`--max`, default 900 s, now a run deadline, not per file), prints each result on stderr as it finishes, and keeps the
+  final table in file order. At most 8 wait children run at once.
+
+### Fixed
+
+- `code-forge facts` verified nothing: delegates echo claims as `<kind>: <token>` and every answer was dropped as "no
+  answer". Answers now match by that form or by fact id (one answer per claim); a check that breaks the read-only rules,
+  or a silent command (`test`, `grep -q`), marks only that claim unverifiable with the reason instead of refusing the
+  whole sheet; the `<cli> <subcommand> --help | grep -c -- <flag>` check is allowed only for CLIs the brief names, never
+  interpreters or launchers.
+- Two files of one block could both take the block's single L3 patch rung (the rung was recorded only when the patch
+  check saved); a pending `next: patch` on a sibling file now counts as used.
+
 ## [0.4.0] — 2026-10-02
 
 ### Added

package/README.md

@@ -8,6 +8,20 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 > `examples/` have all landed (`docs/reference/blocks.json` lists every build block). What changed
 > in each version is in [CHANGELOG.md](CHANGELOG.md).
 
+## What's new in 0.5
+
+- **Parallel review.** The worker reviews `review.parallel_tickets` files at once (default 3), with
+  a session limit per provider (`review.provider_concurrency`), backoff on rate limits, and
+  `budget.usd` still holding. `code-forge review` now waits on all files under one `--max`
+  deadline and prints each result as it finishes. `code-forge doctor` shows the numbers;
+  `npm run bench:review` measured 6 reviews in 12 s at 1 and 4 s at 3.
+- **`code-forge facts` verifies again.** It dropped every answer in 0.4.0; now answers match, and a check
+  that breaks the read-only rules marks only its own claim as not counted, with the reason.
+- **Clearer budget refusals.** A session refused because other running sessions hold the budget says
+  how much they hold and what this session would cost.
+- **Plan approval in plan mode.** The skill shows a checked plan to you in the harness's plan mode
+  (Claude Code: EnterPlanMode → ExitPlanMode) before any block starts.
+
 ## What's new in 0.4
 
 - **Cost control.** Set `budget.usd` per run: one warning at 80%, no new session at 100%. Every
@@ -176,7 +190,7 @@ CLI verbs like any other and every one of them is exercised by this package's ow
 
 `schema/code-forge.schema.json` is the source of truth for `.code-forge.yml`.
 [docs/reference/config.md](docs/reference/config.md) lists every key with its type and default.
-Keys added for 0.4:
+Keys added in 0.4 and 0.5 (the last two rows are new in 0.5):
 
 | Key | Default | What it does |
 |---|---|---|
@@ -188,6 +202,8 @@ Keys added for 0.4:
 | `review.multimodel_for_docs` | `false` | let docs and contract blocks use multimodel review too |
 | `review.allow_open_book_codex` | `false` | let Codex run reviewer, judge, System 2 and plan author anyway |
 | `review.session_timeout_s` | `300` | a review session that runs longer is killed and retried once |
+| `review.parallel_tickets` | `3` | review tickets the worker runs at once (1 to 16); `1` reviews one file at a time |
+| `review.provider_concurrency` | anthropic `4`, openai `2`, xai `2` | review sessions at once per provider |
 
 `code-forge block open … --kind code|docs|contract` sets a block's kind when its file endings do
 not say it. The reference page is generated:

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 40,
+  "block_count": 46,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -523,6 +523,89 @@
         "B37"
       ],
       "note": "root-added 2026-10-02"
+    },
+    "B39": {
+      "title": "facts: match answers that echo the packet form or by fact_id, one row per claim; a rule-breaking check marks only its claim UNVERIFIABLE; narrow subcommand-help form (brief-named CLIs, no interpreters or launchers); silent commands never VERIFIED",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/session/facts.mjs",
+        "src/cli/facts.mjs",
+        "test/session/facts.test.mjs"
+      ],
+      "depends_on": [
+        "B12c"
+      ],
+      "note": "root-added 2026-10-03; found by running code-forge facts on its own repo"
+    },
+    "B40": {
+      "title": "Keyed locks, per-provider session limit (review.provider_concurrency), rate-limit backoff",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "src/util/locks.mjs",
+        "test/util/locks.test.mjs",
+        "test/session/provider-limit.test.mjs"
+      ],
+      "depends_on": [
+        "B39"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B41": {
+      "title": "Budget reservation under concurrency: slot first, then check + reserve estimated cost under one lock",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/ledger/spend-concurrency.test.mjs"
+      ],
+      "depends_on": [
+        "B40"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B42": {
+      "title": "Worker ticket pool: review.parallel_tickets, same-file rule, block lock for budget row and L3 rung, sibling patch counts as rung used",
+      "wave": 10,
+      "level": "L2",
+      "status": "landed",
+      "owned": [
+        "test/worker/pool.test.mjs"
+      ],
+      "depends_on": [
+        "B41"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B43": {
+      "title": "code-forge review enqueues all files, waits together under one deadline, at most 8 waiters",
+      "wave": 10,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "test/cli/review-parallel.test.mjs"
+      ],
+      "depends_on": [
+        "B42"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
+    },
+    "B44": {
+      "title": "Parallel review docs, doctor review-concurrency row, bench:review (N=1 vs N=3)",
+      "wave": 10,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "scripts/bench-review.mjs",
+        "test/bench-review.test.mjs"
+      ],
+      "depends_on": [
+        "B43"
+      ],
+      "note": "root-added 2026-10-03; plan plans/parallel-review (approved in plan mode)"
     }
   }
 }

package/docs/reference/config.md

@@ -112,6 +112,11 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.recheck_scope` | enum: `fix_hunks`, `file` |  | `"fix_hunks"` |  |
 | `review.late_findings` | enum: `sweep`, `block` |  | `"sweep"` |  |
 | `review.allow_open_book_codex` | boolean |  | `false` | B32: let openai (Codex) run reviewer/judge/S2/author with its read-only sandbox, which can read files on this machine. Off: those sessions are refused. |
+| `review.provider_concurrency` | object |  | — |  |
+| `review.provider_concurrency.anthropic` | integer |  | `4` | min 1 |
+| `review.provider_concurrency.openai` | integer |  | `2` | min 1 |
+| `review.provider_concurrency.xai` | integer |  | `2` | min 1 |
+| `review.parallel_tickets` | integer |  | `3` | min 1; max 16; B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap. |
 | `engine` | enum: `auto`, `solo`, `harness`, `subprocess` |  | `"auto"` |  |
 | `harnesses` | array<string> |  | — |  |
 | `harness` | object |  | — |  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",
@@ -32,6 +32,7 @@
     "!scripts/release.mjs",
     "!scripts/changelog.mjs",
     "!scripts/known-fix.mjs",
+    "!scripts/bench-review.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -41,7 +42,8 @@
     "typecheck": "tsc --checkJs --noEmit",
     "release": "node scripts/release.mjs",
     "changelog": "node scripts/changelog.mjs",
-    "known-fix": "node scripts/known-fix.mjs"
+    "known-fix": "node scripts/known-fix.mjs",
+    "bench:review": "node scripts/bench-review.mjs"
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",

package/schema/code-forge.schema.json

@@ -142,7 +142,18 @@
         "max_rounds_per_file": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 },
         "recheck_scope": { "type": "string", "enum": ["fix_hunks", "file"], "default": "fix_hunks" },
         "late_findings": { "type": "string", "enum": ["sweep", "block"], "default": "sweep" },
-        "allow_open_book_codex": { "type": "boolean", "default": false, "description": "B32: let openai (Codex) run reviewer/judge/S2/author with its read-only sandbox, which can read files on this machine. Off: those sessions are refused." }
+        "allow_open_book_codex": { "type": "boolean", "default": false, "description": "B32: let openai (Codex) run reviewer/judge/S2/author with its read-only sandbox, which can read files on this machine. Off: those sessions are refused." },
+        "provider_concurrency": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "B40: how many sessions of each provider may run at once in this process; a rate-limited session waits 2 s, then 6 s (±30 %) before it retries.",
+          "properties": {
+            "anthropic": { "type": "integer", "minimum": 1, "default": 4 },
+            "openai": { "type": "integer", "minimum": 1, "default": 2 },
+            "xai": { "type": "integer", "minimum": 1, "default": 2 }
+          }
+        },
+        "parallel_tickets": { "type": "integer", "minimum": 1, "maximum": 16, "default": 3, "description": "B42: how many review tickets the worker runs at once (oldest first); 1 = one at a time. Tickets for the same file never overlap." }
       }
     },
     "engine": { "type": "string", "enum": ["auto", "solo", "harness", "subprocess"], "default": "auto" },

package/skill/SKILL.md

@@ -37,6 +37,7 @@ State lives in the plan file's header — `facts → planned → hardened → co
 1. `forge facts --brief <brief> --out <plans_dir>/<slug>.facts.md` — an L0 delegate checks every claim with a read-only command. You read the sheet; you never read the sources yourself (`references/plan.md` §0).
 2. `forge author --job plan --brief <brief> --facts <sheet> --out <plan>` — refuses without `--facts` (exit 2) and refuses a sheet older than the brief. The draft's §0 is the sheet, verbatim.
 3. Harden: `forge author --job harden --brief <brief> --facts <sheet> --draft <plan> --answers <file>` until `questions[]` is empty. The human answers; you relay, never answer for them (`references/harden.md`). Before the exit gate, record each block's lane: `forge jev ask lane --block <id> --plan <plan> --state <file>` (`--rules` without Jev); the plan's level must equal it. Exit gate: `forge plan check <plan>` green, with a lane for every block on its `lanes:` line (`references/plan.md`).
+   Then show the plan to the owner for approval in the harness's plan mode, never as chat text (Claude Code: EnterPlanMode, write the plan, ExitPlanMode); a harness without a plan mode shows it and waits for an explicit yes. No block is dispatched before that approval (`references/plan.md` §4.1).
 4. Per block, in dispatch order, never more than `caps.coders` alive: `forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> --brief <file> --lines <n> [--kind code|docs|contract]` prints the pointer `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>`. Send the pointer per the engine's adapter — `solo` → `references/adapters/solo.md`, `harness` → `references/adapters/claude-code.md`, `subprocess` → `references/adapters/subprocess.md` — and wait for `ACK <sha8> lines=<n>`.
 5. The coder's first message is its **facts diff**, then its forecast (cases and lines, `templates/block-record.md`), then code, file by file: after each file `forge review-file <path> --block <id> --run <r>`, then `forge review-file --wait <ticket>` before the next file. Rounds ≥ 2 re-check only the fix hunks (`references/review.md`).
 6. `===BLOCK <id> COMPLETE===` or `===BLOCK <id> FAILED: <reason>===` ends the coder's turn. Its report is a claim sheet: re-measure it (`references/code.md` §5).

package/skill/references/adapters/claude-code.md

@@ -14,6 +14,10 @@ The tool return is the completion signal; the report must begin with `ACK <sha8>
 
 **Between completion and close come the review rounds.** The subagent ran `forge review-file <path> --block <id> --run <r>` per file and `--wait`ed on each ticket inside its turn, so most rounds happen before the sentinel; when the tool returns, first drain every `pending` ticket with `forge review-file --wait <ticket>` yourself — a pending ticket is a review in flight, not an open finding, and waiting on it costs no round. Then only an open `fix_now` finding, or a file the coder never submitted, starts a fix round (each one counts toward the file's cap): dispatch a new `Agent` call at the level the ladder says (`review.md` §5 — the coder is gone with its tool return, so the fix brief carries the open findings and the fix history) and it runs `review-file` again on the fixed file. Rounds are bounded: four rounds per file, then the L3 rung once, then `stopped: review_cap` for the human. Only when every changed file has a signed `review.approved` row do you run the re-measurement of `code.md` §5 and `forge block close <id> --run <r> --report <file>` (the subagent's final report, saved to a file) — the transcript grep reads `.code-forge/runs/<run>/<block>.log`; pass `--transcript <file>` when the harness saved the subagent's transcript elsewhere. Closing with a file still unreviewed is a human decision: `forge block waive <id> <finding> --run <r> --file <path> --reason "<why>"` per finding, or `forge block close … --no-require-reviews`, both audited as their own rows.
 
+## §2.1 Plan approval
+
+The plan goes to the owner through plan mode (`plan.md` §4.1): `EnterPlanMode` → write the plan file → `ExitPlanMode`. The approval returned by `ExitPlanMode` is the go signal for the first `forge block open`.
+
 ## §3 What is lost and what is not
 
 Lost: live observation of the coder (only the progress log and the final report), a resumable transcript (a lost subagent is re-dispatched with the fix history in a new brief — `continuity.md` §2). Not lost: session isolation, signed rows, the gate, the ladder, the facts rule, the convergence rule (`degraded.md` §2).

package/skill/references/ledger.md

@@ -18,7 +18,9 @@ Terminal output in this version. Sections: cost per block — completed and stil
 
 Every `session` row carries `usd` (tokens × the static price table) or `usd: null, usd_unknown: true` when the provider/level has no price — never a guess; a `session.background` coder's price is always unknown. Spend code-forge never saw (a cloud or hand-run coder) goes in with `forge ledger add coder --run <r> --block <b> --usd <n> [--note "..."]`, a signed `session` row with `manual: true`. With `budget.usd` set, every session spawn first sums the run's spend: at 80 % one `budget.warning` row and one stderr line per run; at 100 % the session is refused (`budget.usd 20.00 reached (spent 20.13); raise budget.usd or end the run`), a `budget.refused` row is written, nothing is spawned, and a review reports `review.unavailable {reason: budget}`. A budget whose spend cannot be read refuses too (fail closed).
 
-Known limits, accepted: unknown-price sessions and `session.background` coders add **0** to the spent total — record their real cost with `forge ledger add coder --usd <n>`; `forge run status` shows `unknown_usd_sessions` and prints `N sessions have no known price; the budget does not count them` when N > 0. Two sessions spawned at the same moment can each write a `budget.warning` row (a rare duplicate; the warning still means the same thing).
+Sessions that run at the same time (B41): each session first takes its provider slot, then — under one in-process lock per run — reads the spend, checks it and reserves its estimated cost (the packet's bytes / 4 in, plus a fixed tokens_out per role and level, priced with the same table; a session waiting for a slot reserves nothing). A session is refused when spent + reserved by running sessions + its own estimate passes the budget: `budget.usd 20.00 would be exceeded: spent 3.10, reserved by running sessions 15.80, this session about 1.92; it starts when running sessions finish or when budget.usd is raised`, or, when its estimate alone is above the budget, `this session's estimated cost (about 64.00) is above budget.usd 20.00; raise budget.usd`; the `budget.refused` row then carries `reserved_usd` and `estimate_usd`. The reservation is released when the session's row is written, or when the spawn fails or throws. The 80 % warning is checked under the same lock, so it is written once per run.
+
+Known limits, accepted: unknown-price sessions and `session.background` coders add **0** to the spent total — record their real cost with `forge ledger add coder --usd <n>`; a background coder's reservation is released at its start row, since its cost is never seen; a session refused because of running sessions' reservations is refused, not queued — run it again once they finish; `forge run status` shows `unknown_usd_sessions` and prints `N sessions have no known price; the budget does not count them` when N > 0. The lock and the reservations live in one process only: two separate code-forge processes starting a session of one run at the same moment can still each pass the check or each write a `budget.warning` row.
 
 ## §4 Calibration — `forge ledger calibration --slug <slug> [--question <id>]`
 

package/skill/references/plan.md

@@ -38,6 +38,15 @@ Every clause of the parent's acceptance maps to exactly one block; an unmapped c
 
 Prints every failing row by name and exits 1 on any of: an acceptance clause with a claim token that resolves to no VERIFIED fact and no tolerance row (`unbackable clause without tolerance: <block> <clause>`); a missing caller map or a block absent from it; a block without `cases` and `lines`; a forecast above `budget.block_cases` / `budget.block_lines` without a named split; overlapping `owned_files` in one wave; a cyclic `depends_on` or an import of a batch-mate; a glob with `[ ] ( ) ! + @`; more than `caps.coders` concurrent blocks in a slot; `questions[]` still open; the facts sheet's sha absent from the draft; a block whose level has no recorded lane, or differs from it (`block <id>: level L2 differs from the recorded lane L1 (jev)`). A required section under a near-miss heading at its template position (§0.x, §3) passes with a `WARN` naming the exact heading. stdout ends with the lane recorded per block (`lanes: B1 L1 (jev) · B2 L0 (rules)`). Green ⇒ set `status: hardened` after the harden job (`harden.md`), never before.
 
+### §4.1 Owner approval in plan mode
+
+A plan that passed `forge plan check` still needs the owner's yes before any block is dispatched. Show it in the harness's plan mode so the owner reviews the whole plan in one place and approves or edits it there:
+
+- **Claude Code:** call `EnterPlanMode`, write the plan (context, blocks with their levels and lanes, dispatch order, risks, verification) to the plan file, then call `ExitPlanMode`. Its approval is the go signal; a rejection or an edit sends you back to `harden`.
+- **A harness without a plan mode:** print the plan's §1–§4 and §6 and wait for an explicit yes. Silence is not approval.
+
+Never treat a chat summary of the plan as the approval step, and never start `forge block open` before it.
+
 ## §5 Cost
 
 One L0 session per plan for the facts (typically a claim list of 40–80 items) and one L3 session per author round; `forge report --slug <slug>` shows both as `facts $` and coder/review splits.

package/skill/references/review.md

@@ -44,6 +44,10 @@ Two L2 reviewers, one per effective provider (`resolve(L2)` and `review.second_l
 
 `review.block_budget_tokens` (and optionally `review.block_budget_usd`) bounds every review, recheck, judge and S2 session made for the block. When the forecast exceeds it the worker degrades one step at a time, cheapest first: batch small files of one tier into one packet (`review.batch_small_files`) → one judge per block instead of per file → standard band `full` → `quick` → high tier `A + B + judge` → one `full` L2 + judge, the floor. Tools-only is never a review; a light `quick` stays `quick`. Still over ⇒ `review.over_budget`: raise the budget once per run (a config edit by the human, on record) or split the block — never silently, never below the floors. The ledger keeps `depth_unconstrained` and `depth_chosen` per file so `forge report` can show `missed_after_degrade`.
 
+## §7a Parallel tickets
+
+The worker runs `review.parallel_tickets` (1–16, default 3) tickets at once, oldest first; a finished ticket frees its slot for the next pending one. It never reviews the same (block, file) twice at once: a ticket for a file that is already in review stays pending without taking a slot. The budget row and the block's one L3 rung are taken under the **block lock**, so two files of one block cannot both take the rung. Each session also takes a provider slot (`review.provider_concurrency`, defaults anthropic 4 · openai 2 · xai 2) and reserves its estimated cost under a lock (`budget.usd`). A rate-limited session backs off about 2 s, then 6 s, before retrying the same step. A throw in one ticket is that ticket's `unavailable`; on stop, running tickets finish. `1` is the serial worker. The orchestrator needs no change: it still calls `review-file` per file and waits on the tickets.
+
 ## §8 Review only
 
-A human who wants a review and nothing else runs `forge review`: it reviews the changed files in one `R-<timestamp>` block at L2, prints the verdicts, then stops the block and ends the run — no plan, no coder, no proof, never a close. Inside a block the orchestrator keeps using `forge review-file`.
+A human who wants a review and nothing else runs `forge review`: it reviews the changed files in one `R-<timestamp>` block at L2, prints each verdict as it finishes (all files wait together under one `--max` deadline, default 900 s), then stops the block and ends the run — no plan, no coder, no proof, never a close. Inside a block the orchestrator keeps using `forge review-file`.

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.4.0"
+PINNED_VERSION="0.5.1"
 set -eu
 
 self="$0"

package/src/cli/facts.mjs

@@ -16,7 +16,7 @@ import { buildFacts, FactsError } from '../session/facts.mjs';
 import { runRootFor, SessionError } from '../session/spawn.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
-import { writeSafe } from '../util/redact.mjs';
+import { redact, writeSafe } from '../util/redact.mjs';
 import { slugFor } from './run.mjs';
 import { exitCodeFor } from './spawn.mjs';
 
@@ -34,6 +34,19 @@ function readable(file, { fileOnly = false } = {}) {
   }
 }
 
+/**
+ * One stderr line for a downgraded row: the id must be `F<n>` (else `F?`), the reason is redacted
+ * and every control character (newlines included) becomes a space, so a row is always one line.
+ * @param {{fact_id: string, reason: string}} d
+ * @returns {string}
+ */
+export function downgradeLine(d) {
+  const id = /^F\d+$/.test(String(d.fact_id)) ? d.fact_id : 'F?';
+  // eslint-disable-next-line no-control-regex
+  const reason = redact(String(d.reason).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
+  return `facts: ${id} not counted — ${reason}\n`;
+}
+
 const USAGE = 'usage: code-forge facts --brief <file> [--sources <path>...] [--out <file>] [--run <id>] [--timeout <seconds>]\n';
 
 /**
@@ -107,6 +120,8 @@ export async function runFactsVerb(args, deps = {}) {
       return exitCodeFor(result);
     }
     const facts = result.facts ?? [];
+    // B39: a row whose check broke a rule is kept as UNVERIFIABLE (not counted); say so, exit 0
+    for (const d of result.downgraded ?? []) writeSafe(stderr, downgradeLine(d));
     writeSafe(stdout, `${JSON.stringify({ out: outPath, claims: result.claims.length, verified: facts.filter((f) => f.tag === 'VERIFIED').length })}\n`);
     return 0;
   } catch (err) {

package/src/cli/review.mjs

@@ -16,7 +16,9 @@
  *    default clause. A generated file lives in this command's temp root, never in the tree.
  * 4. Flow, every step a `code-forge` child with a `GIT_*`-free env: `run start` (launches the
  *    worker) → `block open R-<stamp> --level L2 --base <sha> --owned <files…>` → `review-file`
- *    per file → `review-file --wait` per ticket (`--max`, default 900 s per file) → summary →
+ *    per file (all enqueued first) → one `review-file --wait` per ticket, all together under ONE run
+ *    deadline (`--max`, default 900 s for the whole review; a ticket pending at the deadline is
+ *    reported `stopped: timeout`, exit 1), results announced on stderr as they finish → summary in file order →
  *    `block stop` (a review never closes a block) → `run end` unless `--keep-run`. The cleanup runs
  *    in a `finally`, on SIGINT/SIGTERM and after a timeout, and no worker outlives the command.
  *    Each cleanup step is independent (a failed or throwing step is reported on stderr and the
@@ -42,6 +44,7 @@ import { parseFlags } from '../state/cli-args.mjs';
 import { assertRunId, newRunId, StateError } from '../state/paths.mjs';
 import { processStartTime, readRun } from '../state/run.mjs';
 import { exec } from '../util/exec.mjs';
+import { semaphore } from '../util/locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { isAlive, listEntries, readStartTime, UNKNOWN_START_TIME } from '../util/reaper.mjs';
 import { pidsDir, runRoot, setRunRoot, tmpBase } from '../util/tmp.mjs';
@@ -54,6 +57,8 @@ export const USAGE =
   'usage: code-forge review [--base <ref>] [--files <path…>] [--acceptance <file> | --intent "<text>"] [--run <id>] [--max <seconds>] [--json] [--keep-run]\n';
 
 export const DEFAULT_MAX_S = 900;
+/** The most `review-file --wait` children that run at once. */
+export const MAX_WAITERS = 8;
 export const DEFAULT_CLAUSE = 'Review for correctness, security and test quality; no intent was stated.';
 const GIT_TIMEOUT_MS = 30_000;
 const STEP_TIMEOUT_MS = 120_000;
@@ -511,14 +516,40 @@ export async function runReview(args, deps = {}) {
       const answer = lastJSON(res.stdout);
       queued.push({ file, ticket: typeof answer?.ticket === 'string' ? answer.ticket : null, answer });
     }
-    for (const q of queued) {
-      if (q.ticket === null) {
-        outcomes.push(classify(q.file, { status: q.answer?.status ?? 'refused', reason: q.answer?.reason ?? q.answer?.status ?? 'not queued' }));
-        continue;
-      }
-      const res = await cf(['review-file', '--wait', q.ticket, '--max', `${maxS}s`], maxS * 1000 + 60_000);
-      outcomes.push(classify(q.file, lastJSON(res.stdout)));
-    }
+    // Every file is enqueued above before any wait starts. One run deadline (`--max`, measured from
+    // here) covers all the waits, which run together: each `review-file --wait` gets the time still
+    // left, and a ticket still pending at the deadline is reported `stopped: timeout`. A result is
+    // announced on stderr as its file finishes; the table below keeps the file order.
+    // At most MAX_WAITERS `review-file --wait` children at once (a review of many files must not
+    // start one Node process per file); a wait that starts late still counts down to the same
+    // deadline, and one that starts after it is reported pending without a child.
+    const deadline = Date.now() + maxS * 1000;
+    const waiters = semaphore(MAX_WAITERS);
+    /** @type {Array<FileOutcome | undefined>} */
+    const byIndex = new Array(queued.length);
+    const finish = (/** @type {number} */ i, /** @type {FileOutcome} */ o) => {
+      byIndex[i] = o;
+      note(`${o.file}  ${label(o)}`);
+    };
+    const settled = await Promise.allSettled(
+      queued.map(async (q, i) => {
+        if (q.ticket === null) {
+          finish(i, classify(q.file, { status: q.answer?.status ?? 'refused', reason: q.answer?.reason ?? q.answer?.status ?? 'not queued' }));
+          return;
+        }
+        await waiters.run(async () => {
+          const left = deadline - Date.now();
+          if (left <= 0) {
+            finish(i, classify(q.file, { status: 'pending' }));
+            return;
+          }
+          const res = await cf(['review-file', '--wait', q.ticket, '--max', `${Math.ceil(left / 1000)}s`], left + 60_000);
+          finish(i, classify(q.file, lastJSON(res.stdout)));
+        });
+      }),
+    );
+    for (const s of settled) if (s.status === 'rejected') throw s.reason;
+    for (const o of byIndex) outcomes.push(/** @type {FileOutcome} */ (o));
     const allOk = outcomes.every((o) => o.result === 'approved' || o.result === 'unchanged');
     code = allOk ? 0 : 1;
     if (json) out(`${JSON.stringify({ ok: allOk, base: base.sha, base_from: base.from, run: runId, block: blockId, files: outcomes, skipped, totals: totals(outcomes) })}\n`);

package/src/doctor/index.mjs

@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkTmp, checkTools } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkTmp, checkTools } from './local.mjs';
 import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -68,6 +68,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
   rows.push(...checkTmp(cfg));
+  rows.push(checkReviewConcurrency(cfg));
   if (!cfg) {
     rows.push(row('probes', 'FAIL', 'probes', 'skipped: no valid config'));
     rows.push(SIGNER_ROW);

package/src/doctor/local.mjs

@@ -17,8 +17,10 @@ import { missingTools } from '../install/tools.mjs';
 import { OP_MESSAGES } from '../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { ledgerDir } from '../ledger/paths.mjs';
+import { DEFAULT_PROVIDER_CONCURRENCY, providerLimit } from '../session/spawn.mjs';
 import { listEntries } from '../util/reaper.mjs';
 import { ownerState, tmpBase } from '../util/tmp.mjs';
+import { parallelTickets } from '../worker/loop.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
@@ -188,3 +190,16 @@ export function checkTmp(cfg) {
   const detail = `${roots} stale roots, ${pids} stale pids`;
   return [row('tmp', roots + pids > 0 ? 'WARN' : 'OK', 'tmp', roots + pids > 0 ? `${detail} (the next code-forge run start removes them)` : detail)];
 }
+
+/**
+ * B44: the `review concurrency` INFO row — how many review tickets run at once and each provider's
+ * session slots, from the effective config (defaults when a key is unset). Never throws.
+ * @param {Record<string, any> | null} cfg @returns {import('./rows.mjs').Row}
+ */
+export function checkReviewConcurrency(cfg) {
+  const c = cfg ?? {};
+  const n = parallelTickets(c);
+  const extra = Object.keys(c.review?.provider_concurrency ?? {}).filter((p) => !Object.hasOwn(DEFAULT_PROVIDER_CONCURRENCY, p));
+  const slots = [...Object.keys(DEFAULT_PROVIDER_CONCURRENCY), ...extra].map((p) => `${p} ${providerLimit(c, p)}`).join(' · ');
+  return row('review-concurrency', 'INFO', 'review concurrency', `${n} ${n === 1 ? 'ticket' : 'tickets'} at once; provider slots ${slots}`);
+}