@karajan-family/code 4.21.0

package/src/bootstrap.js

@@ -0,0 +1,276 @@
+/**
+ * Project bootstrap — mandatory prerequisite gate.
+ *
+ * Before any KJ tool that executes agents (kj_run, kj_code, kj_review, etc.),
+ * this module validates that ALL environment prerequisites are met.
+ *
+ * Philosophy: NEVER degrade gracefully. If something is missing, STOP and
+ * tell the user exactly what to fix. No silent fallbacks, no auto-disabling.
+ *
+ * Results are cached in `.kj-ready.json` per project (TTL-based) so that
+ * slow checks (SonarQube reachability, agent detection) don't repeat on
+ * every invocation.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ensureGitRepo } from "./utils/git.js";
+import { runCommand } from "./utils/process.js";
+import { checkBinary } from "./utils/agent-detect.js";
+import { exists } from "./utils/fs.js";
+import { getConfigPath, resolveRole } from "./config.js";
+import { isSonarReachable, sonarUp } from "./sonar/manager.js";
+import { withDocLink } from "./utils/doc-links.js";
+
+const BOOTSTRAP_VERSION = 1;
+const BOOTSTRAP_TTL_HOURS = 24;
+const BOOTSTRAP_FILENAME = ".kj-ready.json";
+
+function getPackageVersion() {
+  const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
+// ── Individual checks ────────────────────────────────────────────────
+
+async function checkGitRepo() {
+  let ok;
+  try {
+    ok = await ensureGitRepo();
+  } catch { /* git may not be installed */
+    ok = false;
+  }
+
+  if (!ok) {
+    // Auto-init: initialize git repo for new projects
+    const initResult = await runCommand("git", ["init"]);
+    if (initResult.exitCode !== 0) {
+      return {
+        name: "gitRepo",
+        ok: false,
+        detail: "Not a git repository and git init failed",
+        fix: "Ensure git is installed and you have write permissions to this directory."
+      };
+    }
+    return { name: "gitRepo", ok: true, detail: "Initialized new git repository", fix: null };
+  }
+
+  return { name: "gitRepo", ok: true, detail: "Inside a git repository", fix: null };
+}
+
+async function checkGitRemote() {
+  try {
+    const res = await runCommand("git", ["remote", "get-url", "origin"]);
+    if (res.exitCode === 0 && res.stdout.trim()) {
+      return { name: "gitRemote", ok: true, detail: res.stdout.trim(), fix: null };
+    }
+  } catch { /* fall through */ }
+  // No remote is acceptable for new projects — non-blocking
+  return {
+    name: "gitRemote",
+    ok: true,
+    detail: "No remote configured (new project)",
+    fix: null
+  };
+}
+
+async function checkConfigExists() {
+  const configPath = getConfigPath();
+  const configOk = await exists(configPath);
+  return {
+    name: "config",
+    ok: configOk,
+    detail: configOk ? configPath : "Config file not found",
+    fix: configOk ? null : "Run 'kj_init' to create your Karajan config file."
+  };
+}
+
+async function checkCoreBinaries() {
+  const missing = [];
+  for (const bin of ["node", "npm", "git"]) {
+    const result = await checkBinary(bin);
+    if (!result.ok) {
+      missing.push(bin);
+    }
+  }
+  if (missing.length > 0) {
+    return {
+      name: "coreBinaries",
+      ok: false,
+      detail: `Missing: ${missing.join(", ")}`,
+      fix: `Install missing binaries: ${missing.join(", ")}.`
+    };
+  }
+  return { name: "coreBinaries", ok: true, detail: "node, npm, git available", fix: null };
+}
+
+async function checkConfiguredAgents(config) {
+  const { provider } = resolveRole(config, "coder");
+  if (!provider) {
+    return {
+      name: "agents",
+      ok: false,
+      detail: "No coder provider configured",
+      fix: "Run 'kj_init' or set a coder provider in kj.config.yml."
+    };
+  }
+  const result = await checkBinary(provider);
+  if (!result.ok) {
+    return {
+      name: "agents",
+      ok: false,
+      detail: `Coder agent "${provider}" not found`,
+      fix: `Install "${provider}" CLI. Run 'kj_doctor' for installation instructions.`
+    };
+  }
+  return { name: "agents", ok: true, detail: `coder: ${provider}`, fix: null };
+}
+
+async function checkSonarQubeReady(config) {
+  if (config.sonarqube?.enabled === false) {
+    return { name: "sonarqube", ok: true, detail: "Disabled in config", fix: null };
+  }
+
+  const host = config.sonarqube?.host || "http://localhost:9000";
+
+  // First attempt
+  let reachable = await isSonarReachable(host);
+  if (reachable) {
+    return { name: "sonarqube", ok: true, detail: `Reachable at ${host}`, fix: null };
+  }
+
+  // Auto-remediation: start and wait up to 60s for SonarQube to be ready
+  try {
+    await sonarUp(host);
+    const deadline = Date.now() + 60000;
+    while (Date.now() < deadline) {
+      reachable = await isSonarReachable(host);
+      if (reachable) {
+        return { name: "sonarqube", ok: true, detail: `Started and reachable at ${host}`, fix: null };
+      }
+      await new Promise(r => setTimeout(r, 5000));
+    }
+  } catch { /* fall through */ }
+
+  return {
+    name: "sonarqube",
+    ok: false,
+    detail: `Not reachable at ${host}`,
+    fix: `Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.`
+  };
+}
+
+// ── Bootstrap file management ────────────────────────────────────────
+
+function bootstrapPath(projectDir) {
+  return path.join(projectDir, BOOTSTRAP_FILENAME);
+}
+
+async function readBootstrapFile(projectDir) {
+  try {
+    const raw = await fs.readFile(bootstrapPath(projectDir), "utf8");
+    return JSON.parse(raw);
+  } catch { /* bootstrap file may not exist or contain invalid JSON */
+    return null;
+  }
+}
+
+function isBootstrapValid(bootstrap, projectDir) {
+  if (!bootstrap || bootstrap.version !== BOOTSTRAP_VERSION) return false;
+  if (bootstrap.karajanVersion !== getPackageVersion()) return false;
+  if (bootstrap.projectDir !== projectDir) return false;
+  const age = Date.now() - new Date(bootstrap.createdAt).getTime();
+  if (age > BOOTSTRAP_TTL_HOURS * 3600 * 1000) return false;
+  return true;
+}
+
+async function writeBootstrapFile(projectDir, checks) {
+  const data = {
+    version: BOOTSTRAP_VERSION,
+    karajanVersion: getPackageVersion(),
+    createdAt: new Date().toISOString(),
+    projectDir,
+    checks: Object.fromEntries(checks.map(c => [c.name, { ok: c.ok, detail: c.detail }]))
+  };
+  await fs.writeFile(bootstrapPath(projectDir), JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function formatBootstrapFailure(failures) {
+  const lines = failures.map(f =>
+    `  FAIL  ${f.name}: ${f.detail}\n        Fix: ${f.fix}`
+  );
+  return withDocLink([
+    "BOOTSTRAP FAILED — Environment not ready for Karajan Code.\n",
+    "The following prerequisite(s) are not met:\n",
+    ...lines,
+    "",
+    "Run 'kj_doctor' for a complete environment diagnostic.",
+    "Do NOT work around these issues — fix them properly."
+  ].join("\n"), "bootstrap_failed");
+}
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Ensure the project environment is ready for KJ execution.
+ * Reads cached `.kj-ready.json` if valid; otherwise runs all checks.
+ * Throws Error with actionable message if any prerequisite fails.
+ */
+export async function ensureBootstrap(projectDir, config) {
+  // Plugin discovery runs unconditionally on every bootstrap, regardless
+  // of whether the bootstrap cache says environment is valid. A user
+  // dropping a new file into `.karajan/plugins/` expects it to be picked
+  // up without running `kj init` again.
+  //
+  // Pre-v2.7.5 this was never called — `loadPlugins()` was exported but
+  // never imported from production code, so any plugin the user added
+  // was silently ignored. Fixed in TSK-0329.
+  try {
+    const { loadPlugins } = await import("./plugins/loader.js");
+    await loadPlugins({ projectDir });
+  } catch { /* plugin system failed — non-blocking, continue bootstrap */ }
+
+  // TSK-0339: register the Planning Game adapter in the integrations registry
+  // when enabled. The orchestrator no longer imports `src/planning-game/*`
+  // directly — it calls `getIntegration("tracker")?.hookName(...)` instead.
+  // Other trackers (GitHub Projects, Jira, Linear, …) drop in by writing
+  // a sibling adapter that calls `registerIntegration("tracker", …)`.
+  if (config?.planning_game?.enabled) {
+    try {
+      const { registerPgAdapter } = await import("./planning-game/pipeline-adapter.js");
+      await registerPgAdapter();
+    } catch { /* PG registration failed — non-blocking, continue bootstrap */ }
+  }
+
+  const cached = await readBootstrapFile(projectDir);
+  if (isBootstrapValid(cached, projectDir)) {
+    return; // Environment already validated
+  }
+
+  const checks = await Promise.all([
+    checkGitRepo(),
+    checkGitRemote(),
+    checkConfigExists(),
+    checkCoreBinaries(),
+    checkConfiguredAgents(config),
+    checkSonarQubeReady(config)
+  ]);
+
+  const failures = checks.filter(c => !c.ok);
+  if (failures.length > 0) {
+    throw new Error(formatBootstrapFailure(failures));
+  }
+
+  await writeBootstrapFile(projectDir, checks);
+}
+
+/**
+ * Delete `.kj-ready.json` to force re-validation on next run.
+ */
+export async function invalidateBootstrap(projectDir) {
+  try {
+    await fs.unlink(bootstrapPath(projectDir));
+  } catch { /* file may not exist */ }
+}

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

@@ -0,0 +1,116 @@
+// 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;
+
+// `error\s+authenticating` + `IneligibleTierError` (KJC-BUG-0113): the
+// retired Gemini Code Assist CLI fails with "Error authenticating:
+// IneligibleTierError … migrate to Antigravity" — it classified as
+// UNKNOWN_FATAL and left the run without the AUTH escalation message.
+const AUTH_PATTERNS = /\b401\b|\b403\b|unauthorized|invalid\s+api\s+key|authentication\s+failed|expired\s+token|error\s+authenticating|IneligibleTierError/i;
+const SILENCED_PATTERNS = /killed\s+after\s+\d+\s*ms|silence\s*timeout|no\s+output\s+for\s+\d+/i;
+// `session\s+limit` / `weekly\s+limit` cover Claude Code's usage caps
+// ("You've hit your session limit · resets 10:10pm"). Without them the
+// message fell through to UNKNOWN_FATAL and the run aborted instead of
+// hibernating until the reset.
+// Decomposed by family (S5843, complexity 36 → 3 named groups). The
+// union of tokens is identical to the original single alternation.
+const RATE_LIMIT_GROUPS = [
+  /rate\s*limit|too\s+many\s+requests|\b429\b|throttl/i,
+  /exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached/i,
+  /usage\s+limit|monthly\s+limit|weekly\s+limit|daily\s+limit|session\s+limit/i,
+];
+const RATE_LIMIT_PATTERNS = { test: (text) => RATE_LIMIT_GROUPS.some((re) => re.test(text)) };
+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/decision-tracker.js

@@ -0,0 +1,125 @@
+/**
+ * Tracks every routing decision the Brain makes during a session and enforces
+ * safety limits (max decisions per session, indecision-loop detection).
+ *
+ * Decisions are appended to `session.brainDecisions`. Consumers call
+ * `recordDecision(tracker, decision, context)` after a buildDecision() call
+ * and `checkLimits(tracker)` before making another decision.
+ *
+ * The limits are soft guards, not hard failures: hitting a limit surfaces
+ * a status that the orchestrator can use to escalate to Solomon or pause
+ * the session for human input.
+ */
+
+import { setBrainDecisions } from "../session/mutators.js";
+
+export const DEFAULT_MAX_DECISIONS = 20;
+export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in a row
+
+/**
+ * @typedef {Object} RecordedDecision
+ * @property {number} seq
+ * @property {string} at                            - ISO timestamp
+ * @property {string} intent                        - e.g. "sw:medium" (taskType:level)
+ * @property {string[]} rolesOn
+ * @property {"low"|"medium"|"high"} confidence
+ * @property {string} rationale
+ * @property {string[]} appliedOverrides
+ */
+
+/**
+ * @typedef {Object} TrackerStatus
+ * @property {"ok"|"max-reached"|"indecision"} status
+ * @property {number} decisionCount
+ * @property {string} [detail]
+ */
+
+/**
+ * Initialize a tracker bound to a session. If the session already has a
+ * `brainDecisions` array (e.g. from a resumed session), keep it.
+ *
+ * @param {Object} session
+ * @param {{ max?: number }} [options]
+ * @returns {{ session: Object, max: number }}
+ */
+export function createTracker(session, { max = DEFAULT_MAX_DECISIONS } = {}) {
+  if (!Array.isArray(session.brainDecisions)) {
+    setBrainDecisions(session, []);
+  }
+  return { session, max };
+}
+
+/**
+ * Append a decision to the tracker.
+ *
+ * @param {{ session: Object, max: number }} tracker
+ * @param {Object} decision                         - output of buildDecision()
+ * @param {{ taskType?: string, level?: string }} intent
+ * @returns {RecordedDecision}
+ */
+export function recordDecision(tracker, decision, intent = {}) {
+  const seq = tracker.session.brainDecisions.length + 1;
+  const entry = {
+    seq,
+    at: new Date().toISOString(),
+    intent: `${intent.taskType || "?"}:${intent.level || "?"}`,
+    rolesOn: Array.isArray(decision.rolesOn) ? [...decision.rolesOn] : [],
+    confidence: decision.confidence || "medium",
+    rationale: decision.rationale || "",
+    appliedOverrides: Array.isArray(decision.appliedOverrides) ? [...decision.appliedOverrides] : [],
+  };
+  tracker.session.brainDecisions.push(entry);
+  return entry;
+}
+
+/**
+ * Compute status of the tracker. Called BEFORE recording a new decision so
+ * the orchestrator can decide to escalate instead of calling the Brain again.
+ *
+ * @param {{ session: Object, max: number }} tracker
+ * @returns {TrackerStatus}
+ */
+export function checkLimits(tracker) {
+  const decisions = tracker.session.brainDecisions || [];
+  const decisionCount = decisions.length;
+
+  if (decisionCount >= tracker.max) {
+    return {
+      status: "max-reached",
+      decisionCount,
+      detail: `Brain made ${decisionCount} decisions (limit ${tracker.max}). Escalate to Solomon or human.`,
+    };
+  }
+
+  // Indecision loop: last N decisions share the exact same intent.
+  const window = decisions.slice(-INDECISION_REPEAT_THRESHOLD);
+  if (window.length >= INDECISION_REPEAT_THRESHOLD && window.every((d) => d.intent === window[0].intent)) {
+    return {
+      status: "indecision",
+      decisionCount,
+      detail: `Brain classified the same intent (${window[0].intent}) ${INDECISION_REPEAT_THRESHOLD} times in a row — loop detected.`,
+    };
+  }
+
+  return { status: "ok", decisionCount };
+}
+
+/**
+ * Build a short summary of all decisions made in the session. Useful for the
+ * final report and for debugging.
+ *
+ * @param {{ session: Object }} tracker
+ * @returns {{ total: number, byIntent: Record<string,number>, lastRationale: string }}
+ */
+export function summarize(tracker) {
+  const decisions = tracker.session.brainDecisions || [];
+  const byIntent = {};
+  for (const d of decisions) {
+    byIntent[d.intent] = (byIntent[d.intent] || 0) + 1;
+  }
+  return {
+    total: decisions.length,
+    byIntent,
+    lastRationale: decisions.at(-1)?.rationale ?? "",
+  };
+}