karajan-code 4.32.0 → 4.34.0

package/package.json

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

package/src/agents/aider-agent.js

@@ -45,23 +45,13 @@ export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     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;
+    return this._exec(task, model);
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
     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;
+    return this._exec(task, model);
   }
 
   async _exec(task, model) {

package/src/agents/base-agent.js

@@ -13,15 +13,8 @@
 import { defaultEnvironment } from "../infrastructure/environment.js";
 import { buildAgentEnv } from "../utils/role-env.js";
 import { isModelCompatible } from "../config/role-resolver.js";
+import { deadModelRecord } from "./dead-models.js";
 
-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 {
   /**
@@ -108,6 +101,14 @@ export class BaseAgent {
       this.logger?.warn?.(`model "${roleModel}" belongs to another family — dropping it for ${this.name} (role ${role})`);
       return null;
     }
+    // KJC-TSK-0827: a model kj has watched this provider retire is not worth
+    // a call. The pin stays the user's to change, so the warning names the
+    // exact line instead of kj editing their config behind their back.
+    const dead = roleModel ? deadModelRecord(this.name, roleModel) : null;
+    if (dead) {
+      this.logger?.warn?.(`model "${roleModel}" was retired by ${this.name} (seen ${dead.at}) — using the provider default. Change it with roles.${role}.model in kj.config.yml`);
+      return null;
+    }
     return roleModel;
   }
 
@@ -119,16 +120,4 @@ export class BaseAgent {
     if (role === "reviewer") return false;
     return Boolean(this.config?.coder_options?.auto_approve);
   }
-
-  /**
-   * Heuristic: does the agent's error look like "model not supported"?
-   * Used by the retry/fallback path.
-   * @param {Partial<AgentResult>} result
-   * @returns {boolean}
-   */
-  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

@@ -343,23 +343,13 @@ export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     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;
+    return this._runTaskExec(task, model, role);
   }
 
   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;
+    return this._reviewTaskExec(task, model);
   }
 
   async _runTaskExec(task, model, _role) {

package/src/agents/codex-agent.js

@@ -57,23 +57,13 @@ export class CodexAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     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;
+    return this._exec(task, model, role);
   }
 
   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;
+    return this._exec(task, model, role);
   }
 
   async _exec(task, model, role) {

package/src/agents/dead-models.js

@@ -0,0 +1,74 @@
+/**
+ * Models the provider has retired, remembered (KJC-TSK-0827).
+ *
+ * KJC-TSK-0859 made a dead model recoverable: the chain moves on. What it does
+ * not do is stop the SECOND run from paying for the same corpse, and the third,
+ * and every one after, because the dead model is still what the config pins.
+ * The field case: codex retired gpt-5.4 and gpt-5.4-mini on 2026-09-09 and the
+ * reviewer kept calling a dead model on every single run.
+ *
+ * So kj remembers, per account (this is a global fact, not a project one), and
+ * skips a model it has watched die. Two deliberate limits:
+ *
+ *  - kj NEVER edits the user's declaration. The pin is theirs; kj says which
+ *    line to change and keeps working meanwhile. (The card asked for the
+ *    config to be rewritten; that part is the user's call, and it is asked in
+ *    the card rather than decided here.)
+ *  - an entry expires. A wrong verdict must heal by itself, and a provider
+ *    bringing a model back must not need a cache flush nobody would think of.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getKarajanHome } from "../utils/paths.js";
+
+/** A month is long enough to stop paying for it, short enough to be wrong. */
+export const DEAD_MODEL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+const storePath = () => join(getKarajanHome(), "dead-models.json");
+const keyOf = (provider, model) => `${provider}::${model}`;
+
+function load() {
+  const file = storePath();
+  if (!existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    // A corrupt store is not a reason to fail a run: kj forgets and relearns.
+    return {};
+  }
+}
+
+/** @returns {boolean} true when the record was written. */
+export function recordDeadModel({ provider, model, reason = null, now = Date.now() }) {
+  if (!provider || !model) return false;
+  const store = load();
+  store[keyOf(provider, model)] = { provider, model, reason, at: new Date(now).toISOString(), expiresAt: now + DEAD_MODEL_TTL_MS };
+  try {
+    const file = storePath();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(store, null, 2));
+    return true;
+  } catch {
+    // Remembering is an optimisation, never a gate: if the home is read-only
+    // the run still works, it just pays the dead call again.
+    return false;
+  }
+}
+
+/** @returns {null|{provider: string, model: string, reason: string|null, at: string}} */
+export function deadModelRecord(provider, model, now = Date.now()) {
+  if (!provider || !model) return null;
+  const hit = load()[keyOf(provider, model)];
+  if (!hit) return null;
+  if (!hit.expiresAt || hit.expiresAt <= now) return null; // expired: try it again
+  return hit;
+}
+
+/** Live entries only, newest first — for `kj doctor` and friends. */
+export function listDeadModels(now = Date.now()) {
+  return Object.values(load())
+    .filter((e) => e.expiresAt > now)
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}

package/src/agents/gemini-agent.js

@@ -44,23 +44,13 @@ export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     const model = this.getRoleModel(role);
-    const result = await this._exec(task, model, "run");
-    if (!result.ok && model && this.isModelNotSupportedError(result)) {
-      this.logger?.warn(`${this.cliBin} model "${model}" not supported — retrying with agent default`);
-      return this._exec(task, null, "run");
-    }
-    return result;
+    return this._exec(task, model, "run");
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
     const model = this.getRoleModel(role);
-    const result = await this._exec(task, model, "review");
-    if (!result.ok && model && this.isModelNotSupportedError(result)) {
-      this.logger?.warn(`${this.cliBin} model "${model}" not supported — retrying with agent default`);
-      return this._exec(task, null, "review");
-    }
-    return result;
+    return this._exec(task, model, "review");
   }
 
   async _exec(task, model, mode) {

package/src/agents/model-errors.js

@@ -0,0 +1,35 @@
+/**
+ * "That model is gone" — one definition, two readers (KJC-TSK-0859).
+ *
+ * A dead model announced itself in two unrelated places: each agent matched
+ * these patterns privately to retry with its provider default, and the brain's
+ * error classifier had no idea the class existed, so it filed the failure as
+ * UNKNOWN_FATAL and aborted the run. Same event, two verdicts.
+ *
+ * The patterns live here so the agent and the brain read the SAME definition,
+ * and a model that a provider retired becomes a reason to move down the
+ * declared chain instead of a reason to stop.
+ */
+export 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,
+];
+
+/** @param {string} text @returns {boolean} */
+export function isModelUnavailableText(text) {
+  if (!text) return false;
+  return MODEL_NOT_SUPPORTED_PATTERNS.some((re) => re.test(text));
+}
+
+/** The matched sentence, for a message that names what died. */
+export function pickModelUnavailableMessage(text) {
+  for (const re of MODEL_NOT_SUPPORTED_PATTERNS) {
+    const line = String(text).split("\n").find((l) => re.test(l));
+    if (line) return line.trim();
+  }
+  return null;
+}

package/src/agents/opencode-agent.js

@@ -37,23 +37,13 @@ export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     const model = this.getRoleModel(role);
-    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;
+    return this._exec(task, model, false);
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
     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;
+    return this._exec(task, model, true);
   }
 
   async _exec(task, model, jsonFormat) {

package/src/brain/agent-error-classifier.js

@@ -13,6 +13,7 @@
 //   - NETWORK_TIMEOUT por ECONN*/socket hang up sin cooldown.
 
 import { parseCooldown } from "../utils/rate-limit-detector.js";
+import { isModelUnavailableText, pickModelUnavailableMessage } from "../agents/model-errors.js";
 
 export const ERROR_CLASS = Object.freeze({
   RATE_LIMIT_SHORT: "RATE_LIMIT_SHORT",
@@ -21,6 +22,10 @@ export const ERROR_CLASS = Object.freeze({
   // 15-jun-2026. Cuando llegues al cap mensual, el reset es 1-mes —
   // muy distinto del daily de Claude Pro. Esta clase distingue ambos.
   QUOTA_EXHAUSTED_MONTHLY: "QUOTA_EXHAUSTED_MONTHLY",
+  // KJC-TSK-0859: un modelo que el proveedor retiró no es un error fatal ni
+  // un problema de cuota — es motivo para tomar el siguiente eslabón de la
+  // cadena declarada. No tiene cooldown: esperar no lo va a resucitar.
+  MODEL_UNAVAILABLE: "MODEL_UNAVAILABLE",
   API_DOWN: "API_DOWN",
   AUTH_FAILED: "AUTH_FAILED",
   NETWORK_TIMEOUT: "NETWORK_TIMEOUT",
@@ -80,7 +85,20 @@ export function classifyAgentError({ provider = "unknown", stdout = "", stderr =
     return { ...base, class: ERROR_CLASS.SILENCED, message: pickMessage(combined, SILENCED_PATTERNS) || "Agent silenciado por timeout", recoverable: true };
   }
 
-  // 3. RATE_LIMIT con cooldown. Thresholds:
+  // 3. MODEL_UNAVAILABLE: el modelo fijado ya no existe para esta cuenta.
+  //    Antes caía en UNKNOWN_FATAL y abortaba el run: el agente lo detectaba
+  //    por su cuenta y reintentaba con su default, pero el brain no se
+  //    enteraba. Va antes del rate limit porque no tiene cooldown alguno.
+  if (isModelUnavailableText(combined)) {
+    return {
+      ...base,
+      class: ERROR_CLASS.MODEL_UNAVAILABLE,
+      message: pickModelUnavailableMessage(combined) || "el modelo configurado ya no está disponible",
+      recoverable: true,
+    };
+  }
+
+  // 4. RATE_LIMIT con cooldown. Thresholds:
   //    cooldown > 7d  → MONTHLY (Anthropic Agent SDK $200/mes desde jun-2026)
   //    cooldown > 1h  → DAILY (Claude Pro daily, OpenAI rate-limit-by-day)
   //    cooldown <= 1h → SHORT (rate limit transitorio)

package/src/brain/one-shot-policy.js

@@ -0,0 +1,26 @@
+/**
+ * Recovery for a command that runs once (KJC-BUG-0194).
+ *
+ * The pipeline can afford to wait: a quota wall means hibernate, persist the
+ * session and resume when the window reopens. A one-shot command cannot.
+ * Sleeping five hours inside `kj code` or `kj audit` is worse than the failure
+ * it is handling, and an MCP caller gets no answer at all.
+ *
+ * So here a quota wall takes the next declared candidate AT ONCE, and with
+ * none left it stops and says what it tried. Everything else keeps the
+ * pipeline's behaviour: a retired model still moves on immediately, provider
+ * 500s still back off, an auth failure still aborts.
+ */
+import { DEFAULT_RECOVERY_POLICY } from "./with-brain-recovery.js";
+import { ERROR_CLASS } from "./agent-error-classifier.js";
+
+const takeTheNextOne = { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true };
+
+export const ONE_SHOT_POLICY = Object.freeze({
+  ...DEFAULT_RECOVERY_POLICY,
+  classes: {
+    ...DEFAULT_RECOVERY_POLICY.classes,
+    [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: takeTheNextOne,
+    [ERROR_CLASS.QUOTA_EXHAUSTED_MONTHLY]: takeTheNextOne,
+  },
+});

package/src/brain/role-fallback-chain.js

@@ -0,0 +1,100 @@
+/**
+ * The declared chain, finally connected (KJC-TSK-0859).
+ *
+ * `roles.<role>.fallback` has been in the config schema since KJC-TSK-0415,
+ * recursive and carrying a `model`, and `withBrainRecovery` has always known
+ * how to walk it. Nothing ever built it: of the call sites that recover an
+ * agent run, not one passed `fallback`. A wire laid and never connected.
+ *
+ * This builds it from config, one instantiated agent per link, so the user's
+ * declared order is what runs. Each link may change the model, the provider or
+ * both: a chain within one provider is the case the card asks for, and
+ * crossing providers falls out for free.
+ */
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+
+/** A chain longer than this is a config smell, not a plan. */
+export const MAX_CHAIN_LINKS = 5;
+
+/** The config a link runs with: same project, this link's provider and model. */
+export function withRoleModel(config, role, provider, model) {
+  return {
+    ...config,
+    roles: { ...config?.roles, [role]: { ...config?.roles?.[role], provider, model: model ?? null } },
+  };
+}
+
+const keyOf = (provider, model) => `${provider}::${model ?? ""}`;
+
+/**
+ * @param {{config: object, role: string, agentMethod?: string,
+ *   createAgentFn?: Function, logger?: object}} args
+ * @returns {null|{agent: object, provider: string, model: string|null,
+ *   maxWaitHours: number|undefined, fallback: object|null}}
+ */
+export function buildRoleFallbackChain({ config, role, agentMethod = "runTask", createAgentFn = defaultCreateAgent, logger = null }) {
+  const primary = resolveRole(config, role);
+  // The primary is already in play: a link repeating it would retry the same
+  // thing and look like progress.
+  const seen = new Set([keyOf(primary.provider, primary.model)]);
+
+  const build = (link, depth) => {
+    if (!link?.provider) return null;
+    if (depth > MAX_CHAIN_LINKS) {
+      logger?.warn?.(`[brain] ${role}: fallback chain longer than ${MAX_CHAIN_LINKS} links — the rest is ignored`);
+      return null;
+    }
+    const key = keyOf(link.provider, link.model);
+    if (seen.has(key)) {
+      logger?.warn?.(`[brain] ${role}: fallback link ${key} repeats one already in the chain — skipped`);
+      return build(link.fallback, depth + 1);
+    }
+    seen.add(key);
+    let agent;
+    try {
+      agent = createAgentFn(link.provider, withRoleModel(config, role, link.provider, link.model), logger);
+    } catch (err) {
+      // An unknown provider in the chain is the user's typo, not a reason to
+      // lose the links behind it. Said out loud, then skipped.
+      logger?.warn?.(`[brain] ${role}: fallback link ${key} unusable (${err.message}) — skipped`);
+      return build(link.fallback, depth + 1);
+    }
+    return {
+      agent: { runTask: (args) => agent[agentMethod](args), provider: link.provider, model: link.model ?? null },
+      provider: link.provider,
+      model: link.model ?? null,
+      maxWaitHours: link.max_wait_hours,
+      fallback: build(link.fallback, depth + 1),
+    };
+  };
+
+  const declared = build(config?.roles?.[role]?.fallback, 1);
+
+  // KJC-TSK-0859: the provider's own default model is the last resort, and it
+  // always was — every agent kept a private retry that dropped the pinned
+  // model and tried again. Making it the chain's tail puts that step where the
+  // user can see it, after the candidates they declared and never before.
+  if (!primary.model) return declared;
+  const tailKey = keyOf(primary.provider, null);
+  if (seen.has(tailKey)) return declared;
+  seen.add(tailKey);
+  let tailAgent;
+  try {
+    tailAgent = createAgentFn(primary.provider, withRoleModel(config, role, primary.provider, null), logger);
+  } catch {
+    return declared; // the primary provider is already in use; if it cannot be
+  }                   // built again, the declared chain is what we have.
+  const tail = {
+    agent: { runTask: (args) => tailAgent[agentMethod](args), provider: primary.provider, model: null },
+    provider: primary.provider,
+    model: null,
+    maxWaitHours: undefined,
+    fallback: null,
+  };
+  if (!declared) return tail;
+  let last = declared;
+  while (last.fallback) last = last.fallback;
+  last.fallback = tail;
+  return declared;
+}

package/src/brain/with-brain-recovery.js

@@ -7,6 +7,7 @@
 // puede ignorarlo (fallback a long standby capped) hasta que llegue 0414.
 
 import { classifyAgentError, ERROR_CLASS } from "./agent-error-classifier.js";
+import { recordDeadModel } from "../agents/dead-models.js";
 import { persistStandby, markStandbyDone } from "./standby-store.js";
 
 const ONE_MIN = 60 * 1000;
@@ -31,6 +32,10 @@ export const DEFAULT_RECOVERY_POLICY = Object.freeze({
     [ERROR_CLASS.RATE_LIMIT_SHORT]: { mode: "standby", maxRetries: 3 },
     [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: { mode: "hibernate", maxRetries: 1, fallbackEligible: true },
     [ERROR_CLASS.QUOTA_EXHAUSTED_MONTHLY]: { mode: "hibernate", maxRetries: 1, fallbackEligible: true },
+    // KJC-TSK-0859: a retired model has no cooldown to wait out, so it takes
+    // the next link straight away. Without a chain it aborts, because
+    // retrying the same dead model is how a run burns quota saying nothing.
+    [ERROR_CLASS.MODEL_UNAVAILABLE]: { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true },
     [ERROR_CLASS.API_DOWN]: { mode: "backoff", maxRetries: 3, baseMs: 5_000, factor: 3, jitterPct: 0.2 },
     [ERROR_CLASS.NETWORK_TIMEOUT]: { mode: "backoff", maxRetries: 3, baseMs: 5_000, factor: 3, jitterPct: 0.2 },
     [ERROR_CLASS.SILENCED]: { mode: "backoff", maxRetries: 2, baseMs: 30_000, factor: 2, jitterPct: 0.15 },
@@ -88,14 +93,38 @@ export async function withBrainRecovery({
   // > maxWaitHours (default 12h) y hay fallback, switch en vez de hibernar.
   fallback = null,
 }) {
+  // The substitution is only useful if it names WHICH model died and which
+  // one took over, and agents expose it under different keys.
+  const modelOf = (a) => a?.model || a?.config?.model || null;
+  // Retrying the same agent is one entry with a count, not four lines: the
+  // order the user needs is the order of CANDIDATES, not of attempts.
+  const noteAttempt = (list, entry) => {
+    const last = list.at(-1);
+    if (last && last.provider === entry.provider && last.model === entry.model && last.class === entry.class) {
+      last.attempts += 1;
+      return;
+    }
+    list.push({ ...entry, attempts: 1 });
+  };
+  const formatTried = (list) =>
+    list
+      .map((t) => `${t.provider}${t.model ? ` (${t.model})` : ""} → ${t.class}${t.attempts > 1 ? ` x${t.attempts}` : ""}`)
+      .join("; ");
   let effectiveAgent = agent;
   let effectiveProvider = provider || agent?.provider || "unknown";
   let effectiveFallback = fallback;
   const attemptsByClass = {};
+  // KJC-TSK-0859: attemptsByClass counts, it does not remember. With a chain
+  // exhausted the user got "the work failed" and no idea what had been tried,
+  // so every failure also lands here, in order.
+  const tried = [];
 
   while (true) {
     const result = await effectiveAgent.runTask(taskArgs);
-    if (result?.ok) return result;
+    // KJC-TSK-0873: quien HA CORRIDO viaja con el resultado. Tras una caída al
+    // fallback, el llamante creía que había escrito el provider declarado, y
+    // con eso el recuento del panel contaba trabajo ajeno como propio.
+    if (result?.ok) return { ...result, provider: effectiveProvider };
 
     const cls = classifyAgentError({
       provider: effectiveProvider,
@@ -104,16 +133,46 @@ export async function withBrainRecovery({
       exitCode: result?.exitCode ?? null,
     });
     const classPolicy = policy.classes[cls.class] || { mode: "abort", maxRetries: 0 };
+    const failedModel = modelOf(effectiveAgent);
+    noteAttempt(tried, { provider: effectiveProvider, model: failedModel, class: cls.class, message: cls.message });
+    // KJC-TSK-0827: remember the corpse, or the next run pays for it again.
+    // Recording is an optimisation: a read-only home just means kj forgets.
+    if (cls.class === ERROR_CLASS.MODEL_UNAVAILABLE && failedModel) {
+      recordDeadModel({ provider: effectiveProvider, model: failedModel, reason: cls.message });
+    }
     attemptsByClass[cls.class] = (attemptsByClass[cls.class] || 0) + 1;
     const attempt = attemptsByClass[cls.class];
 
     emit(emitter, "brain:agent-error", eventBase, { role, class: cls.class, attempt, message: cls.message, provider: effectiveProvider });
     logger?.warn?.(`[brain] ${role} (${effectiveProvider}) → ${cls.class} attempt ${attempt}/${classPolicy.maxRetries}: ${cls.message}`);
 
+    // KJC-TSK-0859: un modelo retirado se resuelve ANTES de abortar. No hay
+    // cooldown que esperar, así que la condición de la cadena por cuota
+    // (retryAfter > maxWait) no aplica: si hay eslabón siguiente, se toma.
+    if (classPolicy.fallbackImmediate && effectiveFallback?.agent) {
+      const from = `${effectiveProvider}${modelOf(effectiveAgent) ? ` (${modelOf(effectiveAgent)})` : ""}`;
+      const to = effectiveFallback.provider || effectiveFallback.agent.provider || "unknown";
+      const toModel = effectiveFallback.model || modelOf(effectiveFallback.agent);
+      emit(emitter, "brain:fallback-switched", eventBase, { role, from: effectiveProvider, to, class: cls.class, immediate: true });
+      logger?.warn?.(`[brain] ${role}: ${cls.message} — substituting ${from} with ${to}${toModel ? ` (${toModel})` : " (provider default)"}. Pin it in kj.config.yml under roles.${role} to stop the substitution.`);
+      effectiveAgent = effectiveFallback.agent;
+      effectiveProvider = to;
+      effectiveFallback = effectiveFallback.fallback || null;
+      for (const k of Object.keys(attemptsByClass)) attemptsByClass[k] = 0;
+      continue;
+    }
+
     // ABORT: no recuperable.
     if (classPolicy.mode === "abort" || attempt > classPolicy.maxRetries) {
-      emit(emitter, "brain:fatal", eventBase, { role, class: cls.class, message: cls.message });
-      return { ok: false, action: "abort", recovery: cls, error: `Brain aborted: ${cls.class} — ${cls.message}` };
+      emit(emitter, "brain:fatal", eventBase, { role, class: cls.class, message: cls.message, tried });
+      return {
+        ok: false, action: "abort", recovery: cls, tried,
+        // With a chain behind us the LAST error explains nothing: the user
+        // needs the order, which is also what tells them where to look.
+        error: tried.length > 1
+          ? `Brain aborted for ${role} after trying, in order: ${formatTried(tried)} — last error: ${cls.message}`
+          : `Brain aborted: ${cls.class} — ${cls.message}`,
+      };
     }
 
     // KJC-TSK-0415: ¿switch a fallback antes de hibernar?
@@ -170,7 +229,7 @@ export async function withBrainRecovery({
       if (tooLongToWait) {
         logger?.info?.(`[brain] hibernated session ${sessionState?.sessionId ?? "(no id)"} → ${standbyFile} (resume at ${cls.retryUntil}; wait > ${Math.round(maxWaitMs/ONE_HOUR)}h, exiting)`);
         emit(emitter, "brain:hibernate-request", eventBase, { role, class: cls.class, retryUntil: cls.retryUntil, retryAfter: cls.retryAfter, standbyFile });
-        return { ok: false, action: "hibernate", recovery: cls, standbyFile };
+        return { ok: false, action: "hibernate", recovery: cls, standbyFile, tried };
       }
 
       // Standby-in-process: keep kj alive, sleep until the cooldown,