karajan-code 2.14.3 → 2.15.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.14.3 released** — Patch. Three preflight improvements surfaced by the first real `kj run` against a greenfield project (greta-app): (1) `gh` keyring auth is now recognized — Karajan no longer demands `GH_TOKEN` env var when the user has done `gh auth login --web` (KJC-BUG-0049 puntual). (2) New **degradable checks** system: when a preflight check fails on an optional feature (e.g. `auto_pr` without gh token), the feature is silently disabled with a WARN instead of aborting the entire run. (3) New **project-aware preflight**: detects signals (Dockerfile / firebase.json / pyproject.toml / Cargo.toml / *.tf / .env.example), checks the corresponding tools are installed, validates write permissions on `projectDir/.kj/.karajan`, compares `.env` vs `.env.example`, and validates `gh` push access to the actual remote (not just global auth). New command `kj doctor --project` runs only this phase. 2 PRs (#690, #691). 4608/4608 tests passing. Safe upgrade from 2.14.2.
+> **v2.15.0 released** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
 >
 > **v2.14.2** — Patch. More dogfooding fallout from GRETA Plan 2 v2.14.1: the **▶ Run button** on the HU Board appeared on every `pending` card regardless of `blocked_by` (you could launch a HU whose deps don't exist yet — the user caught it instantly), and titles on the board lost their **`[EPICA]` prefix** at some point in v2.14.x evolution, making it impossible to tell at a glance which area of the plan a card belonged to. Fixes: `canRunHu` now requires `blockedBy.length === 0` before showing ▶; the planner prompt now demands `description: "[EPICA] one-sentence description"` with INFRA/SHARED fallbacks. Plus a new doc `docs/task-templates/spec-conventions.md` collecting the 6 SPEC conventions the planner v2.14.x understands (épicas, scope exclusions, transversal deps, reuse, async observers, explicit deps), so users don't have to rediscover them by dogfooding. 2 PRs (#687, #688). 4584/4584 tests passing. Safe upgrade from 2.14.1.
 >

package/package.json

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

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

@@ -0,0 +1,101 @@
+// KJC-TSK-0411: clasificador universal de errores de agente IA.
+//
+// Devuelve clase rica + metadata accionable para que Brain (TSK-0412)
+// decida retry/standby/hibernar/abortar sin tener que repetir lógica
+// de parsing en cada stage.
+//
+// Reutiliza parseCooldown del rate-limit-detector legacy para no
+// duplicar regex. Este módulo extiende la clasificación:
+//   - RATE_LIMIT_SHORT vs QUOTA_EXHAUSTED_DAILY se distinguen por
+//     cooldownMs (threshold 1h).
+//   - SILENCED se detecta por exit 143/null + "killed after Nms".
+//   - AUTH_FAILED por 401/403 + "Unauthorized"/"invalid api key".
+//   - NETWORK_TIMEOUT por ECONN*/socket hang up sin cooldown.
+
+import { parseCooldown } from "../utils/rate-limit-detector.js";
+
+export const ERROR_CLASS = Object.freeze({
+  RATE_LIMIT_SHORT: "RATE_LIMIT_SHORT",
+  QUOTA_EXHAUSTED_DAILY: "QUOTA_EXHAUSTED_DAILY",
+  // KJC-TSK-0415: Anthropic Max 20x cambia a $200/mes Agent SDK desde
+  // 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",
+  API_DOWN: "API_DOWN",
+  AUTH_FAILED: "AUTH_FAILED",
+  NETWORK_TIMEOUT: "NETWORK_TIMEOUT",
+  SILENCED: "SILENCED",
+  UNKNOWN_FATAL: "UNKNOWN_FATAL",
+});
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+const AUTH_PATTERNS = /\b401\b|\b403\b|unauthorized|invalid\s+api\s+key|authentication\s+failed|expired\s+token/i;
+const SILENCED_PATTERNS = /killed\s+after\s+\d+\s*ms|silence\s*timeout|no\s+output\s+for\s+\d+/i;
+const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|daily\s+limit/i;
+const API_DOWN_PATTERNS = /\b50[0-4]\b|bad\s+gateway|service\s+unavailable|gateway\s+timeout|overloaded|internal\s+server\s+error/i;
+const NETWORK_PATTERNS = /ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket\s+hang\s+up|fetch\s+failed|network\s+error/i;
+
+function pickMessage(combined, pattern) {
+  const line = combined.split("\n").find((l) => pattern.test(l));
+  return (line || combined).trim().slice(0, 300);
+}
+
+/**
+ * @param {object} args
+ * @param {string} [args.provider] - claude|codex|gemini|opencode|aider
+ * @param {string} [args.stdout]
+ * @param {string} [args.stderr]
+ * @param {number|null} [args.exitCode]
+ * @returns {{ class: string, provider: string, message: string, retryAfter: number|null, retryUntil: string|null, recoverable: boolean, exitCode: number|null }}
+ */
+export function classifyAgentError({ provider = "unknown", stdout = "", stderr = "", exitCode = null }) {
+  const combined = `${stderr}\n${stdout}`;
+  const base = { provider, exitCode, retryAfter: null, retryUntil: null };
+
+  // 1. AUTH_FAILED tiene prioridad absoluta — no es recuperable, escalar al usuario.
+  if (AUTH_PATTERNS.test(combined)) {
+    return { ...base, class: ERROR_CLASS.AUTH_FAILED, message: pickMessage(combined, AUTH_PATTERNS), recoverable: false };
+  }
+
+  // 2. SILENCED: subprocess killed por silenceTimeout. exit=143 (SIGTERM) o null.
+  //    También detectamos por mensaje aunque exitCode no encaje (resiliente).
+  if (SILENCED_PATTERNS.test(combined) || (exitCode === 143 && !combined.trim())) {
+    return { ...base, class: ERROR_CLASS.SILENCED, message: pickMessage(combined, SILENCED_PATTERNS) || "Agent silenciado por timeout", recoverable: true };
+  }
+
+  // 3. 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)
+  if (RATE_LIMIT_PATTERNS.test(combined)) {
+    const msg = pickMessage(combined, RATE_LIMIT_PATTERNS);
+    const { cooldownUntil, cooldownMs } = parseCooldown(msg) ?? {};
+    let quotaClass;
+    if (cooldownMs != null && cooldownMs > ONE_WEEK_MS) quotaClass = ERROR_CLASS.QUOTA_EXHAUSTED_MONTHLY;
+    else if (cooldownMs != null && cooldownMs > ONE_HOUR_MS) quotaClass = ERROR_CLASS.QUOTA_EXHAUSTED_DAILY;
+    else quotaClass = ERROR_CLASS.RATE_LIMIT_SHORT;
+    return {
+      ...base,
+      class: quotaClass,
+      message: msg,
+      retryAfter: cooldownMs ?? null,
+      retryUntil: cooldownUntil ?? null,
+      recoverable: true,
+    };
+  }
+
+  // 4. NETWORK errors antes que API_DOWN — ECONN* es a nivel socket, no respuesta HTTP.
+  if (NETWORK_PATTERNS.test(combined)) {
+    return { ...base, class: ERROR_CLASS.NETWORK_TIMEOUT, message: pickMessage(combined, NETWORK_PATTERNS), recoverable: true };
+  }
+
+  // 5. API_DOWN: 5xx, overloaded.
+  if (API_DOWN_PATTERNS.test(combined)) {
+    return { ...base, class: ERROR_CLASS.API_DOWN, message: pickMessage(combined, API_DOWN_PATTERNS), recoverable: true };
+  }
+
+  // 6. UNKNOWN_FATAL: salida no clasificada con exitCode != 0.
+  return { ...base, class: ERROR_CLASS.UNKNOWN_FATAL, message: combined.trim().slice(0, 300) || `exit ${exitCode}`, recoverable: false };
+}

package/src/brain/standby-scheduler.js

@@ -0,0 +1,92 @@
+// KJC-TSK-0414 PR 1: scheduler event-driven para hibernación.
+//
+// Diseño: setTimeout único por sesión, dispara EXACTAMENTE en cooldownUntil.
+// Cero polling. Si el proceso muere antes del fire, reconcileAll() al
+// arrancar el board re-programa los timeouts pendientes (o reanuda
+// inmediatamente los expirados).
+
+import { listPendingStandby, acquireStandbyLock, markStandbyDone } from "./standby-store.js";
+
+// Mapa sessionId → NodeJS.Timeout — accesible para test/cancel.
+const _scheduled = new Map();
+
+export function _resetScheduledForTests() {
+  for (const t of _scheduled.values()) clearTimeout(t);
+  _scheduled.clear();
+}
+
+/**
+ * Programa un único setTimeout que dispara `onResume(sessionId)` en cooldownUntil.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.cooldownUntil - ISO timestamp
+ * @param {Function} args.onResume - callback(sessionId) cuando llega el momento
+ * @param {object} [args.logger]
+ * @returns {{ scheduled: boolean, msUntil?: number, immediate?: boolean }}
+ */
+export function scheduleResume({ sessionId, cooldownUntil, onResume, logger }) {
+  if (!sessionId || !cooldownUntil || typeof onResume !== "function") {
+    return { scheduled: false };
+  }
+  cancelScheduled(sessionId);
+  const targetMs = new Date(cooldownUntil).getTime();
+  if (Number.isNaN(targetMs)) return { scheduled: false };
+  const delay = targetMs - Date.now();
+  if (delay <= 0) {
+    // Ya expiró — reanudar inmediato (caso: board reiniciado tras llegar la hora).
+    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown ya expirado, resume inmediato`);
+    Promise.resolve().then(() => onResume(sessionId)).catch(() => { /* swallow */ });
+    return { scheduled: true, immediate: true };
+  }
+  const timer = setTimeout(() => {
+    _scheduled.delete(sessionId);
+    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown alcanzado, disparando resume`);
+    try { onResume(sessionId); } catch (err) { logger?.warn?.(`[standby-scheduler] onResume threw: ${err.message}`); }
+  }, delay);
+  if (typeof timer.unref === "function") timer.unref();
+  _scheduled.set(sessionId, timer);
+  logger?.info?.(`[standby-scheduler] ${sessionId}: scheduled in ${Math.round(delay / 1000)}s (until ${cooldownUntil})`);
+  return { scheduled: true, msUntil: delay };
+}
+
+/** Cancela el setTimeout de una sesión (caso: usuario hizo kj resume manual). */
+export function cancelScheduled(sessionId) {
+  const t = _scheduled.get(sessionId);
+  if (!t) return false;
+  clearTimeout(t);
+  _scheduled.delete(sessionId);
+  return true;
+}
+
+/**
+ * Reconciliación al arrancar el board / kj. Lee todas las sesiones pendientes
+ * y para cada una:
+ *   - cooldownUntil < now → onResume inmediato
+ *   - cooldownUntil > now → re-programa setTimeout
+ *
+ * Idempotente: el lockfile en standby-store previene dobles spawns si
+ * reconcileAll() corre dos veces concurrentes (board reload).
+ *
+ * @param {object} args
+ * @param {Function} args.onResume - callback(sessionId)
+ * @param {object} [args.logger]
+ * @returns {{ scheduled: number, immediate: number, total: number }}
+ */
+export function reconcileAll({ onResume, logger }) {
+  const sessions = listPendingStandby();
+  let scheduled = 0;
+  let immediate = 0;
+  for (const s of sessions) {
+    if (!s?.sessionId || !s?.cooldownUntil) continue;
+    const r = scheduleResume({ sessionId: s.sessionId, cooldownUntil: s.cooldownUntil, onResume, logger });
+    if (r.scheduled && r.immediate) immediate += 1;
+    else if (r.scheduled) scheduled += 1;
+  }
+  logger?.info?.(`[standby-scheduler] reconcile: ${sessions.length} sesiones (${immediate} resume inmediato, ${scheduled} programadas)`);
+  return { scheduled, immediate, total: sessions.length };
+}
+
+// Re-export para que callers no tengan que importar standby-store si solo
+// necesitan el flow scheduler → lock → done.
+export { acquireStandbyLock, markStandbyDone };

package/src/brain/standby-store.js

@@ -0,0 +1,129 @@
+// KJC-TSK-0414 PR 1: persistencia de sesiones hibernadas al disco.
+//
+// Cuando Brain decide hibernar (QUOTA_EXHAUSTED_DAILY con retryAfter > 5min),
+// serializa el estado completo del run en ~/.kj/standby/<sessionId>.json.
+// El proceso de kj run muere (exit 0) tras persistir; el board (o kj resume)
+// lo reanuda cuando llega cooldownUntil.
+//
+// Layout en disco:
+//   ~/.kj/standby/
+//     <sessionId>.json    ← sesiones pendientes (scheduler les mete setTimeout)
+//     <sessionId>.lock    ← lockfile durante spawn de kj resume
+//     done/
+//       <sessionId>.json  ← finalizadas (consumibles por GC en TSK-0414 PR3)
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
+
+function getKjHome() {
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  if (process.env.VITEST) return path.join(os.tmpdir(), `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`, ".kj");
+  return path.join(os.homedir(), ".kj");
+}
+
+export function standbyDir() {
+  return path.join(getKjHome(), "standby");
+}
+
+export function standbyDoneDir() {
+  return path.join(standbyDir(), "done");
+}
+
+function sanitizeId(sessionId) {
+  if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId requerido");
+  return sessionId.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
+}
+
+/**
+ * Persiste el estado completo de un run hibernado.
+ *
+ * @param {object} state - shape:
+ *   { sessionId, planId?, huId?, role, iteration?, prompt, agentConfig,
+ *     retryCount?, cooldownUntil, reason, snapshot_sha?, outcome_so_far? }
+ * @returns {string} path absoluto del JSON escrito
+ */
+export function persistStandby(state) {
+  if (!state || !state.sessionId) throw new Error("state.sessionId requerido");
+  if (!state.cooldownUntil) throw new Error("state.cooldownUntil requerido");
+  const dir = standbyDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${sanitizeId(state.sessionId)}.json`);
+  const payload = {
+    ...state,
+    createdAt: state.createdAt || new Date().toISOString(),
+    persistedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), "utf-8");
+  return file;
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {object|null}
+ */
+export function loadStandby(sessionId) {
+  const file = path.join(standbyDir(), `${sanitizeId(sessionId)}.json`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lista todas las sesiones pendientes (no las de done/).
+ * @returns {object[]}
+ */
+export function listPendingStandby() {
+  const dir = standbyDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => FILENAME_RE.test(f))
+    .map((f) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Mueve una sesión a done/ — consumible por GC en TSK-0414 PR3.
+ * @param {string} sessionId
+ * @returns {boolean} true si se movió
+ */
+export function markStandbyDone(sessionId) {
+  const id = sanitizeId(sessionId);
+  const src = path.join(standbyDir(), `${id}.json`);
+  if (!fs.existsSync(src)) return false;
+  const doneDir = standbyDoneDir();
+  fs.mkdirSync(doneDir, { recursive: true });
+  const dst = path.join(doneDir, `${id}-${Date.now()}.json`);
+  fs.renameSync(src, dst);
+  return true;
+}
+
+/**
+ * Lockfile para evitar dobles spawns de kj resume sobre la misma sesión.
+ * Devuelve { acquired: true, release: () => void } o { acquired: false } si ya hay lock.
+ *
+ * @param {string} sessionId
+ * @returns {{ acquired: boolean, release?: Function }}
+ */
+export function acquireStandbyLock(sessionId) {
+  const id = sanitizeId(sessionId);
+  const lockFile = path.join(standbyDir(), `${id}.lock`);
+  try {
+    fs.mkdirSync(standbyDir(), { recursive: true });
+    fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+    return { acquired: true, release: () => { try { fs.unlinkSync(lockFile); } catch { /* */ } } };
+  } catch {
+    return { acquired: false };
+  }
+}

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

@@ -0,0 +1,178 @@
+// KJC-TSK-0412: wrapper central de recovery. Cualquier stage que invoque
+// un agente IA pasa por aquí. Brain consume classifyAgentError (TSK-0411)
+// y decide: standby corto, backoff exponencial, hibernar, o abortar.
+//
+// Hibernar al disco (acción persistente) es TSK-0414 — esta PR devuelve
+// { ok: false, action: "hibernate", retryUntil } cuando aplica; el caller
+// puede ignorarlo (fallback a long standby capped) hasta que llegue 0414.
+
+import { classifyAgentError, ERROR_CLASS } from "./agent-error-classifier.js";
+import { persistStandby } from "./standby-store.js";
+
+const ONE_MIN = 60 * 1000;
+
+const ONE_HOUR = 60 * 60 * 1000;
+const DEFAULT_FALLBACK_WAIT_HOURS = 12;
+
+export const DEFAULT_RECOVERY_POLICY = Object.freeze({
+  hibernateThresholdMs: 5 * ONE_MIN, // > 5 min de espera → hibernar
+  longStandbyCapMs: 10 * ONE_MIN,    // si el caller no hiberna, espera máx 10 min
+  // KJC-TSK-0415: threshold de fallback. Si retryAfter > esto Y el role
+  // tiene fallback configurado → switch provider en vez de hibernar.
+  fallbackWaitHoursDefault: DEFAULT_FALLBACK_WAIT_HOURS,
+  classes: {
+    [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 },
+    [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 },
+    [ERROR_CLASS.AUTH_FAILED]: { mode: "abort", maxRetries: 0 },
+    [ERROR_CLASS.UNKNOWN_FATAL]: { mode: "abort", maxRetries: 0 },
+  },
+});
+
+function backoffDelay(policyForClass, attempt) {
+  const { baseMs = 5_000, factor = 2, jitterPct = 0.1 } = policyForClass;
+  const ms = baseMs * factor ** attempt;
+  const jitter = ms * jitterPct * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(ms + jitter));
+}
+
+function sleep(ms) {
+  // En tests (VITEST / NODE_ENV=test) saltamos sleeps reales — los tests que
+  // necesitan timing controlado inyectan sleepFn explícito. Esto evita que
+  // tests de stages downstream que llaman a withBrainRecovery se cuelguen
+  // esperando standby cuando el agente fake devuelve un error recoverable.
+  if (process.env.VITEST || process.env.NODE_ENV === "test") return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function emit(emitter, type, eventBase, detail) {
+  if (!emitter || typeof emitter.emit !== "function") return;
+  try {
+    emitter.emit("progress", { ...(eventBase || {}), type, detail });
+  } catch { /* nunca bloquees un retry por un emitter mal */ }
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.agent - Agent con runTask({...})
+ * @param {object} args.taskArgs - args pasados a agent.runTask
+ * @param {string} args.role - "planner" | "coder" | "reviewer" | ...
+ * @param {string} [args.provider] - claude|codex|gemini|opencode (default: agent.provider)
+ * @param {object} [args.policy] - override DEFAULT_RECOVERY_POLICY
+ * @param {object} [args.emitter] - bus de eventos
+ * @param {object} [args.eventBase]
+ * @param {object} [args.logger]
+ * @param {Function} [args.sleepFn] - inyectable para tests
+ * @returns {Promise<{ ok: boolean, output?: string, action?: string, recovery?: object, error?: string }>}
+ */
+export async function withBrainRecovery({
+  agent, taskArgs, role, provider,
+  policy = DEFAULT_RECOVERY_POLICY,
+  emitter, eventBase, logger,
+  sleepFn = sleep,
+  // TSK-0414 PR2: si presente, en hibernate persiste { sessionId, planId?, huId?,
+  // argv?, ... } a ~/.kj/standby/<sessionId>.json y devuelve standbyFile en
+  // el resultado.
+  sessionState,
+  // KJC-TSK-0415: fallback chain. Si QUOTA_EXHAUSTED_* con retryAfter
+  // > maxWaitHours (default 12h) y hay fallback, switch en vez de hibernar.
+  fallback = null,
+}) {
+  let effectiveAgent = agent;
+  let effectiveProvider = provider || agent?.provider || "unknown";
+  let effectiveFallback = fallback;
+  const attemptsByClass = {};
+
+  while (true) {
+    const result = await effectiveAgent.runTask(taskArgs);
+    if (result?.ok) return result;
+
+    const cls = classifyAgentError({
+      provider: effectiveProvider,
+      stdout: result?.output || "",
+      stderr: result?.error || "",
+      exitCode: result?.exitCode ?? null,
+    });
+    const classPolicy = policy.classes[cls.class] || { mode: "abort", maxRetries: 0 };
+    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}`);
+
+    // 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}` };
+    }
+
+    // KJC-TSK-0415: ¿switch a fallback antes de hibernar?
+    // Aplica si:
+    //   - classPolicy.fallbackEligible (QUOTA_EXHAUSTED_*)
+    //   - hay fallback configurado
+    //   - retryAfter excede maxWaitHours del fallback (default 12h)
+    if (classPolicy.fallbackEligible && effectiveFallback?.agent && cls.retryAfter) {
+      const maxWaitMs = (effectiveFallback.maxWaitHours ?? policy.fallbackWaitHoursDefault ?? DEFAULT_FALLBACK_WAIT_HOURS) * ONE_HOUR;
+      if (cls.retryAfter > maxWaitMs) {
+        const from = effectiveProvider;
+        const to = effectiveFallback.provider || effectiveFallback.agent.provider || "unknown";
+        emit(emitter, "brain:fallback-switched", eventBase, { role, from, to, class: cls.class, retryAfter: cls.retryAfter, maxWaitMs });
+        logger?.info?.(`[brain] ${role}: fallback ${from} → ${to} (retryAfter ${Math.round(cls.retryAfter/3600000)}h > maxWait ${maxWaitMs/3600000}h)`);
+        // Switch al fallback. Reset attempts para que el nuevo provider
+        // pueda fallar/retry independientemente. Fallback puede tener su
+        // propio fallback en cadena.
+        effectiveAgent = effectiveFallback.agent;
+        effectiveProvider = to;
+        effectiveFallback = effectiveFallback.fallback || null;
+        for (const k of Object.keys(attemptsByClass)) attemptsByClass[k] = 0;
+        continue;
+      }
+    }
+
+    // HIBERNATE: persistir + signal action=hibernate al caller.
+    // Si el caller pasó `sessionState` (TSK-0414 PR2), persistimos el JSON
+    // automáticamente en ~/.kj/standby/<sessionId>.json. Caller decide qué
+    // hacer con action=hibernate (típicamente exit 0 para liberar memoria).
+    if (classPolicy.mode === "hibernate" && cls.retryAfter && cls.retryAfter > policy.hibernateThresholdMs) {
+      let standbyFile = null;
+      if (sessionState && sessionState.sessionId) {
+        try {
+          standbyFile = persistStandby({
+            ...sessionState,
+            cooldownUntil: cls.retryUntil,
+            reason: cls.class,
+            role, provider: effectiveProvider,
+            classifierMessage: cls.message,
+          });
+          logger?.info?.(`[brain] hibernated session ${sessionState.sessionId} → ${standbyFile} (resume at ${cls.retryUntil})`);
+        } catch (err) {
+          logger?.warn?.(`[brain] failed to persist standby: ${err.message}`);
+        }
+      }
+      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 };
+    }
+
+    // STANDBY: espera hasta cooldownUntil (capado por longStandbyCapMs).
+    if (classPolicy.mode === "standby") {
+      const waitMs = Math.min(cls.retryAfter || ONE_MIN, policy.longStandbyCapMs);
+      emit(emitter, "brain:standby", eventBase, { role, class: cls.class, waitMs, retryUntil: cls.retryUntil });
+      await sleepFn(waitMs);
+      continue;
+    }
+
+    // BACKOFF exponencial con jitter.
+    if (classPolicy.mode === "backoff") {
+      const waitMs = backoffDelay(classPolicy, attempt - 1);
+      emit(emitter, "brain:backoff", eventBase, { role, class: cls.class, attempt, waitMs });
+      await sleepFn(waitMs);
+      continue;
+    }
+
+    // Modo desconocido — defensive abort.
+    return { ok: false, action: "abort", recovery: cls, error: `Brain: unknown mode '${classPolicy.mode}' for class ${cls.class}` };
+  }
+}

package/src/cli/register-plan.js

@@ -7,6 +7,8 @@ import {
   planDeleteCommand,
   planAddHuCommand,
   planRemoveHuCommand,
+  planMigrateResultCommand,
+  planFixCommand,
 } from "../commands/plan.js";
 import { parseCanvasMarkdown } from "../canvas/parse-md.js";
 import { validateCanvas } from "../canvas/validate.js";
@@ -149,4 +151,31 @@ export function registerPlan(program, { pkgVersion }) {
       await planRemoveHuCommand({ config, planId, huId });
     });
   });
+
+  // KJC-TSK-0402: re-ejecuta reviewer + self-fix + structural pass sobre
+  // un plan existente. Acepta --prompt opcional con feedback humano que
+  // el reviewer inyecta como contexto extra antes de revisar.
+  plan.command("fix")
+    .description("Relanzar self-fix loop sobre plan existente (con --prompt opcional)")
+    .argument("<planId>")
+    .option("--prompt <text>", "Feedback del usuario para guiar al reviewer")
+    .option("--json", "Output JSON con before/after counts")
+    .action(async (planId, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        await planFixCommand({ config, planId, prompt: flags.prompt, logger, json: flags.json });
+      });
+    });
+
+  // KJC-TSK-0394 step 4: migración one-shot que siembra `result` en las
+  // HUs de los plan files existentes (basado en su status legacy). Solo
+  // toca el campo result, NO el status — el cleanup del enum lo hará
+  // step 5. Idempotente.
+  plan.command("migrate-result")
+    .description("Backfill the `result` field on existing plan HUs (KJC-TSK-0394 step 4)")
+    .option("--dry-run", "Show what would change without writing")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+        await planMigrateResultCommand({ config, flags: { dryRun: flags.dryRun } });
+      });
+    });
 }

package/src/cli/register-standby.js

@@ -0,0 +1,26 @@
+// KJC-TSK-0414 PR2: registra `kj standby list` + `kj standby resume <id>`.
+// `resume` es subcomando de standby para no colisionar con el `kj resume`
+// pre-existente (Solomon pauses con --answer). Modelos mentales distintos:
+//   - `kj resume <id> --answer X`  → Solomon pauseado (existente)
+//   - `kj standby resume <id>`     → run hibernada por quota
+import { resumeCommand, standbyListCommand } from "../commands/standby.js";
+
+export function registerStandby(program) {
+  const standby = program.command("standby").description("Sesiones hibernadas (QUOTA_EXHAUSTED_DAILY etc.)");
+  standby
+    .command("list", { isDefault: true })
+    .description("Lista sesiones pendientes de reanudar")
+    .option("--json", "Output JSON")
+    .action(async (flags) => {
+      await standbyListCommand({ json: flags.json });
+    });
+
+  standby
+    .command("resume")
+    .description("Reanuda una sesión hibernada (re-spawn comando original)")
+    .argument("<sessionId>")
+    .option("--force", "Reanudar aunque cooldownUntil todavía esté en el futuro (no recomendado)")
+    .action(async (sessionId, flags) => {
+      await resumeCommand({ sessionId, force: Boolean(flags.force) });
+    });
+}

package/src/cli.js

@@ -9,6 +9,7 @@ import { registerPlan } from "./cli/register-plan.js";
 import { registerRolesSkills } from "./cli/register-roles-skills.js";
 import { registerMeta } from "./cli/register-meta.js";
 import { registerSonar } from "./cli/register-sonar.js";
+import { registerStandby } from "./cli/register-standby.js";
 import { printUpdateNotice } from "./utils/update-check.js";
 import { printWelcomeScreen } from "./utils/welcome.js";
 
@@ -44,6 +45,7 @@ registerPlan(program, { pkgVersion: PKG_VERSION });
 registerRolesSkills(program, { pkgVersion: PKG_VERSION });
 registerMeta(program, { pkgVersion: PKG_VERSION });
 registerSonar(program);
+registerStandby(program);
 
 /**
  * Find subcommands whose name is "close enough" to a typo. Used by the

package/src/commands/architect.js

@@ -3,6 +3,7 @@ import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 function formatLayers(layers, lines) {
   lines.push("### Layers");
@@ -71,8 +72,11 @@ export async function architectCommand({ task, config, logger, context, json })
     const progress = createCliProgressReporter({ role: "architect" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "architect" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "architect" },
+        role: "architect", provider: architectRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {

package/src/commands/discover.js

@@ -1,6 +1,7 @@
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
 
@@ -75,8 +76,11 @@ export async function discoverCommand({ task, config, logger, mode, json }) {
     const progress = createCliProgressReporter({ role: "discover" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "discover" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "discover" },
+        role: "discover", provider: discoverRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {