karajan-code 1.34.4 → 1.36.0

package/README.md

@@ -152,6 +152,7 @@ Use `kj roles show <role>` to inspect any template.
 Karajan auto-detects and auto-configures everything it can:
 
 - **TDD**: Detects test framework (vitest, jest, mocha) → auto-enables TDD
+- **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions — never silently degrades
 - **SonarQube**: Auto-starts Docker container, generates config if missing
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
@@ -163,9 +164,9 @@ No per-project configuration required. If you want to customize, config is layer
 
 Because it should be.
 
-Karajan has **1847 tests** across 149 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
+Karajan has **1966 tests** across 157 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
 
-This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **52 releases in 23 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
+This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **55 releases in 26 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
 
 ## Recommended companions
 

package/docs/README.es.md

@@ -29,8 +29,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 
 **Caracteristicas principales:**
 - **Pipeline multi-agente** con 11 roles configurables
-- **4 agentes de IA soportados**: Claude, Codex, Gemini, Aider
-- **Servidor MCP** con 15 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **5 agentes de IA soportados**: Claude, Codex, Gemini, Aider, OpenCode
+- **Servidor MCP** con 20 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
+- **Bootstrap obligatorio** — valida prerequisitos del entorno (git, remote, config, agentes, SonarQube) antes de cada ejecucion. Si algo falta, para con instrucciones claras
 - **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
 - **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
 - **Perfiles de revision** — standard, strict, relaxed, paranoid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.34.4",
+  "version": "1.36.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

@@ -5,21 +5,28 @@ import { resolveBin } from "./resolve-bin.js";
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["--yes", "--message", task.prompt];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("aider"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    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;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["--yes", "--message", task.prompt];
     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;
+  }
+
+  async _exec(task, model) {
+    const args = ["--yes", "--message", task.prompt];
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("aider"), args, {
       onOutput: task.onOutput,

package/src/agents/base-agent.js

@@ -1,3 +1,12 @@
+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 {
   constructor(name, config, logger) {
     this.name = name;
@@ -24,4 +33,10 @@ export class BaseAgent {
     if (role === "reviewer") return false;
     return Boolean(this.config?.coder_options?.auto_approve);
   }
+
+  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

@@ -35,6 +35,29 @@ function collectAssistantText(obj) {
     .map(block => block.text);
 }
 
+/**
+ * Extract usage metrics from stream-json/json NDJSON output.
+ * Looks for the "result" line which contains total_cost_usd,
+ * usage.input_tokens/output_tokens, and modelUsage.
+ * Returns an object with tokens_in, tokens_out, cost_usd, model or null if not found.
+ */
+export function extractUsageFromStreamJson(raw) {
+  const lines = (raw || "").split("\n").filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = tryParseJson(lines[i]);
+    if (!obj || obj.type !== "result") continue;
+
+    const tokens_in = obj.usage?.input_tokens ?? 0;
+    const tokens_out = obj.usage?.output_tokens ?? 0;
+    const cost_usd = obj.total_cost_usd ?? undefined;
+    const modelUsage = obj.modelUsage;
+    const model = modelUsage ? Object.keys(modelUsage)[0] || null : null;
+
+    return { tokens_in, tokens_out, cost_usd, model };
+  }
+  return null;
+}
+
 /**
  * Extract the final text result from stream-json NDJSON output.
  * Each line is a JSON object. We collect assistant text content from
@@ -135,8 +158,28 @@ const ALLOWED_TOOLS = [
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     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;
+  }
+
+  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;
+  }
+
+  async _runTaskExec(task, model, role) {
+    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
     if (model) args.push("--model", model);
 
     // Use stream-json when onOutput is provided to get real-time feedback
@@ -150,7 +193,8 @@ export class ClaudeAgent extends BaseAgent {
       }));
       const raw = pickOutput(res);
       const output = extractTextFromStreamJson(raw);
-      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+      const usage = extractUsageFromStreamJson(raw);
+      return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
     }
 
     // Without streaming, use json output to get structured response via stderr
@@ -158,12 +202,12 @@ export class ClaudeAgent extends BaseAgent {
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts());
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
-    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+    const usage = extractUsageFromStreamJson(raw);
+    return { ok: res.exitCode === 0, output, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
   }
 
-  async reviewTask(task) {
+  async _reviewTaskExec(task, model) {
     const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
-    const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,
@@ -171,6 +215,7 @@ export class ClaudeAgent extends BaseAgent {
       timeout: task.timeoutMs
     }));
     const raw = pickOutput(res);
-    return { ok: res.exitCode === 0, output: raw, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode };
+    const usage = extractUsageFromStreamJson(raw);
+    return { ok: res.exitCode === 0, output: raw, error: res.exitCode === 0 ? "" : raw, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/codex-agent.js

@@ -2,27 +2,48 @@ import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract token usage from Codex CLI stdout.
+ * Codex prints "tokens used\n<number>" at the end, where number may have comma separators.
+ * Returns { tokens_out } with the total token count, or null if not found.
+ * Since Codex doesn't split input/output, we assign the total to tokens_out
+ * as a conservative estimate for cost calculation.
+ */
+export function extractCodexTokens(stdout) {
+  const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
+  if (!match) return null;
+  const total = Number(match[1].replace(/,/g, ""));
+  if (!Number.isFinite(total) || total <= 0) return null;
+  return { tokens_in: 0, tokens_out: total };
+}
+
 export class CodexAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["exec"];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    if (this.isAutoApproveEnabled(role)) args.push("--full-auto");
-    args.push("-");
-    const res = await runCommand(resolveBin("codex"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs,
-      input: task.prompt
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    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;
   }
 
   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;
+  }
+
+  async _exec(task, model, role) {
     const args = ["exec"];
-    const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
+    if (role !== "reviewer" && this.isAutoApproveEnabled(role)) args.push("--full-auto");
     args.push("-");
     const res = await runCommand(resolveBin("codex"), args, {
       onOutput: task.onOutput,
@@ -30,6 +51,7 @@ export class CodexAgent extends BaseAgent {
       timeout: task.timeoutMs,
       input: task.prompt
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractCodexTokens(res.stdout);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/gemini-agent.js

@@ -5,21 +5,29 @@ import { resolveBin } from "./resolve-bin.js";
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["-p", task.prompt];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("gemini"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const result = await this._exec(task, model, "run");
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, "run");
+    }
+    return result;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["-p", task.prompt, "--output-format", "json"];
     const model = this.getRoleModel(role);
+    const result = await this._exec(task, model, "review");
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null, "review");
+    }
+    return result;
+  }
+
+  async _exec(task, model, mode) {
+    const args = ["-p", task.prompt];
+    if (mode === "review") args.push("--output-format", "json");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("gemini"), args, {
       onOutput: task.onOutput,

package/src/agents/model-registry.js

@@ -49,15 +49,16 @@ export function buildDefaultPricingTable() {
 }
 
 // Auto-register built-in models
+// Names must match what each CLI accepts as --model argument
 registerModel("claude", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
-registerModel("claude/sonnet", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
-registerModel("claude/opus", { provider: "anthropic", pricing: { input_per_million: 15, output_per_million: 75 } });
-registerModel("claude/haiku", { provider: "anthropic", pricing: { input_per_million: 0.25, output_per_million: 1.25 } });
+registerModel("sonnet", { provider: "anthropic", pricing: { input_per_million: 3, output_per_million: 15 } });
+registerModel("opus", { provider: "anthropic", pricing: { input_per_million: 15, output_per_million: 75 } });
+registerModel("haiku", { provider: "anthropic", pricing: { input_per_million: 0.25, output_per_million: 1.25 } });
 registerModel("codex", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
-registerModel("codex/o4-mini", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
-registerModel("codex/o3", { provider: "openai", pricing: { input_per_million: 10, output_per_million: 40 } });
+registerModel("o4-mini", { provider: "openai", pricing: { input_per_million: 1.5, output_per_million: 4 } });
+registerModel("o3", { provider: "openai", pricing: { input_per_million: 10, output_per_million: 40 } });
 registerModel("gemini", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
-registerModel("gemini/pro", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
-registerModel("gemini/flash", { provider: "google", pricing: { input_per_million: 0.075, output_per_million: 0.3 } });
+registerModel("gemini-2.5-pro", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
+registerModel("gemini-2.0-flash", { provider: "google", pricing: { input_per_million: 0.075, output_per_million: 0.3 } });
 registerModel("aider", { provider: "aider", pricing: { input_per_million: 3, output_per_million: 15 } });
 registerModel("opencode", { provider: "opencode", pricing: { input_per_million: 0, output_per_million: 0 } });

package/src/agents/opencode-agent.js

@@ -5,22 +5,29 @@ import { resolveBin } from "./resolve-bin.js";
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
-    const args = ["run"];
     const model = this.getRoleModel(role);
-    if (model) args.push("--model", model);
-    args.push(task.prompt);
-    const res = await runCommand(resolveBin("opencode"), args, {
-      onOutput: task.onOutput,
-      silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
-    });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    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;
   }
 
   async reviewTask(task) {
     const role = task.role || "reviewer";
-    const args = ["run", "--format", "json"];
     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;
+  }
+
+  async _exec(task, model, jsonFormat) {
+    const args = ["run"];
+    if (jsonFormat) args.push("--format", "json");
     if (model) args.push("--model", model);
     args.push(task.prompt);
     const res = await runCommand(resolveBin("opencode"), args, {

package/src/bootstrap.js

@@ -0,0 +1,235 @@
+/**
+ * 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";
+
+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 = false;
+  try {
+    ok = await ensureGitRepo();
+  } catch {
+    ok = false;
+  }
+  return {
+    name: "gitRepo",
+    ok,
+    detail: ok ? "Inside a git repository" : "Not a git repository",
+    fix: "Run 'git init' in your project directory."
+  };
+}
+
+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 */ }
+  return {
+    name: "gitRemote",
+    ok: false,
+    detail: "origin remote not configured",
+    fix: "Run 'git remote add origin <your-repo-url>'."
+  };
+}
+
+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: try to start
+  try {
+    await sonarUp(host);
+    reachable = await isSonarReachable(host);
+    if (reachable) {
+      return { name: "sonarqube", ok: true, detail: `Started and reachable at ${host}`, fix: null };
+    }
+  } 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 {
+    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 [
+    "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");
+}
+
+// ── 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) {
+  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 */ }
+}