@codedology/code-forge 0.4.0 → 0.5.1

package/src/session/spawn.mjs

@@ -16,7 +16,15 @@
  * Retry ladder (§5.6, V9): step 0 is the level's own model; step `k + 1` is `fallback[k]`. For a
  * Claude coder, `fallback[0]` (same provider) rides on `--fallback-model` inside step 0 and is not
  * spawned again. A step that reports unavailability (CLI missing, login expired, HTTP 402, or
- * rate-limited twice in a row) hands over to the next step; any other failure is final.
+ * rate-limited three times in a row) hands over to the next step; any other failure is final.
+ *
+ * Provider slots and backoff (B40): every attempt holds one slot of the module-level semaphore of
+ * its step's provider (`review.provider_concurrency[provider]`, defaults anthropic 4, openai 2,
+ * xai 2) for as long as the attempt runs, and frees it on every exit path. B41: the slot is taken
+ * FIRST, then the budget gate (check + reservation under the run's lock) runs; a refused session
+ * frees its slot at once, and a session waiting for a slot holds no reservation. A rate-limited attempt frees its slot, waits
+ * `RATE_LIMIT_BACKOFF_MS` (2 s, then 6 s, each ±30 % jitter) and tries the same step again; after
+ * the second wait a third rate limit moves the ladder to the next step.
  *
  * Every spawn prints `level=<Lx> provider=<p> model=<id> effort=<e> fallback_step=<n>` on stderr,
  * and every attempt writes one ledger row (`event: session`) with `tokens_source` `reported` when
@@ -47,10 +55,11 @@ import { removeCodexHome } from '../engines/codex-home.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { parseSentinel } from '../engines/sentinel.mjs';
 import { parseUsage } from '../engines/usage-parse.mjs';
-import { budgetUsdOf, checkBudget, priceSession, SPEND_UNREADABLE_MESSAGE } from '../ledger/spend.mjs';
+import { budgetUsdOf, checkBudget, estimateSessionUsd, priceSession, reservedUsd, reserveBudget, SPEND_UNREADABLE_MESSAGE, withBudgetLock } from '../ledger/spend.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { exec } from '../util/exec.mjs';
 import { isForbidden, mergeForbidden } from '../util/forbidden.mjs';
+import { semaphore } from '../util/locks.mjs';
 import { readStartTime, registerPid, UNKNOWN_START_TIME } from '../util/reaper.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { currentRunRoot, pidsDir, runRoot, tmpBase, untrustedReason } from '../util/tmp.mjs';
@@ -64,6 +73,57 @@ export const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
 /** Unavailability reasons that move the ladder to the next step (§5.6). */
 export const UNAVAILABLE_REASONS = Object.freeze(['cli-missing', 'login-expired', 'http-402', 'rate-limited']);
 
+/** B40: concurrent sessions per provider when `review.provider_concurrency` does not say. */
+export const DEFAULT_PROVIDER_CONCURRENCY = Object.freeze({ anthropic: 4, openai: 2, xai: 2 });
+
+/** B40: the waits before each retry of a rate-limited step (ms, before jitter); its length is the retry count. */
+export const RATE_LIMIT_BACKOFF_MS = Object.freeze([2000, 6000]);
+
+/** B40: each backoff wait is its base ±30 %. */
+export const RATE_LIMIT_JITTER = 0.3;
+
+/**
+ * B40: the session limit of `provider` — `review.provider_concurrency[provider]` when it is an
+ * integer ≥ 1, else the default (1 for a provider with no default).
+ * @param {Record<string, any>} cfg @param {string} provider @returns {number}
+ */
+export function providerLimit(cfg, provider) {
+  const set = /** @type {any} */ (cfg)?.review?.provider_concurrency?.[provider];
+  if (Number.isInteger(set) && set >= 1) return set;
+  return Object.hasOwn(DEFAULT_PROVIDER_CONCURRENCY, provider) ? DEFAULT_PROVIDER_CONCURRENCY[/** @type {"anthropic"|"openai"|"xai"} */ (provider)] : 1;
+}
+
+/** @type {Map<string, import('../util/locks.mjs').Semaphore>} one semaphore per (provider, limit), created on first use. */
+const providerSemaphores = new Map();
+
+/**
+ * B40: the in-process semaphore holding `provider`'s session slots at `limit`.
+ * @param {string} provider @param {number} limit
+ * @returns {import('../util/locks.mjs').Semaphore}
+ */
+export function providerSemaphore(provider, limit) {
+  const key = `${provider}:${limit}`;
+  let sem = providerSemaphores.get(key);
+  if (sem === undefined) {
+    sem = semaphore(limit);
+    providerSemaphores.set(key, sem);
+  }
+  return sem;
+}
+
+/**
+ * B40: the wait before retry number `n` (0-based) of a rate-limited step: the base ±30 %, from
+ * `random` in [0, 1) (0.5 gives the base exactly).
+ * @param {number} n @param {() => number} random @returns {number}
+ */
+export function backoffMs(n, random) {
+  const base = RATE_LIMIT_BACKOFF_MS[n];
+  return Math.round(base * (1 + RATE_LIMIT_JITTER * (2 * random() - 1)));
+}
+
+/** @param {number} ms @returns {Promise<void>} */
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 /** An error the spawner raises before anything runs (`code`: `usage`, `forbidden`, `closed-book`). */
 export class SessionError extends Error {
   /** @param {string} code @param {string} message */
@@ -445,6 +505,8 @@ function childEnv(/** @type {NodeJS.ProcessEnv} */ env) {
  *   `budget.usd` check reads (default: `readAllRows(opts.slug)`).
  * @property {{write: (s: string) => unknown}} [stderr]
  * @property {NodeJS.ProcessEnv} [env]
+ * @property {(ms: number) => Promise<unknown>} [sleep] - B40: the rate-limit backoff wait (tests: a recorder).
+ * @property {() => number} [random] - B40: the backoff jitter source, in [0, 1) (default `Math.random`).
  */
 
 /**
@@ -569,11 +631,51 @@ export async function spawnSession(opts, deps = {}) {
   if (opts.background) steps.length = 1;
 
   const attempts = [];
-  let rateLimitedOnce = false;
+  const sleep = deps.sleep ?? realSleep;
+  const random = deps.random ?? Math.random;
+  let rateLimitWaits = 0; // backoff waits taken on the current step
   for (let i = 0; i < steps.length; i += 1) {
     const step = steps[i];
-    const refused = await budgetGate(opts, deps, writeRow, stderr);
-    if (refused) return { ...refused, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
+    // B40/B41: the provider slot first, then the budget gate — a session queued for a slot never
+    // holds a reservation; a refusal frees the slot at once (the `finally` below)
+    const releaseSlot = await providerSemaphore(step.provider, providerLimit(cfg, step.provider)).acquire();
+    /** @type {number | null} */
+    let waitMs = null;
+    try {
+      const gate = await budgetGate(opts, deps, writeRow, stderr, step);
+      if (gate.refused) return { ...gate.refused, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
+      // B41: the reservation is released once the row is written (inside runAttempt) and, as a net,
+      // in the `finally` below on every other exit path (a throw, a background start)
+      const releaseReservation = gate.release;
+      try {
+        const outcome = await runAttempt(step, i + 1 === steps.length, releaseReservation);
+        if (outcome.result) return outcome.result;
+        waitMs = outcome.waitMs;
+      } finally {
+        releaseReservation();
+      }
+    } finally {
+      releaseSlot();
+    }
+    if (waitMs !== null) {
+      // B40: the slot is free while we wait; the same step is tried again (through the budget gate)
+      writeSafe(stderr, `rate-limited: provider=${step.provider} model=${step.model} retry in ${(waitMs / 1000).toFixed(1)} s\n`);
+      await sleep(waitMs);
+      i -= 1;
+      continue;
+    }
+    rateLimitWaits = 0;
+  }
+  throw new Error('spawnSession: unreachable — the ladder always has a step');
+
+  /**
+   * One attempt of `step` (the caller holds its provider slot).
+   * @param {ReturnType<typeof ladderFor>[number]} step @param {boolean} isLast - no step after this one.
+   * @param {() => void} releaseReservation - B41: called as soon as the session row is written.
+   * @returns {Promise<{result: SessionResult | null, waitMs: number | null}>} a `result` ends the
+   *   session; otherwise `waitMs` = back off and retry the step, null = go to the next step.
+   */
+  async function runAttempt(step, isLast, releaseReservation) {
     const sessionDir = path.join(runRootDir, 'sessions', `${role}-${Date.now()}-${randomBytes(4).toString('hex')}`);
     mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
     let keep = false;
@@ -594,8 +696,12 @@ export async function spawnSession(opts, deps = {}) {
         // background session's home stays until the run root is swept.
         const bg = startBackground(built, sessionDir, runRootDir, { ...childEnv(deps.env ?? process.env), ...(built.env ?? {}) });
         // a detached child's tokens are never read back: its price is unknown (use `ledger add coder`)
-        if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started', usd: null, usd_unknown: true });
-        return { status: 'started', ...bg, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
+        try {
+          if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started', usd: null, usd_unknown: true });
+        } finally {
+          releaseReservation();
+        }
+        return { waitMs: null, result: { status: 'started', ...bg, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts } };
       }
 
       const attempt = await runForeground(built, opts, deps);
@@ -611,21 +717,24 @@ export async function spawnSession(opts, deps = {}) {
         duration_ms: attempt.duration_ms,
         ...(level === 'L3' && step.fallback_step > 0 ? { l3_fallback: true } : {}),
       };
-      if (writeRow) await writeRow(row);
+      try {
+        if (writeRow) await writeRow(row);
+      } finally {
+        releaseReservation(); // B41: the row now carries the spend (or the write failed)
+      }
       attempts.push({ fallback_step: step.fallback_step, provider: step.provider, model: step.model, status: attempt.status, reason: attempt.reason ?? null });
-      if (attempt.status === 'unavailable' && attempt.reason === 'rate-limited' && !rateLimitedOnce) {
-        rateLimitedOnce = true; // rate-limited once: the same step gets one more try (§5.6 "twice in a row")
-        i -= 1;
-        continue;
+      if (attempt.status === 'unavailable' && attempt.reason === 'rate-limited' && rateLimitWaits < RATE_LIMIT_BACKOFF_MS.length) {
+        // B40: back off (2 s, then 6 s, ±30 %) and try the same step again — never at once
+        const waitMs = backoffMs(rateLimitWaits, random);
+        rateLimitWaits += 1;
+        return { waitMs, result: null };
       }
-      rateLimitedOnce = false;
-      if (attempt.status === 'unavailable' && i + 1 < steps.length) continue;
-      return { ...attempt, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, row, attempts };
+      if (attempt.status === 'unavailable' && !isLast) return { waitMs: null, result: null };
+      return { waitMs: null, result: { ...attempt, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, row, attempts } };
     } finally {
       if (!keep) rmSync(sessionDir, { recursive: true, force: true });
     }
   }
-  throw new Error('spawnSession: unreachable — the ladder always has a step');
 }
 
 /**
@@ -647,14 +756,49 @@ function sessionUsd(provider, level, usage) {
  * read throws) the session is refused too. It sits at the top of the ladder loop, so every attempt
  * — each fallback step, the rate-limit retry of a step, and every `spawnSession` call a caller
  * makes again (B30's timeout retry) — passes it.
+ *
+ * B41: with a budget, the ledger read, the check and the reservation of this attempt's estimated
+ * cost (`estimateSessionUsd`: the packet's bytes / 4 in, a fixed tokens_out per role and level)
+ * run under the run's budget lock, so concurrent sessions of one run see each other's holds. No
+ * budget (or no run) ⇒ no lock, no reservation.
  * @param {SessionOpts} opts @param {SessionDeps} deps
  * @param {((row: Record<string, any>) => Promise<unknown>) | null} writeRow
  * @param {{write: (s: string) => unknown}} stderr
- * @returns {Promise<SessionResult | null>} the refusal result, or null to go on.
+ * @param {{provider: string}} step - the ladder step about to run (its provider prices the estimate).
+ * @returns {Promise<{refused: SessionResult, release?: undefined} | {refused: null, release: () => void}>}
+ *   the refusal result, or the (idempotent) release of this attempt's reservation.
  */
-async function budgetGate(opts, deps, writeRow, stderr) {
+async function budgetGate(opts, deps, writeRow, stderr, step) {
   const budget = budgetUsdOf(opts.cfg);
-  if (budget === null || typeof opts.run !== 'string' || opts.run.length === 0) return null;
+  if (budget === null || typeof opts.run !== 'string' || opts.run.length === 0) return { refused: null, release: () => {} };
+  const run = opts.run;
+  const estimate = estimateSessionUsd({ provider: step.provider, level: opts.level, role: opts.role, tokensIn: packetTokens(opts) });
+  return withBudgetLock(run, async () => {
+    const refused = await checkGate(opts, deps, writeRow, stderr, budget, estimate);
+    if (refused) return { refused };
+    return { refused: null, release: reserveBudget(run, estimate) };
+  });
+}
+
+/**
+ * The packet's (or brief's) tokens plus the system prompt's, by the ledger's bytes / 4 rule (an
+ * unreadable packet counts 0 bytes; tokens_out is still reserved).
+ * @param {SessionOpts} opts @returns {number}
+ */
+function packetTokens(opts) {
+  return estimateTokens(fileSize(opts.promptPath) + (typeof opts.systemPromptText === 'string' ? Buffer.byteLength(opts.systemPromptText) : 0));
+}
+
+/**
+ * The B33 check proper (called under the budget lock): read the run's spend, fail closed, refuse
+ * when spent + reserved + `estimate` passes the budget.
+ * @param {SessionOpts} opts - `opts.run` is a non-empty string (checked by `budgetGate`).
+ * @param {SessionDeps} deps
+ * @param {((row: Record<string, any>) => Promise<unknown>) | null} writeRow
+ * @param {{write: (s: string) => unknown}} stderr @param {number} budget @param {number} estimate
+ * @returns {Promise<SessionResult | null>} the refusal result, or null to go on.
+ */
+async function checkGate(opts, deps, writeRow, stderr, budget, estimate) {
   /** @type {Array<Record<string, any>> | null} */
   let rows = null;
   try {
@@ -677,7 +821,7 @@ async function budgetGate(opts, deps, writeRow, stderr) {
     }
     return { status: 'unavailable', reason: 'budget', message: SPEND_UNREADABLE_MESSAGE, answer: null, spent_usd: null, budget_usd: budget };
   }
-  const verdict = await checkBudget({ budget, run: opts.run, rows, block: opts.block ?? null, role: opts.role, writeRow, stderr });
+  const verdict = await checkBudget({ budget, run: /** @type {string} */ (opts.run), rows, block: opts.block ?? null, role: opts.role, writeRow, stderr, reserved: reservedUsd(/** @type {string} */ (opts.run)), estimate });
   if (!verdict.refuse) return null;
   return { status: 'unavailable', reason: 'budget', message: verdict.message, answer: null, spent_usd: verdict.spent, budget_usd: budget };
 }

package/src/util/locks.mjs

@@ -0,0 +1,104 @@
+/**
+ * In-process locks (parallel review, block B40): a keyed mutex and a counting semaphore.
+ *
+ * Both live in this process only — no files, no cross-process coordination — and use no timers,
+ * so a waiting lock never keeps the event loop alive on its own.
+ *
+ * `keyedLock(key, fn)`: calls for the same key run one at a time, in call order (FIFO); calls for
+ * different keys run together. A throw (or rejection) in `fn` releases the key and is passed on.
+ *
+ * `semaphore(n)`: `acquire()` resolves to a `release` function once fewer than `n` holders are
+ * active; waiters are served in order. `release` is idempotent (a second call does nothing).
+ * `run(fn)` acquires, runs `fn`, and releases on every exit path.
+ */
+
+/** @type {Map<unknown, Promise<void>>} the tail of each key's queue. */
+const tails = new Map();
+
+/**
+ * Run `fn` once every earlier call for `key` has finished.
+ * @template T
+ * @param {unknown} key
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function keyedLock(key, fn) {
+  const prev = tails.get(key) ?? Promise.resolve();
+  /** @type {() => void} */
+  let release = () => {};
+  const done = new Promise((resolve) => {
+    release = () => resolve(undefined);
+  });
+  const tail = prev.then(() => done);
+  tails.set(key, tail);
+  return prev.then(async () => {
+    try {
+      return await fn();
+    } finally {
+      release();
+      if (tails.get(key) === tail) tails.delete(key);
+    }
+  });
+}
+
+/**
+ * @typedef {object} Semaphore
+ * @property {() => Promise<() => void>} acquire - resolves to an idempotent `release`.
+ * @property {<T>(fn: () => T | Promise<T>) => Promise<T>} run - `fn` under one slot, released on every exit path.
+ * @property {number} active - holders right now.
+ * @property {number} pending - waiters right now.
+ */
+
+/**
+ * A counting semaphore: never more than `n` holders at once.
+ * @param {number} n - an integer ≥ 1.
+ * @returns {Semaphore}
+ */
+export function semaphore(n) {
+  if (!Number.isInteger(n) || n < 1) throw new TypeError('semaphore: n must be an integer >= 1');
+  let active = 0;
+  /** @type {Array<(release: () => void) => void>} */
+  const waiters = [];
+
+  /** @returns {() => void} */
+  function grant() {
+    active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      active -= 1;
+      const next = waiters.shift();
+      if (next) next(grant());
+    };
+  }
+
+  /** @returns {Promise<() => void>} */
+  function acquire() {
+    if (active < n && waiters.length === 0) return Promise.resolve(grant());
+    return new Promise((resolve) => {
+      waiters.push(resolve);
+    });
+  }
+
+  /** @template T @param {() => T | Promise<T>} fn @returns {Promise<T>} */
+  async function run(fn) {
+    const release = await acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  return {
+    acquire,
+    run,
+    get active() {
+      return active;
+    },
+    get pending() {
+      return waiters.length;
+    },
+  };
+}

package/src/worker/engine.mjs

@@ -45,7 +45,8 @@ import { computeFileSet, ownsFile } from '../gates/scope.mjs';
 import { newFileState, runRound } from '../review/fixloop.mjs';
 import { readRun } from '../state/run.mjs';
 import { redact } from '../util/redact.mjs';
-import { blockRungUsed, loadState, saveState } from './review-state.mjs';
+import { keyedLock } from '../util/locks.mjs';
+import { blockAnchors, blockRungUsed, loadState, saveState } from './review-state.mjs';
 import { assertTicketId } from './ticket.mjs';
 
 /**
@@ -207,47 +208,123 @@ export async function reviewTicket(ticket, ctx) {
   }
 }
 
+/**
+ * The key of a block's lock (B42): the block's budget row and its L3 rung are taken under it.
+ * It carries the run, so two runs in one process never share a lock.
+ * @param {string} runId @param {string} block @returns {string}
+ */
+export const blockLockKey = (runId, block) => `block:${runId}\0${block}`;
+
+/**
+ * Whether the block's one L3 rung is taken: a verified anchor says so (`blockRungUsed`), OR another
+ * file of the block has a saved state whose round decided `next: patch` — that round took the rung,
+ * but its anchor records `l3_rung_used` only once the patch_check ticket saves. A sibling state that
+ * does not load is counted as taken (fail closed; its own ticket refuses it).
+ * @param {import('./review-state.mjs').Where} where
+ * @returns {{status: 'ok' | 'tampered', used: boolean}}
+ */
+export function rungTaken(where) {
+  const rung = blockRungUsed(where);
+  if (rung.status === 'tampered' || rung.used) return rung;
+  const anchors = blockAnchors(where) ?? [];
+  const siblings = new Set(anchors.map((a) => a.file).filter((f) => typeof f === 'string' && f !== where.file));
+  for (const file of siblings) {
+    let other;
+    try {
+      other = loadState({ ...where, file });
+    } catch {
+      return { status: 'ok', used: true };
+    }
+    if (other.status !== 'ok' || other.state?.next?.action === 'patch') return { status: 'ok', used: true };
+  }
+  return rung;
+}
+
+/**
+ * Whether this round could take the block's L3 rung (so it must run under the block lock): never
+ * when the rung is taken or the round is the patch_check (the rung is already this file's); never
+ * for a file's first full round while the cap and the per-level ladder are both above 1 (round 1
+ * cannot stall, reach the cap or exhaust the ladder); else conservatively yes.
+ * @param {import('../review/fixloop.mjs').FileState} state @param {'full' | 'recheck' | 'patch_check'} kind
+ * @param {Record<string, any>} cfg @param {boolean} rungUsed
+ * @returns {boolean}
+ */
+export function mayTakeRung(state, kind, cfg, rungUsed) {
+  if (rungUsed || kind === 'patch_check') return false;
+  const int = (/** @type {unknown} */ v, /** @type {number} */ d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
+  const maxRounds = int(cfg?.review?.max_rounds_per_file, 4);
+  const perLevel = int(cfg?.escalation?.review_rounds_per_level, 2);
+  if (kind === 'full' && state.round === 0 && state.rounds_at_level === 0 && maxRounds > 1 && perLevel > 1) return false;
+  return true;
+}
+
 /**
  * One fix-loop round for the ticket (see the module doc).
+ *
+ * Concurrency (B42): the worker runs several tickets at once but never two for the same
+ * (block, file) (its file lock, `loop.mjs`), so this file's state `seq` is read and saved by one
+ * ticket at a time. What the files of a BLOCK share is taken under the block lock
+ * (`blockLockKey`): the budget row's check-then-write (written once per block) and the L3 rung —
+ * the rung read and, for a round that could take the rung (`mayTakeRung`), the whole round and its
+ * state save, so two files of one block never both take it. A round that cannot take the rung (a
+ * first full round, or any round once the rung is gone) runs outside the block lock, in parallel
+ * with the block's other files.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
  * @param {{base: string | null, level: string, owned: string[], blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string}} opts
  * @returns {Promise<ReviewOutcome>}
  */
 async function fixLoopRound(ticket, ctx, { base, level, owned, blockKindOf, key, workDir, factsExcerpt }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
-  let rows;
-  try {
-    rows = (await ctx.readRows()).filter((r) => r?.run === ctx.runId);
-  } catch (err) {
-    return { status: 'unavailable', reason: failureReason(err), approved: false, engine: 'adaptive', sessions: [] };
-  }
-  // Check-then-write is safe here: a run has exactly ONE worker, and it processes its tickets one
-  // at a time (`loop.mjs` awaits each `processTicket`), so no second ticket of this block can read
-  // the rows between this check and the budget row's write.
-  if (!rows.some((r) => r?.event === 'review.budget' && r.block === ticket.block)) {
-    await recordBlockBudget(ticket, ctx, { base, owned });
-  }
-  const where = { runRootDir: ctx.runRootDir, runId: ctx.runId, block: ticket.block, file: ticket.file, key, rows };
-  const loaded = loadState(where);
-  const rung = blockRungUsed(where);
-  if (loaded.status === 'tampered' || rung.status === 'tampered') return { status: 'refused', reason: 'review-state-tampered', approved: false, engine: 'adaptive', sessions: [] };
-  const rungUsed = rung.used;
-  let state = loaded.state;
-  if (state === null || state.status === 'complete') state = newFileState({ file: ticket.file, level, l3RungUsed: rungUsed });
-  state.l3_rung_used = state.l3_rung_used || rungUsed;
+  const readRows = ctx.readRows;
+  /** @type {{outcome: ReviewOutcome} | {round: () => Promise<ReviewOutcome>}} */
+  const prepared = await keyedLock(blockLockKey(ctx.runId, ticket.block), async () => {
+    let rows;
+    try {
+      rows = (await readRows()).filter((r) => r?.run === ctx.runId);
+    } catch (err) {
+      return { outcome: /** @type {ReviewOutcome} */ ({ status: 'unavailable', reason: failureReason(err), approved: false, engine: 'adaptive', sessions: [] }) };
+    }
+    // Check-then-write under the block lock: no other ticket of this block reads the rows between
+    // this check and the budget row's write, so the row is written once per block.
+    if (!rows.some((r) => r?.event === 'review.budget' && r.block === ticket.block)) {
+      await recordBlockBudget(ticket, ctx, { base, owned });
+    }
+    const where = { runRootDir: ctx.runRootDir, runId: ctx.runId, block: ticket.block, file: ticket.file, key, rows };
+    const loaded = loadState(where);
+    const rung = rungTaken(where);
+    if (loaded.status === 'tampered' || rung.status === 'tampered') return { outcome: /** @type {ReviewOutcome} */ ({ status: 'refused', reason: 'review-state-tampered', approved: false, engine: 'adaptive', sessions: [] }) };
+    const rungUsed = rung.used;
+    let state = loaded.state;
+    if (state === null || state.status === 'complete') state = newFileState({ file: ticket.file, level, l3RungUsed: rungUsed });
+    state.l3_rung_used = state.l3_rung_used || rungUsed;
 
-  if (state.status === 'stopped') {
-    return { ...loopFields(state, null), status: 'stopped', stopped: state.next?.reason ?? 'stopped', approved: false, engine: 'adaptive', sessions: [], findings: state.open };
-  }
+    if (state.status === 'stopped') {
+      return { outcome: /** @type {ReviewOutcome} */ ({ ...loopFields(state, null), status: 'stopped', stopped: state.next?.reason ?? 'stopped', approved: false, engine: 'adaptive', sessions: [], findings: state.open }) };
+    }
 
-  /** @type {'full' | 'recheck' | 'patch_check'} */
-  let kind = state.round === 0 ? 'full' : 'recheck';
-  if (state.next?.action === 'retry') kind = state.pending_kind ?? kind;
-  else if (state.next?.action === 'patch') {
-    kind = 'patch_check';
-    state.l3_rung_used = true; // the orchestrator ran the block's one L3 patch before this ticket
-  }
+    /** @type {'full' | 'recheck' | 'patch_check'} */
+    let kind = state.round === 0 ? 'full' : 'recheck';
+    if (state.next?.action === 'retry') kind = state.pending_kind ?? kind;
+    else if (state.next?.action === 'patch') {
+      kind = 'patch_check';
+      state.l3_rung_used = true; // the orchestrator ran the block's one L3 patch before this ticket
+    }
+    const fixed = state;
+    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq: loaded.seq, base, blockKindOf, workDir, factsExcerpt });
+    // a round that could take the rung keeps the block lock until its state is saved
+    if (mayTakeRung(fixed, kind, ctx.cfg, rungUsed)) return { outcome: await round() };
+    return { round };
+  });
+  return 'outcome' in prepared ? prepared.outcome : prepared.round();
+}
 
+/**
+ * Run the prepared round and save the file's state: the ticket's outcome.
+ * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
+ * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string}} opts
+ * @returns {Promise<ReviewOutcome>}
+ */
+async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt }) {
   /** @type {Record<string, any> | null} */
   let engineOutcome = null;
   let approvalWritten = false;
@@ -307,7 +384,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, blockKindOf, key,
       state.pending_kind = kind;
     }
   }
-  await saveState({ ...where, state, seq: loaded.seq, writeRow: /** @type {(row: Record<string, any>) => Promise<unknown>} */ (ctx.writeRow) });
+  await saveState({ ...where, state, seq, writeRow: /** @type {(row: Record<string, any>) => Promise<unknown>} */ (ctx.writeRow) });
 
   const eng = /** @type {Record<string, any> | null} */ (engineOutcome);
   const head = { ...loopFields(state, kind), engine: eng?.engine ?? 'adaptive', sessions: eng?.sessions ?? rechecks };