karajan-code 4.12.0 → 4.14.0

package/src/harden/harness-hooks.js

@@ -12,8 +12,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-const SCRIPT_REL = join(".karajan", "harness", "pretooluse.mjs");
-
 const SCRIPT_BODY = `#!/usr/bin/env node
 // kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
 // tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
@@ -43,38 +41,67 @@ process.stdin.on("end", () => {
 });
 `;
 
-const hookEntry = (matcher) => ({ matcher, hooks: [{ type: "command", command: `node ${SCRIPT_REL}` }] });
-
-/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
-export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
-  const scriptAbs = join(projectDir, SCRIPT_REL);
-  mkdirSync(join(projectDir, ".karajan", "harness"), { recursive: true });
-  writeFileSync(scriptAbs, SCRIPT_BODY, { mode: 0o755 });
+/** Write a managed hook script under .karajan/harness/ and return its path. */
+export function writeHarnessScript(projectDir, name, body) {
+  const dir = join(projectDir, ".karajan", "harness");
+  mkdirSync(dir, { recursive: true });
+  const abs = join(dir, name);
+  writeFileSync(abs, body, { mode: 0o755 });
+  return abs;
+}
 
+/**
+ * Merge hook entries into .claude/settings.json. Preserve, never clobber:
+ * invalid JSON or a hook event with an unexpected (non-array) shape is the
+ * user's business — the file is left alone and the caller wires manually.
+ * entries: [{ event, matcher?, script }] where script is a .karajan/harness
+ * basename; an entry is present when that script already appears under the
+ * same event (and matcher, when given).
+ */
+export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
   const settingsPath = join(projectDir, ".claude", "settings.json");
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
       settings = JSON.parse(readFileSync(settingsPath, "utf8"));
     } catch {
-      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (tool gate script written, wire it manually)`);
-      return { script: scriptAbs, wired: false };
+      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
     }
   }
   settings.hooks = settings.hooks || {};
-  // Preserve, never clobber: an existing PreToolUse with an unexpected shape
-  // is the user's business — leave the file alone (same as invalid JSON).
-  if ("PreToolUse" in settings.hooks && !Array.isArray(settings.hooks.PreToolUse)) {
-    logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.PreToolUse — leaving it untouched (tool gate script written, wire it manually)`);
-    return { script: scriptAbs, wired: false };
+  for (const { event } of entries) {
+    if (event in settings.hooks && !Array.isArray(settings.hooks[event])) {
+      logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.${event} — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
+    }
   }
-  const pre = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
-  for (const matcher of ["Write", "Bash"]) {
-    const present = pre.some((e) => e?.matcher === matcher && JSON.stringify(e).includes("pretooluse.mjs"));
-    if (!present) pre.push(hookEntry(matcher));
+  for (const { event, matcher, script } of entries) {
+    const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const present = list.some(
+      (e) => JSON.stringify(e).includes(script) && (matcher === undefined || e?.matcher === matcher),
+    );
+    if (!present) {
+      const cmd = { type: "command", command: `node ${join(".karajan", "harness", script)}` };
+      list.push(matcher === undefined ? { hooks: [cmd] } : { matcher, hooks: [cmd] });
+    }
+    settings.hooks[event] = list;
   }
-  settings.hooks.PreToolUse = pre;
   mkdirSync(join(projectDir, ".claude"), { recursive: true });
   writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
-  return { script: scriptAbs, wired: true };
+  return { wired: true };
+}
+
+/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
+export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
+  const { wired } = mergeClaudeHooks({
+    projectDir,
+    logger,
+    entries: [
+      { event: "PreToolUse", matcher: "Write", script: "pretooluse.mjs" },
+      { event: "PreToolUse", matcher: "Bash", script: "pretooluse.mjs" },
+    ],
+  });
+  return { script: scriptAbs, wired };
 }

package/src/harden/sentinel-hooks.js

@@ -0,0 +1,295 @@
+/**
+ * sentinel-hooks — SEN-A (KJC-TSK-0713, epic KJC-PCS-0071 Karajan Sentinel).
+ * v3 had authority without intelligence; v4 intelligence without authority.
+ * The Sentinel separates them: a deterministic PROGRAM (zero LLM) supervises
+ * the agent through the harness's synchronous hooks — PostToolUse records
+ * method facts per session, Stop BLOCKS ending the turn while violations are
+ * open. Claude Code only: it is the one harness with synchronous blocking
+ * hooks, which is why the guaranteed level requires Claude as host (ADR).
+ */
+
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { CARD_REF_RE } from "../review/card-first.js";
+import { mergeClaudeHooks, writeHarnessScript } from "./harness-hooks.js";
+
+/** The harness lives at the PROJECT root — resolve it even from a subdir. */
+export function resolveSentinelRoot(dir = process.cwd()) {
+  try {
+    return (
+      execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir
+    );
+  } catch {
+    return dir;
+  }
+}
+
+const LIB_BODY = `// kj sentinel shared lib (KJC-TSK-0714) — managed by \`kj harden\`.
+// Single source for every sentinel script: state, branch, classification,
+// violations, and escape recording.
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+export const STATE = join(here, "sentinel-state.json");
+export const ROOT = join(here, "..", "..");
+export const TESTS = /(^|\\/)(tests?|__tests__|spec)\\/|\\.(test|spec)\\.[a-z]+$/;
+export const CODE = /\\.(m?[jt]sx?|c[jt]s|py|go|rs|java|rb|php|cs|swift|kt|astro|svelte|vue|c|h|cc|cpp|hpp)$/;
+export const CARD = new RegExp(${JSON.stringify(CARD_REF_RE.source)}, "i");
+export const BASE_BRANCHES = new Set(["main", "master"]);
+export const load = () => { try { return JSON.parse(readFileSync(STATE, "utf8")); } catch { return {}; } };
+export const save = (state) => writeFileSync(STATE, JSON.stringify(state, null, 2));
+export const session = (state, sid) => {
+  state.sessions ||= {};
+  return (state.sessions[sid] ||= { edited_sources: [], edited_tests: [], escapes: [], errors: [], blocks: 0 });
+};
+export const branchOf = () => {
+  try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
+  catch { return null; }
+};
+export const violations = (s, branch) => {
+  const v = [];
+  if (!s || !(s.edited_sources || []).length) return v;
+  if (BASE_BRANCHES.has(branch)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion");
+  else if (branch && !CARD.test(branch)) v.push("La rama '" + branch + "' no referencia ninguna card — usa feat/<CARD-ID>-descripcion (y una card VIVA en el board)");
+  if (!(s.edited_tests || []).length) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
+  return v;
+};
+export const recordEscape = (sid, escape, tool) => {
+  const state = load();
+  const s = session(state, sid);
+  s.at = Date.now();
+  if (!s.escapes.includes(escape)) s.escapes.push(escape);
+  (state.escape_events ||= []).push({ escape, tool, sid, ts: Date.now() });
+  save(state);
+};
+`;
+
+const POST_BODY = `#!/usr/bin/env node
+// kj sentinel state writer (KJC-TSK-0713) — managed by \`kj harden\`.
+// Records deterministic method facts per session; never blocks, never fails
+// a tool call (PostToolUse, always exit 0).
+import { relative } from "node:path";
+import { CODE, TESTS, ROOT, load, save, session } from "./sentinel-lib.mjs";
+const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII"];
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    const file = input.file_path || input.notebook_path;
+    if (!["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(tool) || !file) process.exit(0);
+    const state = load();
+    const s = session(state, sid);
+    s.at = Date.now();
+    const rel = relative(ROOT, file).replaceAll("\\\\", "/");
+    const bucket = TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
+    if (bucket && !bucket.includes(rel)) bucket.push(rel);
+    for (const e of ESCAPES)
+      if (process.env[e] === "1" && !s.escapes.includes(e)) {
+        s.escapes.push(e);
+        (state.escape_events ||= []).push({ escape: e, tool, sid, ts: Date.now() });
+      }
+    const ids = Object.keys(state.sessions);
+    if (ids.length > 5) delete state.sessions[ids.sort((a, b) => (state.sessions[a].at || 0) - (state.sessions[b].at || 0))[0]];
+    save(state);
+  } catch { /* fail open — the sentinel never breaks a tool call */ }
+  process.exit(0);
+});
+`;
+
+const STOP_BODY = `#!/usr/bin/env node
+// kj sentinel stop gate (KJC-TSK-0713) — managed by \`kj harden\`. Exit 2
+// BLOCKS ending the turn while method violations are open (stderr lists each
+// one with its remediation). Fails OPEN on corrupt state, git errors, or
+// after 3 unresolved blocks — a sentinel bug never bricks the session — and
+// the fail-open is recorded in the state. \`--status\` prints, never blocks.
+import { spawnSync } from "node:child_process";
+import { load, save, branchOf, violations, ROOT } from "./sentinel-lib.mjs";
+if (process.argv.includes("--status")) {
+  const st = load();
+  const branch = branchOf();
+  const sessions = Object.entries(st.sessions || {});
+  if (!sessions.length) console.log("sentinel: sin actividad registrada en esta sesion");
+  for (const [sid, s] of sessions) {
+    console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : ""));
+    for (const x of violations(s, branch)) console.log("  ROJO: " + x);
+  }
+  process.exit(0);
+}
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    const { session_id: sid = "default" } = JSON.parse(raw);
+    const state = load();
+    // Tamper check runs regardless of session state: shell indirection leaves
+    // no edit-tool record, but it cannot survive \`kj sentinel verify\`, whose
+    // root of trust is the INSTALLED kj package (outside this project tree) —
+    // nothing under .karajan can vouch for itself. No kj on PATH → fail open.
+    const ver = spawnSync("kj", ["sentinel", "verify", "--json"], { cwd: ROOT, encoding: "utf8" });
+    let tampered = [];
+    if (!ver.error && ver.status !== null && ver.status !== 0) {
+      try { tampered = JSON.parse(ver.stdout).mismatched || ["unknown"]; } catch { tampered = ["unknown"]; }
+    }
+    if (tampered.length) {
+      state.tamper_blocks = (state.tamper_blocks || 0) + 1;
+      save(state);
+      if (state.tamper_blocks > 3) {
+        console.error("kj sentinel: fail-open tras 3 bloqueos por manipulacion sin restaurar — corre kj harden y avisa a tu usuario");
+        process.exit(0);
+      }
+      console.error("kj sentinel: scripts del supervisor modificados fuera de kj harden (" + tampered.join(", ") + ") — restaura con kj harden antes de terminar; si lo cambiaste tu (humano), reinstalar lo deja en verde.");
+      process.exit(2);
+    }
+    state.tamper_blocks = 0;
+    const s = state.sessions?.[sid];
+    if (!s) process.exit(0);
+    const v = violations(s, branchOf());
+    if (!v.length) {
+      s.blocks = 0;
+      save(state);
+      if ((s.escapes || []).length)
+        console.log(JSON.stringify({ systemMessage: "kj sentinel: esta sesion uso " + s.escapes.length + " escape(s): " + s.escapes.join(", ") + " — decision registrada; detalle en kj sentinel status." }));
+      process.exit(0);
+    }
+    s.blocks = (s.blocks || 0) + 1;
+    if (s.blocks > 3) {
+      (s.errors ||= []).push("fail-open: 3 bloqueos consecutivos sin resolver — el sentinel se aparta para no colgar la sesion");
+      save(state);
+      console.error("kj sentinel: fail-open tras 3 bloqueos sin resolver — revisa kj sentinel status con tu usuario");
+      process.exit(0);
+    }
+    save(state);
+    console.error("kj sentinel: el turno NO puede terminar con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve las violaciones (o pide a tu usuario el escape) y termina de nuevo. Estado: kj sentinel status");
+    process.exit(2);
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+const PRETOOL_BODY = `#!/usr/bin/env node
+// kj sentinel pretooluse gate (KJC-TSK-0714) — managed by \`kj harden\`.
+// Consults the session method state BEFORE the tool runs: the rule fires
+// before the damage, not in the post-mortem. Exit 2 blocks (stderr says the
+// remediation); read-only tools are never wired here; every honored escape
+// is recorded as an auditable event. Fails OPEN on anything unexpected.
+import { relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, load, violations, recordEscape } from "./sentinel-lib.mjs";
+const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+const PUBLISH = /\\bnpm\\s+publish\\b|\\bfirebase\\s+deploy\\b|\\bgh\\s+release\\s+create\\b/;
+const PUSH = /\\bgit\\s+push\\b/;
+const PROTECTED = /\\.claude\\/settings\\.json\\b|\\.karajan\\/(hooks|harness)\\//;
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    // Self-protection (KJC-TSK-0715) rules run BEFORE any escape, including
+    // KJ_SENTINEL_OFF: the sentinel is not dismantled from inside a session —
+    // only the human, editing outside it.
+    if (EDIT_TOOLS.includes(tool)) {
+      const target = input.file_path || input.notebook_path;
+      const relT = target ? relative(ROOT, String(target)).replaceAll("\\\\", "/") : "";
+      if (relT && PROTECTED.test(relT)) {
+        console.error("kj sentinel: ese fichero es parte del supervisor (" + relT + ") — solo el humano desmonta el sentinel, editalo fuera de la sesion.");
+        process.exit(2);
+      }
+    }
+    // Any Bash that NAMES the supervisor's files is denied — a write-verb
+    // blocklist is bypassable (cp, dd, one-liners), and reading them is what
+    // the Read/Grep tools are for. Shell indirection (variables, globs,
+    // substitution) cannot be resolved from command text: that vector is
+    // caught by the Stop gate's checksum verification, which blocks the turn.
+    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\\\", "/"))) {
+      console.error("kj sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion.");
+      process.exit(2);
+    }
+    if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    if (EDIT_TOOLS.includes(tool)) {
+      const file = input.file_path || input.notebook_path;
+      const rel = file ? relative(ROOT, String(file)).replaceAll("\\\\", "/") : "";
+      if (rel && CODE.test(rel) && !TESTS.test(rel)) {
+        const branch = branchOf();
+        const why = !branch ? null : BASE_BRANCHES.has(branch) ? "base" : !CARD.test(branch) ? "nocard" : null;
+        if (why) {
+          if (process.env.KJ_ALLOW_NO_CARD === "1") { recordEscape(sid, "KJ_ALLOW_NO_CARD", tool); process.exit(0); }
+          console.error(why === "base"
+            ? "kj sentinel: no se editan fuentes en la rama base '" + branch + "' — crea la card (kj hu add) y la rama: git checkout -b feat/<CARD-ID>-descripcion. (KJ_ALLOW_NO_CARD=1 = excepcion consciente, queda registrada)"
+            : "kj sentinel: la rama '" + branch + "' no referencia ninguna card — crea/mueve la card a running (kj hu add | kj hu move) y usa una rama feat/<CARD-ID>-descripcion. (KJ_ALLOW_NO_CARD=1 = excepcion consciente, queda registrada)");
+          process.exit(2);
+        }
+      }
+    }
+    if (tool === "Bash") {
+      const cmd = String(input.command || "");
+      if (PUBLISH.test(cmd)) {
+        if (process.env.KJ_ALLOW_RELEASE === "1") { recordEscape(sid, "KJ_ALLOW_RELEASE", tool); process.exit(0); }
+        const res = spawnSync("kj", ["release", "check", "--json"], { cwd: ROOT, encoding: "utf8" });
+        if (res.error || res.status === null) process.exit(0);
+        if (res.status !== 0) {
+          let items = "";
+          try { items = (JSON.parse(res.stdout).checks || []).filter((c) => !c.ok).map((c) => "\\n- " + c.name + ": " + c.detail).join(""); } catch { /* raw output */ }
+          console.error("kj sentinel: release check en ROJO — no se publica ni despliega hasta resolverlo:" + (items || "\\n- corre kj release check para el detalle") + "\\n(KJ_ALLOW_RELEASE=1 = excepcion consciente, queda registrada)");
+          process.exit(2);
+        }
+      } else if (PUSH.test(cmd)) {
+        const v = violations(load().sessions?.[sid], branchOf());
+        if (v.length) {
+          console.error("kj sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve antes de empujar. Estado: kj sentinel status");
+          process.exit(2);
+        }
+      }
+    }
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+const SCRIPT_BODIES = {
+  "sentinel-lib.mjs": LIB_BODY,
+  "posttooluse.mjs": POST_BODY,
+  "stop.mjs": STOP_BODY,
+  "pretooluse-sentinel.mjs": PRETOOL_BODY,
+};
+
+/**
+ * Tamper detection (KJC-TSK-0715): compare the on-disk harness scripts with
+ * what THIS kj install would write. The root of trust is the installed kj
+ * package — outside the project tree, beyond the session's tool reach —
+ * because nothing under .karajan can vouch for itself.
+ */
+export function verifySentinelScripts({ projectDir } = {}) {
+  const dir = join(projectDir || resolveSentinelRoot(), ".karajan", "harness");
+  const mismatched = [];
+  for (const [name, body] of Object.entries(SCRIPT_BODIES)) {
+    try {
+      if (readFileSync(join(dir, name), "utf8") !== body) mismatched.push(name);
+    } catch {
+      mismatched.push(name);
+    }
+  }
+  return { ok: mismatched.length === 0, mismatched };
+}
+
+/** Write the sentinel scripts (shared lib + state writer + gates) and wire them. */
+export function installSentinelHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const [lib, post, stop, pre] = Object.entries(SCRIPT_BODIES).map(([name, body]) =>
+    writeHarnessScript(projectDir, name, body),
+  );
+  const { wired } = mergeClaudeHooks({
+    projectDir,
+    logger,
+    entries: [
+      { event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "pretooluse-sentinel.mjs" },
+      { event: "PreToolUse", matcher: "Bash", script: "pretooluse-sentinel.mjs" },
+      { event: "PostToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "posttooluse.mjs" },
+      { event: "Stop", script: "stop.mjs" },
+    ],
+  });
+  return { scripts: [lib, post, stop, pre], wired };
+}

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),

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/utils/agent-detect.js

@@ -9,9 +9,38 @@ const KNOWN_AGENTS = [
   { name: "aider", install: getInstallCommand("aider") },
   { name: "opencode", install: getInstallCommand("opencode") },
   { name: "qwen", install: getInstallCommand("qwen") },
-  { name: "copilot", install: getInstallCommand("copilot") }
+  { name: "copilot", install: getInstallCommand("copilot") },
+  // KJC-TSK-0729: promoted from the observation census once its adapter
+  // landed — detecting is not supporting; supporting is.
+  { name: "kimi", install: getInstallCommand("kimi") },
+  { name: "agy", install: getInstallCommand("agy") }
 ];
 
+/**
+ * KJC-TSK-0728 — observation census (from the Orca landscape): agent CLIs kj
+ * can SEE but does not drive. Detecting is not supporting — these never feed
+ * pipeline pickers; they feed the AI-surface inventory and one doctor line.
+ * `bin` differs from `name` when the vendor ships an umbrella binary.
+ */
+const OBSERVED_AGENTS = [
+  { name: "grok", bin: "grok" },
+  { name: "cursor-agent", bin: "cursor-agent" },
+  { name: "pi", bin: "pi" },
+  { name: "kilocode", bin: "kilocode" },
+  { name: "vibe", bin: "vibe" },
+  { name: "rovodev", bin: "acli" },
+];
+
+/** Probe the observation census in parallel; callers filter on `available`. */
+export async function detectObservedAgents() {
+  return Promise.all(
+    OBSERVED_AGENTS.map(async (agent) => {
+      const check = await checkBinary(agent.bin);
+      return { name: agent.name, bin: agent.bin, available: check.ok, version: check.ok ? check.version : null };
+    })
+  );
+}
+
 export async function checkBinary(name, versionArg = "--version") {
   const resolved = resolveBin(name);
   // KJC-BUG-0113: a zombie CLI that hangs on --version (seen with the
@@ -61,4 +90,4 @@ export function isHostAgent(provider) {
   return host !== null && host === provider;
 }
 
-export { KNOWN_AGENTS };
+export { KNOWN_AGENTS, OBSERVED_AGENTS };

package/src/utils/os-detect.js

@@ -56,6 +56,11 @@ const INSTALL_COMMANDS = {
     linux: "npm install -g @qwen-code/qwen-code",
     windows: "npm install -g @qwen-code/qwen-code"
   },
+  agy: {
+    macos: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+    linux: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+    windows: "irm https://antigravity.google/cli/install.ps1 | iex"
+  },
   copilot: {
     macos: "npm install -g @github/copilot",
     linux: "npm install -g @github/copilot",