karajan-code 1.35.0 → 1.36.1

package/docs/README.es.md

@@ -29,8 +29,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 
 **Caracteristicas principales:**
 - **Pipeline multi-agente** con 11 roles configurables
-- **4 agentes de IA soportados**: Claude, Codex, Gemini, Aider
-- **Servidor MCP** con 15 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **5 agentes de IA soportados**: Claude, Codex, Gemini, Aider, OpenCode
+- **Servidor MCP** con 20 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **Bootstrap obligatorio** — valida prerequisitos del entorno (git, remote, config, agentes, SonarQube) antes de cada ejecucion. Si algo falta, para con instrucciones claras
 - **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
 - **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
@@ -128,33 +129,135 @@ Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-
 
 `kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
 
-## Inicio rapido
+## Tres formas de usar Karajan
+
+Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
+
+### 1. CLI — Directamente desde terminal
 
 ```bash
-# Ejecutar una tarea con defaults (claude=coder, codex=reviewer, TDD)
 kj run "Implementar autenticacion de usuario con JWT"
-
-# Solo coder (sin revision)
 kj code "Anadir validacion de inputs al formulario de registro"
-
-# Solo reviewer (revisar diff actual)
 kj review "Revisar los cambios de autenticacion"
+kj plan "Refactorizar la capa de base de datos"
+```
 
-# Generar un plan de implementacion
-kj plan "Refactorizar la capa de base de datos para usar connection pooling"
+### 2. MCP — Dentro de tu agente de IA
 
-# Pipeline completo con todas las opciones
-kj run "Corregir inyeccion SQL critica en el endpoint de busqueda" \
-  --coder claude \
-  --reviewer codex \
-  --reviewer-fallback claude \
-  --methodology tdd \
-  --enable-triage \
-  --enable-tester \
-  --enable-security \
-  --auto-commit \
-  --auto-push \
-  --max-iterations 5
+El caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. El agente tiene acceso a 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y delega el trabajo pesado al pipeline de Karajan.
+
+```
+Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
+```
+
+**El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
+
+### 3. kj-tail — Monitorizar desde otro terminal
+
+**La herramienta companera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
+
+```bash
+kj-tail
+```
+
+Veras la salida del pipeline en vivo — etapas, resultados, iteraciones, errores — tal como ocurren.
+
+```bash
+kj-tail                  # Seguir pipeline en tiempo real (por defecto)
+kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
+kj-tail -t               # Mostrar timestamps
+kj-tail -s               # Snapshot: mostrar log actual y salir
+kj-tail -n 50            # Mostrar ultimas 50 lineas y seguir
+kj-tail --help           # Todas las opciones
+```
+
+> **Importante**: `kj-tail` debe ejecutarse desde el mismo directorio donde el agente de IA esta trabajando. Lee `<proyecto>/.kj/run.log`, que se crea cuando Karajan arranca un pipeline via MCP.
+
+**Flujo tipico:**
+
+```
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  Terminal 1               │    │  Terminal 2               │
+│                           │    │                           │
+│  $ claude                 │    │  $ kj-tail                │
+│  > implementa la          │    │                           │
+│    siguiente tarea        │    │  ├─ 📋 Triage: medium     │
+│    prioritaria            │    │  ├─ 🔬 Researcher ✅      │
+│                           │    │  ├─ 🧠 Planner ✅         │
+│  (Claude llama a kj_run   │    │  ├─ 🔨 Coder ✅           │
+│   via MCP — solo ves      │    │  ├─ 🔍 Sonar: OK         │
+│   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
+│                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
+│                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
+│                           │    │  ├─ ✅ Review: APPROVED    │
+│                           │    │  ├─ 🧪 Tester: passed     │
+│                           │    │  └─ 🏁 Result: APPROVED   │
+└──────────────────────────┘    └──────────────────────────┘
+```
+
+**Ejemplo con pipeline completo** — tarea compleja con todos los roles:
+
+```
+┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
+│                                                                              │
+│  $ claude                                                                    │
+│                                                                              │
+│  > Construye una API REST para un sistema de reservas. Requisitos:           │
+│  > - Express + TypeScript con validacion Zod en cada endpoint                │
+│  > - Endpoints: POST /bookings, GET /bookings/:id,                           │
+│  >   PATCH /bookings/:id/cancel                                              │
+│  > - Una reserva tiene: id, guestName, roomType (standard|suite|penthouse),  │
+│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
+│  > - Validar: checkOut posterior a checkIn, sin fechas pasadas,              │
+│  >   roomType debe ser un valor valido del enum                              │
+│  > - Cancelar devuelve 409 si ya esta cancelada                              │
+│  > - Usa TDD. Ejecutalo con Karajan con architect y planner activos,         │
+│  >   modo paranoid. Coder claude, reviewer codex.                            │
+│                                                                              │
+│  Claude llama a kj_run via MCP con:                                          │
+│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
+│                                                                              │
+│  kj-tail v1.36.1 — .kj/run.log                                              │
+│                                                                              │
+│  ├─ 📋 Triage: medium (sw) — activando researcher, architect, planner        │
+│  ├─ ⚙️ Preflight passed — all checks OK                                     │
+│  ├─ 🔬 Researcher: 8 ficheros, 3 patrones, 5 restricciones                  │
+│  ├─ 🏗️ Architect: diseno 3 capas (routes → service → validators)            │
+│  ├─ 🧠 Planner: 6 pasos — tests primero, luego rutas, servicio, validadores │
+│  │                                                                           │
+│  ▶ Iteracion 1/5                                                             │
+│  ├─ 🔨 Coder (claude): 3 endpoints + 18 tests                               │
+│  ├─ 📋 TDD: PASS (3 src, 2 test)                                            │
+│  ├─ 🔍 Sonar: Quality gate OK                                               │
+│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
+│  │   "Falta 404 para GET booking inexistente"                                │
+│  │   "Endpoint cancel sin test de idempotencia"                              │
+│  ├─ ⚖️ Solomon: approve_with_conditions (2 condiciones)                     │
+│  │   "Anadir respuesta 404 y test para GET /bookings/:id con id desconocido" │
+│  │   "Anadir test: cancelar reserva ya cancelada devuelve 409, no 500"       │
+│  │                                                                           │
+│  ▶ Iteracion 2/5                                                             │
+│  ├─ 🔨 Coder (claude): corregido — 22 tests                                 │
+│  ├─ 📋 TDD: PASS                                                            │
+│  ├─ 🔍 Sonar: OK                                                            │
+│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
+│  ├─ 🧪 Tester: passed — cobertura 94%, 22 tests                             │
+│  ├─ 🔒 Security: passed — 0 criticos, 1 bajo (helmet recomendado)           │
+│  ├─ 📊 Audit: CERTIFIED (3 advertencias)                                    │
+│  │                                                                           │
+│  🏁 Resultado: APPROVED                                                      │
+│     🔬 Investigacion: 8 ficheros, 3 patrones                                 │
+│     🗺 Plan: 6 pasos (tests primero)                                         │
+│     🧪 Cobertura: 94%, 22 tests                                              │
+│     🔒 Seguridad: OK                                                         │
+│     🔍 Sonar: OK                                                             │
+│     💰 Presupuesto: $0.42 (claude: $0.38, codex: $0.04)                      │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Comandos CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.35.0",
+  "version": "1.36.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -38,6 +38,7 @@
   ],
   "bin": {
     "kj": "bin/kj.js",
+    "kj-tail": "bin/kj-tail",
     "karajan-mcp": "bin/karajan-mcp.js"
   },
   "scripts": {

package/src/agents/aider-agent.js

@@ -5,21 +5,28 @@ import { resolveBin } from "./resolve-bin.js";
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["--yes", "--message", task.prompt];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("aider"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const result = await this._exec(task, model);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Aider model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null);
+    }
+    return result;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["--yes", "--message", task.prompt];
     const model = this.getRoleModel(role);
+    const result = await this._exec(task, model);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Aider model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null);
+    }
+    return result;
+  }
+
+  async _exec(task, model) {
+    const args = ["--yes", "--message", task.prompt];
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("aider"), args, {
       onOutput: task.onOutput,

package/src/agents/base-agent.js

@@ -1,3 +1,12 @@
+const MODEL_NOT_SUPPORTED_PATTERNS = [
+  /model.{0,30}is not supported/i,
+  /model.{0,30}not available/i,
+  /model.{0,30}does not exist/i,
+  /unsupported model/i,
+  /invalid model/i,
+  /model_not_found/i
+];
+
 export class BaseAgent {
   constructor(name, config, logger) {
     this.name = name;
@@ -24,4 +33,10 @@ export class BaseAgent {
     if (role === "reviewer") return false;
     return Boolean(this.config?.coder_options?.auto_approve);
   }
+
+  isModelNotSupportedError(result) {
+    const text = [result?.error, result?.output, result?.stderr, result?.stdout]
+      .filter(Boolean).join("\n");
+    return MODEL_NOT_SUPPORTED_PATTERNS.some(re => re.test(text));
+  }
 }

package/src/agents/claude-agent.js

@@ -35,6 +35,29 @@ function collectAssistantText(obj) {
     .map(block => block.text);
 }
 
+/**
+ * Extract usage metrics from stream-json/json NDJSON output.
+ * Looks for the "result" line which contains total_cost_usd,
+ * usage.input_tokens/output_tokens, and modelUsage.
+ * Returns an object with tokens_in, tokens_out, cost_usd, model or null if not found.
+ */
+export function extractUsageFromStreamJson(raw) {
+  const lines = (raw || "").split("\n").filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = tryParseJson(lines[i]);
+    if (!obj || obj.type !== "result") continue;
+
+    const tokens_in = obj.usage?.input_tokens ?? 0;
+    const tokens_out = obj.usage?.output_tokens ?? 0;
+    const cost_usd = obj.total_cost_usd ?? undefined;
+    const modelUsage = obj.modelUsage;
+    const model = modelUsage ? Object.keys(modelUsage)[0] || null : null;
+
+    return { tokens_in, tokens_out, cost_usd, model };
+  }
+  return null;
+}
+
 /**
  * Extract the final text result from stream-json NDJSON output.
  * Each line is a JSON object. We collect assistant text content from
@@ -135,8 +158,28 @@ const ALLOWED_TOOLS = [
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     const model = this.getRoleModel(role);
+    const result = await this._runTaskExec(task, model, role);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Claude model "${model}" not supported — retrying with agent default`);
+      return this._runTaskExec(task, null, role);
+    }
+    return result;
+  }
+
+  async reviewTask(task) {
+    const role = task.role || "reviewer";
+    const model = this.getRoleModel(role);
+    const result = await this._reviewTaskExec(task, model);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Claude model "${model}" not supported — retrying with agent default`);
+      return this._reviewTaskExec(task, null);
+    }
+    return result;
+  }
+
+  async _runTaskExec(task, model, role) {
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     if (model) args.push("--model", model);
 
     // Use stream-json when onOutput is provided to get real-time feedback
@@ -150,7 +193,8 @@ export class ClaudeAgent extends BaseAgent {
       }));
       const raw = pickOutput(res);
       const output = extractTextFromStreamJson(raw);
-      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+      const usage = extractUsageFromStreamJson(raw);
+      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
     }
 
     // Without streaming, use json output to get structured response via stderr
@@ -158,12 +202,12 @@ export class ClaudeAgent extends BaseAgent {
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts());
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
-    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+    const usage = extractUsageFromStreamJson(raw);
+    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
   }
 
-  async reviewTask(task) {
+  async _reviewTaskExec(task, model) {
     const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
-    const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,
@@ -171,6 +215,7 @@ export class ClaudeAgent extends BaseAgent {
       timeout: task.timeoutMs
     }));
     const raw = pickOutput(res);
-    return { ok: res.exitCode === 0, output: raw, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+    const usage = extractUsageFromStreamJson(raw);
+    return { ok: res.exitCode === 0, output: raw, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/codex-agent.js

@@ -2,27 +2,48 @@ import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract token usage from Codex CLI stdout.
+ * Codex prints "tokens used\n<number>" at the end, where number may have comma separators.
+ * Returns { tokens_out } with the total token count, or null if not found.
+ * Since Codex doesn't split input/output, we assign the total to tokens_out
+ * as a conservative estimate for cost calculation.
+ */
+export function extractCodexTokens(stdout) {
+  const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
+  if (!match) return null;
+  const total = Number(match[1].replace(/,/g, ""));
+  if (!Number.isFinite(total) || total <= 0) return null;
+  return { tokens_in: 0, tokens_out: total };
+}
+
 export class CodexAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["exec"];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    if (this.isAutoApproveEnabled(role)) args.push("--full-auto");
-    args.push("-");
-    const res = await runCommand(resolveBin("codex"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs,
-      input: task.prompt
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const result = await this._exec(task, model, role);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Codex model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, role);
+    }
+    return result;
   }
 
   async reviewTask(task) {
+    const role = task.role || "reviewer";
+    const model = this.getRoleModel(role);
+    const result = await this._exec(task, model, role);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Codex model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, role);
+    }
+    return result;
+  }
+
+  async _exec(task, model, role) {
     const args = ["exec"];
-    const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
+    if (role !== "reviewer" && this.isAutoApproveEnabled(role)) args.push("--full-auto");
     args.push("-");
     const res = await runCommand(resolveBin("codex"), args, {
       onOutput: task.onOutput,
@@ -30,6 +51,7 @@ export class CodexAgent extends BaseAgent {
       timeout: task.timeoutMs,
       input: task.prompt
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractCodexTokens(res.stdout);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/gemini-agent.js

@@ -5,21 +5,29 @@ import { resolveBin } from "./resolve-bin.js";
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("gemini"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const result = await this._exec(task, model, "run");
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, "run");
+    }
+    return result;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["-p", task.prompt, "--output-format", "json"];
     const model = this.getRoleModel(role);
+    const result = await this._exec(task, model, "review");
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, "review");
+    }
+    return result;
+  }
+
+  async _exec(task, model, mode) {
+    const args = ["-p", task.prompt];
+    if (mode === "review") args.push("--output-format", "json");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("gemini"), args, {
       onOutput: task.onOutput,

package/src/agents/model-registry.js

@@ -49,15 +49,16 @@ export function buildDefaultPricingTable() {
 }
 
 // Auto-register built-in models
+// Names must match what each CLI accepts as --model argument
 registerModel("claude", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
-registerModel("claude/sonnet", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
-registerModel("claude/opus", { provider: "anthropic", pricing: { input_per_million: 15, output_per_million: 75 } });
-registerModel("claude/haiku", { provider: "anthropic", pricing: { input_per_million: 0.25, output_per_million: 1.25 } });
+registerModel("sonnet", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
+registerModel("opus", { provider: "anthropic", pricing: { input_per_million: 15, output_per_million: 75 } });
+registerModel("haiku", { provider: "anthropic", pricing: { input_per_million: 0.25, output_per_million: 1.25 } });
 registerModel("codex", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
-registerModel("codex/o4-mini", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
-registerModel("codex/o3", { provider: "openai", pricing: { input_per_million: 10, output_per_million: 40 } });
+registerModel("o4-mini", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
+registerModel("o3", { provider: "openai", pricing: { input_per_million: 10, output_per_million: 40 } });
 registerModel("gemini", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
-registerModel("gemini/pro", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
-registerModel("gemini/flash", { provider: "google", pricing: { input_per_million: 0.075, output_per_million: 0.3 } });
+registerModel("gemini-2.5-pro", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
+registerModel("gemini-2.0-flash", { provider: "google", pricing: { input_per_million: 0.075, output_per_million: 0.3 } });
 registerModel("aider", { provider: "aider", pricing: { input_per_million: 3, output_per_million: 15 } });
 registerModel("opencode", { provider: "opencode", pricing: { input_per_million: 0, output_per_million: 0 } });

package/src/agents/opencode-agent.js

@@ -5,22 +5,29 @@ import { resolveBin } from "./resolve-bin.js";
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["run"];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    args.push(task.prompt);
-    const res = await runCommand(resolveBin("opencode"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const result = await this._exec(task, model, false);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`OpenCode model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, false);
+    }
+    return result;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["run", "--format", "json"];
     const model = this.getRoleModel(role);
+    const result = await this._exec(task, model, true);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`OpenCode model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, true);
+    }
+    return result;
+  }
+
+  async _exec(task, model, jsonFormat) {
+    const args = ["run"];
+    if (jsonFormat) args.push("--format", "json");
     if (model) args.push("--model", model);
     args.push(task.prompt);
     const res = await runCommand(resolveBin("opencode"), args, {

package/src/commands/doctor.js

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import os from "node:os";
 import path from "node:path";
 import { runCommand } from "../utils/process.js";
 import { exists } from "../utils/fs.js";
@@ -239,6 +241,101 @@ async function checkRuleFiles(config) {
   ];
 }
 
+/**
+ * Detect duplicate TOML table headers (e.g. [mcp_servers."karajan-mcp"] appearing twice).
+ * Full TOML parsing would require a dependency — this catches the most common config error.
+ */
+function findDuplicateTomlKeys(content) {
+  const tableHeaders = [];
+  const duplicates = [];
+  for (const line of content.split("\n")) {
+    const match = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (match) {
+      const key = match[1].trim();
+      if (tableHeaders.includes(key)) {
+        duplicates.push(key);
+      } else {
+        tableHeaders.push(key);
+      }
+    }
+  }
+  return duplicates;
+}
+
+async function checkAgentConfigs() {
+  const checks = [];
+  const home = os.homedir();
+
+  // Claude: ~/.claude.json
+  const claudeJsonPath = path.join(home, ".claude.json");
+  try {
+    const raw = await fs.readFile(claudeJsonPath, "utf8");
+    JSON.parse(raw);
+    checks.push({ name: "agent-config:claude", label: "Agent config: claude (~/.claude.json)", ok: true, detail: "Valid JSON", fix: null });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // File doesn't exist — not an error, Claude may not be configured
+    } else {
+      checks.push({
+        name: "agent-config:claude",
+        label: "Agent config: claude (~/.claude.json)",
+        ok: false,
+        detail: `Invalid JSON: ${err.message.split("\n")[0]}`,
+        fix: "Fix the JSON syntax in ~/.claude.json. Common issues: trailing commas, missing quotes."
+      });
+    }
+  }
+
+  // Codex: ~/.codex/config.toml
+  const codexTomlPath = path.join(home, ".codex", "config.toml");
+  try {
+    const raw = await fs.readFile(codexTomlPath, "utf8");
+    const duplicates = findDuplicateTomlKeys(raw);
+    if (duplicates.length > 0) {
+      checks.push({
+        name: "agent-config:codex",
+        label: "Agent config: codex (~/.codex/config.toml)",
+        ok: false,
+        detail: `Duplicate TOML keys: ${duplicates.join(", ")}`,
+        fix: `Remove duplicate entries in ~/.codex/config.toml: ${duplicates.join(", ")}`
+      });
+    } else {
+      checks.push({ name: "agent-config:codex", label: "Agent config: codex (~/.codex/config.toml)", ok: true, detail: "Valid TOML (no duplicate keys)", fix: null });
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      checks.push({
+        name: "agent-config:codex",
+        label: "Agent config: codex (~/.codex/config.toml)",
+        ok: false,
+        detail: `Cannot read: ${err.message.split("\n")[0]}`,
+        fix: "Check file permissions on ~/.codex/config.toml"
+      });
+    }
+  }
+
+  // KJ config: ~/.karajan/kj.config.yml (validate YAML)
+  const kjConfigPath = getConfigPath();
+  try {
+    const raw = await fs.readFile(kjConfigPath, "utf8");
+    const yaml = await import("js-yaml");
+    yaml.default.load(raw);
+    checks.push({ name: "agent-config:karajan", label: "Agent config: karajan (kj.config.yml)", ok: true, detail: "Valid YAML", fix: null });
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      checks.push({
+        name: "agent-config:karajan",
+        label: "Agent config: karajan (kj.config.yml)",
+        ok: false,
+        detail: `Invalid YAML: ${err.message.split("\n")[0]}`,
+        fix: `Fix YAML syntax in ${kjConfigPath}. Run 'kj init' to regenerate if needed.`
+      });
+    }
+  }
+
+  return checks;
+}
+
 export async function runChecks({ config }) {
   const checks = [];
 
@@ -260,6 +357,7 @@ export async function runChecks({ config }) {
     checks.push(...await checkBecariaInfra(config));
   }
 
+  checks.push(...await checkAgentConfigs());
   checks.push(...await checkRuleFiles(config));
   checks.push(await checkRtk());