@karajan-family/code 4.21.0

package/src/review/gate-gitignore.js

@@ -0,0 +1,77 @@
+/**
+ * Gate trackability (KJC-TSK-0646) — a `.karajan/` dir-exclude in
+ * .gitignore silently keeps the v4 contract (review-gate marker, hooks)
+ * out of git: git cannot re-include children of an excluded DIRECTORY.
+ * Reproduced three times in the field before this existed.
+ *
+ * `kj review --install-gate` calls this: when the exact `.karajan/`
+ * (or `.karajan/*`) exclude is present, it is rewritten to the
+ * star-pattern with re-includes for the contract, keeping everything
+ * else in the file byte-identical. No mention of .karajan → no-op.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// KJC-BUG-0123 (issue #1268): exported as the SINGLE source of truth — kj
+// init and the orchestrator's autoInit write this same block instead of a
+// bare `.karajan/` exclude (which git cannot re-include children of).
+export const CONTRACT_BLOCK = [
+  ".karajan/*",
+  "# …except the v4 environment contract, which the whole team inherits:",
+  "!.karajan/review-gate",
+  "!.karajan/hooks/",
+  ".karajan/hooks/*",
+  "!.karajan/hooks/pre-commit",
+  "!.karajan/hooks/commit-msg",
+  "!.karajan/hooks/pre-push",
+  "!.karajan/hooks/post-merge",
+  "!.karajan/adrs/",
+];
+
+/**
+ * KJC-BUG-0123: append the canonical contract block to .gitignore when the
+ * file has no `.karajan` mention at all (fresh projects — `kj init` path).
+ * Files that already mention .karajan are left to ensureGateTrackable,
+ * which rewrites legacy root excludes without touching anything else.
+ */
+export async function ensureContractBlockPresent(projectDir) {
+  const file = path.join(projectDir, ".gitignore");
+  let text = "";
+  try { text = (await fs.readFile(file, "utf8")) || ""; } catch { /* no .gitignore yet */ }
+  if (text.includes(".karajan")) return { changed: false };
+  const sep = text && !text.endsWith("\n") ? "\n" : "";
+  await fs.writeFile(file, `${text}${sep}# Karajan environment (verdicts stay local; the contract is tracked)\n${CONTRACT_BLOCK.join("\n")}\n`);
+  return { changed: true };
+}
+
+export async function ensureGateTrackable(projectDir) {
+  const file = path.join(projectDir, ".gitignore");
+  let text;
+  try { text = await fs.readFile(file, "utf8"); } catch { return { changed: false }; }
+
+  // Already migrated only when EVERY re-include of the contract is present —
+  // a partial state (e.g. a hand-written marker re-include without the hook
+  // ones) must still be completed, not silently accepted.
+  const reIncludes = CONTRACT_BLOCK.filter((l) => l.startsWith("!"));
+  if (reIncludes.every((l) => text.includes(l))) return { changed: false };
+
+  const isRootExclude = (l) => {
+    const t = l.trim();
+    return t === ".karajan/" || t === ".karajan" || t === ".karajan/*";
+  };
+  const lines = text.split("\n");
+  const idx = lines.findIndex(isRootExclude);
+  if (idx === -1) return { changed: false };
+
+  // Drop EVERY .karajan root exclude (a later duplicate would override the
+  // re-includes — last match wins in gitignore) and every pre-existing
+  // partial contract line, then insert the canonical block once at the
+  // position of the first exclude. Exactly one coherent block, idempotent.
+  const partials = new Set(CONTRACT_BLOCK);
+  const marker = "@@kj-contract-block@@";
+  const cleaned = lines.map((l, i) => (i === idx ? marker : l))
+    .filter((l) => l === marker || (!isRootExclude(l) && !partials.has(l.trim())));
+  const result = cleaned.flatMap((l) => (l === marker ? CONTRACT_BLOCK : [l]));
+  await fs.writeFile(file, result.join("\n"));
+  return { changed: true };
+}

package/src/review/git-stash-helper.js

@@ -0,0 +1,104 @@
+// Surgical stash helper for the TDD discipline gate (KJC-TSK-0398 PR2).
+// Stashes only the source files we want to hide for the "red" run and
+// restores them afterwards. Tracked files use `git stash push -- <paths>`;
+// untracked files (not yet known to git) are moved aside to a private
+// `.karajan/tmp/stash-<id>/` tree because `git stash` would ignore them.
+
+import { mkdir, rename, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+function defaultRunner(cmd, args, opts) {
+  return runCommand(cmd, args, opts);
+}
+
+async function isTracked(runner, projectDir, file) {
+  const res = await runner("git", ["ls-files", "--error-unmatch", "--", file], { cwd: projectDir });
+  return res.exitCode === 0;
+}
+
+async function stashRefForToken(runner, projectDir, marker) {
+  const res = await runner("git", ["stash", "list"], { cwd: projectDir });
+  if (res.exitCode !== 0) return null;
+  for (const line of String(res.stdout || "").split("\n")) {
+    if (line.includes(marker)) {
+      const m = line.match(/^(stash@\{\d+\})/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+// Move `files` aside so a test run sees them as missing. Returns a token to
+// pass to `restoreFiles()`. Throws on failure with the partial token attached.
+export async function stashFilesAside(files, { projectDir = process.cwd(), runner = defaultRunner, tmpRoot } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return { trackedStashRef: null, untrackedMoves: [], marker: null };
+  }
+  const tracked = [];
+  const untracked = [];
+  for (const f of files) {
+    if (await isTracked(runner, projectDir, f)) tracked.push(f);
+    else if (existsSync(resolve(projectDir, f))) untracked.push(f);
+  }
+
+  const marker = `kj-tdd-discipline-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const stashRoot = tmpRoot || join(projectDir, ".karajan", "tmp", marker);
+  const untrackedMoves = [];
+  let trackedStashRef = null;
+
+  if (tracked.length > 0) {
+    const args = ["stash", "push", "--keep-index", "-m", marker, "--", ...tracked];
+    const res = await runner("git", args, { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash push failed: ${res.stderr || res.stdout}`);
+    }
+    trackedStashRef = await stashRefForToken(runner, projectDir, marker);
+  }
+
+  for (const f of untracked) {
+    const src = resolve(projectDir, f);
+    const dst = join(stashRoot, f);
+    await mkdir(dirname(dst), { recursive: true });
+    await rename(src, dst);
+    untrackedMoves.push({ src, dst });
+  }
+
+  return { trackedStashRef, untrackedMoves, marker, stashRoot };
+}
+
+// Reverse a `stashFilesAside` token. Idempotent: a restored token becomes a no-op.
+export async function restoreFiles(token, { projectDir = process.cwd(), runner = defaultRunner } = {}) {
+  if (!token || (token.trackedStashRef == null && token.untrackedMoves.length === 0)) return;
+
+  for (const { src, dst } of token.untrackedMoves) {
+    if (existsSync(dst)) {
+      await mkdir(dirname(src), { recursive: true });
+      await rename(dst, src);
+    }
+  }
+  if (token.stashRoot && existsSync(token.stashRoot)) {
+    await rm(token.stashRoot, { recursive: true, force: true });
+  }
+
+  if (token.trackedStashRef) {
+    const res = await runner("git", ["stash", "pop", token.trackedStashRef], { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash pop failed: ${res.stderr || res.stdout}`);
+    }
+  }
+  token.trackedStashRef = null;
+  token.untrackedMoves = [];
+}
+
+// Run `body` with `files` stashed aside, always restoring them — even when
+// `body` throws. The TDD discipline stage wraps its "red" run with this.
+export async function withStashedFiles(files, body, opts = {}) {
+  const token = await stashFilesAside(files, opts);
+  try {
+    return await body(token);
+  } finally {
+    await restoreFiles(token, opts).catch(() => { /* swallow: surface body error */ });
+  }
+}

package/src/review/mutation-pregate.js

@@ -0,0 +1,48 @@
+/**
+ * Mutation pre-gate (MUT-A, KJC-TSK-0716) — audita "tests prove behavior":
+ * asserts flojos dejan mutantes vivos con la suite verde. OPT-IN
+ * (method_gates.mutation: warn|block — cuesta minutos) y SOLO en --staged:
+ * supervivientes como advisory al reviewer; block cierra ANTES con la
+ * lista exacta. Indisponible = degrada avisando, nunca en silencio.
+ */
+import { runMutation } from "../mutate/runner.js";
+import { getDiffScope } from "../mutate/diff-scope.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { getMutationTool } from "../mutate/tool-registry.js";
+
+export const formatSurvivor = (s) =>
+  `${s.file}:${s.line} (${s.mutator ?? s.status ?? "?"}) — mátalo con un assert que distinga el cambio`;
+
+async function defaultMutate({ projectDir }) {
+  const { language } = await detectProjectStack(projectDir);
+  const tool = getMutationTool(language);
+  if (!tool.supported) throw new Error(`lenguaje no soportado (${language ?? "desconocido"}) — ${tool.reason}`);
+  const scope = await getDiffScope({ staged: true, language });
+  if (scope.empty) return { result: { score: 100, killed: 0, total: 0, survived: [] } };
+  const outcome = await runMutation({ binary: tool.binary, args: scope.args, cwd: projectDir });
+  if (!outcome.result) throw new Error(`la herramienta ${tool.id} no produjo un informe legible`);
+  return outcome;
+}
+
+/**
+ * @returns {Promise<{enabled: boolean, ok: boolean, available?: boolean, mode?: string, survived?: object[], score?: number, reason?: string}>}
+ */
+export async function runMutationPregate({ config = {}, projectDir = process.cwd(), deps = {} } = {}) {
+  const mode = config?.method_gates?.mutation;
+  if (mode !== "warn" && mode !== "block") return { enabled: false, ok: true };
+  const { mutateFn = defaultMutate } = deps;
+  let outcome;
+  try {
+    outcome = await mutateFn({ projectDir });
+  } catch (err) {
+    // Sin herramienta no hay medición: se degrada DICIENDO qué red cayó.
+    return { enabled: true, ok: true, available: false, mode, reason: err.message };
+  }
+  // Payload malformado del runner = misma degradación que el error (catch
+  // de codex): jamás crashear el review gate por un informe roto.
+  if (!outcome?.result || !Array.isArray(outcome.result.survived ?? [])) {
+    return { enabled: true, ok: true, available: false, mode, reason: "el runner de mutación devolvió un informe ilegible" };
+  }
+  const { survived = [], score } = outcome.result;
+  return { enabled: true, available: true, mode, survived, score, ok: mode === "warn" || survived.length === 0 };
+}

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

@@ -0,0 +1,122 @@
+/**
+ * One-shot cross-AI review (ENV-B1, KJC-TSK-0637) — the v4 primitive.
+ *
+ * The HOST agent (Claude Code, Codex) orchestrates the work; Karajan
+ * routes the review to a DIFFERENT AI and records the verdict tied to
+ * the exact diff (verdict-store). No cross-AI reviewer available is an
+ * error, never a silent fallback to the host: without a second pair of
+ * eyes there is no verdict, and without a verdict the pre-commit gate
+ * (ENV-C) keeps the commit out.
+ */
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+import { buildReviewerPrompt } from "../prompts/reviewer.js";
+import { resolveReviewProfile } from "./profiles.js";
+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"];
+
+/**
+ * Pick a reviewer that is NOT the host agent.
+ * @returns {Promise<string|null>} provider name, or null if none exists.
+ */
+export async function pickCrossReviewer({ config, hostAgent, detectAgents = detectAvailableAgents }) {
+  const configured = resolveRole(config, "reviewer").provider;
+  if (configured && configured !== hostAgent) return configured;
+
+  const agents = await detectAgents();
+  const candidates = agents
+    .filter((a) => a.available && a.name !== hostAgent)
+    .map((a) => a.name);
+  return CROSS_ORDER.find((name) => candidates.includes(name)) || candidates[0] || null;
+}
+
+/**
+ * Review a raw diff with a cross-AI reviewer and persist the verdict.
+ * @returns {Promise<object>} the stored verdict record.
+ */
+export async function runOneShotReview({
+  diff, task, config, logger, projectDir,
+  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)");
+  }
+
+  const reviewer = await pickCrossReviewer({ config, hostAgent, detectAgents });
+  if (!reviewer) {
+    throw new Error(
+      `cross-AI review requires an agent other than the host (${hostAgent || "unknown"}) — install codex, claude or another supported CLI`
+    );
+  }
+
+  const { rules } = await resolveReviewProfile({ mode: "standard", 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) })
+      );
+    }
+  }
+
+  if (!result?.ok) {
+    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 ${activeReviewer} returned no parseable verdict`);
+  }
+
+  return saveVerdict(projectDir, diff, {
+    verdict: parsed.approved ? "approved" : "rejected",
+    reviewer: activeReviewer,
+    host: hostAgent || null,
+    // KJC-TSK-0680: where the review ran — makes any isolation claim auditable.
+    workspace: await detectWorkspace(projectDir),
+    issues: parsed.blocking_issues || [],
+    suggestions: parsed.non_blocking_suggestions || [],
+    summary: parsed.summary || parsed.raw_summary || "",
+    confidence: parsed.confidence ?? null,
+  });
+}

package/src/review/parser.js

@@ -0,0 +1,80 @@
+/**
+ * Review output parsing helpers.
+ * Extracted from orchestrator.js to improve testability and reduce complexity.
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+
+export function parseMaybeJsonString(value) {
+  if (typeof value !== "string") return null;
+  return extractFirstJson(value);
+}
+
+function isReviewPayload(obj) {
+  return obj?.approved !== undefined && obj?.blocking_issues !== undefined;
+}
+
+function findReviewInArray(arr) {
+  for (let i = arr.length - 1; i >= 0; i -= 1) {
+    const item = arr[i];
+    if (isReviewPayload(item)) return item;
+
+    const nested = item?.result || item?.message?.content?.[0]?.text;
+    if (typeof nested === "string") {
+      const parsedNested = parseMaybeJsonString(nested);
+      if (parsedNested?.approved !== undefined) return parsedNested;
+    }
+  }
+  return null;
+}
+
+export function normalizeReviewPayload(payload) {
+  if (!payload) return null;
+  if (isReviewPayload(payload)) return payload;
+  if (Array.isArray(payload)) return findReviewInArray(payload);
+
+  if (typeof payload.result === "string") {
+    const parsedResult = parseMaybeJsonString(payload.result);
+    if (parsedResult?.approved !== undefined) return parsedResult;
+  }
+
+  return null;
+}
+
+export function parseJsonOutput(raw) {
+  const cleaned = raw.trim();
+  if (!cleaned) return null;
+  try {
+    const parsed = JSON.parse(cleaned);
+    return normalizeReviewPayload(parsed);
+  } catch { /* not a single JSON blob */
+    const lines = cleaned
+      .split("\n")
+      .map((x) => x.trim())
+      .filter(Boolean);
+
+    const parsedLines = [];
+    for (const line of lines) {
+      try {
+        parsedLines.push(JSON.parse(line));
+      } catch { /* line is not JSON */
+        continue;
+      }
+    }
+
+    const normalizedLines = normalizeReviewPayload(parsedLines);
+    if (normalizedLines) {
+      return normalizedLines;
+    }
+
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      try {
+        const parsed = JSON.parse(lines[i]);
+        return normalizeReviewPayload(parsed);
+      } catch { /* line is not JSON */
+        continue;
+      }
+    }
+  }
+  return null;
+}

package/src/review/policy-gate.js

@@ -0,0 +1,26 @@
+/**
+ * Adaptador del gate de policy en el flujo de review de karajan-code
+ * (GOV-A, KJC-TSK-0745). La decisión warn/deny/inexcepcionable/excepción
+ * vive en el kernel (@karajan-family/governance); aquí solo el dominio: la
+ * excepción se pide con KJ_ALLOW_POLICY=1 + KJ_POLICY_REASON, y el
+ * artefacto de este dominio es el diff staged — por eso el alcance
+ * registrado dice "este diff exacto".
+ */
+import { evaluateGate } from "@karajan-family/governance";
+
+/**
+ * @returns {{ok: boolean, invalid?: boolean, warns: object[], denials: object[], exempted: object[]}}
+ */
+export function evaluatePolicyGate({
+  policy, errors = [], role = "coder", files = [], netLinesAdded = null,
+  diffHashValue = null, env = process.env, recordException = () => {},
+  standingExceptions = [], now = new Date(),
+}) {
+  return evaluateGate({
+    policy, errors, role, files, netLinesAdded,
+    artifactHash: diffHashValue,
+    exemption: { requested: env.KJ_ALLOW_POLICY === "1", justification: env.KJ_POLICY_REASON, hint: 'KJ_POLICY_REASON="por qué"' },
+    recordException: (entry) => recordException({ ...entry, scope: "este diff exacto" }),
+    standingExceptions, now,
+  });
+}

package/src/review/profiles.js

@@ -0,0 +1,66 @@
+/**
+ * Review profile resolver.
+ * Loads mode-specific reviewer instructions with fallback chain:
+ *   1. Project-level / user-level / built-in reviewer-{mode}.md
+ *   2. Project-level / user-level / built-in reviewer.md
+ *   3. Hardcoded default
+ */
+
+import path from "node:path";
+import { loadFirstExisting } from "../roles/base-role.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+const KNOWN_MODES = new Set(["paranoid", "strict", "standard", "relaxed"]);
+
+const DEFAULT_RULES = "Focus on critical issues: security vulnerabilities, logic errors, and broken tests.";
+
+function buildCandidates(fileName, projectDir) {
+  const candidates = [];
+
+  if (projectDir) {
+    candidates.push(path.join(projectDir, ".karajan", "roles", fileName));
+  }
+
+  candidates.push(path.join(getKarajanHome(), "roles", fileName));
+
+  const builtIn = path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    "..",
+    "..",
+    "templates",
+    "roles",
+    fileName
+  );
+  candidates.push(builtIn);
+
+  return candidates;
+}
+
+export async function resolveReviewProfile({ mode = "standard", projectDir } = {}) {
+  // Known modes: try mode-specific file first, then base reviewer.md
+  if (KNOWN_MODES.has(mode)) {
+    const modePaths = buildCandidates(`reviewer-${mode}.md`, projectDir);
+    const modeRules = await loadFirstExisting(modePaths);
+    if (modeRules) {
+      return { mode, rules: modeRules };
+    }
+
+    // Fallback to base reviewer.md
+    const basePaths = buildCandidates("reviewer.md", projectDir);
+    const baseRules = await loadFirstExisting(basePaths);
+    if (baseRules) {
+      return { mode, rules: baseRules };
+    }
+
+    return { mode, rules: DEFAULT_RULES };
+  }
+
+  // Custom/unknown modes: only check base reviewer.md
+  const basePaths = buildCandidates("reviewer.md", projectDir);
+  const baseRules = await loadFirstExisting(basePaths);
+  if (baseRules) {
+    return { mode, rules: baseRules };
+  }
+
+  return { mode, rules: DEFAULT_RULES };
+}

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/review/schema.js

@@ -0,0 +1,31 @@
+export function validateReviewResult(reviewResult) {
+  if (!reviewResult || typeof reviewResult !== "object") {
+    throw new TypeError("Reviewer output must be a JSON object");
+  }
+
+  if (typeof reviewResult.approved !== "boolean") {
+    throw new TypeError("Reviewer output missing boolean field: approved");
+  }
+
+  if (!Array.isArray(reviewResult.blocking_issues)) {
+    throw new TypeError("Reviewer output missing array field: blocking_issues");
+  }
+
+  if (!Array.isArray(reviewResult.non_blocking_suggestions)) {
+    reviewResult.non_blocking_suggestions = [];
+  }
+
+  if (typeof reviewResult.summary !== "string") {
+    reviewResult.summary = "";
+  }
+
+  if (typeof reviewResult.confidence !== "number") {
+    reviewResult.confidence = 0.5;
+  }
+
+  if (reviewResult.approved && reviewResult.blocking_issues.length > 0) {
+    throw new Error("Invalid reviewer output: approved=true with blocking issues");
+  }
+
+  return reviewResult;
+}