karajan-code 4.13.0 → 4.14.0

package/README.md

@@ -22,7 +22,7 @@
 
 ---
 
-Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
+Your AI agent (Claude Code, Codex, Copilot, Antigravity, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
 - **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. The install wires it as a native MCP tool (`kj_rag_query`) so querying the index is the agent's cheapest path. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk. A distilled engineering canon rides along: `kj rag query --library` serves pattern cards (when it applies, when it does NOT, the canonical citation) so plans name a greenfield alternative instead of following the legacy line by inertia.
 - **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
@@ -34,6 +34,7 @@ Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Kar
 - **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
 - **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
 - **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
+- **The review panel never runs dry** — nine built-in agents (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — the gemini successor —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), and when the configured reviewer exhausts its quota, `kj review` switches to an authenticated candidate with a LOUD notice — or hands you the menu of candidates with their tier (free / subscription / local) and the exact login command. Never a silent failure, never the brain reviewing itself.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 

package/docs/README.es.md

@@ -14,7 +14,7 @@
 
 ---
 
-Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
+Tu agente de IA (Claude Code, Codex, Copilot, Antigravity, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
 - **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. La instalación lo cablea como herramienta MCP nativa (`kj_rag_query`), de modo que consultar el índice sea el camino más barato del agente. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk. Y viaja con un canon de ingeniería destilado: `kj rag query --library` sirve fichas de patrón (cuándo aplica, cuándo NO, la cita canónica) para que los planes nombren una alternativa greenfield en vez de seguir la línea del legacy por inercia.
 - **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
@@ -26,6 +26,7 @@ Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código.
 - **Nada personal se publica** — cada boundary de salida se audita antes de dejar la máquina: el pre-commit rechaza un diff con tus datos vetados, los tokens de plataforma hardcodeados (`ghp_`, `sk-`, `AKIA`…) bloquean directamente, el scan del tarball guarda el publish, y `kj privacy scan <dir>` audita cualquier build. Tu denylist vive en `~/.karajan/privacy.yml` — la instalación pregunta y la escribe por ti.
 - **Instalar ES activar** — `kj env install` ejecuta él mismo el enforcement (hooks de git, gate de veredicto, tool gate) en vez de confiar en que el agente corra pasos de setup, y termina imprimiendo el método en la propia conversación que instaló. Un commit fuera del método se rechaza, no se narra.
 - **El turno no puede terminar en rojo — el Sentinel** — un supervisor determinista (cero LLM) cableado a los hooks síncronos del harness registra el estado del método de la sesión según corren las herramientas, y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas. El programa manda, el agente piensa. Ver [niveles de garantía](#niveles-de-garantía-gobernado-vs-supervisado).
+- **El panel de revisión nunca se seca** — nueve agentes integrados (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — el sucesor de gemini —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), y cuando al reviewer configurado se le agota la cuota, `kj review` cambia a un candidato autenticado AVISANDO en alto — o te entrega el menú de candidatos con su tier (gratis / suscripción / local) y el comando de login exacto. Jamás un fallo mudo, jamás el brain revisándose a sí mismo.
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -76,8 +76,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
+    "lint": "eslint src/ packages/",
+    "lint:fix": "eslint src/ packages/ --fix",
     "lint:syntax": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",

package/packages/ai-trash/src/cli.js

@@ -113,7 +113,9 @@ async function cmdPurge(root, id, out, err) {
 async function cmdEmpty(root, flags, out) {
   await ensureRoot(root);
   const m = await loadManifest(root);
-  let dropped = [];
+  // Assigned in every branch below (the trailing else covers the default),
+  // so an initializer would never be read (no-useless-assignment).
+  let dropped;
   if (flags["older-than-days"]) {
     const days = Number(flags["older-than-days"]);
     if (!Number.isFinite(days) || days < 0) throw new Error("--older-than-days must be >= 0");

package/packages/hu-board/public/utils/formatters.js

@@ -117,7 +117,7 @@ function humaniseProjectName(id) {
   if (!id || typeof id !== 'string') return id || '';
   const tail = id.split(/[/_]/).filter(Boolean).pop() || id;
   const words = tail
-    .split(/[\s\-]+/)
+    .split(/[\s-]+/)
     .map((w) => w.replace(/[^\p{L}\p{N}]/gu, ''))
     .filter((w) => w.length > 0);
   if (words.length === 0) return id;

package/packages/hu-board/src/cleanup-zombies.js

@@ -23,7 +23,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { homedir } from 'node:os';
 import {
   getDb,
   getKjHome,

package/packages/hu-board/src/command-runner.js

@@ -18,7 +18,6 @@
 
 import { mkdirSync, openSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";

package/packages/hu-board/src/config-yaml.js

@@ -30,7 +30,6 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { tmpdir } from 'node:os';
 import yaml from 'js-yaml';
 import { getKjHome } from './db.js';
 
@@ -448,7 +447,7 @@ export function readConfig({ scope = 'global' } = {}) {
       parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {};
       exists = true;
     } catch (err) {
-      throw new Error(`No se pudo parsear ${p}: ${err.message}`);
+      throw new Error(`No se pudo parsear ${p}: ${err.message}`, { cause: err });
     }
   }
   const fields = EDITABLE_FIELDS.map((f) => {

package/packages/hu-board/src/ephemeral-cleaner.js

@@ -150,8 +150,6 @@ export function cleanupEphemeralProjects({
   const candidates = findEphemeralProjects(allProjects, { ...opts, now: now() });
   if (candidates.length === 0) return [];
 
-  const countStories = db.prepare("SELECT COUNT(*) AS n FROM stories WHERE project_id = ?");
-  const countSessions = db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE project_id = ?");
   const delStories = db.prepare("DELETE FROM stories WHERE project_id = ?");
   const delSessions = db.prepare("DELETE FROM sessions WHERE project_id = ?");
   const delProject = db.prepare("DELETE FROM projects WHERE id = ?");

package/packages/hu-board/src/plan-mutations.js

@@ -16,7 +16,6 @@
  */
 import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { writeJsonAtomicSync } from 'karajan-core/atomic-write';
 import { spawn } from 'node:child_process';
 import { trackRun, untrack } from './run-tracker.js';

package/packages/hu-board/src/preflight.js

@@ -28,7 +28,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getHuBoardPlansDirs } from './db.js';
 

package/packages/hu-board/src/routes/api.js

@@ -21,7 +21,6 @@ export async function readPlanCached(p) {
   planFileCache.set(p, { mtimeMs, plan });
   return plan;
 }
-import os from 'node:os';
 import path from 'node:path';
 import { spawn as spawnChild } from 'node:child_process';
 import {
@@ -36,7 +35,6 @@ import {
   getKjHome,
   getHuBoardRunsDir,
   getHuBoardPlansDir,
-  getHuBoardLegacyPlansDir,
   getHuBoardPlansDirs,
   getStoryRow,
   listPlanIdsForProject,
@@ -93,19 +91,6 @@ function huStoriesDir() {
   return path.join(getKjHome(), 'hu-stories');
 }
 
-/**
- * Best-effort removal of the hu-stories/<id>/ directory.
- */
-async function removeBatchDir(batchId) {
-  try {
-    const dir = path.join(huStoriesDir(), batchId);
-    await fsp.rm(dir, { recursive: true, force: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * GET /api/dashboard - Global dashboard statistics.
  */

package/packages/hu-board/src/server.js

@@ -4,7 +4,6 @@ import rateLimit from 'express-rate-limit';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { writeFileSync, rmSync, mkdirSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { initDb, closeDb } from './db.js';
 import { fullScan, startWatcher } from './sync.js';
 import apiRoutes from './routes/api.js';

package/packages/hu-board/src/sync.js

@@ -1,5 +1,5 @@
 import { watch } from 'chokidar';
-import { readFileSync, readdirSync, existsSync, statSync, rmSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, rmSync } from 'node:fs';
 import { dirname, join, basename } from 'node:path';
 import { homedir } from 'node:os';
 import {

package/packages/hu-board/src/token-store.js

@@ -12,7 +12,6 @@
 
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 const TOKEN_BYTES = 32;

package/packages/hu-board/src/zombie-reaper.js

@@ -45,7 +45,6 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 
 const DEFAULT_CODING_HOURS = 6;
 const DEFAULT_PAUSED_HOURS = 24;

package/src/agents/agy-agent.js

@@ -0,0 +1,61 @@
+import { BaseAgent } from "./base-agent.js";
+import { resolveBin } from "./resolve-bin.js";
+
+/**
+ * Antigravity CLI (`agy`) — KJC-TSK-0729 fase 2b: the ninth built-in agent.
+ * Google's official successor to the retired gemini CLI (dead 2026-06-18),
+ * covered by the user's Google AI Pro/Ultra subscription — the natural
+ * third AI for solomon arbitration, back at last.
+ *
+ * Verified live against agy 1.1.10:
+ *  - `-p <prompt>` runs print mode; `--output-format json` emits ONE JSON
+ *    object: {status: "SUCCESS", response, usage}. Non-SUCCESS status can
+ *    arrive with exit 0, so ok checks BOTH.
+ *  - `--disable-slash-commands` keeps prompt content (diffs can contain
+ *    "/lines") from expanding as slash commands in print mode.
+ *  - Permission prompts are denied in print mode unless
+ *    `--dangerously-skip-permissions` (coder mode only).
+ *  - Auth lives under ~/.gemini/antigravity-cli (device/browser login).
+ */
+export class AgyAgent extends BaseAgent {
+  async runTask(task) {
+    return this._exec(task, this.getRoleModel(task.role || "coder"), ["--dangerously-skip-permissions"]);
+  }
+
+  async reviewTask(task) {
+    return this._exec(
+      { ...task, prompt: `Do NOT use any tools. Answer directly from this prompt only.\n\n${task.prompt}` },
+      this.getRoleModel(task.role || "reviewer"),
+      [],
+    );
+  }
+
+  async _exec(task, model, extraArgs) {
+    const args = ["-p", task.prompt, "--output-format", "json", "--disable-slash-commands", ...extraArgs];
+    if (model) args.push("--model", model);
+    const res = await this.runCommand(resolveBin("agy"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs,
+    });
+    const parsed = extractAgyOutput(res.stdout);
+    const ok = res.exitCode === 0 && parsed?.status === "SUCCESS";
+    return {
+      ok,
+      output: parsed?.response ?? res.stdout,
+      error: ok ? res.stderr : parsed?.error || res.stderr || `agy status: ${parsed?.status || "unparseable"}`,
+      exitCode: res.exitCode,
+    };
+  }
+}
+
+/** Parse agy's single-object JSON print output ({status, response}), null if not JSON. */
+export function extractAgyOutput(stdout) {
+  if (!stdout) return null;
+  try {
+    const obj = JSON.parse(stdout.trim());
+    return typeof obj === "object" && obj !== null ? obj : null;
+  } catch {
+    return null;
+  }
+}

package/src/agents/index.js

@@ -5,6 +5,8 @@ import { AiderAgent } from "./aider-agent.js";
 import { OpenCodeAgent } from "./opencode-agent.js";
 import { QwenAgent } from "./qwen-agent.js";
 import { CopilotAgent } from "./copilot-agent.js";
+import { KimiAgent } from "./kimi-agent.js";
+import { AgyAgent } from "./agy-agent.js";
 
 const agentRegistry = new Map();
 
@@ -53,3 +55,5 @@ registerAgent("aider", AiderAgent, { bin: "aider", installUrl: "https://aider.ch
 registerAgent("opencode", OpenCodeAgent, { bin: "opencode", installUrl: "https://opencode.ai" });
 registerAgent("qwen", QwenAgent, { bin: "qwen", installUrl: "https://github.com/QwenLM/qwen-code" });
 registerAgent("copilot", CopilotAgent, { bin: "copilot", installUrl: "https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli" });
+registerAgent("kimi", KimiAgent, { bin: "kimi", installUrl: "https://github.com/MoonshotAI/kimi-code" });
+registerAgent("agy", AgyAgent, { bin: "agy", installUrl: "https://antigravity.google" });

package/src/agents/kimi-agent.js

@@ -0,0 +1,44 @@
+import { BaseAgent } from "./base-agent.js";
+import { resolveBin } from "./resolve-bin.js";
+
+/**
+ * Kimi Code (Moonshot, binary `kimi`) — KJC-TSK-0729 fase 2: the eighth
+ * built-in agent and the free-tier reserve of the reviewer/solomon panel.
+ *
+ * Verified live against kimi-code 0.27.0:
+ *  - `-p <prompt>` runs one prompt non-interactively and prints the
+ *    response (text output by default) — the prompt travels as an argument,
+ *    same E2BIG caveat as claude/copilot (KJC-BUG-0121) for huge diffs.
+ *  - `-m <model>` picks a model alias; `-y` auto-approves actions.
+ *  - Auth is the device-code login (`kimi login`), no env keys involved;
+ *    "No model configured" on a logged machine means the login did not
+ *    populate the managed provider (re-run `kimi login`).
+ */
+export class KimiAgent extends BaseAgent {
+  async runTask(task) {
+    // Coder mode IS an agentic run: file edits and shell need approval.
+    return this._exec(task, this.getRoleModel(task.role || "coder"), ["-y"]);
+  }
+
+  async reviewTask(task) {
+    // Review/arbitration answers from the prompt alone — no auto-approval,
+    // and an explicit no-tools instruction so a headless run never stalls
+    // waiting for a permission prompt nobody can answer.
+    return this._exec(
+      { ...task, prompt: `Do NOT use any tools. Answer directly from this prompt only.\n\n${task.prompt}` },
+      this.getRoleModel(task.role || "reviewer"),
+      [],
+    );
+  }
+
+  async _exec(task, model, extraArgs) {
+    const args = ["-p", task.prompt, ...extraArgs];
+    if (model) args.push("-m", model);
+    const res = await this.runCommand(resolveBin("kimi"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs,
+    });
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+  }
+}

package/src/checks/ai-surface.js

@@ -50,8 +50,11 @@ export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir
  * Diff the current surface against the last-seen snapshot and persist the
  * new state. First run records the baseline silently.
  */
-export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json") } = {}) {
-  const surface = collectAiSurface({ projectDir, home });
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
+  // KJC-TSK-0728: extraSurface carries entries the (async) caller collected
+  // outside config files — e.g. observed agent CLIs as "grok (cli)" — so
+  // they ride the same snapshot and the same "NEW since last check" drift.
+  const surface = [...new Set([...collectAiSurface({ projectDir, home }), ...extraSurface])].sort();
   let state = {};
   try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
   const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;

package/src/checks/binaries.js

@@ -12,7 +12,7 @@
  * the install command and can offer to run it).
  */
 
-import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+import { checkBinary, KNOWN_AGENTS, detectObservedAgents } from "../utils/agent-detect.js";
 import { runCommand } from "../utils/process.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
@@ -38,6 +38,33 @@ function createAgentCheck(agent) {
   };
 }
 
+/**
+ * KJC-TSK-0728 — ONE aggregate line for the observation census (agent CLIs
+ * kj sees but does not drive). Only FOUND CLIs are listed; the missing ones
+ * make no noise, and the check never fails. `detector` is injectable for
+ * tests.
+ */
+export function createObservedAgentsCheck({ detector = detectObservedAgents } = {}) {
+  return {
+    name: "agents:observed",
+    label: "Agent CLIs observed (not driven)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      let found = [];
+      try {
+        found = (await detector()).filter((a) => a.available);
+      } catch { /* census is best-effort */ }
+      return {
+        ok: true,
+        severity: "info",
+        detail: found.length
+          ? found.map((a) => `${a.name} (${(a.version || "").split(" ").at(-1) || "?"})`).join(", ")
+          : "none detected",
+      };
+    },
+  };
+}
+
 /**
  * Check the presence of a core binary (node, npm, git).
  */
@@ -165,6 +192,7 @@ export function getBinaryChecks() {
   for (const agent of KNOWN_AGENTS) {
     checks.push(createAgentCheck(agent));
   }
+  checks.push(createObservedAgentsCheck());
   for (const bin of ["node", "npm", "git"]) {
     checks.push(createCoreBinaryCheck(bin));
   }

package/src/commands/check.js

@@ -7,6 +7,7 @@
 import { checkHarden } from "../harden/check.js";
 import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
+import { detectObservedAgents } from "../utils/agent-detect.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
@@ -14,8 +15,15 @@ export async function checkCommand({ projectDir = process.cwd(), profile = "stan
   // rides along in check output but never affects the exit code.
   const method = await collectMethodStats({ projectDir }).catch(() => null);
   // KJC-TSK-0694: same deal for the MCP inventory — a nudge, never a gate.
+  // KJC-TSK-0728: observed agent CLIs ride the same snapshot as "(cli)"
+  // entries, so a newly-appeared agent binary trips the same drift question.
   let aiSurface = null;
-  try { aiSurface = checkAiSurface({ projectDir }); } catch { /* inventory is best-effort */ }
+  try {
+    const clis = (await detectObservedAgents().catch(() => []))
+      .filter((a) => a.available)
+      .map((a) => `${a.name} (cli)`);
+    aiSurface = checkAiSurface({ projectDir, extraSurface: clis });
+  } catch { /* inventory is best-effort */ }
 
   if (json) {
     logger.info?.(JSON.stringify({ ...result, method, aiSurface }));

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/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",

package/src/utils/role-env.js

@@ -32,8 +32,9 @@ const PREFIXES = [
 
 // Vars only ONE agent authenticates with — granting them globally would
 // defeat the point (the coder does not need your GitHub token; copilot does).
-const AGENT_EXTRAS = {
+export const AGENT_EXTRAS = {
   copilot: ["GITHUB_", "GH_"],
+  kimi: ["KIMI_", "MOONSHOT_"],
 };
 
 const matches = (pattern, key) =>