karajan-code 1.3.0 → 1.5.0

package/README.md

@@ -36,7 +36,10 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Review profiles** — standard, strict, relaxed, paranoid
 - **Budget tracking** — per-session token and cost monitoring with `--trace`
 - **Git automation** — auto-commit, auto-push, auto-PR after approval
-- **Session management** — pause/resume with fail-fast detection
+- **Session management** — pause/resume with fail-fast detection and automatic cleanup of expired sessions
+- **Plugin system** — extend with custom agents via `.karajan/plugins/`
+- **Smart model selection** — auto-selects optimal model per role based on triage complexity (lighter models for trivial tasks, powerful models for complex ones)
+- **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -193,6 +196,8 @@ kj run "Fix the login bug" [options]
 | `--auto-pr` | Create PR after push |
 | `--no-auto-rebase` | Disable auto-rebase before push |
 | `--branch-prefix <prefix>` | Branch naming prefix (default: `feat/`) |
+| `--smart-models` | Enable smart model selection based on triage complexity |
+| `--no-smart-models` | Disable smart model selection |
 | `--no-sonar` | Skip SonarQube analysis |
 | `--pg-task <cardId>` | Planning Game card ID for task context |
 | `--pg-project <projectId>` | Planning Game project ID |
@@ -352,6 +357,16 @@ budget:
   currency: usd                # usd | eur
   exchange_rate_eur: 0.92
 
+# Smart model selection (requires --enable-triage)
+model_selection:
+  enabled: true                # Auto-select models based on triage complexity
+  tiers:                       # Override default tier map per provider
+    claude:
+      simple: claude/sonnet    # Use sonnet even for simple tasks
+  role_overrides:              # Override level mapping per role
+    reviewer:
+      trivial: medium          # Reviewer always at least medium tier
+
 # Output
 output:
   report_dir: ./.reviews
@@ -428,7 +443,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 761+ tests with Vitest
+npm test              # Run 964+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```
@@ -439,6 +454,7 @@ npm run validate      # Lint + test
 
 ## Links
 
+- [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))
 - [Changelog](CHANGELOG.md)
 - [Security Policy](SECURITY.md)
 - [License (AGPL-3.0)](LICENSE)

package/docs/README.es.md

@@ -36,7 +36,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
 - **Tracking de presupuesto** — monitorizacion de tokens y costes por sesion con `--trace`
 - **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
-- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast
+- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast y limpieza automatica de sesiones expiradas
+- **Sistema de plugins** — extiende con agentes custom via `.karajan/plugins/`
+- **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -227,7 +229,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 761+ tests con Vitest
+npm test              # Ejecutar 899+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```
@@ -238,6 +240,7 @@ npm run validate      # Lint + test
 
 ## Enlaces
 
+- [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
 - [Licencia (AGPL-3.0)](../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli.js

@@ -24,7 +24,7 @@ async function withConfig(commandName, flags, fn) {
 }
 
 const program = new Command();
-program.name("kj").description("Karajan Code CLI").version("1.2.1");
+program.name("kj").description("Karajan Code CLI").version("1.5.0");
 
 program
   .command("init")
@@ -71,6 +71,7 @@ program
   .option("--max-total-minutes <n>")
   .option("--base-branch <name>")
   .option("--base-ref <ref>")
+  .option("--coder-fallback <name>")
   .option("--reviewer-fallback <name>")
   .option("--reviewer-retries <n>")
   .option("--auto-commit")
@@ -82,6 +83,8 @@ program
   .option("--no-sonar")
   .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
   .option("--pg-project <projectId>", "Planning Game project ID")
+  .option("--smart-models", "Enable smart model selection based on triage complexity")
+  .option("--no-smart-models", "Disable smart model selection")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
   .action(async (task, flags) => {

package/src/config.js

@@ -33,7 +33,7 @@ const DEFAULTS = {
   review_rules: "./review-rules.md",
   coder_rules: "./coder-rules.md",
   base_branch: "main",
-  coder_options: { model: null, auto_approve: true },
+  coder_options: { model: null, auto_approve: true, fallback_coder: null },
   reviewer_options: {
     output_format: "json",
     require_schema: true,
@@ -106,6 +106,11 @@ const DEFAULTS = {
     currency: "usd",
     exchange_rate_eur: 0.92
   },
+  model_selection: {
+    enabled: true,
+    tiers: {},
+    role_overrides: {}
+  },
   session: {
     max_iteration_minutes: 15,
     max_total_minutes: 120,
@@ -240,6 +245,7 @@ export function applyRunOverrides(config, flags) {
   if (flags.maxIterationMinutes) out.session.max_iteration_minutes = Number(flags.maxIterationMinutes);
   if (flags.maxTotalMinutes) out.session.max_total_minutes = Number(flags.maxTotalMinutes);
   if (flags.baseBranch) out.base_branch = flags.baseBranch;
+  if (flags.coderFallback) out.coder_options.fallback_coder = flags.coderFallback;
   if (flags.reviewerFallback) out.reviewer_options.fallback_reviewer = flags.reviewerFallback;
   if (flags.reviewerRetries !== undefined) out.reviewer_options.retries = Number(flags.reviewerRetries);
   if (flags.autoCommit !== undefined) out.git.auto_commit = Boolean(flags.autoCommit);
@@ -259,6 +265,9 @@ export function applyRunOverrides(config, flags) {
   out.planning_game = out.planning_game || {};
   if (flags.pgTask) out.planning_game.enabled = true;
   if (flags.pgProject) out.planning_game.project_id = flags.pgProject;
+  out.model_selection = out.model_selection || { enabled: true, tiers: {}, role_overrides: {} };
+  if (flags.smartModels === true) out.model_selection.enabled = true;
+  if (flags.smartModels === false || flags.noSmartModels === true) out.model_selection.enabled = false;
   return out;
 }
 

package/src/mcp/run-kj.js

@@ -49,6 +49,8 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.autoPr, "--auto-pr", args);
   if (options.autoRebase === false) args.push("--no-auto-rebase");
   normalizeBoolFlag(options.noSonar, "--no-sonar", args);
+  if (options.smartModels === true) args.push("--smart-models");
+  if (options.smartModels === false) args.push("--no-smart-models");
   addOptionalValue(args, "--pg-task", options.pgTask);
   addOptionalValue(args, "--pg-project", options.pgProject);
 

package/src/mcp/tools.js

@@ -85,6 +85,7 @@ export const tools = [
         autoPr: { type: "boolean" },
         autoRebase: { type: "boolean" },
         branchPrefix: { type: "string" },
+        smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
         noSonar: { type: "boolean" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },

package/src/orchestrator/agent-fallback.js

@@ -0,0 +1,83 @@
+import { createAgent } from "../agents/index.js";
+import { addCheckpoint } from "../session-store.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
+
+/**
+ * Run a coder-like role with fallback on rate limit.
+ * Tries the primary agent first. If it fails with a rate limit,
+ * switches to the fallback agent (if configured).
+ * Non-rate-limit failures stop immediately (no fallback).
+ *
+ * Returns { execResult, attempts, allRateLimited }
+ */
+export async function runCoderWithFallback({
+  coderName,
+  fallbackCoder,
+  config,
+  logger,
+  emitter,
+  RoleClass,
+  roleInput,
+  session,
+  iteration,
+  onAttemptResult
+}) {
+  const candidates = [coderName];
+  if (fallbackCoder && fallbackCoder !== coderName) {
+    candidates.push(fallbackCoder);
+  }
+
+  const attempts = [];
+  let allRateLimited = true;
+
+  for (const name of candidates) {
+    const agentConfig = {
+      ...config,
+      roles: { ...config.roles, coder: { ...config.roles?.coder, provider: name } }
+    };
+
+    const role = new RoleClass({ config: agentConfig, logger, emitter, createAgentFn: createAgent });
+    await role.init();
+
+    const execResult = await role.execute(roleInput);
+
+    if (onAttemptResult) {
+      await onAttemptResult({ coder: name, result: execResult.result });
+    }
+
+    const rateLimited = !execResult.ok && detectRateLimit({
+      stderr: execResult.result?.error || "",
+      stdout: execResult.result?.output || ""
+    }).isRateLimit;
+
+    attempts.push({
+      coder: name,
+      ok: execResult.ok,
+      rateLimited,
+      result: execResult.result,
+      execResult
+    });
+
+    await addCheckpoint(session, {
+      stage: "coder-attempt",
+      iteration,
+      coder: name,
+      ok: execResult.ok,
+      rateLimited
+    });
+
+    if (execResult.ok) {
+      return { execResult, attempts, allRateLimited: false };
+    }
+
+    // Only fallback on rate limit errors
+    if (!rateLimited) {
+      allRateLimited = false;
+      return { execResult: null, attempts, allRateLimited: false };
+    }
+
+    logger.warn(`Agent ${name} hit rate limit, trying fallback...`);
+  }
+
+  return { execResult: null, attempts, allRateLimited };
+}

package/src/orchestrator/iteration-stages.js

@@ -1,4 +1,5 @@
 import { createAgent } from "../agents/index.js";
+import { CoderRole } from "../roles/coder-role.js";
 import { RefactorerRole } from "../roles/refactorer-role.js";
 import { SonarRole } from "../roles/sonar-role.js";
 import { addCheckpoint, markSessionStatus, saveSession, pauseSession } from "../session-store.js";
@@ -7,7 +8,9 @@ import { evaluateTddPolicy } from "../review/tdd-policy.js";
 import { validateReviewResult } from "../review/schema.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { runReviewerWithFallback } from "./reviewer-fallback.js";
+import { runCoderWithFallback } from "./agent-fallback.js";
 import { invokeSolomon } from "./solomon-escalation.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration }) {
   logger.setContext({ iteration, stage: "coder" });
@@ -35,8 +38,70 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
 
   if (!coderExecResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: coderExecResult.result?.error || "",
+      stdout: coderExecResult.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      // Try fallback agent if configured
+      const fallbackCoder = config.coder_options?.fallback_coder;
+      if (fallbackCoder && fallbackCoder !== coderRole.provider) {
+        logger.warn(`Coder ${coderRole.provider} hit rate limit, falling back to ${fallbackCoder}`);
+        emitProgress(
+          emitter,
+          makeEvent("coder:fallback", { ...eventBase, stage: "coder" }, {
+            message: `Coder ${coderRole.provider} rate-limited, switching to ${fallbackCoder}`,
+            detail: { primary: coderRole.provider, fallback: fallbackCoder }
+          })
+        );
+
+        const fallbackResult = await runCoderWithFallback({
+          coderName: fallbackCoder,
+          fallbackCoder: null,
+          config,
+          logger,
+          emitter,
+          RoleClass: CoderRole,
+          roleInput: { task: plannedTask, reviewerFeedback: session.last_reviewer_feedback, sonarSummary: session.last_sonar_summary, onOutput: coderOnOutput },
+          session,
+          iteration,
+          onAttemptResult: ({ coder, result }) => {
+            trackBudget({ role: "coder", provider: coder, model: coderRole.model, result, duration_ms: Date.now() - coderStart });
+          }
+        });
+
+        if (fallbackResult.execResult?.ok) {
+          await addCheckpoint(session, { stage: "coder", iteration, note: `Coder completed via fallback (${fallbackCoder})` });
+          emitProgress(
+            emitter,
+            makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
+              message: `Coder completed (fallback: ${fallbackCoder})`
+            })
+          );
+          return;
+        }
+      }
+
+      // No fallback or fallback also failed — pause
+      const question = `Agent ${coderRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "coder", reason: "rate_limit", agent: coderRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("coder:rate_limit", { ...eventBase, stage: "coder" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: coderRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
@@ -71,8 +136,30 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
   const refResult = await refRole.execute(plannedTask);
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
   if (!refResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = refResult.result?.error || refResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: refResult.result?.error || "",
+      stdout: refResult.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      const question = `Agent ${refactorerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "refactorer", reason: "rate_limit", agent: refactorerRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("refactorer:rate_limit", { ...eventBase, stage: "refactorer" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: refactorerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("refactorer:end", { ...eventBase, stage: "refactorer" }, {
@@ -318,12 +405,35 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
   });
 
   if (!reviewerExec.execResult || !reviewerExec.execResult.ok) {
-    await markSessionStatus(session, "failed");
     const lastAttempt = reviewerExec.attempts.at(-1);
     const details =
       lastAttempt?.result?.error ||
       lastAttempt?.execResult?.summary ||
       `reviewer=${lastAttempt?.reviewer || "unknown"}`;
+
+    const rateLimitCheck = detectRateLimit({
+      stderr: lastAttempt?.result?.error || "",
+      stdout: lastAttempt?.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      const question = `Reviewer ${reviewerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
+      await pauseSession(session, {
+        question,
+        context: { iteration, stage: "reviewer", reason: "rate_limit", agent: reviewerRole.provider, detail: rateLimitCheck.message }
+      });
+      emitProgress(
+        emitter,
+        makeEvent("reviewer:rate_limit", { ...eventBase, stage: "reviewer" }, {
+          status: "paused",
+          message: question,
+          detail: { agent: reviewerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
+        })
+      );
+      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {

package/src/orchestrator/pre-loop-stages.js

@@ -5,6 +5,7 @@ import { createAgent } from "../agents/index.js";
 import { addCheckpoint, markSessionStatus } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { parsePlannerOutput } from "../prompts/planner.js";
+import { selectModelsForRoles } from "../utils/model-selector.js";
 
 export async function runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   logger.setContext({ iteration: 0, stage: "triage" });
@@ -47,6 +48,31 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     reasoning: triageOutput.result?.reasoning || null
   };
 
+  let modelSelection = null;
+  if (triageOutput.ok && config?.model_selection?.enabled) {
+    const level = triageOutput.result?.level;
+    if (level) {
+      const { modelOverrides, reasoning } = selectModelsForRoles({ level, config });
+      for (const [role, model] of Object.entries(modelOverrides)) {
+        if (config.roles?.[role] && !config.roles[role].model) {
+          config.roles[role].model = model;
+        }
+      }
+      modelSelection = { modelOverrides, reasoning };
+      emitProgress(
+        emitter,
+        makeEvent("model-selection:applied", { ...eventBase, stage: "triage" }, {
+          message: "Smart model selection applied",
+          detail: modelSelection
+        })
+      );
+    }
+  }
+
+  if (modelSelection) {
+    stageResult.modelSelection = modelSelection;
+  }
+
   emitProgress(
     emitter,
     makeEvent("triage:end", { ...eventBase, stage: "triage" }, {

package/src/orchestrator.js

@@ -255,11 +255,17 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     logger.info(`Iteration ${i}/${config.max_iterations}`);
 
     // --- Coder ---
-    await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    if (coderResult?.action === "pause") {
+      return coderResult.result;
+    }
 
     // --- Refactorer ---
     if (refactorerEnabled) {
-      await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      if (refResult?.action === "pause") {
+        return refResult.result;
+      }
     }
 
     // --- TDD Policy ---
@@ -302,6 +308,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
         iteration: i, reviewRules, task, repeatDetector, budgetSummary
       });
+      if (reviewerResult.action === "pause") {
+        return reviewerResult.result;
+      }
       review = reviewerResult.review;
       if (reviewerResult.stalled) {
         return reviewerResult.stalledResult;

package/src/utils/model-selector.js

@@ -0,0 +1,107 @@
+const DEFAULT_MODEL_TIERS = {
+  claude: { trivial: "claude/haiku", simple: "claude/haiku", medium: "claude/sonnet", complex: "claude/opus" },
+  codex: { trivial: "codex/o4-mini", simple: "codex/o4-mini", medium: "codex/o4-mini", complex: "codex/o3" },
+  gemini: { trivial: "gemini/flash", simple: "gemini/flash", medium: "gemini/pro", complex: "gemini/pro" },
+  aider: { trivial: null, simple: null, medium: null, complex: null }
+};
+
+const DEFAULT_ROLE_OVERRIDES = {
+  reviewer: { trivial: "medium", simple: "medium" },
+  triage: { medium: "simple", complex: "simple" }
+};
+
+const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
+
+export function getDefaultModelTiers() {
+  return JSON.parse(JSON.stringify(DEFAULT_MODEL_TIERS));
+}
+
+export function getDefaultRoleOverrides() {
+  return JSON.parse(JSON.stringify(DEFAULT_ROLE_OVERRIDES));
+}
+
+export function resolveModelForRole({ role, provider, level, tierMap, roleOverrides }) {
+  if (!provider || !level || !VALID_LEVELS.has(level)) return null;
+
+  const tiers = tierMap || DEFAULT_MODEL_TIERS;
+  const providerTiers = tiers[provider];
+  if (!providerTiers) return null;
+
+  const overrides = roleOverrides || DEFAULT_ROLE_OVERRIDES;
+  const roleOvr = overrides[role];
+
+  let effectiveLevel = level;
+  if (roleOvr && roleOvr[level]) {
+    const mappedLevel = roleOvr[level];
+    if (VALID_LEVELS.has(mappedLevel)) {
+      effectiveLevel = mappedLevel;
+    }
+  }
+
+  return providerTiers[effectiveLevel] || null;
+}
+
+export function selectModelsForRoles({ level, config, roles }) {
+  if (!level || !VALID_LEVELS.has(level)) {
+    return { modelOverrides: {}, reasoning: "No valid triage level provided" };
+  }
+
+  const modelSelection = config?.model_selection || {};
+  const userTiers = modelSelection.tiers || {};
+  const userRoleOverrides = modelSelection.role_overrides || {};
+
+  const mergedTiers = { ...getDefaultModelTiers() };
+  for (const [provider, levels] of Object.entries(userTiers)) {
+    mergedTiers[provider] = { ...(mergedTiers[provider] || {}), ...levels };
+  }
+
+  const mergedRoleOverrides = { ...getDefaultRoleOverrides() };
+  for (const [role, levels] of Object.entries(userRoleOverrides)) {
+    mergedRoleOverrides[role] = { ...(mergedRoleOverrides[role] || {}), ...levels };
+  }
+
+  const allRoles = roles || Object.keys(config?.roles || {});
+  const modelOverrides = {};
+  const details = [];
+
+  for (const role of allRoles) {
+    const roleConfig = config?.roles?.[role];
+    if (!roleConfig) continue;
+
+    if (roleConfig.model) {
+      details.push(`${role}: skipped (explicit model "${roleConfig.model}")`);
+      continue;
+    }
+
+    if (roleConfig.disabled) {
+      details.push(`${role}: skipped (disabled)`);
+      continue;
+    }
+
+    const provider = roleConfig.provider;
+    if (!provider) {
+      details.push(`${role}: skipped (no provider)`);
+      continue;
+    }
+
+    const model = resolveModelForRole({
+      role,
+      provider,
+      level,
+      tierMap: mergedTiers,
+      roleOverrides: mergedRoleOverrides
+    });
+
+    if (model) {
+      modelOverrides[role] = model;
+      details.push(`${role}: ${model} (level=${level}, provider=${provider})`);
+    } else {
+      details.push(`${role}: no model for provider "${provider}"`);
+    }
+  }
+
+  return {
+    modelOverrides,
+    reasoning: `Smart model selection (level=${level}): ${details.join("; ")}`
+  };
+}

package/src/utils/rate-limit-detector.js

@@ -0,0 +1,43 @@
+/**
+ * Detects rate limit / usage cap messages from CLI agent output.
+ * Returns { isRateLimit, agent, message } where agent is the best guess
+ * of which CLI triggered it (or "unknown").
+ */
+
+const RATE_LIMIT_PATTERNS = [
+  // Claude CLI
+  { pattern: /usage limit/i, agent: "claude" },
+  { pattern: /plan's usage limit/i, agent: "claude" },
+  { pattern: /Claude Pro usage limit/i, agent: "claude" },
+
+  // OpenAI / Codex CLI
+  { pattern: /exceeded your current quota/i, agent: "codex" },
+
+  // Gemini CLI
+  { pattern: /resource exhausted/i, agent: "gemini" },
+  { pattern: /quota exceeded/i, agent: "gemini" },
+
+  // Generic (match any agent)
+  { pattern: /rate limit/i, agent: "unknown" },
+  { pattern: /token limit reached/i, agent: "unknown" },
+  { pattern: /\b429\b/, agent: "unknown" },
+  { pattern: /too many requests/i, agent: "unknown" },
+  { pattern: /throttl/i, agent: "unknown" },
+];
+
+export function detectRateLimit({ stderr = "", stdout = "" }) {
+  const combined = `${stderr}\n${stdout}`;
+
+  for (const { pattern, agent } of RATE_LIMIT_PATTERNS) {
+    if (pattern.test(combined)) {
+      const matchedLine = combined.split("\n").find((l) => pattern.test(l)) || combined.trim();
+      return {
+        isRateLimit: true,
+        agent,
+        message: matchedLine.trim()
+      };
+    }
+  }
+
+  return { isRateLimit: false, agent: "", message: "" };
+}