@karajan-family/code 4.21.0

package/src/brain/decisor.js

@@ -0,0 +1,243 @@
+/**
+ * Brain decisor — intent-driven pipeline routing.
+ *
+ * Takes the triage output + task text + config and produces a Decision that
+ * the orchestrator applies as pipelineFlags overrides. The existing stage
+ * if/else in runFlow continues to drive execution; Brain just tells it which
+ * roles are relevant for this particular task.
+ *
+ * This is an MVP that keeps the current architecture. A future iteration
+ * (Pipeline Sovereignty / KJC-PCS-0022) can promote the Decision into a
+ * true DAG with parallel stage execution.
+ */
+
+/**
+ * @typedef {Object} TriageOutput
+ * @property {"trivial"|"simple"|"medium"|"complex"} level
+ * @property {string[]} roles                       - roles triage suggests running
+ * @property {string} [taskType]                    - sw | infra | doc | add-tests | refactor | no-code | audit
+ * @property {string} [reasoning]
+ * @property {number} [confidence]                  - 0..1, often absent
+ * @property {string[]} [domainHints]
+ */
+
+/**
+ * @typedef {Object} Decision
+ * @property {string[]} rolesOn                     - roles to enable in pipelineFlags
+ * @property {string[]} rolesOff                    - roles to explicitly disable
+ * @property {"low"|"medium"|"high"} confidence
+ * @property {string} rationale                     - human-readable reasoning
+ * @property {boolean} consultSolomon               - true if the Brain is unsure
+ * @property {string} [solomonReason]               - why Solomon is needed
+ * @property {string[]} appliedOverrides            - names of manual overrides respected
+ */
+
+const VALID_ROLES = new Set([
+  "planner", "researcher", "architect", "coder", "reviewer", "refactorer",
+  "tester", "security", "impeccable", "triage", "discover", "hu_reviewer", "solomon",
+]);
+
+/**
+ * Translate triage level → base set of roles. Conservative baseline that the
+ * decisor then adjusts via taskType and domain hints.
+ */
+function baselineForLevel(level) {
+  switch (level) {
+    case "trivial": return new Set(["coder"]);
+    case "simple": return new Set(["coder", "reviewer"]);
+    case "medium": return new Set(["coder", "reviewer", "tester"]);
+    case "complex": return new Set(["researcher", "architect", "planner", "coder", "reviewer", "tester", "security"]);
+    default: return new Set(["coder", "reviewer"]);
+  }
+}
+
+/**
+ * Apply taskType adjustments on top of the baseline set (mutates in place).
+ */
+function applyTaskTypeAdjustments(roles, taskType) {
+  switch (taskType) {
+    case "doc":
+      // Documentation tasks: skip testing and security, keep reviewer for tone/clarity.
+      roles.delete("tester");
+      roles.delete("security");
+      roles.delete("refactorer");
+      break;
+    case "add-tests":
+      // Adding tests: tester is primary, security less relevant.
+      roles.add("tester");
+      roles.delete("security");
+      break;
+    case "refactor":
+      // Refactor: no new behavior; tester verifies nothing broke; reviewer checks structure.
+      roles.add("refactorer");
+      roles.add("tester");
+      break;
+    case "infra":
+      // Infra: architect helps; security critical.
+      roles.add("architect");
+      roles.add("security");
+      break;
+    case "audit":
+      // Audit: no coder; reviewer + security.
+      roles.delete("coder");
+      roles.add("reviewer");
+      roles.add("security");
+      break;
+    case "no-code":
+      // No-code tasks (e.g. running SQL queries): drop coder+reviewer+tester.
+      roles.delete("coder");
+      roles.delete("reviewer");
+      roles.delete("tester");
+      break;
+  }
+}
+
+/**
+ * Apply explicit overrides (CLI flags / config) on top of the decision.
+ * force = add; skip = remove. Tracks what was applied.
+ *
+ * @param {Set<string>} roles
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} overrides
+ * @returns {string[]} applied override names
+ */
+function applyOverrides(roles, overrides) {
+  const applied = [];
+  for (const r of overrides.forceRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.add(r);
+    applied.push(`force:${r}`);
+  }
+  for (const r of overrides.skipRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.delete(r);
+    applied.push(`skip:${r}`);
+  }
+  return applied;
+}
+
+/**
+ * Build a routing Decision from triage output + task text + config.
+ *
+ * @param {Object} args
+ * @param {TriageOutput} args.triage
+ * @param {string} [args.task]
+ * @param {Object} [args.config]                   - resolved config (for rolesEnabled in pipeline)
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} [args.overrides]
+ * @returns {Decision}
+ */
+export function buildDecision({ triage, task: _task, config = {}, overrides = {} } = {}) {
+  const level = triage?.level || "simple";
+  const taskType = triage?.taskType || "sw";
+
+  // 1. Baseline by complexity.
+  const roles = baselineForLevel(level);
+
+  // 2. Include triage's own suggested roles (triage already factors domain hints).
+  if (Array.isArray(triage?.roles)) {
+    for (const r of triage.roles) {
+      if (VALID_ROLES.has(r)) roles.add(r);
+    }
+  }
+
+  // 3. Task-type-specific adjustments.
+  applyTaskTypeAdjustments(roles, taskType);
+
+  // 4. Config pipeline.X.enabled=false forces a role off (respect user config).
+  const pipeline = config?.pipeline || {};
+  for (const r of Array.from(roles)) {
+    if (pipeline[r]?.enabled === false) {
+      roles.delete(r);
+    }
+  }
+
+  // 5. Manual CLI/flag overrides (highest priority).
+  const appliedOverrides = applyOverrides(roles, overrides);
+
+  // 6. Invariants: coder is always on unless explicitly audit/no-code AND not force-added.
+  if (taskType !== "audit" && taskType !== "no-code" && !overrides.skipRoles?.includes("coder")) {
+    roles.add("coder");
+  }
+
+  // 7. Confidence + Solomon consultation.
+  const explicitConfidence = typeof triage?.confidence === "number" ? triage.confidence : null;
+  let confidence = "medium";
+  let consultSolomon = false;
+  let solomonReason;
+  if (explicitConfidence !== null) {
+    if (explicitConfidence < 0.6) {
+      confidence = "low";
+      consultSolomon = true;
+      solomonReason = `triage confidence ${explicitConfidence.toFixed(2)} < 0.6`;
+    } else if (explicitConfidence >= 0.85) {
+      confidence = "high";
+    }
+  }
+  // Ambiguous level (absent or off-vocabulary) → low confidence regardless.
+  if (!triage?.level) {
+    confidence = "low";
+    consultSolomon = true;
+    solomonReason = "triage returned no level";
+  }
+
+  const rolesOn = Array.from(roles).sort((a, b) => a.localeCompare(b));
+  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort((a, b) => a.localeCompare(b));
+
+  const rationale = buildRationale({ level, taskType, rolesOn, appliedOverrides, triage });
+
+  return {
+    rolesOn,
+    rolesOff,
+    confidence,
+    rationale,
+    consultSolomon,
+    solomonReason,
+    appliedOverrides,
+  };
+}
+
+function buildRationale({ level, taskType, rolesOn, appliedOverrides, triage }) {
+  const parts = [
+    `level=${level}`,
+    `taskType=${taskType}`,
+    `roles=[${rolesOn.join(",")}]`,
+  ];
+  if (triage?.domainHints?.length) {
+    parts.push(`hints=[${triage.domainHints.slice(0, 3).join(",")}]`);
+  }
+  if (appliedOverrides.length) {
+    parts.push(`overrides=[${appliedOverrides.join(",")}]`);
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Apply a Decision onto an existing pipelineFlags object. Returns a NEW
+ * object — the input is not mutated. Setting roleEnabled flags via a
+ * consistent naming pattern: `${role}Enabled`.
+ *
+ * Unknown roles are silently ignored; the orchestrator only consumes a
+ * fixed set of *Enabled flags.
+ *
+ * @param {Decision} decision
+ * @param {Object} pipelineFlags
+ * @returns {Object} new flags object
+ */
+export function applyDecisionToFlags(decision, pipelineFlags = {}) {
+  const next = { ...pipelineFlags };
+  const flagFor = (role) => {
+    if (role === "hu_reviewer") return "huReviewerEnabled";
+    return `${role}Enabled`;
+  };
+  for (const role of decision.rolesOn) {
+    next[flagFor(role)] = true;
+  }
+  for (const role of decision.rolesOff) {
+    next[flagFor(role)] = false;
+  }
+  // Coder/security/reviewer aren't always toggled via flags in the current
+  // orchestrator (coder is implicit). Don't touch fields the orchestrator
+  // doesn't know; next simply carries them.
+  return next;
+}
+
+export { VALID_ROLES };

package/src/brain/solomon-consult.js

@@ -0,0 +1,171 @@
+/**
+ * Brain → Solomon consultation for routing decisions.
+ *
+ * When the Brain's Decision is low confidence, ambiguous, or the triage+config
+ * combination yields conflicting signals, the Brain consults Solomon. Solomon
+ * ruling is treated as *advisory*: if it returns a concrete role adjustment
+ * (e.g. "add security"), Brain applies it; otherwise Brain keeps the baseline.
+ *
+ * This is intentionally conservative. A future iteration can make Solomon a
+ * binding arbiter for routing (like it is for pipeline-control decisions).
+ *
+ * Architectural invariant: this module is the ONLY sanctioned path from
+ * Brain to Solomon for routing concerns. Stages / rules / agents must not
+ * bypass Brain to reach Solomon directly — see the note on `invokeSolomon`
+ * in `src/orchestrator/solomon-escalation.js` and docs/ARCHITECTURE.md.
+ *
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
+ */
+
+/**
+ * Build a synthetic conflict payload suitable for invokeSolomon().
+ *
+ * @param {Object} args
+ * @param {import("./decisor.js").Decision} args.decision
+ * @param {Object} args.triage
+ * @param {string} args.task
+ * @returns {Conflict} conflict
+ */
+export function buildRoutingConflict({ decision, triage, task }) {
+  return {
+    task,
+    stage: "brain-routing",
+    reason: decision.solomonReason || "low-confidence routing decision",
+    iterationCount: 0,
+    maxIterations: 1,
+    history: [],
+    summary: `Brain rationale: ${decision.rationale}. Roles on: ${decision.rolesOn.join(", ")}. Confidence: ${decision.confidence}.`,
+    // Extra data Solomon's prompt can introspect via conflict.detail
+    detail: {
+      triageLevel: triage?.level,
+      triageTaskType: triage?.taskType,
+      triageConfidence: triage?.confidence,
+      rolesOn: decision.rolesOn,
+      rolesOff: decision.rolesOff,
+      reason: decision.solomonReason,
+    },
+  };
+}
+
+/**
+ * Invoke Solomon with a routing question and translate its ruling back into
+ * adjustments to the Decision's rolesOn/rolesOff lists.
+ *
+ * If anything goes wrong (Solomon disabled, invocation throws, ruling
+ * malformed), the original decision is returned unchanged with a diagnostic
+ * appended to its rationale.
+ *
+ * @param {Object} args
+ * @param {import("./decisor.js").Decision} args.decision
+ * @param {Object} args.triage
+ * @param {string} args.task
+ * @param {Object} args.config
+ * @param {Object} args.logger
+ * @param {Object} [args.emitter]
+ * @param {Object} [args.eventBase]
+ * @param {Object} [args.session]
+ * @param {Function} [args.askQuestion]
+ * @returns {Promise<import("./decisor.js").Decision>}
+ */
+export async function consultSolomonForRouting({
+  decision,
+  triage,
+  task,
+  config,
+  logger,
+  emitter = null,
+  eventBase = {},
+  session = {},
+  askQuestion = null,
+}) {
+  if (!decision?.consultSolomon) return decision;
+  // Route through the existing infrastructure.
+  let invokeSolomon;
+  try {
+    ({ invokeSolomon } = await import("../orchestrator/solomon-escalation.js"));
+  } catch (err) {
+    logger?.warn?.(`brain/solomon-consult: escalation module unavailable (${err.message})`);
+    return decision;
+  }
+
+  const conflict = buildRoutingConflict({ decision, triage, task });
+
+  let ruling;
+  try {
+    ruling = await invokeSolomon({
+      config,
+      logger,
+      emitter,
+      eventBase,
+      stage: "brain-routing",
+      conflict,
+      askQuestion,
+      session,
+      iteration: 0,
+    });
+  } catch (err) {
+    logger?.warn?.(`brain/solomon-consult: invokeSolomon threw (${err.message}) — keeping baseline`);
+    return {
+      ...decision,
+      rationale: `${decision.rationale} | solomon=failed(${err.message})`,
+    };
+  }
+
+  if (!ruling || typeof ruling !== "object") {
+    return {
+      ...decision,
+      rationale: `${decision.rationale} | solomon=no-ruling`,
+    };
+  }
+
+  return applyRulingToDecision(decision, ruling, logger);
+}
+
+/**
+ * Apply a Solomon ruling to a decision. Known ruling fields Solomon may
+ * return that we understand in routing context:
+ *   - action: "approve" / "continue" / "retry_different_approach" / "escalate"
+ *   - suggestedActions: list of strings that may include "add X" / "remove X"
+ *   - conditions: list of strings
+ *
+ * For routing we only look at suggestedActions (text-based) and parse simple
+ * "add X" / "skip X" / "remove X" hints against the valid role set. Everything
+ * else is logged for the rationale and ignored.
+ */
+export function applyRulingToDecision(decision, ruling, logger) {
+  const rolesOn = new Set(decision.rolesOn);
+  const rolesOff = new Set(decision.rolesOff);
+  const applied = [];
+
+  const suggestions = Array.isArray(ruling.suggestedActions) ? ruling.suggestedActions : [];
+  for (const raw of suggestions) {
+    const action = String(raw || "").toLowerCase();
+    const addMatch = action.match(/\b(?:add|enable|include)\s+(\w+)/);
+    const skipMatch = action.match(/\b(?:skip|disable|remove|drop)\s+(\w+)/);
+    if (addMatch) {
+      const role = addMatch[1];
+      rolesOn.add(role);
+      rolesOff.delete(role);
+      applied.push(`solomon-add:${role}`);
+    } else if (skipMatch) {
+      const role = skipMatch[1];
+      rolesOff.add(role);
+      rolesOn.delete(role);
+      applied.push(`solomon-skip:${role}`);
+    }
+  }
+
+  const ruleVerdict = ruling.action || ruling.verdict || "unknown";
+  logger?.info?.(`brain/solomon-consult: Solomon verdict=${ruleVerdict} applied=[${applied.join(",")}]`);
+
+  return {
+    ...decision,
+    rolesOn: Array.from(rolesOn).sort((a, b) => a.localeCompare(b)),
+    rolesOff: Array.from(rolesOff).sort((a, b) => a.localeCompare(b)),
+    appliedOverrides: [...decision.appliedOverrides, ...applied],
+    confidence: applied.length > 0 ? "high" : decision.confidence,
+    consultSolomon: false,
+    rationale: `${decision.rationale} | solomon=${ruleVerdict}${applied.length ? ` applied=${applied.join(",")}` : ""}`,
+  };
+}

package/src/brain/standby-scheduler.js

@@ -0,0 +1,8 @@
+// Shim de compatibilidad: standby-scheduler vive ahora en karajan-core.
+// Mantiene la ruta para callers internos del CLI.
+export {
+  _resetScheduledForTests,
+  scheduleResume,
+  cancelScheduled,
+  reconcileAll,
+} from "karajan-core/standby-scheduler";

package/src/brain/standby-store.js

@@ -0,0 +1,12 @@
+// Shim de compatibilidad: standby-store vive ahora en karajan-core.
+// Mantiene la ruta para callers internos del CLI.
+export {
+  standbyDir,
+  standbyDoneDir,
+  persistStandby,
+  buildStandbyState,
+  loadStandby,
+  listPendingStandby,
+  markStandbyDone,
+  acquireStandbyLock,
+} from "karajan-core/standby-store";

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

@@ -0,0 +1,235 @@
+// 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, markStandbyDone } 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,
+  // Standby-in-process: when the cooldown is short enough we keep the
+  // process alive and `await sleepFn(retryAfter)`, then retry the
+  // agent. The user sees nothing terminal — kj just pauses. A SIGINT /
+  // SIGTERM during the wait prints `kj standby resume <id>` and exits
+  // cleanly. For waits longer than this the process exits straight
+  // away (a multi-day weekly cap is not worth keeping kj running).
+  standbyWaitHoursMax: 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: the cooldown is too long for a short standby. Persist
+    // the snapshot first so a SIGINT / SIGTERM during the wait leaves a
+    // recoverable session on disk. Then either:
+    //   (a) wait in-process until cooldownUntil and retry (the common
+    //       case — daily quotas reset in a few hours), or
+    //   (b) when the wait would exceed `standbyWaitHoursMax`, return
+    //       action="hibernate" so the caller exits and the user
+    //       resumes later with `kj standby resume <id>` (weekly /
+    //       monthly caps).
+    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,
+          });
+        } catch (err) {
+          logger?.warn?.(`[brain] failed to persist standby: ${err.message}`);
+        }
+      }
+
+      const maxWaitMs = (policy.standbyWaitHoursMax ?? DEFAULT_FALLBACK_WAIT_HOURS) * ONE_HOUR;
+      const tooLongToWait = cls.retryAfter > maxWaitMs;
+
+      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 };
+      }
+
+      // Standby-in-process: keep kj alive, sleep until the cooldown,
+      // then retry. A SIGINT / SIGTERM during the wait prints the
+      // resume command and exits — the standby JSON is already on
+      // disk so the user can pick it up later.
+      const sid = sessionState?.sessionId ?? null;
+      const onSignal = (signal) => {
+        // eslint-disable-next-line no-console
+        console.log(`\n⏸  Standby interrupted (${signal}). Resume with:`);
+        // eslint-disable-next-line no-console
+        if (sid) console.log(`     kj standby resume ${sid}`);
+        // eslint-disable-next-line no-console
+        else console.log(`     kj standby list   (no session id was assigned)`);
+        process.exit(signal === "SIGINT" ? 130 : 143);
+      };
+      const detach = () => {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+      };
+      process.once("SIGINT", onSignal);
+      process.once("SIGTERM", onSignal);
+
+      const hours = Math.round((cls.retryAfter / ONE_HOUR) * 10) / 10;
+      logger?.info?.(`[brain] ${role}: standby for ~${hours}h until ${cls.retryUntil} (Ctrl+C to detach; will resume with 'kj standby resume ${sid}').`);
+      emit(emitter, "brain:standby-wait", eventBase, { role, class: cls.class, waitMs: cls.retryAfter, retryUntil: cls.retryUntil, standbyFile });
+
+      try {
+        await sleepFn(cls.retryAfter);
+      } finally {
+        detach();
+      }
+
+      // Wait finished without an interrupt — mark the standby JSON
+      // done so it does not auto-resume from disk later.
+      if (sid) {
+        try { markStandbyDone(sid); } catch { /* ignore */ }
+      }
+      emit(emitter, "brain:standby-resumed", eventBase, { role, class: cls.class });
+      continue;
+    }
+
+    // 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}` };
+  }
+}