karajan-code 4.13.0 → 4.15.0

package/src/commands/tournament.js

@@ -0,0 +1,85 @@
+/**
+ * `kj tournament` (KJC-TSK-0723, TOR-A) — fan the SAME task out to N coders
+ * in N isolated worktree lanes and collect the evidence. The deterministic
+ * scoreboard (TOR-B) and the governed judgement/merge (TOR-C) build on the
+ * artifacts this command leaves under .kj/tournaments/<id>/.
+ */
+import path from "node:path";
+import { runTournament } from "../tournament/run.js";
+import { scoreTournament } from "../tournament/scoreboard.js";
+import { judgeTournament } from "../tournament/judge.js";
+import { crownWinner } from "../tournament/crown.js";
+
+// The id feeds a path — same traversal class codex caught in TOR-A's coder
+// names: strict slug, no separators, before any filesystem use.
+function tournamentDirFor(config, rawId) {
+  const id = String(rawId);
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(id)) {
+    throw new Error(`tournament: id inválido "${id}" — usa el id que imprimió el torneo (p. ej. tor-abc123)`);
+  }
+  return path.join(config?.projectDir || process.cwd(), ".kj", "tournaments", id);
+}
+
+export async function tournamentCommand({
+  task, config, logger = console, flags = {},
+  runTournamentFn = runTournament, scoreTournamentFn = scoreTournament,
+  judgeTournamentFn = judgeTournament, crownWinnerFn = crownWinner,
+}) {
+  // TOR-C: `--judge <id>` ranks the finalists; `--crown <id>` commits the
+  // winner through the real gate in its lane.
+  if (flags.judge) {
+    const judgement = await judgeTournamentFn({ tournamentDir: tournamentDirFor(config, flags.judge), config, logger });
+    if (flags.json) logger?.info?.(JSON.stringify(judgement));
+    else logger?.info?.(`  siguiente: kj tournament --crown ${flags.judge}${judgement.escalated ? " (ganador vía solomon)" : ""}`);
+    return judgement;
+  }
+  if (flags.crown) {
+    const crown = await crownWinnerFn({
+      tournamentDir: tournamentDirFor(config, flags.crown), config, logger, cardRef: flags.card || null,
+    });
+    if (flags.json) logger?.info?.(JSON.stringify(crown));
+    return crown;
+  }
+
+  // TOR-B: `--score <id>` scores an EXISTING tournament from its artifacts.
+  if (flags.score) {
+    const tournamentDir = tournamentDirFor(config, flags.score);
+    const board = await scoreTournamentFn({ tournamentDir });
+    if (flags.json) {
+      logger?.info?.(JSON.stringify(board));
+      return board;
+    }
+    logger?.info?.(`scoreboard ${board.id} — regla: ${board.rule}`);
+    for (const r of board.rows) {
+      if (!r.finalist) {
+        logger?.info?.(`  ${r.coder.padEnd(10)} eliminado (${r.eliminated_by})`);
+        continue;
+      }
+      const mut = typeof r.mutation?.score === "number" ? `${r.mutation.score}%` : "n/a";
+      logger?.info?.(`  ${r.coder.padEnd(10)} FINALISTA  loc:${String(r.loc.net).padStart(5)}  tests:${r.loc.testsTouched}  mutation:${mut}`);
+    }
+    logger?.info?.(`  ranking: ${board.ranking.join(" > ") || "(sin finalistas)"}`);
+    return board;
+  }
+
+  if (!task || !String(task).trim()) {
+    throw new Error("tournament: falta la tarea — kj tournament \"<tarea>\" --coders claude,codex");
+  }
+  const coders = String(flags.coders || "")
+    .split(",")
+    .map((c) => c.trim())
+    .filter(Boolean);
+  if (coders.length < 2) {
+    throw new Error("tournament: hacen falta al menos 2 en --coders — p. ej. --coders claude,codex,agy (con uno no hay torneo)");
+  }
+
+  const res = await runTournamentFn({ task, coders, config, logger });
+
+  const completed = res.lanes.filter((l) => l.status === "completed");
+  const green = completed.filter((l) => l.suite?.ok);
+  logger?.info?.("");
+  logger?.info?.(`torneo ${res.id}: ${completed.length}/${res.lanes.length} carriles completados, ${green.length} con suite verde`);
+  logger?.info?.(`  evidencia: ${res.dir}`);
+  logger?.info?.("  siguiente: el scoreboard determinista (TOR-B) puntuará los carriles; de momento compara los diff.patch a mano.");
+  return res;
+}

package/src/config/overrides.js

@@ -81,7 +81,14 @@ function applyRoleOverrides(out, flags) {
   // boolean means the flag belongs to the command itself (`kj audit
   // --security`, KJC-TSK-0695) and must not become a provider.
   for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
-    if (typeof flags[flag] === "string" && flags[flag]) out.roles[role].provider = flags[flag];
+    if (typeof flags[flag] === "string" && flags[flag]) {
+      // A model pin belongs to the provider it was written for — switching
+      // provider by flag drops it (KJC-TSK-0729: codex's pinned mini reached
+      // agy, which answered with its model list instead of a verdict). An
+      // explicit --<role>-model flag re-pins below, after this loop.
+      if (out.roles[role].provider && out.roles[role].provider !== flags[flag]) out.roles[role].model = null;
+      out.roles[role].provider = flags[flag];
+    }
   }
   // coder/reviewer also update top-level aliases
   if (flags.coder) out.coder = flags.coder;

package/src/harden/config-engine.js

@@ -15,6 +15,24 @@ import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 
 const BLOCK_VERSION = 1;
 
+// KJC-BUG-0137 (issue #1357): is the tool a config demands actually installed?
+// Declared dependency or a resolvable bin both count; an unreadable
+// package.json is no evidence of the tool.
+function hasTool(dirs, tool) {
+  for (const d of dirs) {
+    if (existsSync(join(d, "node_modules", ".bin", tool))) return true;
+    const pkgPath = join(d, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg.devDependencies?.[tool] || pkg.dependencies?.[tool]) return true;
+    } catch {
+      /* unreadable ⇒ keep looking */
+    }
+  }
+  return false;
+}
+
 function writeFile(target, content) {
   mkdirSync(dirname(target), { recursive: true });
   writeFileSync(target, content);
@@ -47,6 +65,15 @@ function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [target
         results.push({ file, action: "covered", by: variant });
         continue;
       }
+      // KJC-BUG-0137: no tool ⇒ no config — report the actionable gap instead.
+      if (cfg.requires && !hasTool(altDirs, cfg.requires)) {
+        results.push({
+          file,
+          action: "omitted",
+          note: `${cfg.requires} is not installed — npm i -D ${cfg.requires}, then re-run kj harden`,
+        });
+        continue;
+      }
     }
 
     if (cfg.json) {

package/src/harden/config-templates.js

@@ -95,10 +95,15 @@ export const UNIVERSAL_CONFIGS = [
   { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
 ];
 
-/** `json:true` ⇒ seed-only (no comment syntax for a marker). */
+/**
+ * `json:true` ⇒ seed-only (no comment syntax for a marker). `requires` names
+ * the tool the config is for: absent from the project ⇒ the config is omitted
+ * with the install command in the report (KJC-BUG-0137) — a config without its
+ * tool is decorative, and kj never generates a demand it didn't satisfy.
+ */
 export const JS_CONFIGS = [
-  { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY },
-  { file: ".prettierrc.json", json: true, body: PRETTIER_BODY },
+  { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY, requires: "eslint" },
+  { file: ".prettierrc.json", json: true, body: PRETTIER_BODY, requires: "prettier" },
 ];
 export const PY_CONFIGS = [{ file: "ruff.toml", blockId: "ruff", style: "hash", body: RUFF_BODY }];
 export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style: "hash", body: GOLANGCI_BODY }];

package/src/harden/workflow-engine.js

@@ -34,6 +34,16 @@ export function detectPackageManager(projectDir) {
   return "npm";
 }
 
+// KJC-BUG-0137: the JS quality workflow only carries a lint step when the
+// project HAS a lint script — and then it enforces (no --if-present).
+function hasLintScript(projectDir) {
+  try {
+    return Boolean(JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")).scripts?.lint);
+  } catch {
+    return false;
+  }
+}
+
 export function installWorkflows({
   projectDir = process.cwd(),
   language = null,
@@ -43,7 +53,7 @@ export function installWorkflows({
 } = {}) {
   const dir = join(projectDir, WORKFLOWS_DIR);
   const pm = detectPackageManager(projectDir);
-  const quality = qualityWorkflowFor(language, pm);
+  const quality = qualityWorkflowFor(language, pm, hasLintScript(projectDir));
   const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir), pm });
   const mut = mutation ? mutationWorkflowFor(language, pm) : null;
   const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : [])];

package/src/harden/workflow-templates.js

@@ -8,6 +8,20 @@
 
 // Blocks AI self-attribution in PR commit messages. Pure bash + grep, no Node.
 // Pins github.base_ref to an env var (never interpolated into the run block).
+// KJC-BUG-0136 (issue #1374): actions pinned to full commit SHAs — a
+// mutable tag lets its owner run arbitrary code inside EVERY hardened
+// repo's CI, with access to the workflow's secrets; 5 of this project's 7
+// audit findings came from files kj itself generated. The version rides in
+// a comment (the practice kj audit demands). To bump one:
+//   gh api repos/<owner>/<repo>/commits/<tag> --jq .sha
+export const PINNED_ACTIONS = {
+  checkout: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4",
+  setupNode: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4",
+  setupPython: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5",
+  setupGo: "actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5",
+  setupPhp: "shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2",
+};
+
 export const NO_AI_ATTRIBUTION_WORKFLOW = [
   "name: Block AI attribution",
   "on:",
@@ -19,7 +33,7 @@ export const NO_AI_ATTRIBUTION_WORKFLOW = [
   "  scan:",
   "    runs-on: ubuntu-latest",
   "    steps:",
-  "      - uses: actions/checkout@v4",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
   "        with:",
   "          fetch-depth: 0",
   "      - name: Scan commit messages for AI attribution",
@@ -50,34 +64,35 @@ const header = (steps) =>
     "  quality:",
     "    runs-on: ubuntu-latest",
     "    steps:",
-    "      - uses: actions/checkout@v4",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
     ...steps,
   ].join("\n");
 
 // Per-package-manager commands (KJC-BUG-0131, issue #1330): `npm ci` in a
 // pnpm/yarn repo dies with EUSAGE (no package-lock.json). corepack ships with
 // Node 22 and resolves the right pnpm/yarn from `packageManager` — no
-// third-party action. pnpm passes flags AFTER the script name to the script
-// itself, so --if-present must go BEFORE it; yarn has no --if-present at all,
-// so lint runs through `npm run` (scripts don't touch the lockfile).
-const PM_COMMANDS = {
-  npm: { setup: [], install: "npm ci", lint: "npm run -s lint --if-present", test: "npm test" },
+// third-party action. Yarn scripts run through `npm run` (scripts don't touch
+// the lockfile). Lint ENFORCES — never --if-present: a step that passes when
+// its script is missing protects nothing (KJC-BUG-0137, issue #1357); the
+// engine omits the step instead when the project has no lint script.
+export const PM_COMMANDS = {
+  npm: { setup: [], install: "npm ci", lint: "npm run -s lint", test: "npm test" },
   pnpm: {
     setup: ["      - run: corepack enable"],
     install: "pnpm install --frozen-lockfile",
-    lint: "pnpm run --if-present -s lint",
+    lint: "pnpm run -s lint",
     test: "pnpm test",
   },
   yarn: {
     setup: ["      - run: corepack enable"],
     install: "yarn install --frozen-lockfile",
-    lint: "npm run -s lint --if-present",
+    lint: "npm run -s lint",
     test: "yarn test",
   },
 };
 
 const nodeSetupSteps = (pm) => [
-  "      - uses: actions/setup-node@v4",
+  `      - uses: ${PINNED_ACTIONS.setupNode}`,
   "        with:",
   "          node-version: 22",
   ...(PM_COMMANDS[pm] || PM_COMMANDS.npm).setup,
@@ -86,7 +101,7 @@ const nodeSetupSteps = (pm) => [
 
 const QUALITY_BY_LANGUAGE = {
   python: header([
-    "      - uses: actions/setup-python@v5",
+    `      - uses: ${PINNED_ACTIONS.setupPython}`,
     "        with:",
     "          python-version: '3.12'",
     "      - run: pip install ruff pytest",
@@ -94,14 +109,14 @@ const QUALITY_BY_LANGUAGE = {
     "      - run: pytest",
   ]),
   go: header([
-    "      - uses: actions/setup-go@v5",
+    `      - uses: ${PINNED_ACTIONS.setupGo}`,
     "        with:",
     "          go-version: stable",
     "      - run: go vet ./...",
     "      - run: go test ./...",
   ]),
   php: header([
-    "      - uses: shivammathur/setup-php@v2",
+    `      - uses: ${PINNED_ACTIONS.setupPhp}`,
     "        with:",
     "          php-version: '8.3'",
     "      - run: composer install --no-interaction --no-progress",
@@ -109,12 +124,16 @@ const QUALITY_BY_LANGUAGE = {
     "      - run: vendor/bin/phpunit",
   ]),
 };
-/** Stack-aware Quality workflow entry, or null for an unknown language. */
-export function qualityWorkflowFor(language, pm = "npm") {
+/**
+ * Stack-aware Quality workflow entry, or null for an unknown language.
+ * `lint:false` drops the JS lint step entirely (project has no lint script,
+ * KJC-BUG-0137) — mirroring the local hook, which also omits it.
+ */
+export function qualityWorkflowFor(language, pm = "npm", lint = true) {
   const c = PM_COMMANDS[pm] || PM_COMMANDS.npm;
   const body =
     language === "javascript" || language === "typescript"
-      ? header([...nodeSetupSteps(pm), `      - run: ${c.lint}`, `      - run: ${c.test}`])
+      ? header([...nodeSetupSteps(pm), ...(lint ? [`      - run: ${c.lint}`] : []), `      - run: ${c.test}`])
       : QUALITY_BY_LANGUAGE[language];
   return body ? { file: "kj-quality.yml", blockId: "wf-quality", body } : null;
 }
@@ -132,7 +151,7 @@ export const SHRINK_BUDGET_WORKFLOW = [
   "    runs-on: ubuntu-latest",
   '    env: { LOC_LIMIT: "200" }',
   "    steps:",
-  "      - uses: actions/checkout@v4",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
   "        with:",
   "          fetch-depth: 0",
   "      - name: Net LOC delta within budget",
@@ -161,7 +180,7 @@ export const packSmokeWorkflow = (pm = "npm") =>
     "  pack-smoke:",
     "    runs-on: ubuntu-latest",
     "    steps:",
-    "      - uses: actions/checkout@v4",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
     ...nodeSetupSteps(pm),
     "      - name: Pack and install the tarball clean",
     "        run: |",
@@ -179,13 +198,13 @@ export const packSmokeWorkflow = (pm = "npm") =>
 const MUTATION_TOOLCHAIN = {
   javascript: "node", // resolved per package manager in mutationWorkflowFor
   python: [
-    "      - uses: actions/setup-python@v5",
+    `      - uses: ${PINNED_ACTIONS.setupPython}`,
     "        with:",
     "          python-version: '3.12'",
     "      - run: pip install mutmut pytest",
   ],
   php: [
-    "      - uses: shivammathur/setup-php@v2",
+    `      - uses: ${PINNED_ACTIONS.setupPhp}`,
     "        with:",
     "          php-version: '8.3'",
     "      - run: composer install --no-interaction --no-progress",
@@ -211,10 +230,10 @@ export function mutationWorkflowFor(language, pm = "npm") {
     "  mutation:",
     "    runs-on: ubuntu-latest",
     "    steps:",
-    "      - uses: actions/checkout@v4",
+    `      - uses: ${PINNED_ACTIONS.checkout}`,
     "        with:",
     "          fetch-depth: 0",
-    "      - uses: actions/setup-node@v4",
+    `      - uses: ${PINNED_ACTIONS.setupNode}`,
     "        with:",
     "          node-version: 22",
     ...toolchain,

package/src/prompts/diff-clip.js

@@ -0,0 +1,27 @@
+/**
+ * diff-clip — KJC-BUG-0134 (issue #1381). A bare [TRUNCATED] marker inside
+ * the diff body reads as file content: reviewers blamed whichever file the
+ * cut landed in and rejected complete, untouched code (each false positive
+ * costs a solomon round). The clip is DECLARED as the pipeline's own, kept
+ * OUTSIDE the diff body, cut on a line boundary, and the reviewer is told
+ * the diff is partial so it never reasons about the completeness of files
+ * it cannot fully see. Shared by every prompt that hands a diff to an AI.
+ */
+
+export const DIFF_CLIP_CHARS = 12000;
+
+/** @returns {{body: string, note: string|null}} note is null when no clip happened. */
+export function clipDiff(diff, limit = DIFF_CLIP_CHARS) {
+  if (!diff) return { body: "", note: null };
+  if (diff.length <= limit) return { body: diff, note: null };
+  const hard = diff.slice(0, limit);
+  const nl = hard.lastIndexOf("\n");
+  const body = nl > 0 ? hard.slice(0, nl) : hard;
+  const omittedLines = diff.slice(body.length).split("\n").filter(Boolean).length;
+  const note = [
+    `NOTE FROM THE KJ PIPELINE (not part of the diff): the diff above was clipped by kj at ~${limit} characters — ${omittedLines} more line(s) exist but are NOT shown.`,
+    "The cut is kj's, not the author's: no file in the working tree is truncated.",
+    "Do not raise issues about incomplete or cut-off content, and do not reason about the completeness of files you cannot fully see. Review only what is visible.",
+  ].join(" ");
+  return { body, note };
+}

package/src/prompts/reviewer.js

@@ -2,6 +2,8 @@ import { buildRtkInstructions } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 import { getLanguageInstruction } from "../utils/locale.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
+import { clipDiff } from "./diff-clip.js";
+import { buildSplitSignal } from "./split-signal.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -34,7 +36,9 @@ const SERENA_INSTRUCTIONS = [
  * and always different) goes last.
  */
 export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
-  const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
+  const { body: clippedDiff, note: clipNote } = clipDiff(diff);
+  // KJC-BUG-0138: full diff on purpose — the moved-to side survives clipping.
+  const splitSignal = buildSplitSignal(diff);
 
   const langInstruction = getLanguageInstruction(language);
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
@@ -60,7 +64,9 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
     section(`Review rules:\n${reviewRules}`, STABLE),
     section(skillSection, STABLE),
     section(`Task context:\n${task}`, VOLATILE),
-    section(`Git diff:\n${truncatedDiff}`, VOLATILE),
+    section(`Git diff:\n${clippedDiff}`, VOLATILE),
+    section(clipNote, VOLATILE),
+    section(splitSignal, VOLATILE),
   ]);
 }
 

package/src/prompts/split-signal.js

@@ -0,0 +1,82 @@
+/**
+ * split-signal — KJC-BUG-0138 (issue #1364). A file split is not a coverage
+ * deletion, but the reviewer doesn't correlate a file losing content with new
+ * files gaining it (4/13 pure-refactor PRs falsely rejected). Deterministic
+ * pre-analysis, zero LLM: significant removed lines reappearing verbatim among
+ * another file's ADDITIONS in the same diff are moves — when ≥ MIN_RATIO of a
+ * file's removals move, the reviewer gets the correlation as a pipeline note.
+ * Exact `--- a/` / `+++ b/` headers only (BUG-0132: `++content` ≠ header).
+ */
+
+const MIN_REMOVED = 10; // fewer significant removals ⇒ too small to misread
+const MIN_RATIO = 0.5; // below this, the removal is mostly a real removal
+
+// Braces/punctuation reappear by accident — only letter-bearing lines count.
+function significant(text) {
+  const t = text.trim();
+  return t.length >= 10 && /[a-zA-Z]/.test(t);
+}
+
+/** @returns {string|null} pipeline note, or null when nothing moved. Feed the
+ * PRE-CLIPPING diff: the added side must inform even when clipped away. */
+export function buildSplitSignal(diff) {
+  if (!diff) return null;
+  const removedByFile = new Map();
+  const addedByFile = new Map();
+  let src = null;
+  let dst = null;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("--- ")) {
+      src = raw.startsWith("--- a/") ? raw.slice(6) : null;
+      continue;
+    }
+    if (raw.startsWith("+++ ")) {
+      dst = raw.startsWith("+++ b/") ? raw.slice(6) : null;
+      continue;
+    }
+    if (raw.startsWith("+") && dst && significant(raw.slice(1))) {
+      const counts = addedByFile.get(dst) ?? new Map();
+      const t = raw.slice(1).trim();
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+      addedByFile.set(dst, counts);
+    } else if (raw.startsWith("-") && src && significant(raw.slice(1))) {
+      const lines = removedByFile.get(src) ?? [];
+      lines.push(raw.slice(1).trim());
+      removedByFile.set(src, lines);
+    }
+  }
+
+  const findings = [];
+  for (const [file, removed] of removedByFile) {
+    if (removed.length < MIN_REMOVED) continue;
+    const dests = new Map();
+    let moved = 0;
+    for (const text of removed) {
+      for (const [other, counts] of addedByFile) {
+        if (other === file) continue; // in-place edits are not moves
+        const n = counts.get(text) ?? 0;
+        if (n > 0) {
+          counts.set(text, n - 1); // each added line vouches for ONE removal
+          dests.set(other, (dests.get(other) ?? 0) + 1);
+          moved++;
+          break;
+        }
+      }
+    }
+    if (moved / removed.length >= MIN_RATIO) {
+      const where = [...dests.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([d, n]) => `${d} (${n})`)
+        .join(", ");
+      findings.push(`- ${file}: ${moved} of ${removed.length} significant removed lines reappear ADDED in ${where}`);
+    }
+  }
+  if (findings.length === 0) return null;
+
+  return [
+    "NOTE FROM THE KJ PIPELINE (deterministic pre-analysis, not from the author): this diff MOVES content between files:",
+    ...findings,
+    "Moved content is a file split/relocation, not a deletion. Before reporting removed tests or lost coverage, check the ADDED side listed above in this SAME diff. Do not treat moved lines as deleted.",
+  ].join("\n");
+}

package/src/review/one-shot-review.js

@@ -16,6 +16,7 @@ import { parseMaybeJsonString } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { saveVerdict } from "./verdict-store.js";
 import { detectWorkspace } from "./workspace.js";
+import { isQuotaExhausted, candidateStatus, pickQuotaFallback, formatCandidateMenu } from "./reviewer-fallback.js";
 
 // Cross-AI preference when the configured reviewer IS the host.
 const CROSS_ORDER = ["codex", "claude", "gemini", "opencode", "aider"];
@@ -44,6 +45,7 @@ export async function runOneShotReview({
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
+  candidateStatusFn = candidateStatus,
 }) {
   if (!diff || !diff.trim()) {
     throw new Error("nothing to review — the diff is empty (stage your changes or pass --range)");
@@ -57,26 +59,58 @@ export async function runOneShotReview({
   }
 
   const { rules } = await resolveReviewProfile({ mode: "standard", projectDir });
-  const prompt = await buildReviewerPrompt({
-    task: task || "Review the following diff for correctness, security and maintainability.",
-    diff, reviewRules: rules, mode: "standard", provider: reviewer, projectDir,
-  });
+  const attempt = async (who, cfg = config) => {
+    const prompt = await buildReviewerPrompt({
+      task: task || "Review the following diff for correctness, security and maintainability.",
+      diff, reviewRules: rules, mode: "standard", provider: who, projectDir,
+    });
+    logger?.info?.(`kj review: host=${hostAgent || "none"} → reviewer=${who} (cross-AI)`);
+    return createAgentFn(who, cfg, logger).reviewTask({ prompt, role: "reviewer" });
+  };
+
+  let activeReviewer = reviewer;
+  let result = await attempt(activeReviewer);
+
+  // KJC-TSK-0730 — quota failover: exhausted quota is not a review failure,
+  // it is a provider outage. One retry with an authenticated candidate
+  // (loud notice, never silent), or an actionable menu. Never the host:
+  // the brain does not review itself.
+  if (!result?.ok && isQuotaExhausted(result?.error) && (config?.reviewer_options?.auto_fallback ?? true)) {
+    const statuses = await candidateStatusFn();
+    const fallback = pickQuotaFallback(statuses, { exclude: [activeReviewer, hostAgent].filter(Boolean) });
+    if (fallback) {
+      logger?.warn?.(
+        `⚠ reviewer ${activeReviewer} sin cuota → usando ${fallback} SOLO en esta invocación. ` +
+        `Para fijarlo: roles.reviewer.provider: ${fallback} (avisando, nunca en silencio — KJC-TSK-0730).`
+      );
+      activeReviewer = fallback;
+      // The role's model pin belongs to the exhausted provider (a codex
+      // model name means nothing to copilot) — the candidate runs on its
+      // own default model.
+      result = await attempt(activeReviewer, {
+        ...config,
+        roles: { ...config?.roles, reviewer: { ...config?.roles?.reviewer, model: null } },
+      });
+    } else {
+      throw new Error(
+        `reviewer ${activeReviewer} sin cuota y ningún candidato autenticado con adaptador.\n` +
+        formatCandidateMenu(statuses, { exclude: [hostAgent].filter(Boolean) })
+      );
+    }
+  }
 
-  logger?.info?.(`kj review: host=${hostAgent || "none"} → reviewer=${reviewer} (cross-AI)`);
-  const agent = createAgentFn(reviewer, config, logger);
-  const result = await agent.reviewTask({ prompt, role: "reviewer" });
   if (!result?.ok) {
-    throw new Error(`reviewer ${reviewer} failed: ${result?.error || "no output"}`);
+    throw new Error(`reviewer ${activeReviewer} failed: ${result?.error || "no output"}`);
   }
 
   const parsed = parseMaybeJsonString(result.output);
   if (!parsed || typeof parsed.approved !== "boolean") {
-    throw new Error(`reviewer ${reviewer} returned no parseable verdict`);
+    throw new Error(`reviewer ${activeReviewer} returned no parseable verdict`);
   }
 
   return saveVerdict(projectDir, diff, {
     verdict: parsed.approved ? "approved" : "rejected",
-    reviewer,
+    reviewer: activeReviewer,
     host: hostAgent || null,
     // KJC-TSK-0680: where the review ran — makes any isolation claim auditable.
     workspace: await detectWorkspace(projectDir),