karajan-code 4.13.0 → 4.15.0

package/src/review/reviewer-fallback.js

@@ -0,0 +1,125 @@
+/**
+ * reviewer-fallback (KJC-TSK-0730) — running out of reviewer quota must
+ * never leave the method without a third party, and must never be silent:
+ * either an authenticated candidate takes over WITH a loud notice, or the
+ * user gets a menu of candidates with their tier and the exact login
+ * command. Born from the real codex weekly-quota outage of 2026-08-06.
+ *
+ * The registry is declarative. `install` is only present when the command
+ * was VERIFIED (never invent package names); auth heuristics are cheap
+ * local file checks — informative for the menu, while the actual failover
+ * only sticks if the candidate answers.
+ */
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { checkBinary } from "../utils/agent-detect.js";
+
+export const REVIEWER_CANDIDATES = [
+  {
+    name: "codex",
+    tier: "suscripción ChatGPT (cuota semanal compartida entre modelos)",
+    login: "codex → Sign in with ChatGPT",
+    install: "npm i -g @openai/codex",
+    authPaths: [".codex/auth.json"],
+  },
+  {
+    name: "copilot",
+    tier: "gratis (tier free de GitHub Copilot; más cuota con suscripción)",
+    login: "copilot → autenticación GitHub",
+    install: "npm i -g @github/copilot",
+    authPaths: [".copilot/config.json"],
+  },
+  {
+    name: "agy",
+    tier: "suscripción Google AI Pro/Ultra (sucesor del gemini CLI, retirado 06-2026)",
+    login: "agy → /login (cuenta Google)",
+    install: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+    authPaths: [".gemini/antigravity-cli"],
+  },
+  {
+    name: "kimi",
+    tier: "gratis (Kimi Code, Moonshot K2.x)",
+    login: "kimi login (device-code; si dice 'No model configured', repítelo)",
+    install: null,
+    authPaths: [".kimi-code/credentials"],
+  },
+  {
+    name: "qwen",
+    tier: "requiere plan o API key (el tier gratis hosted se retiró en 04-2026)",
+    login: "qwen → OAuth o API key OpenAI-compatible",
+    install: "npm i -g @qwen-code/qwen-code",
+    authPaths: [".qwen/oauth_creds.json"],
+  },
+  {
+    name: "aider",
+    tier: "API keys propias (pago por token: OpenAI/Anthropic/OpenRouter…)",
+    login: "exportar OPENAI_API_KEY / ANTHROPIC_API_KEY (o ~/.aider.conf.yml)",
+    install: "pipx install aider-chat || pip3 install aider-chat",
+    authPaths: [".aider.conf.yml"],
+    authEnv: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "OPENROUTER_API_KEY"],
+  },
+  {
+    name: "opencode",
+    tier: "gratis con modelos locales (LiteLLM/Ollama) o API keys propias",
+    login: "provider en ~/.config/opencode/opencode.json",
+    install: null,
+    authPaths: [".config/opencode/opencode.json"],
+  },
+];
+
+const QUOTA_RE = /usage limit|quota|rate.?limit|credits? (?:exhausted|left: ?0)|hit your .{0,20}limit/i;
+
+/** True when the agent error smells like exhausted quota, not a real failure. */
+export function isQuotaExhausted(text) {
+  return typeof text === "string" && QUOTA_RE.test(text);
+}
+
+/** installed × authenticated for every candidate, from cheap local checks. */
+export async function candidateStatus({ home = os.homedir(), checkBin = checkBinary, env = process.env } = {}) {
+  return Promise.all(
+    REVIEWER_CANDIDATES.map(async (c) => {
+      let installed = false;
+      try {
+        installed = (await checkBin(c.name)).ok;
+      } catch { /* not installed */ }
+      // Session-file heuristics, or env keys for CLIs (aider) that carry
+      // no session file. Key present ≠ credit left — it is menu signal;
+      // the failover only sticks if the candidate actually answers.
+      const authenticated =
+        c.authPaths.some((p) => existsSync(path.join(home, p))) ||
+        (c.authEnv || []).some((name) => Boolean(env[name]));
+      return { ...c, installed, authenticated };
+    }),
+  );
+}
+
+/**
+ * First candidate that is installed, authenticated, has a kj adapter and is
+ * not excluded (the exhausted reviewer and the host — the brain NEVER
+ * reviews itself).
+ */
+export function pickQuotaFallback(statuses, { exclude = [] } = {}) {
+  const found = statuses.find(
+    (s) => s.installed && s.authenticated && !s.adapterPending && !exclude.includes(s.name),
+  );
+  return found ? found.name : null;
+}
+
+/** Human/agent-readable menu: tier, state, and the exact command per candidate. */
+export function formatCandidateMenu(statuses, { exclude = [] } = {}) {
+  const lines = statuses
+    .filter((s) => !exclude.includes(s.name))
+    .map((s) => {
+      let state = "no instalado";
+      if (s.authenticated) state = "logado";
+      else if (s.installed) state = "instalado, SIN login";
+      let action = "";
+      if (!s.authenticated) {
+        action = s.installed || !s.install ? ` — login: ${s.login}` : ` — instalar: ${s.install}`;
+      }
+      const pending = s.adapterPending ? " [adaptador kj pendiente: KJC-TSK-0729]" : "";
+      return `  - ${s.name} (${s.tier}) · ${state}${action}${pending}`;
+    });
+  return `Candidatos a reviewer:\n${lines.join("\n")}\nElige uno, haz su login y fija roles.reviewer.provider — o pasa --reviewer <nombre>.`;
+}

package/src/roles/reviewer-role.js

@@ -2,21 +2,16 @@ import { AgentRole } from "./agent-role.js";
 import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
 import { extractFirstJson } from "../utils/json-extract.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
+import { clipDiff } from "../prompts/diff-clip.js";
+import { buildSplitSignal } from "../prompts/split-signal.js";
 import { isMutationReviewEnabled, buildReviewerMutationSignal } from "../mutate/reviewer-signal.js";
 
-const MAX_DIFF_LENGTH = 12000;
-
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
   "Do NOT use any MCP tools. Focus only on reviewing the code."
 ].join(" ");
 
-function truncateDiff(diff) {
-  if (!diff) return "";
-  return diff.length > MAX_DIFF_LENGTH ? `${diff.slice(0, MAX_DIFF_LENGTH)}\n\n[TRUNCATED]` : diff;
-}
-
 export class ReviewerRole extends AgentRole {
   constructor(opts) {
     super({ ...opts, name: "reviewer" });
@@ -44,6 +39,10 @@ export class ReviewerRole extends AgentRole {
       enabled: isMutationReviewEnabled(),
       projectDir: this.config?.projectDir,
     });
+    // KJC-BUG-0134: a clip is declared as kj's own, outside the diff body.
+    const { body: clippedDiff, note: clipNote } = clipDiff(diff || "");
+    // KJC-BUG-0138: moved-lines correlation, computed on the FULL diff.
+    const splitSignal = buildSplitSignal(diff || "");
     const layout = buildPromptLayout([
       section(SUBAGENT_PREAMBLE, STABLE),
       section(this.instructions, STABLE),
@@ -56,7 +55,9 @@ export class ReviewerRole extends AgentRole {
       section(buildRtkInstructions({ rtkAvailable: Boolean(this.config?.rtk?.available) }), STABLE),
       section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
       section(`Task context:\n${task}`, VOLATILE),
-      section(`Git diff:\n${truncateDiff(diff)}`, VOLATILE),
+      section(`Git diff:\n${clippedDiff}`, VOLATILE),
+      section(clipNote, VOLATILE),
+      section(splitSignal, VOLATILE),
       section(mutationSignal, VOLATILE),
     ]);
     return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };

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,151 @@
+/**
+ * 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) {
+      throw new Error(
+        `tournament: ${verdict.tie ? "empate declarado" : `discrepancia juez(${judgeTop}) vs scoreboard(${boardTop})`} 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;
+}