@karajan-family/code 4.21.0

package/src/tournament/crown.js

@@ -0,0 +1,88 @@
+/**
+ * tournament/crown — TOR-C (KJC-TSK-0725, epic KJC-PCS-0073). The last act:
+ * the tournament winner enters main THROUGH THE NORMAL DOOR, not around it.
+ *
+ * In the winner's still-alive lane: stage everything, run the real cross-AI
+ * review over the EXACT staged diff (verdict bound to its sha256, stored by
+ * the same verdict-store every commit uses), then commit — where the
+ * pre-commit gate validates that verdict like any other commit's. A
+ * rejected review ABORTS the coronation with the reasons: winning the
+ * tournament earns you a candidacy, not a bypass. Losers keep their full
+ * dossier under the tournament dir; their lanes are never removed here.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { runOneShotReview } from "../review/one-shot-review.js";
+
+const execFileAsync = promisify(execFile);
+
+const defaultExec = async (cmd, args, { cwd }) => {
+  const res = await execFileAsync(cmd, args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+  return { exitCode: 0, stdout: res.stdout || "" };
+};
+
+async function defaultReview({ lane, task, config, logger }) {
+  const { stdout: diff } = await execFileAsync("git", ["diff", "--cached"], { cwd: lane, maxBuffer: 64 * 1024 * 1024 });
+  try {
+    const record = await runOneShotReview({
+      diff,
+      task: `Tournament winner review. Original task:\n${task}`,
+      config: { ...config, projectDir: lane },
+      logger,
+      projectDir: lane,
+    });
+    return { ok: record.verdict === "approved", ...record };
+  } catch (err) {
+    return { ok: false, verdict: "error", error: err.message };
+  }
+}
+
+/**
+ * Crown the judged winner: governed review + commit in its lane.
+ * @returns {Promise<{winner: string, branch: string, commit: string, verdict: object}>}
+ */
+export async function crownWinner({ tournamentDir, config = {}, logger = console, cardRef = null, deps = {} }) {
+  const { execFn = defaultExec, reviewFn = defaultReview } = deps;
+
+  const judgementPath = path.join(tournamentDir, "judgement.json");
+  if (!fs.existsSync(judgementPath)) {
+    throw new Error("tournament: no hay judgement.json — corre primero kj tournament --judge <id>");
+  }
+  const judgement = JSON.parse(fs.readFileSync(judgementPath, "utf8"));
+  const summary = JSON.parse(fs.readFileSync(path.join(tournamentDir, "summary.json"), "utf8"));
+  const winner = judgement.winner;
+  const meta = JSON.parse(fs.readFileSync(path.join(tournamentDir, winner, "meta.json"), "utf8"));
+  const lane = meta.lane;
+  if (!lane || !fs.existsSync(lane)) {
+    throw new Error(`tournament: el carril del ganador (${winner}) ya no existe — corona justo después de juzgar, antes de limpiar carriles`);
+  }
+
+  logger?.info?.(`coronando a ${winner} en ${meta.branch} — por la puerta normal, no por un atajo`);
+  await execFn("git", ["add", "-A"], { cwd: lane });
+
+  const verdict = await reviewFn({ lane, task: summary.task, config, logger });
+  if (!verdict?.ok) {
+    const issues = (verdict?.issues || []).map((i) => `  - ${i.description}`).join("\n");
+    throw new Error(
+      `tournament: la review RECHAZÓ al ganador (${winner}) — ganar el torneo da candidatura, no bypass.\n${issues || verdict?.error || ""}`
+    );
+  }
+
+  const ref = cardRef ? ` (${cardRef})` : "";
+  const msg = `feat(tournament): crown ${winner} — ${String(summary.task).slice(0, 50).toLowerCase()}${ref} [${summary.id}]`;
+  await execFn("git", ["commit", "-m", msg], { cwd: lane });
+  const { stdout } = await execFn("git", ["rev-parse", "HEAD"], { cwd: lane });
+  const commit = stdout.trim();
+
+  const crown = {
+    winner, branch: meta.branch, commit,
+    verdict: { verdict: verdict.verdict, reviewer: verdict.reviewer, diffHash: verdict.diffHash },
+    crowned_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(tournamentDir, "crown.json"), JSON.stringify(crown, null, 2));
+  logger?.info?.(`✓ coronado: ${winner} · commit ${commit.slice(0, 9)} en ${meta.branch} — la rama queda lista para PR`);
+  logger?.info?.("  los perdedores conservan su expediente en el dir del torneo; limpia carriles con kj worktree done cuando quieras");
+  return { winner, branch: meta.branch, commit, verdict: crown.verdict };
+}

package/src/tournament/judge.js

@@ -0,0 +1,150 @@
+/**
+ * tournament/judge — TOR-C (KJC-TSK-0725, epic KJC-PCS-0073).
+ *
+ * The scoreboard (TOR-B) ELIMINATES; the judge CHOOSES among survivors —
+ * a cross-AI reviewer ranking the finalists with the deterministic table
+ * in sight, so the LLM judges what metrics cannot see (design, readability,
+ * over-engineering) without overruling what they can. Two hard rules:
+ * a participant coder never judges its own tournament (nor does the host),
+ * and a WINNER disagreement with the scoreboard — or a declared tie —
+ * escalates to solomon carrying BOTH positions. Only first place crowns:
+ * lower-order differences are informative and never escalate (the card's
+ * "discrepancia fuerte" — over-escalating would make solomon the judge). Diffs travel WHOLE or the limit is
+ * DECLARED in the prompt (the [TRUNCATED]-blamed-on-the-file lesson,
+ * BUG-0134): the judge must never mistake our clipping for the coder's code.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+import { detectHostAgent } from "../utils/agent-detect.js";
+import { candidateStatus } from "../review/reviewer-fallback.js";
+
+const MAX_DIFF_CHARS = 60_000;
+
+/** The configured reviewer unless it competed or hosts; else the first clean candidate. */
+export function pickJudge({ configured, participants = [], host = null, statuses = [] }) {
+  const dirty = new Set([...participants, host].filter(Boolean));
+  if (configured && !dirty.has(configured)) return configured;
+  const clean = statuses.find((s) => s.installed && s.authenticated && !s.adapterPending && !dirty.has(s.name));
+  return clean ? clean.name : null;
+}
+
+async function defaultJudge({ config, participants }) {
+  const configured = resolveRole(config, "reviewer").provider;
+  const statuses = await candidateStatus();
+  return pickJudge({ configured, participants, host: detectHostAgent(), statuses });
+}
+
+async function defaultAgent({ judge, prompt, config, logger }) {
+  return createAgent(judge, config, logger).reviewTask({ prompt, role: "reviewer" });
+}
+
+function finalistBlock(board, torDir, coder) {
+  const row = board.rows.find((r) => r.coder === coder);
+  let diff = fs.readFileSync(path.join(torDir, coder, "diff.patch"), "utf8");
+  let clipped = false;
+  if (diff.length > MAX_DIFF_CHARS) {
+    diff = diff.slice(0, MAX_DIFF_CHARS);
+    clipped = true;
+  }
+  return [
+    `### Finalista: ${coder}`,
+    `Scoreboard: ${JSON.stringify(row)}`,
+    clipped
+      ? `NOTA DEL SISTEMA: el diff se muestra RECORTADO a ${MAX_DIFF_CHARS} caracteres por límite del prompt — el recorte es NUESTRO, no un defecto del código; júzgalo por lo visible y dilo en tus razones.`
+      : "",
+    "```diff", diff, "```",
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Judge a scored tournament: rank finalists, escalate on tie/disagreement.
+ * @returns {Promise<{winner: string, judge: string|null, escalated: boolean, walkover?: boolean}>}
+ */
+export async function judgeTournament({ tournamentDir, config = {}, logger = console, deps = {} }) {
+  const { judgeFn = defaultJudge, agentFn = defaultAgent, solomonFn = null } = deps;
+  const board = JSON.parse(fs.readFileSync(path.join(tournamentDir, "scoreboard.json"), "utf8"));
+  const finalists = board.rows.filter((r) => r.finalist).map((r) => r.coder);
+  const participants = board.rows.map((r) => r.coder);
+
+  if (finalists.length === 0) throw new Error("tournament: sin finalistas (todas las suites rojas) — no hay nada que juzgar");
+  if (finalists.length === 1) {
+    const judgement = { winner: finalists[0], judge: null, escalated: false, walkover: true, board_ranking: board.ranking };
+    fs.writeFileSync(path.join(tournamentDir, "judgement.json"), JSON.stringify(judgement, null, 2));
+    logger?.info?.(`torneo ${board.id}: ganador por walkover — ${finalists[0]} (único finalista)`);
+    return judgement;
+  }
+
+  const judge = await judgeFn({ config, participants });
+  if (!judge) {
+    throw new Error(
+      "tournament: sin juez limpio — todos los agentes disponibles compitieron o son el host. " +
+      "Un participante jamás juzga su propio torneo: quita un coder o añade un agente."
+    );
+  }
+
+  const prompt = [
+    "Eres el JUEZ de un torneo de código: varios coders resolvieron la MISMA tarea de forma independiente.",
+    "La fase determinista ya eliminó a los que suspendieron la suite. Tu trabajo: ordenar a los finalistas",
+    "por calidad de solución (diseño, legibilidad, ausencia de sobre-ingeniería), con el scoreboard a la vista.",
+    `Regla del scoreboard: ${board.rule}`,
+    `Ranking del scoreboard: ${board.ranking.join(" > ")}`,
+    `TAREA ORIGINAL:\n${board.task}`,
+    ...finalists.map((c) => finalistBlock(board, tournamentDir, c)),
+    'Responde SOLO con JSON: {"ranking": ["coder", ...], "reasons": {"coder": "por qué"}, "tie": false}',
+    "Declara tie:true únicamente si de verdad no puedes distinguirlos.",
+  ].join("\n\n");
+
+  logger?.info?.(`torneo ${board.id}: juez=${judge} sobre ${finalists.length} finalistas`);
+  const res = await agentFn({ judge, prompt, config, logger });
+  if (!res?.ok) throw new Error(`tournament: el juez ${judge} falló: ${res?.error || "sin salida"}`);
+  let verdict;
+  try {
+    verdict = JSON.parse(String(res.output).replace(/^[^{]*/, "").replace(/[^}]*$/, ""));
+  } catch {
+    throw new Error(`tournament: el juez ${judge} no devolvió un veredicto parseable`);
+  }
+  // An LLM verdict is untrusted input: the ranking must name FINALISTS and
+  // nobody else — a hallucinated coder must fail loud, never get crowned.
+  const isFinalist = (c) => finalists.includes(c);
+  if (!Array.isArray(verdict.ranking) || verdict.ranking.length === 0 || !verdict.ranking.every(isFinalist)) {
+    throw new Error(`tournament: ranking del juez inválido (${JSON.stringify(verdict.ranking)}) — debe nombrar solo finalistas: ${finalists.join(", ")}`);
+  }
+
+  // Only FIRST place crowns a winner: a judge that reorders lower positions
+  // but agrees on who wins is agreement, not a dispute for solomon.
+  const judgeTop = verdict.ranking?.[0];
+  const boardTop = board.ranking[0];
+  const disagreement = judgeTop !== boardTop;
+  const escalated = Boolean(verdict.tie || disagreement);
+
+  let winner = judgeTop;
+  let solomon = null;
+  if (escalated) {
+    if (!solomonFn) {
+      const why = verdict.tie ? "empate declarado" : `discrepancia juez(${judgeTop}) vs scoreboard(${boardTop})`;
+      throw new Error(`tournament: ${why} y sin árbitro configurado`);
+    }
+    solomon = await solomonFn({
+      judgeRanking: verdict.ranking,
+      boardRanking: board.ranking,
+      reasons: verdict.reasons,
+      tie: Boolean(verdict.tie),
+    });
+    if (!isFinalist(solomon?.winner)) {
+      throw new Error(`tournament: solomon devolvió un ganador inválido (${solomon?.winner}) — debe ser finalista`);
+    }
+    winner = solomon.winner;
+  }
+
+  const judgement = {
+    winner, judge, escalated,
+    judge_ranking: verdict.ranking, judge_reasons: verdict.reasons || {},
+    board_ranking: board.ranking, solomon,
+    judged_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(tournamentDir, "judgement.json"), JSON.stringify(judgement, null, 2));
+  logger?.info?.(`torneo ${board.id}: ganador=${winner}${escalated ? " (vía solomon)" : " (juez y scoreboard de acuerdo)"}`);
+  return judgement;
+}

package/src/tournament/run.js

@@ -0,0 +1,142 @@
+/**
+ * tournament/run — TOR-A (KJC-TSK-0723, epic KJC-PCS-0073).
+ *
+ * Orca's pitch is "fan one prompt across N agents, compare, merge the
+ * winner" — with a human eyeballing diffs. Karajan's tournament keeps the
+ * fan-out and replaces the eyeballing with the method: this module runs the
+ * SAME task through N coders, each in its own isolated worktree lane (the
+ * PAR machinery), and collects per-lane evidence (diff, suite result, agent
+ * log, metadata) for the deterministic scoreboard (TOR-B) and the governed
+ * judgement/merge (TOR-C). No commits here: lanes stay as working trees.
+ *
+ * A COMPOSER, not a new pipeline: lanes = `git worktree` under
+ * .kj/worktrees (same dir as kj worktree / headless lanes); agents = the
+ * registered adapters with the PAR idiom (laneConfig.projectDir = lane,
+ * task.cwd = lane); suite = the package manager the repo actually uses.
+ * Every dependency is injectable; one lane's failure never sinks another.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createAgent } from "../agents/index.js";
+import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
+import { detectPackageManager } from "../harden/workflow-engine.js";
+import { PM_COMMANDS } from "../harden/workflow-templates.js";
+
+const execFileAsync = promisify(execFile);
+const WORKTREE_DIR = ".kj/worktrees"; // shared with kj worktree + headless lanes
+const TOURNAMENT_DIR = ".kj/tournaments";
+const SUITE_TIMEOUT_MS = 15 * 60 * 1000;
+
+const defaultGit = (args, cwd) => execFileAsync("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+
+async function defaultRunSuite({ lanePath }) {
+  const pm = detectPackageManager(lanePath);
+  const testCmd = (PM_COMMANDS[pm] || PM_COMMANDS.npm).test.split(" ");
+  try {
+    const res = await execFileAsync(testCmd[0], testCmd.slice(1), {
+      cwd: lanePath, timeout: SUITE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
+    });
+    return { ok: true, exitCode: 0, output: res.stdout || "" };
+  } catch (err) {
+    return { ok: false, exitCode: err.code ?? 1, output: `${err.stdout || ""}\n${err.stderr || ""}` };
+  }
+}
+
+/**
+ * Fan the task out to every coder and collect per-lane results.
+ * @returns {Promise<{id: string, dir: string, lanes: Array<object>}>}
+ */
+export async function runTournament({ task, coders = [], config = {}, logger = console, deps = {} }) {
+  const {
+    createAgentFn = createAgent,
+    gitFn = defaultGit,
+    bootstrapFn = bootstrapWorktree,
+    runSuiteFn = defaultRunSuite,
+  } = deps;
+  if (!task || !String(task).trim()) throw new Error("tournament: falta la tarea");
+  if (!Array.isArray(coders) || coders.length < 2) {
+    throw new Error("tournament: hacen falta al menos 2 coders (--coders a,b) — con uno no hay torneo");
+  }
+  // Coder names feed lane/result PATHS: a strict slug (no separators, no
+  // leading dot, no traversal) before any filesystem use — codex's catch.
+  const CODER_RE = /^[a-z0-9][a-z0-9_-]{0,23}$/i;
+  for (const c of coders) {
+    if (!CODER_RE.test(String(c))) {
+      throw new Error(`tournament: nombre de coder inválido "${c}" — solo letras, dígitos, guiones (sin rutas)`);
+    }
+  }
+
+  const projectDir = config.projectDir || process.cwd();
+  const id = `tor-${Date.now().toString(36)}`;
+  const resultsRoot = path.join(projectDir, TOURNAMENT_DIR, id);
+  fs.mkdirSync(resultsRoot, { recursive: true });
+  logger?.info?.(`kj tournament ${id}: ${coders.length} coders → ${coders.join(", ")}`);
+
+  const settled = await Promise.allSettled(coders.map((coder) => runLane({
+    coder, task, id, projectDir, resultsRoot, config, logger,
+    createAgentFn, gitFn, bootstrapFn, runSuiteFn,
+  })));
+
+  const lanes = settled.map((s, i) =>
+    s.status === "fulfilled"
+      ? s.value
+      : { coder: coders[i], status: "failed", error: String(s.reason?.message || s.reason), dir: path.join(resultsRoot, coders[i]) },
+  );
+
+  const summary = { id, task: String(task), created_at: new Date().toISOString(), lanes };
+  fs.writeFileSync(path.join(resultsRoot, "summary.json"), JSON.stringify(summary, null, 2));
+  for (const lane of lanes) {
+    let state = `FAILED: ${lane.error}`;
+    if (lane.status === "completed") state = lane.suite?.ok ? "suite verde" : "suite ROJA";
+    logger?.info?.(`  ${lane.coder.padEnd(10)} ${lane.status.padEnd(10)} ${state}`);
+  }
+  return { id, dir: resultsRoot, lanes };
+}
+
+async function runLane({ coder, task, id, projectDir, resultsRoot, config, logger, createAgentFn, gitFn, bootstrapFn, runSuiteFn }) {
+  const slug = `${id}-${coder}`;
+  const lanePath = path.join(projectDir, WORKTREE_DIR, slug);
+  const branch = `tor/${slug}`;
+  const laneDir = path.join(resultsRoot, coder);
+  fs.mkdirSync(laneDir, { recursive: true });
+
+  await gitFn(["worktree", "add", "-b", branch, lanePath], projectDir);
+  await bootstrapFn({ worktreePath: lanePath, setupCommand: config?.session?.worktree_setup || null });
+
+  // The PAR idiom: the lane IS the project for this agent. A tournament
+  // coder MUST be able to write files — found live in the first real run:
+  // codex without auto_approve produced an honest but useless EMPTY diff.
+  const laneConfig = {
+    ...config,
+    projectDir: lanePath,
+    coder_options: { ...config?.coder_options, auto_approve: true },
+  };
+  const prompt =
+    `You are one of ${"several"} coders solving the SAME task independently. ` +
+    `Work ONLY inside this directory (your isolated worktree). Implement the task with tests. Do not commit.\n\nTASK:\n${task}`;
+  const started = Date.now();
+  const result = await createAgentFn(coder, laneConfig, logger).runTask({ prompt, role: "coder", cwd: lanePath });
+  fs.writeFileSync(path.join(laneDir, "agent.log"), String(result?.output ?? ""));
+  if (!result?.ok) throw new Error(`coder ${coder} failed: ${result?.error || "no output"}`);
+
+  // Intent-to-add first: plain `git diff` is blind to UNTRACKED files, and
+  // new files are the most common coder output — codex's catch.
+  await gitFn(["add", "-N", "."], lanePath);
+  const diff = await gitFn(["diff"], lanePath);
+  fs.writeFileSync(path.join(laneDir, "diff.patch"), diff.stdout || "");
+
+  const suite = await runSuiteFn({ lanePath });
+  fs.writeFileSync(path.join(laneDir, "suite.log"), suite.output || "");
+
+  const meta = {
+    coder, branch, lane: lanePath, tournament: id,
+    duration_ms: Date.now() - started,
+    diff_bytes: (diff.stdout || "").length,
+    suite: { ok: suite.ok, exitCode: suite.exitCode },
+  };
+  fs.writeFileSync(path.join(laneDir, "meta.json"), JSON.stringify(meta, null, 2));
+
+  return { coder, status: "completed", branch, lane: lanePath, dir: laneDir, suite: { ok: suite.ok, exitCode: suite.exitCode } };
+}

package/src/tournament/scoreboard.js

@@ -0,0 +1,124 @@
+/**
+ * tournament/scoreboard — TOR-B (KJC-TSK-0724, epic KJC-PCS-0073).
+ *
+ * The deterministic half of "merge the winner": pure metrics computed from
+ * the artifacts TOR-A leaves under .kj/tournaments/<id>/ (suite verdict,
+ * net LOC, tests touched — parsed from diff.patch), plus injectable
+ * external metrics (mutation via `kj mutate` in the still-alive lane;
+ * sonar reserved) that degrade HONESTLY to null-with-note when their tool
+ * is unavailable — a fake zero would poison the ranking. Red suites are
+ * eliminated, never finalists. The ranking rule is lexicographic and
+ * PRINTED with the result: no opaque composite scores, no hidden weights.
+ * Zero LLM in this whole phase.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const TESTS_RE = /(?:(?:^|\/)(?:tests?|__tests__|spec)\/)|(?:\.(?:test|spec)\.[a-z]+$)/;
+const MUTATE_TIMEOUT_MS = 10 * 60 * 1000;
+
+// EXACT unified-diff header forms — an added line whose content starts with
+// "++" produces "+++<content>" and must still COUNT (codex's catch): only
+// `+++ b/…`, `+++ /dev/null`, `--- a/…`, `--- /dev/null` are headers.
+const ADD_HEADER_RE = /^\+\+\+ (b\/|\/dev\/null)/;
+const DEL_HEADER_RE = /^--- (a\/|\/dev\/null)/;
+
+/** Pure unified-diff stats: files, additions/deletions/net, tests touched. */
+export function parseDiffStats(patch) {
+  const files = [];
+  let additions = 0;
+  let deletions = 0;
+  for (const line of String(patch || "").split("\n")) {
+    if (ADD_HEADER_RE.test(line)) {
+      if (line.startsWith("+++ b/")) files.push(line.slice(6).trim());
+    } else if (DEL_HEADER_RE.test(line)) {
+      // deletion-side header — never a counted line
+    } else if (line.startsWith("+")) additions++;
+    else if (line.startsWith("-")) deletions++;
+  }
+  const testsTouched = files.filter((f) => TESTS_RE.test(f)).length;
+  return { files, additions, deletions, net: additions - deletions, testsTouched };
+}
+
+export async function defaultMutate({ lane }) {
+  // Mutation runs IN the live worktree lane — codex's catch: guard the path
+  // explicitly so a gone/relative lane yields a DISTINCT note instead of
+  // silently degrading the ranking.
+  if (!lane || !path.isAbsolute(lane) || !fs.existsSync(lane)) {
+    return { score: null, note: "lane no longer exists — score after the fan-out, before cleaning lanes" };
+  }
+  try {
+    const res = await execFileAsync("kj", ["mutate", "--json"], { cwd: lane, timeout: MUTATE_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 });
+    const parsed = JSON.parse(res.stdout);
+    return { score: parsed.score ?? null, killed: parsed.killed ?? null, survived: parsed.survived ?? null };
+  } catch {
+    return null; // kj unavailable / no mutants / timeout — honest n/a
+  }
+}
+
+// Sonar-per-lane needs the running-server collector; reserved as a future
+// step (see card). Injectable so TOR-C or tests can supply real findings.
+const defaultSonar = async () => null;
+
+/**
+ * Score every lane of a tournament from its artifacts.
+ * @returns {Promise<{id: string, rows: Array<object>, ranking: string[], rule: string}>}
+ */
+export async function scoreTournament({ tournamentDir, deps = {} }) {
+  const { mutateFn = defaultMutate, sonarFn = defaultSonar } = deps;
+  const summary = JSON.parse(fs.readFileSync(path.join(tournamentDir, "summary.json"), "utf8"));
+
+  const rows = [];
+  for (const lane of summary.lanes) {
+    if (lane.status !== "completed") {
+      rows.push({ coder: lane.coder, finalist: false, eliminated_by: "failed", error: lane.error || null });
+      continue;
+    }
+    const laneDir = lane.dir || path.join(tournamentDir, lane.coder);
+    const meta = JSON.parse(fs.readFileSync(path.join(laneDir, "meta.json"), "utf8"));
+    const loc = parseDiffStats(fs.readFileSync(path.join(laneDir, "diff.patch"), "utf8"));
+
+    let mutation = { score: null, note: "not available" };
+    try {
+      const m = await mutateFn({ coder: lane.coder, lane: meta.lane, laneDir });
+      if (m && typeof m.score === "number") mutation = { ...m, note: null };
+      else if (m?.note) mutation = { score: null, note: m.note };
+    } catch { /* honest n/a — never a fake zero */ }
+    const sonar = await sonarFn({ coder: lane.coder, lane: meta.lane, files: loc.files }).catch(() => null);
+
+    const suiteOk = Boolean(meta.suite?.ok);
+    rows.push({
+      coder: lane.coder,
+      finalist: suiteOk,
+      eliminated_by: suiteOk ? null : "suite",
+      suite: meta.suite,
+      loc,
+      mutation,
+      sonar,
+    });
+  }
+
+  const anyMutation = rows.some((r) => typeof r.mutation?.score === "number");
+  const rule = anyMutation
+    ? "finalistas = suite verde; orden: mutation desc SOLO entre carriles que la tienen (null jamás penaliza — codex's catch), luego LOC neto asc"
+    : "finalistas = suite verde; orden: LOC neto asc (mutation no disponible)";
+
+  const ranking = rows
+    .filter((r) => r.finalist)
+    .sort((a, b) => {
+      const ma = a.mutation?.score;
+      const mb = b.mutation?.score;
+      // Mutation only compares when BOTH lanes have a real score — a null
+      // (tool unavailable) must stay a note, never become a hidden penalty.
+      if (typeof ma === "number" && typeof mb === "number" && mb !== ma) return mb - ma;
+      return a.loc.net - b.loc.net;
+    })
+    .map((r) => r.coder);
+
+  const board = { id: summary.id, task: summary.task, rule, ranking, rows, scored_at: new Date().toISOString() };
+  fs.writeFileSync(path.join(tournamentDir, "scoreboard.json"), JSON.stringify(board, null, 2));
+  return board;
+}

package/src/tracker-bootstrap.js

@@ -0,0 +1,44 @@
+/**
+ * Tracker bootstrap — registers the configured task-tracker adapter into
+ * the orchestrator's integrations registry at runtime.
+ *
+ * This module exists so that `src/orchestrator/` never imports
+ * `src/planning-game/` (or any other tracker) directly — the architecture
+ * invariant `tests/architecture/tracker-coupling.test.js` enforces that.
+ * `runFlow` calls `ensureTrackerRegistered(config)` from here; this
+ * module owns the conditional import of each adapter.
+ *
+ * Adding a new tracker:
+ *   1. Write `src/adapters/<name>/adapter.js` with the hook surface
+ *      documented in `src/orchestrator/integrations.js`.
+ *   2. Add a branch below that imports and registers it when the relevant
+ *      config flag is true.
+ *
+ * The function is idempotent: once registered, subsequent calls are
+ * no-ops (the registry already has an entry for the slot).
+ */
+
+import { getIntegration, registerIntegration } from "./orchestrator/integrations.js";
+
+/**
+ * Ensure the tracker adapter configured by `config` is registered under
+ * the `"tracker"` slot. Safe to call on every `runFlow` invocation.
+ *
+ * @param {object|null} config
+ * @returns {Promise<void>}
+ */
+export async function ensureTrackerRegistered(config) {
+  if (getIntegration("tracker")) return; // Already registered.
+
+  if (config?.planning_game?.enabled) {
+    try {
+      const { planningGameAdapter } = await import("./planning-game/pipeline-adapter.js");
+      registerIntegration("tracker", planningGameAdapter);
+    } catch { /* registration failed — non-blocking, adapter stays absent */ }
+    return;
+  }
+
+  // No tracker enabled — the orchestrator's `getIntegration("tracker")`
+  // calls will return undefined and every hook becomes an optional-chain
+  // no-op. That's the intended behavior for "tracker disabled" runs.
+}

package/src/types/agent.js

@@ -0,0 +1,55 @@
+/**
+ * Agent result / response typedefs. Every provider agent (claude, codex,
+ * gemini, opencode, aider) returns a shape that's a superset of AgentResult.
+ *
+ * AgentResponse<T> is the generic wrapper used when a caller has parsed
+ * the raw output into a structured payload of type T.
+ */
+
+/**
+ * Raw agent result as returned by agent.runTask() / agent.reviewTask().
+ *
+ * @typedef {Object} AgentResult
+ * @property {boolean} ok                       - whether the call succeeded
+ * @property {string} [output]                  - raw stdout / response text
+ * @property {string} [summary]                 - short human summary
+ * @property {Object} [result]                  - structured result (stage-specific)
+ * @property {string} [error]
+ * @property {string} [stderr]
+ * @property {string} [stdout]
+ * @property {number} [exitCode]
+ * @property {AgentUsage} [usage]
+ * @property {string} [provider]
+ * @property {string} [model]
+ */
+
+/**
+ * Token/cost reporting shape. Fields optional because not all providers
+ * report all metrics.
+ *
+ * @typedef {Object} AgentUsage
+ * @property {number} [input_tokens]
+ * @property {number} [output_tokens]
+ * @property {number} [cached_tokens]
+ * @property {number} [total_tokens]
+ * @property {number} [cost_usd]
+ */
+
+/**
+ * Generic agent response — AgentResult whose `result` field is typed.
+ *
+ * Example:
+ *   /** @type {import("../types/agent.js").AgentResponse<import("./review-result.js").ReviewResult>} *\/
+ *
+ * @template T
+ * @typedef {Object} AgentResponse
+ * @property {boolean} ok
+ * @property {T} [result]
+ * @property {string} [output]
+ * @property {string} [summary]
+ * @property {string} [error]
+ * @property {AgentUsage} [usage]
+ * @property {string} [provider]
+ */
+
+export {};