@thebattlearena/corner 0.10.1-beta.82 → 0.10.1-beta.83

package/README.md

@@ -444,7 +444,12 @@ y al pasar a «espera al juez» el fin y el rango (`--range A..B` lo fija a mano
 `plan.jsonl`, que es lo que lee el modo «Pelea del ring» de PR Review Lab. Cuando `humanReviewEvery`
 bloques (2 por default, `null` lo apaga) esperan al juez, suena la campana en PR Review Lab y
 `brief.mjs` no le arma instrucciones al siguiente luchador hasta que el humano revise ese corte en un
-solo diff y firme un veredicto con Tape. PR Review Lab lo escribe en `<combate>/review-verdicts.jsonl`
+solo diff y firme un veredicto con Tape. Con `parallelBlocks: 2` dos bloques corren a la vez **en el mismo
+worktree**, cada luchador sobre los archivos que su bloque declaró (`--files "<globs>"` al estimar o
+arrancar): el script no deja arrancar un bloque con archivos de otro en curso, `mask-guard` rechaza un
+commit con archivos de otro bloque (los de `generatedPaths`, como los docs que regenera un pre-commit,
+no son de nadie: el árbitro los regenera al cerrar la oleada), y `concept … --block <n>` retira solo al
+luchador de ese bloque. Los tests corren al terminar el bloque, sobre lo que tocó. Y mientras el humano revisa un corte, un luchador puede adelantar UN bloque más cuyos archivos no toque el corte: `brief.mjs wrestler … --lookahead "<globs>"`. PR Review Lab lo escribe en `<combate>/review-verdicts.jsonl`
 y el ring lo lee en el siguiente brief o `summary`: si pasa, los bloques quedan en «hecho»; si no
 pasa, vuelven a «en curso» con el feedback y el Tape como rebote, que el brief del siguiente luchador
 trae al principio. Cada veredicto queda en `decisions.md` como decisión del juez (y en Engram).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebattlearena/corner",
-  "version": "0.10.1-beta.82",
+  "version": "0.10.1-beta.83",
   "description": "Corner: tu esquina de Battle Arena en Claude Code (el plugin `battlearena`). Hooks de tracking, objetivo del turno, plan de batalla /battlearena:conquer, Ringside (el panel de tu día), el ring y la radio. Zero-dependency.",
   "type": "module",
   "bin": {

package/ring/agents/cornerman.md

@@ -79,6 +79,11 @@ numbered list of behavior invariants.
      outside tests. One used only by its own spec, or by nobody, is a finding (dead code).
    - **Comments.** Narrating, stale or now-wrong comments in every file the assignment covers,
      **including files the range did not edit** when the brief names them.
+   - **The same question asked again (PR31).** Grep the concept for the same condition (a null
+     check, an optional, a `?.`, a status test) asked for the same reason in several places: three
+     or more is a finding, with where it should be settled once.
+   - **Guards against a provider's events (P16).** A guard against an event a provider's SDK sends
+     cites the SDK code that can send it (`node_modules/<sdk>/…:line`); without it, it is a finding.
    - **Commit messages.** Each message in the range (`git -C <wt> log --format=%B <A>..<B>`) must
      not carry bout-internal ids (D12, P7, HP3, PR5…): they mean nothing in the repo's history.
 5. Return: a table per file (findings with rule ids), a table per invariant (holds / broken, with

package/ring/scripts/brief-build.mjs

@@ -37,7 +37,7 @@ export function rulesBlock({ sources, entries }) {
 }
 
 /**
- * The decisions a brief carries: every foul (what must not be repeated), the ones whose text names
+ * The decisions a brief carries: every foul (what must not be repeated), every ruling of the judge, the ones whose text names
  * a file of the range, and the last `last`; in ledger order, each once. PURE.
  */
 export function decisionsExcerpt(
@@ -54,6 +54,8 @@ export function decisionsExcerpt(
     (line) =>
       tail.has(line) ||
       /\bFOUL\b/.test(line) ||
+      // What the human ruled stays in every brief of the bout, like a foul.
+      / · judge · /.test(line) ||
       names.some((name) => line.includes(name)),
   );
   return kept.length ? kept.join('\n') : '(no decisions yet)';

package/ring/scripts/brief-guard.mjs

@@ -168,7 +168,7 @@ export function guard(input) {
   const problem = problemOf({ ...brief, check, role, pr: state.pr });
   appendFileSync(
     join(bout, GUARD_LOG),
-    `${JSON.stringify({ at: new Date().toISOString(), role, mode, path: brief.path, ok: !problem, problem })}\n`,
+    `${JSON.stringify({ at: new Date().toISOString(), role, mode, path: brief.path, toolUseId: input.tool_use_id ?? null, ok: !problem, problem })}\n`,
   );
   return answer({
     input: input.tool_input,

package/ring/scripts/brief.mjs

@@ -44,7 +44,13 @@ import {
 } from './config.mjs';
 import { recallSection } from './engram.mjs';
 import { conceptsSinceRelay, relayDue } from './relay.mjs';
-import { reviewTurn } from './review-blocks.mjs';
+import { boutLeases } from './lanes.mjs';
+import {
+  lookaheadRefusal,
+  reviewInputs,
+  reviewTurn,
+  runningBlocks,
+} from './review-blocks.mjs';
 import { setPlanState } from './tech-plan-log.mjs';
 import { loadRules } from './rule-ids.mjs';
 
@@ -166,6 +172,84 @@ function boutVars({ dir, state, config }, values) {
   };
 }
 
+/**
+ * The wrestler's block and the files it holds, next to the files other running blocks hold (none:
+ * one block at a time, nothing to add). With parallelBlocks > 1 and another block running, the
+ * brief names its block (--block <n>).
+ */
+function laneSection(bout, block) {
+  const running = boutLeases(bout.dir);
+  if (!block) {
+    if ((bout.config.parallelBlocks ?? 1) > 1 && running.length > 1)
+      throw new Error(
+        `${running.length} blocks are running (${running.map((lease) => `B${lease.n}`).join(', ')}): name this wrestler's block with --block <n>`,
+      );
+    return [];
+  }
+  const mine = running.find((lease) => lease.n === Number(block));
+  if (!mine)
+    throw new Error(
+      `B${block} is not «en curso»: start it with judges-card.mjs plan <pr> ${block} "en curso" --files "<globs>" first`,
+    );
+  const others = running.filter((lease) => lease.n !== mine.n);
+  const list = (files) =>
+    files.length
+      ? files.map((glob) => `\`${glob}\``).join(', ')
+      : '(none declared)';
+  return [
+    `## Your block: B${mine.n} «${mine.title}»`,
+    [
+      `You touch only files matching ${list(mine.files)}.`,
+      others.length
+        ? `Other wrestlers work in this same worktree right now: ${others.map((lease) => `B${lease.n} holds ${list(lease.files)}`).join('; ')}. Never edit, stage or commit their files; mask-guard refuses such a commit. If you need one of them, stop and tell me: I move it between blocks.`
+        : 'No other block is running now.',
+      `Stage by explicit paths only, never \`git add -A\`, \`git stash\`, \`checkout\`, \`reset\` or \`rebase\` (they move the other wrestler's work too).`,
+      `Gates once, when the block is done, not after each edit: the tests of the files you touched, and the typecheck reading only the errors in your files (another block's work in progress may not compile yet).${(bout.config.generatedPaths ?? []).length ? ` Generated files (${list(bout.config.generatedPaths)}) are nobody's: leave them unstaged; I regenerate them when the wave closes.` : ''}`,
+    ].join('\n\n'),
+  ];
+}
+
+/**
+ * While the human reviews a cut, one wrestler may work ahead on a block whose declared files the
+ * cut does not touch (`--lookahead "<globs>"`). Without it, or when it overlaps or another block is
+ * running, the pause holds. Returns the brief's section that bounds the work ahead.
+ */
+function workAhead(bout, lookahead, turn) {
+  if (!lookahead)
+    throw new Error(
+      `${turn.due}. Or work ahead on one block whose files the cut does not touch: --lookahead "<glob>,<glob>"`,
+    );
+  const globs = String(lookahead)
+    .split(',')
+    .map((glob) => glob.trim())
+    .filter(Boolean);
+  const { plan, log } = reviewInputs(bout.dir);
+  const waitingFiles = [
+    ...new Set(
+      turn.waiting.flatMap((item) => {
+        const range = log
+          .filter((line) => line.n === item.n && line.range)
+          .at(-1)?.range;
+        return range
+          ? git(bout.state.worktree, ['diff', '--name-only', range])
+              .split('\n')
+              .filter(Boolean)
+          : [];
+      }),
+    ),
+  ];
+  const refusal = lookaheadRefusal({
+    globs,
+    waitingFiles,
+    running: runningBlocks(plan),
+  });
+  if (refusal) throw new Error(`${turn.due}. ${refusal}`);
+  return [
+    '## Working ahead of the human review (the cut under review must not move)',
+    `The human is reviewing ${turn.waiting.map((item) => `B${item.n}`).join(' + ')}. You work ahead on one block and touch only files matching: ${globs.map((glob) => `\`${glob}\``).join(', ')}. Never edit a file of the cut under review (${waitingFiles.map((file) => `\`${file}\``).join(', ') || 'none'}); if you need one, stop and tell me. If the verdict sends the cut back, its rebound goes first.`,
+  ].join('\n\n');
+}
+
 /** The open rebounds the human's review sent back, as a section of the brief (none: nothing). */
 function humanReview(dir) {
   const path = join(dir, 'rebounds.md');
@@ -180,6 +264,20 @@ function humanReview(dir) {
     : [];
 }
 
+/**
+ * The files the bout changed so far (merge base with its base..head): what Engram searches on when
+ * the brief's own range is empty, as a wrestler starting a new concept has no commit yet.
+ */
+function boutFiles({ worktree, base }) {
+  try {
+    return git(worktree, ['diff', '--name-only', `origin/${base}...HEAD`])
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 const real = (path) => (existsSync(path) ? realpathSync(path) : path);
 
 async function generate(kind, [pr, ...argv]) {
@@ -194,6 +292,7 @@ async function generate(kind, [pr, ...argv]) {
     throw new Error(
       `a relay is due (${conceptsSinceRelay(bout.state)} concepts since the last one): rewrite the card's «How to resume», run judges-card.mjs relay ${pr}, then brief the next wrestler`,
     );
+  let ahead = null;
   if (kind === 'wrestler') {
     // The human's verdicts from PR Review Lab first: a fail comes back as a rebound for this brief.
     const turn = reviewTurn(
@@ -203,7 +302,7 @@ async function generate(kind, [pr, ...argv]) {
     );
     if (turn.applied.length)
       console.error(`human review applied: ${turn.applied.join(' · ')}`);
-    if (turn.due) throw new Error(turn.due);
+    if (turn.due) ahead = workAhead(bout, values.lookahead, turn);
   }
   const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
   const roots = [
@@ -237,17 +336,19 @@ async function generate(kind, [pr, ...argv]) {
     ? await recallSection(bout.config, {
         slug: repoSlug(projectDir()),
         pr,
-        files,
+        files: files.length ? files : boutFiles(bout.state),
       })
     : null;
   // The task goes first and the rules last, as the reference: a brief that opens with the rules
   // reads as a checklist, and a 2026-11 lab on #1212 found fewer real problems that way.
   const body = [
     text.trim(),
-    '## Decisions already taken (excerpt: every foul, the ones on these files, the last 20)',
+    '## Decisions already taken (excerpt: every foul, every ruling of the judge, the ones on these files, the last 20)',
     decisions,
     `The whole ledger: \`${decisionsPath}\`.`,
     ...humanReview(bout.dir),
+    ...(ahead ? [ahead] : []),
+    ...(kind === 'wrestler' ? laneSection(bout, values.block) : []),
     ...(learned ? [learned] : []),
     ...(shape.rules ? ['---', rules.block] : []),
   ].join('\n\n');
@@ -262,6 +363,9 @@ async function generate(kind, [pr, ...argv]) {
     mode: values.mode,
     pr,
     n,
+    ...(kind === 'wrestler' && values.block
+      ? { block: Number(values.block) }
+      : {}),
     rules: shape.rules ? rules.hash : 'none',
   };
   const file = join(briefs, `${kind}-${values.mode}-${n}.md`);

package/ring/scripts/compact-hook.mjs

@@ -16,6 +16,7 @@ import {
   RING_ROOT,
 } from './config.mjs';
 import { findBout, sessionRegistered } from './live.mjs';
+import { openHumanReturns, TAPE_HINT } from './review-blocks.mjs';
 import { checklistLines, loadRules } from './rule-ids.mjs';
 
 /** Claude Code's cap for SessionStart output, with room to spare. */
@@ -55,10 +56,25 @@ export function foulLines(decisions, max = 3000) {
 }
 
 /** The text a compacted referee gets back. PURE. */
-export function compactContext({ pr, dir, checklist, fouls, resume }) {
+export function compactContext({
+  pr,
+  dir,
+  checklist,
+  fouls,
+  resume,
+  returned = [],
+}) {
   const text = [
     `# Ring: you referee bout #${pr} (context restored after a compaction)`,
     '',
+    ...(returned.length
+      ? [
+          '## RETURNED BY THE HUMAN (rebound still open: this goes first)',
+          ...returned,
+          TAPE_HINT,
+          '',
+        ]
+      : []),
     `Reread before acting: the judges card \`${join(dir, 'judges-card.md')}\` and the ledger \`${join(dir, 'decisions.md')}\`. Every wrestler and cornerman is launched with a brief from \`node ${RING_ROOT}/scripts/brief.mjs\` and \`prompt: "ring-brief: <path>"\`; never a brief written by hand. Every finding cites its rule id (or X0).`,
     '',
     '## Architecture checklist (the full rules go in every brief)',
@@ -90,6 +106,7 @@ export function restore(input) {
     checklist: checklistLines(loadRules(config).entries).join('\n'),
     fouls: foulLines(read(join(dir, 'decisions.md'))),
     resume: resumeSection(read(join(dir, 'judges-card.md'))),
+    returned: openHumanReturns(dir),
   });
 }
 

package/ring/scripts/config.mjs

@@ -160,6 +160,12 @@ export const DEFAULTS = Object.freeze({
   // blocks of the plan (points with a reviewed range) wait on the judge, brief.mjs briefs no
   // wrestler until the human signs a verdict on that cut. null: no pause.
   humanReviewEvery: 2,
+  // Blocks that may run at once in the bout's worktree, each wrestler on the files its block
+  // declared (lanes.mjs). 1: one at a time, as always.
+  parallelBlocks: 1,
+  // Files the host regenerates on its own (a pre-commit that writes docs): no block holds them, and
+  // the referee regenerates them when a wave of parallel blocks closes. Globs.
+  generatedPaths: [],
   // Engram (github.com/Gentleman-Programming/engram), the memory of what earlier bouts learned:
   // fouls, the judge's verdicts, accepted precedents, X0 findings and each bout's status. Never the
   // rules. The scripts sync and read it when something answers at this URL (null: off). The

package/ring/scripts/findings.mjs

@@ -643,6 +643,20 @@ const COMMANDS = {
   audit,
 };
 
+/** Each subcommand's usage, printed with its error. */
+const USAGE = {
+  add: 'add <pr> --source range|concept|batch|preferences --range <A>..<B> --file <report> [--up-to <sha>] [--rule <id>]',
+  clean: 'clean <pr> --range <from>..<to>',
+  applied: 'applied <pr> F<n>[,…] --sha <commit>',
+  discard:
+    'discard <pr> F<n>[,…] --id D<k> --reason "<why>" [--judge "<what the human said>"]',
+  ticket:
+    'ticket <pr> F<n>[,…] --ticket <id|"to file"> --reason "<why>" [--judge "<what the human said>"]',
+  escalate: 'escalate <pr> F<n>[,…] --reason "<why>"',
+  shown: 'shown <pr> F<n>[,…] --in "<where the human saw it>"',
+  audit: 'audit <pr> [--full]',
+};
+
 if (isMain(import.meta.url)) {
   const [command, ...rest] = process.argv.slice(2);
   const run = COMMANDS[command];
@@ -658,6 +672,8 @@ if (isMain(import.meta.url)) {
     if (command !== 'audit') await syncAfter(rest[0]);
   } catch (error) {
     console.error(`findings: ${error.message}`);
+    if (USAGE[command])
+      console.error(`usage: node findings.mjs ${USAGE[command]}`);
     process.exit(1);
   }
 }

package/ring/scripts/judges-card.mjs

@@ -59,6 +59,7 @@ import {
   withConceptClosed,
   withProposalDecision,
   wrestlerIds,
+  wrestlerLines,
 } from './relay.mjs';
 import { resumeSection } from './compact-hook.mjs';
 import { boutFormatGate } from './format-gate.mjs';
@@ -115,7 +116,13 @@ import {
 } from './preparation.mjs';
 import { handOffWarning, withChronicleUrl } from './sparring-chronicle.mjs';
 import { refereeRecall, syncAfter } from './engram.mjs';
-import { estimateFacts, reviewTurn } from './review-blocks.mjs';
+import { parseGlobs, wrestlerBlocks } from './lanes.mjs';
+import {
+  estimateFacts,
+  openHumanReturns,
+  reviewTurn,
+  TAPE_HINT,
+} from './review-blocks.mjs';
 import { parsePlan, PLAN, planItem } from './tech-plan.mjs';
 import { addPlanItem, setPlanState } from './tech-plan-log.mjs';
 import { logPageVerdicts } from './verdicts-log.mjs';
@@ -317,10 +324,18 @@ async function summary([pr]) {
   const review = reviewTurn(dir, config.humanReviewEvery, (n, to, ref) =>
     setPlanState(dir, n, to, ref),
   );
+  const returned = openHumanReturns(dir);
   console.log(
     [
       '',
       '## Human review by blocks (PR Review Lab, bout mode)',
+      ...(returned.length
+        ? [
+            `RETURNED BY THE HUMAN, rebound still open (${returned.length}):`,
+            ...returned,
+            TAPE_HINT,
+          ]
+        : []),
       review.applied.length
         ? `verdicts applied now: ${review.applied.join(' · ')}`
         : 'no new verdicts',
@@ -601,6 +616,7 @@ function plan([pr, target, ...rest]) {
       estimate: estimateFacts({
         priority: value('--priority'),
         minutes: value('--minutes'),
+        files: parseGlobs(value('--files')),
       }),
     });
     return void console.log(
@@ -616,17 +632,24 @@ function plan([pr, target, ...rest]) {
     contract: false,
     venue: readState(dir).venue ?? DEFAULT_VENUE,
   });
-  const inline = [value('--minutes'), value('--priority')].some(
-    (given) => given != null,
-  );
+  const inline = [
+    value('--minutes'),
+    value('--priority'),
+    value('--files'),
+  ].some((given) => given != null);
   const changed = setPlanState(dir, target, state, value('--ref'), undefined, {
     range: value('--range'),
     estimate: inline
       ? estimateFacts({
           priority: value('--priority'),
           minutes: value('--minutes'),
+          files: parseGlobs(value('--files')),
         })
       : null,
+    lanes: {
+      parallel: config.parallelBlocks,
+      generated: config.generatedPaths,
+    },
     // Under the human review by blocks a block starts with its estimate and priority.
     requireEstimate: Boolean(config.humanReviewEvery),
   });
@@ -958,14 +981,19 @@ function playByPlayUrl([pr, url]) {
  * concept goes to a fresh wrestler; every `relayEvery` concepts the referee relays first.
  */
 function concept([pr, name, ...argv]) {
-  const { range } = options(argv);
+  const { range, block } = options(argv);
   const dir = currentDir(pr);
   const state = readState(dir);
   const next = withConceptClosed(state, {
     name,
     range,
     at: new Date().toISOString(),
-    wrestlers: wrestlerIds(liveLines(dir)),
+    // With --block only that block's wrestlers retire: another block may still be running.
+    wrestlers: block
+      ? [...wrestlerBlocks(dir)]
+          .filter(([, n]) => n === Number(block))
+          .map(([agent]) => agent)
+      : wrestlerIds(wrestlerLines(dir)),
   });
   writeState(dir, next);
   const { config } = loadConfig(projectDir(), {

package/ring/scripts/lanes.mjs

@@ -0,0 +1,139 @@
+// Several blocks at once in ONE worktree: each block «en curso» holds the files it declared
+// (`--files "<globs>"` at estimate or start), and only that block's wrestler commits them. The
+// referee grants them all when the block starts (the start is refused when another running block
+// holds one of them, or when `parallelBlocks` are already running); a wrestler that needs a file of
+// another block stops and asks the referee, never the other wrestler. mask-guard refuses a commit
+// that stages a file another running block holds. Files the host regenerates (`generatedPaths`,
+// e.g. docs a pre-commit writes) are nobody's: the referee regenerates them when the wave closes.
+// Closing a concept with `--block <n>` retires only that block's wrestlers. Zero-dependency.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { globToRegExp } from './contract.mjs';
+import { wrestlerLines } from './relay.mjs';
+import { parsePlan, parsePlanLog, PLAN, PLAN_LOG } from './tech-plan.mjs';
+
+/** `"a/**, b/*.ts"` as globs. PURE. */
+export const parseGlobs = (text) =>
+  String(text ?? '')
+    .split(',')
+    .map((glob) => glob.trim())
+    .filter(Boolean);
+
+const matcher = (globs) => {
+  const patterns = (globs ?? []).map((glob) => globToRegExp(glob));
+  return (file) => patterns.some((pattern) => pattern.test(file));
+};
+
+/** The blocks «en curso» with the files each holds (its last `files` in plan.jsonl). PURE. */
+export function runningLeases(plan, log) {
+  return parsePlan(plan)
+    .groups.flatMap((group) => group.items)
+    .filter((item) => item.state === 'en curso')
+    .map((item) => ({
+      n: item.n,
+      title: item.title,
+      files:
+        log.filter((line) => line.n === item.n && line.files).at(-1)?.files ??
+        [],
+    }));
+}
+
+/**
+ * Why block `n` may not start next to the blocks already running, or null. With `parallel` 1 (the
+ * default) nothing changes. Otherwise it needs its files, a free slot, and no tracked file that a
+ * running block holds too (generated files are nobody's). PURE.
+ */
+export function startLaneRefusal({
+  n,
+  files,
+  running,
+  parallel,
+  tracked,
+  generated,
+}) {
+  const others = running.filter((lease) => lease.n !== n);
+  if (!parallel || parallel <= 1 || !others.length) return null;
+  if (others.length >= parallel)
+    return `${others.length} blocks are already running (parallelBlocks ${parallel}): ${others.map((lease) => `B${lease.n}`).join(', ')}. Start B${n} when one closes`;
+  if (!files?.length)
+    return `B${n} starts next to ${others.map((lease) => `B${lease.n}`).join(', ')}: declare the files it will touch with --files "<glob>,<glob>" so no two wrestlers edit the same file`;
+  const isGenerated = matcher(generated);
+  const mine = matcher(files);
+  const clashes = others.flatMap((lease) => {
+    const theirs = matcher(lease.files);
+    return tracked
+      .filter((file) => !isGenerated(file) && mine(file) && theirs(file))
+      .map((file) => `${file} (B${lease.n})`);
+  });
+  if (clashes.length)
+    return `B${n} would share files with a running block: ${clashes.slice(0, 8).join(', ')}${clashes.length > 8 ? ', …' : ''}. Narrow its --files, or start another block`;
+  return null;
+}
+
+/**
+ * Why a commit may not go in, or null: a staged file held by a running block other than the one
+ * whose wrestler commits. Unknown committer: a commit may not mix files of two blocks. PURE.
+ */
+export function commitLeaseRefusal({ staged, running, block, generated }) {
+  if (running.length < 2) return null;
+  const isGenerated = matcher(generated);
+  const owners = staged
+    .filter((file) => !isGenerated(file))
+    .flatMap((file) =>
+      running
+        .filter((lease) => matcher(lease.files)(file))
+        .map((lease) => ({ file, n: lease.n })),
+    );
+  const foreign = block
+    ? owners.filter((owner) => owner.n !== block)
+    : owners.filter((owner) => owner.n !== owners[0]?.n);
+  if (!foreign.length) return null;
+  return `this commit stages files another running block holds: ${foreign.map((owner) => `${owner.file} (B${owner.n})`).join(', ')}. Unstage them (git restore --staged <path>); if your block needs one, stop and ask the referee, who moves it between blocks. Never edit or commit another wrestler's files.`;
+}
+
+const jsonl = (path) =>
+  existsSync(path) ? parsePlanLog(readFileSync(path, 'utf8')) : [];
+
+/**
+ * The block each wrestler works on: its agent id (live.jsonl) → the Agent launch (tool_use_id) →
+ * the brief brief-guard saw → that brief's `block` in briefs/index.jsonl. PURE apart from reads.
+ */
+export function wrestlerBlocks(dir) {
+  const briefs = new Map(
+    jsonl(join(dir, 'briefs', 'index.jsonl'))
+      .filter((brief) => brief.kind === 'wrestler' && brief.block)
+      .map((brief) => [
+        `wrestler-${brief.mode}-${brief.n}.md`,
+        Number(brief.block),
+      ]),
+  );
+  const launches = new Map(
+    jsonl(join(dir, 'brief-guard.jsonl'))
+      .filter((entry) => entry.toolUseId && entry.path)
+      .map((entry) => [
+        entry.toolUseId,
+        briefs.get(entry.path.split('/').at(-1)),
+      ]),
+  );
+  const blocks = new Map();
+  for (const line of wrestlerLines(dir)) {
+    try {
+      const event = JSON.parse(line);
+      const agent = /^agent (\S+)$/.exec(event.note ?? '')?.[1];
+      const block = launches.get(event.id);
+      if (event.actor === 'luchador' && agent && block)
+        blocks.set(agent, block);
+    } catch {
+      // A torn line is skipped.
+    }
+  }
+  return blocks;
+}
+
+/** The running blocks of a bout dir, read now. */
+export function boutLeases(dir) {
+  const read = (name) =>
+    existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
+  return runningLeases(read(PLAN), parsePlanLog(read(PLAN_LOG)));
+}

package/ring/scripts/live.mjs

@@ -255,9 +255,17 @@ export function appendLive(file, event, keep = KEEP) {
 export function record(dir, raw) {
   if (!dir) return false;
   const { event } = validateEvent(raw);
-  return event ? appendLive(join(dir, LIVE_LOG), event) : false;
+  if (!event) return false;
+  // live.jsonl is trimmed to its last lines; who each wrestler is must outlive the trim (a concept
+  // close retires them by these ids, and lanes map them to their block).
+  if (event.actor === 'luchador' && /^agent \S+$/.test(event.note ?? ''))
+    appendFileSync(join(dir, WRESTLERS), `${JSON.stringify(event)}\n`);
+  return appendLive(join(dir, LIVE_LOG), event);
 }
 
+/** The launches of the bout's wrestlers (agent ids), kept whole. */
+export const WRESTLERS = 'wrestlers.jsonl';
+
 const within = (dir, path) => {
   const inside = relative(resolve(dir), resolve(path));
   return !inside.startsWith('..') && !isAbsolute(inside);

package/ring/scripts/lookout.mjs

@@ -19,11 +19,13 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
+  boutDir,
   DEFAULTS,
   isMain,
   loadConfig,
   projectDir,
   readState,
+  repoSlug,
   writeState,
 } from './config.mjs';
 import { counts, readLedger, reviewDeclared } from './findings.mjs';
@@ -332,7 +334,11 @@ function approve(dir, ref, { formatUnverified = null } = {}) {
 }
 
 if (isMain(import.meta.url)) {
-  const [command, dir, ...rest] = process.argv.slice(2);
+  const [command, target, ...rest] = process.argv.slice(2);
+  // A bout dir, or the PR number every other ring script takes.
+  const dir = /^\d+$/.test(target ?? '')
+    ? boutDir(repoSlug(projectDir()), target)
+    : target;
   const intervalIndex = rest.indexOf('--interval');
   const interval = intervalIndex === -1 ? 60 : Number(rest[intervalIndex + 1]);
   const fail = (error) => {

package/ring/scripts/mask-guard.mjs

@@ -12,6 +12,7 @@
 // it blocks too: a guard that cannot evaluate must not let the command through.
 import { boutArchGate } from './arch-gate.mjs';
 import { boutFormatGate } from './format-gate.mjs';
+import { boutLeases, commitLeaseRefusal, wrestlerBlocks } from './lanes.mjs';
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -803,6 +804,11 @@ const gitRules = [
     reason: (git, ctx) =>
       `This commit changes the API contract, database models or native surface (${ctx.unapprovedContractFiles(git).join(', ')}) without the judge's approval of exactly this content. Serve the preview (contract-preview.mjs), get the judge's yes, record it with judges-card.mjs approve-contract <pr> --files <paths>, then commit. Any edit after approval needs a new one.`,
   },
+  {
+    // Blocks running side by side in one worktree: a wrestler commits only its block's files.
+    when: (git, ctx) => git.sub === 'commit' && ctx.leaseRefusal(git) !== null,
+    reason: (git, ctx) => ctx.leaseRefusal(git),
+  },
   {
     // An amend adds no commit; everything else waits once the unreviewed range hits the cap.
     when: (git, ctx) =>
@@ -1067,7 +1073,7 @@ const ghRules = [
       gh.action === 'create' &&
       !hasFlag(gh.args, '--draft', '-d'),
     reason: () =>
-      'Every PR ring opens is a draft; only the human marks it ready. Add --draft to gh pr create.',
+      'Every PR opened while a bout is active is a draft, even one the human asked for outside the bout: add --draft to gh pr create, and tell the human the link; they mark it ready (gh pr ready <n>, or «Ready for review» on GitHub).',
   },
   {
     when: (gh) =>
@@ -1290,6 +1296,10 @@ function judgeSegment(segment, words, cwd, ctx) {
       hasAiTrailer(commitMessage(commit, segment, context)),
     commitBoutIds: (commit) => boutIds(commitMessage(commit, segment, context)),
     reviewDebt: (commit) => ctx.reviewDebtAt(context.path(commit.dir)),
+    leaseRefusal: (commit) =>
+      ctx.leaseRefusalAt(context.path(commit.dir), () =>
+        ctx.committedFiles(commit, commitsWorkingTree(commit)),
+      ),
     pushBeyondApproval: (push, refspecs) =>
       ctx.pushBeyondApprovalAt(context.path(push.dir), refspecs),
     findingsBeforePush: (push, refspecs) =>
@@ -1410,7 +1420,7 @@ function insideGitRepo(dir) {
  * The real context of one hook invocation. The host config is loaded lazily, only when a rule
  * reads it: a broken .claude/ring.json must not cost every command a parse, nor fail it.
  */
-function realContext(cwd) {
+function realContext(cwd, agentId = null) {
   const bouts = new Map();
   const slugs = new Map();
   let config = null;
@@ -1506,6 +1516,18 @@ function realContext(cwd) {
       contract ??= loadConfig(projectDir(process.env, cwd)).config;
       return contract;
     },
+    // A commit staging files another running block holds (parallelBlocks > 1), or null.
+    leaseRefusalAt: (dir, staged) => {
+      if ((loaded().parallelBlocks ?? 1) <= 1) return null;
+      const bout = boutOfDir(dir);
+      if (!bout) return null;
+      return commitLeaseRefusal({
+        staged: staged(),
+        running: boutLeases(bout.dir),
+        block: agentId ? (wrestlerBlocks(bout.dir).get(agentId) ?? null) : null,
+        generated: loaded().generatedPaths,
+      });
+    },
     // The unreviewed range of the bout whose worktree holds `dir`, when it is at or over the cap.
     reviewDebtAt: (dir) => {
       const bout = boutOfDir(dir);
@@ -1771,7 +1793,10 @@ function block(reason) {
 function evaluate(payload) {
   if (payload?.tool_name !== 'Bash') return;
   const command = payload?.tool_input?.command ?? '';
-  const verdict = decide(command, realContext(payload?.cwd || process.cwd()));
+  const verdict = decide(
+    command,
+    realContext(payload?.cwd || process.cwd(), payload?.agent_id ?? null),
+  );
   if (verdict.block) return block(verdict.reason);
   if (verdict.warnings.length)
     process.stdout.write(

package/ring/scripts/one-at-a-time.mjs

@@ -211,9 +211,20 @@ function reportInvisible(feed, command) {
   if (!feed.dir || feed.visible) return () => undefined;
   const id = `invisible:${process.pid}`;
   let shown = false;
-  console.error(
-    `one-at-a-time: no declared monitor shows "${commandLabel(command)}" on the Scorecard; a long run needs one: rerun with --monitor <id>, or declare a monitor whose match.command matches it`,
-  );
+  // Once per bout every few hours, not on every tsc or jest.
+  const marker = join(feed.dir, '.no-monitor-warned');
+  const fresh = (() => {
+    try {
+      return Date.now() - statSync(marker).mtimeMs < 6 * 3600_000;
+    } catch {
+      return false;
+    }
+  })();
+  if (!fresh) writeFileSync(marker, '');
+  if (!fresh)
+    console.error(
+      `one-at-a-time: no declared monitor shows "${commandLabel(command)}" on the Scorecard; a long run needs one: rerun with --monitor <id>, or declare a monitor whose match.command matches it`,
+    );
   const timer = setTimeout(() => {
     shown = true;
     record(feed.dir, {

package/ring/scripts/relay.mjs

@@ -11,7 +11,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { LIVE_LOG } from './live.mjs';
+import { LIVE_LOG, WRESTLERS } from './live.mjs';
 
 export const PROPOSALS = 'For the rulebook / precedents';
 const DECIDED = /→\s*(accepted|rejected)\b/;
@@ -115,6 +115,18 @@ export function withConceptClosed(state, { name, range, at, wrestlers }) {
   };
 }
 
+/** The wrestlers' launch lines (wrestlers.jsonl, never trimmed) and the live lines after them. */
+export function wrestlerLines(dir) {
+  try {
+    return [
+      ...readFileSync(join(dir, WRESTLERS), 'utf8').split('\n').filter(Boolean),
+      ...liveLines(dir),
+    ];
+  } catch {
+    return liveLines(dir);
+  }
+}
+
 /** The live lines of a bout, or none. */
 export function liveLines(dir) {
   try {

package/ring/scripts/review-blocks.mjs

@@ -10,6 +10,7 @@ import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { readState, writeState } from './config.mjs';
+import { globToRegExp } from './contract.mjs';
 import { parsePlan, parsePlanLog, PLAN, PLAN_LOG } from './tech-plan.mjs';
 
 export const VERDICTS = 'review-verdicts.jsonl';
@@ -25,6 +26,7 @@ const FACTS = [
   'startSha',
   'startedAt',
   'endedAt',
+  'files',
 ];
 
 /** The facts of point `n` so far: each field from the last plan.jsonl line that has it. PURE. */
@@ -86,8 +88,9 @@ export function startRefusal(facts, to, n) {
 }
 
 /** Checks an estimate: priority 1–4 and whole minutes. PURE. */
-export function estimateFacts({ priority, minutes }) {
+export function estimateFacts({ priority, minutes, files }) {
   const facts = {};
+  if (files?.length) facts.files = files;
   if (priority != null) {
     if (![1, 2, 3, 4].includes(Number(priority)))
       throw new Error('--priority is 1 (first) to 4 (last)');
@@ -168,6 +171,20 @@ export function verdictEffects(verdict) {
 
 const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
 
+/**
+ * The human's «no pasa» still open as rebounds: until the blocks wait on the judge again, every
+ * resume (summary, compaction) shows them first, with their Tape. PURE apart from the read.
+ */
+export function openHumanReturns(dir) {
+  return read(join(dir, 'rebounds.md'))
+    .split('\n')
+    .filter((line) => /^- \[ \] .*Revisión humana/.test(line));
+}
+
+/** What the referee does with a returned cut: read its Tape before writing the rebound. */
+export const TAPE_HINT =
+  'Read each Tape before writing the rebound (Battle Arena connector: mcp__claude_ai_Battle_Arena__qa_session_overview, then qa_session_timeline on the chapter) and cite its minutes in the rebound. If those tools are not in this session, say so to the human in one line and connect them (/mcp, the claude.ai Battle Arena connector); never design the rebound from the feedback line alone.';
+
 /** The author of a block: the git user of the worktree that writes it. */
 export function authorEmail(worktree) {
   try {
@@ -245,3 +262,28 @@ export function reviewTurn(dir, every, setState) {
   const waiting = blocksAwaitingReview(plan, log, verdicts);
   return { applied, waiting, due: reviewDue(waiting, every) };
 }
+
+/**
+ * Why a wrestler may not work ahead while the human reviews a cut, or null. Ahead means one block
+ * at a time (nothing else «en curso») on files declared up front that the cut under review does
+ * not touch, so the human's verdict on the cut never lands on code that moved. PURE.
+ */
+export function lookaheadRefusal({ globs, waitingFiles, running }) {
+  if (!globs.length)
+    return 'a block ahead of the review declares its files: --lookahead "<glob>,<glob>"';
+  if (running.length)
+    return `only one block works ahead of the review: B${running[0].n} «${running[0].title}» is already «en curso»`;
+  const matchers = globs.map((glob) => globToRegExp(glob));
+  const overlap = waitingFiles.filter((file) =>
+    matchers.some((matcher) => matcher.test(file)),
+  );
+  if (overlap.length)
+    return `the block ahead would touch files of the cut under review: ${overlap.join(', ')}. Pick a block that does not, or wait for the verdict`;
+  return null;
+}
+
+/** The blocks «en curso» right now. PURE. */
+export const runningBlocks = (plan) =>
+  parsePlan(plan)
+    .groups.flatMap((group) => group.items)
+    .filter((item) => item.state === 'en curso');

package/ring/scripts/tech-plan-log.mjs

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 
 import { readState } from './config.mjs';
 import { scriptJson } from './contract-endpoints.mjs';
+import { runningLeases, startLaneRefusal } from './lanes.mjs';
 import {
   authorEmail,
   blockFacts,
@@ -39,7 +40,7 @@ export function setPlanState(
   state,
   ref = null,
   at = new Date().toISOString(),
-  { range = null, estimate = null, requireEstimate = false } = {},
+  { range = null, estimate = null, requireEstimate = false, lanes = null } = {},
 ) {
   const file = join(dir, PLAN);
   const markdown = read(file);
@@ -68,6 +69,21 @@ export function setPlanState(
       ? startRefusal(facts, next, item.n)
       : null;
   if (refusal) throw new Error(refusal);
+  const laneRefusal =
+    lanes && next === 'en curso' && next !== item.state
+      ? startLaneRefusal({
+          n: item.n,
+          files: facts.files,
+          running: runningLeases(
+            markdown,
+            parsePlanLog(read(join(dir, PLAN_LOG))),
+          ),
+          parallel: lanes.parallel,
+          tracked: trackedFiles(worktree),
+          generated: lanes.generated,
+        })
+      : null;
+  if (laneRefusal) throw new Error(laneRefusal);
   writeFileSync(file, withPlanState(markdown, item, next));
   appendFileSync(
     join(dir, PLAN_LOG),
@@ -76,6 +92,21 @@ export function setPlanState(
   return { ...item, from: item.state, to: next, facts };
 }
 
+/** The files git tracks in the worktree (none when it is gone). */
+function trackedFiles(worktree) {
+  try {
+    return execFileSync('git', ['-C', worktree, 'ls-files'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    })
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /** The worktree's head, or null when it is gone. */
 function worktreeHead(worktree) {
   try {

package/ring/skills/referee/SKILL.md

@@ -199,7 +199,8 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    - each new range: `brief.mjs cornerman <pr> --mode range --vars <file>` (≤15 lines; the range
      is `lastReviewed..HEAD` unless you pass `--range`; your value: `claims`);
    - when the wrestler closes a concept: `--mode concept` (your values: `invariants`, numbered,
-     and `claims`; `designReference` at a UI venue), over ranges already reviewed one by one. It
+     always including «no question is asked again downstream for the same reason» (PR31), and
+     `claims`; `designReference` at a UI venue), over ranges already reviewed one by one. It
      also reads the concept as one piece through the venue's lenses: what no single range shows;
    - a design review: `--mode batch --files <f1,f2,…>`.
    **A concept ends its wrestler.** When the concept review approves it, run
@@ -219,7 +220,24 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    `humanReviewEvery` blocks waiting, brief.mjs stops: the human reviews that cut in PR Review Lab
    (bout mode) and signs a verdict with a Tape. The next brief applies it: a pass closes the
    blocks, a fail comes back as a rebound the next wrestler fixes first. Do not work around the
-   pause.
+   pause. **Work ahead while the human reviews:** one wrestler may take ONE more block whose files
+   the cut does not touch: `brief.mjs wrestler <pr> --mode resume --vars <file> --lookahead
+   "<glob>,<glob>"` (the files that block will touch). brief.mjs refuses it when those globs match a
+   file of the cut, or when another block is already «en curso». Its brief says which files it may
+   touch; a rebound from the verdict still goes first.
+   **Blocks side by side (`parallelBlocks` > 1 in `.claude/ring.json`)**: up to that many blocks
+   run at once in the SAME worktree, one wrestler each. Pick blocks that neither depend on each
+   other nor share a contract (props, a hook's return, i18n keys, a helper): a file lock does not
+   see that, you do. Start each with its files: `judges-card.mjs plan <pr> <n> "en curso"
+   --minutes <m> --priority <p> --files "<glob>,<glob>"`; the script refuses a start whose files a
+   running block holds. Brief each with `--block <n>` (its brief lists its files and the other
+   wrestler's). mask-guard refuses a commit that stages another block's file; a wrestler that needs
+   one stops and asks you: decide who keeps it (narrow one block's `--files` with `plan <pr>
+   estimate <n> --files …`). Close each with `judges-card.mjs concept <pr> "<name>" --range <A>..<B>
+   --block <n>`: only that block's wrestler retires. The review cap counts both wrestlers' commits:
+   review the shared range as usual. **When the wave closes** (both blocks wait on the judge),
+   regenerate the `generatedPaths` files once and commit them yourself, then run the typecheck and
+   the tests of both blocks on the shared tip before the human's cut.
    If the wrestler claimed something ("does not change counter X"), hand the claim to the
    cornerman to verify against the base. The cornerman always checks the format of the range
    (`format-gate.mjs check`); an unclean file is a finding like any other, fixed by the wrestler

package/ring/skills/referee/references/precedents.md

@@ -47,6 +47,12 @@ _Why: after the first approved slice was cited as the reference, the next one dr
 **PR11. Under doubt between two reasonable options, keep current behavior and wire contracts; ticket
 the rest.** _Why: a refactor that also "improves" behavior cannot be validated against the base._
 
+**PR31. A null or an undefined that crosses more than one function is settled where it is born.**
+With a default, a value that cannot be missing, or a Null Object; never asked again downstream for
+the same reason. Count how many times the range asks the same question: three or more is a finding.
+_Why: in agents-studio-fe#606 «did the call connect?» was asked six times downstream; each range
+review approved its piece, the human rejected the cut, and the first rebound only moved the cascade._
+
 ## Process
 
 **PR12. Small reviewed slices first, polish later.** No automated review loops or convergence before

package/ring/skills/referee/templates/wrestler-brief.md

@@ -32,7 +32,9 @@ WAITING ON THE HUMAN (hard list; do not touch): {{waitingOnHuman}}.
 Design doubts go to me, never to the human: I decide them (or escalate them) and tell you.
 
 Gates (from `.claude/ring.json`, each through one-at-a-time; a long run such as a battery adds
-`--monitor <id>` when its command does not match a declared monitor, so it shows on the Scorecard):
+`--monitor <id>` when its command does not match a declared monitor, so it shows on the Scorecard).
+Run them when the block's work is done, before you report it, on the files you touched; not after
+every edit (a half-written block fails for no reason and holds the machine):
 
 - typecheck: `{{gateTypecheck}}`
 - tests of what you touched: `{{gateTest}}`