karajan-code 1.34.3 → 1.35.0

package/README.md

@@ -116,7 +116,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 | **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
 | **Codex** | `codex` | `npm install -g @openai/codex` |
 | **Gemini** | `gemini` | See [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pip install aider-chat` |
+| **Aider** | `aider` | `pipx install aider-chat` (or `pip3 install aider-chat`) |
 | **OpenCode** | `opencode` | See [OpenCode docs](https://github.com/nicepkg/opencode) |
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.

package/docs/README.es.md

@@ -124,7 +124,7 @@ Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-
 | **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
 | **Codex** | `codex` | `npm install -g @openai/codex` |
 | **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pip install aider-chat` |
+| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
 
 `kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
 

package/package.json

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

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 */ }
+}

package/src/commands/doctor.js

@@ -8,6 +8,7 @@ import { isSonarReachable } from "../sonar/manager.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+import { getInstallCommand } from "../utils/os-detect.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -205,7 +206,7 @@ async function checkBecariaInfra(config) {
 }
 
 async function checkRtk() {
-  const NOT_FOUND_DETAIL = "Not found — install for 60-90% token savings: brew install rtk";
+  const NOT_FOUND_DETAIL = `Not found — install for 60-90% token savings: ${getInstallCommand("rtk")}`;
   let detail = NOT_FOUND_DETAIL;
   try {
     const res = await runCommand("rtk", ["--version"]);

package/src/commands/init.js

@@ -8,6 +8,7 @@ import { getKarajanHome } from "../utils/paths.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
+import { getInstallCommand } from "../utils/os-detect.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -292,7 +293,7 @@ export async function initCommand({ logger, flags = {} }) {
   if (!hasRtk) {
     logger.info("");
     logger.info("RTK (Rust Token Killer) can reduce token usage by 60-90%.");
-    logger.info("  Install: brew install rtk && rtk init --global");
+    logger.info(`  Install: ${getInstallCommand("rtk")}`);
   }
 
   await setupSonarQube(config, logger);

package/src/config.js

@@ -77,7 +77,7 @@ const DEFAULTS = {
     },
     token: null,
     project_key: null,
-    admin_user: "admin",
+    admin_user: null,
     admin_password: null,
     coverage: {
       enabled: false,

package/src/mcp/server-handlers.js

@@ -24,6 +24,7 @@ import { resolveReviewProfile } from "../review/profiles.js";
 import { createRunLog, readRunLog } from "../utils/run-log.js";
 import { currentBranch } from "../utils/git.js";
 import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
+import { ensureBootstrap } from "../bootstrap.js";
 
 /**
  * Resolve the user's project directory.
@@ -118,6 +119,11 @@ const ERROR_CLASSIFIERS = [
     test: (lower) => lower.includes("not a git repository"),
     category: "git_error",
     suggestion: "Current directory is not a git repository. Navigate to your project root or initialize git with 'git init'."
+  },
+  {
+    test: (lower) => lower.includes("bootstrap failed"),
+    category: "bootstrap_error",
+    suggestion: "Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly."
   }
 ];
 
@@ -149,6 +155,16 @@ export async function assertNotOnBaseBranch(config) {
   }
 }
 
+/**
+ * Run bootstrap gate: validate all environment prerequisites before execution.
+ * Throws if any prerequisite fails.
+ */
+async function runBootstrapGate(server, a) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { config } = await loadConfig(projectDir);
+  await ensureBootstrap(projectDir, config);
+}
+
 export function enrichedFailPayload(error, toolName) {
   const msg = error?.message || String(error);
   const { category, suggestion } = classifyError(error);
@@ -191,7 +207,7 @@ export function buildAskQuestion(server) {
 
 const MAX_AUTO_RESUMES = 2;
 const NON_RECOVERABLE_CATEGORIES = new Set([
-  "config_error", "auth_error", "agent_missing", "branch_error", "git_error"
+  "config_error", "auth_error", "agent_missing", "branch_error", "git_error", "bootstrap_error"
 ]);
 
 async function attemptAutoResume({ err, config, logger, emitter, askQuestion, runLog }) {
@@ -783,6 +799,7 @@ async function handleResume(a, server, extra) {
   if (!a.sessionId) {
     return failPayload("Missing required field: sessionId");
   }
+  await runBootstrapGate(server, a);
   if (a.answer) {
     const validation = validateResumeAnswer(a.answer);
     if (!validation.valid) {
@@ -804,6 +821,7 @@ async function handleRun(a, server, extra) {
       return failPayload(`Invalid taskType "${a.taskType}". Valid values: ${[...validTypes].join(", ")}`);
     }
   }
+  await runBootstrapGate(server, a);
   if (!isPreflightAcked()) {
     // Auto-acknowledge with defaults for autonomous operation
     ackPreflight({});
@@ -818,6 +836,7 @@ async function handleCode(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   if (!isPreflightAcked()) {
     // Auto-acknowledge with defaults for autonomous operation
     ackPreflight({});
@@ -832,6 +851,7 @@ async function handleReview(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   return handleReviewDirect(a, server, extra);
 }
 
@@ -839,6 +859,7 @@ async function handlePlan(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   return handlePlanDirect(a, server, extra);
 }
 
@@ -850,6 +871,7 @@ async function handleDiscover(a, server, extra) {
   if (a.mode && !validModes.has(a.mode)) {
     return failPayload(`Invalid mode "${a.mode}". Valid values: ${[...validModes].join(", ")}`);
   }
+  await runBootstrapGate(server, a);
   return handleDiscoverDirect(a, server, extra);
 }
 
@@ -857,6 +879,7 @@ async function handleTriage(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   return handleTriageDirect(a, server, extra);
 }
 
@@ -864,6 +887,7 @@ async function handleResearcher(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   return handleResearcherDirect(a, server, extra);
 }
 
@@ -871,10 +895,12 @@ async function handleArchitect(a, server, extra) {
   if (!a.task) {
     return failPayload("Missing required field: task");
   }
+  await runBootstrapGate(server, a);
   return handleArchitectDirect(a, server, extra);
 }
 
 async function handleAudit(a, server, extra) {
+  await runBootstrapGate(server, a);
   return handleAuditDirect(a, server, extra);
 }
 
@@ -892,6 +918,11 @@ async function handleBoard(a) {
   }
 }
 
+async function handleScan(a, server) {
+  await runBootstrapGate(server, a);
+  return runKjCommand({ command: "scan", options: a });
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -901,7 +932,7 @@ const toolHandlers = {
   kj_agents:    (a) => handleAgents(a),
   kj_preflight: (a) => handlePreflight(a),
   kj_config:    (a) => runKjCommand({ command: "config", commandArgs: a.json ? ["--json"] : [], options: a }),
-  kj_scan:      (a) => runKjCommand({ command: "scan", options: a }),
+  kj_scan:      (a, server) => handleScan(a, server),
   kj_roles:     (a) => handleRoles(a),
   kj_report:    (a) => runKjCommand({ command: "report", commandArgs: buildReportArgs(a), options: a }),
   kj_resume:    (a, server, extra) => handleResume(a, server, extra),

package/src/orchestrator/preflight-checks.js

@@ -2,16 +2,18 @@
  * Preflight environment checks for kj_run.
  *
  * Runs AFTER policy resolution (so we know which stages are active)
- * and BEFORE session iteration loop (so we fail fast or degrade gracefully).
+ * and BEFORE session iteration loop (so we fail fast).
  *
- * Design: always returns ok:true (graceful degradation, never hard-fail).
- * Disabled stages are auto-disabled via configOverrides instead of blocking.
+ * Design: SonarQube checks are BLOCKING when enabled — if SonarQube is
+ * configured but not available, the pipeline STOPS with a clear error.
+ * Security agent checks remain graceful (warning, auto-disable).
  */
 
 import { checkBinary } from "../utils/agent-detect.js";
 import { isSonarReachable, sonarUp } from "../sonar/manager.js";
 import { runCommand } from "../utils/process.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
+import { loadSonarCredentials } from "../sonar/credentials.js";
 
 function normalizeApiHost(rawHost) {
   return String(rawHost || "http://localhost:9000").replace(/host\.docker\.internal/g, "localhost");
@@ -75,14 +77,19 @@ async function checkSonarAuth(config) {
     }
   }
 
-  // Try admin credentials to generate a token
-  const adminUser = process.env.KJ_SONAR_ADMIN_USER || config.sonarqube?.admin_user || "admin";
+  // Try admin credentials: env vars → config → ~/.karajan/sonar-credentials.json (NO default admin/admin)
+  const fileCreds = await loadSonarCredentials() || {};
+  const adminUser = process.env.KJ_SONAR_ADMIN_USER || config.sonarqube?.admin_user || fileCreds.user;
   const candidates = [
     process.env.KJ_SONAR_ADMIN_PASSWORD,
     config.sonarqube?.admin_password,
-    "admin"
+    fileCreds.password
   ].filter(Boolean);
 
+  if (!adminUser || candidates.length === 0) {
+    return { name: "sonar-auth", ok: false, detail: "No Sonar token or admin credentials configured. Set KJ_SONAR_TOKEN, configure sonarqube.token in kj.config.yml, or save credentials in ~/.karajan/sonar-credentials.json." };
+  }
+
   for (const password of [...new Set(candidates)]) {
     const validateRes = await runCommand("curl", [
       "-sS", "-u", `${adminUser}:${password}`,
@@ -128,6 +135,10 @@ async function checkSecurityAgent(config) {
 /**
  * Run preflight environment checks.
  *
+ * SonarQube checks are BLOCKING: if SonarQube is enabled but not available,
+ * ok will be false and errors[] will contain actionable fix instructions.
+ * Security agent checks remain graceful (auto-disable via configOverrides).
+ *
  * @param {object} opts
  * @param {object} opts.config - Karajan config
  * @param {object} opts.logger - Logger instance
@@ -135,7 +146,7 @@ async function checkSecurityAgent(config) {
  * @param {object} opts.eventBase - Base event data
  * @param {object} opts.resolvedPolicies - Output from applyPolicies()
  * @param {boolean} opts.securityEnabled - Whether security stage is enabled
- * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[] }}
+ * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[], errors: object[] }}
  */
 export async function runPreflightChecks({ config, logger, emitter, eventBase, resolvedPolicies, securityEnabled }) {
   const sonarEnabled = Boolean(config.sonarqube?.enabled) && resolvedPolicies.sonar !== false;
@@ -148,6 +159,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     remediations: [],
     configOverrides: {},
     warnings: [],
+    errors: [],
   };
 
   // Short-circuit: nothing to check
@@ -171,20 +183,24 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     result.checks.push(dockerCheck);
 
     emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
-      status: dockerCheck.ok ? "ok" : "warn",
+      status: dockerCheck.ok ? "ok" : "fail",
       message: `Docker: ${dockerCheck.detail}`,
       detail: dockerCheck
     }));
 
     if (!dockerCheck.ok) {
-      result.configOverrides.sonarDisabled = true;
-      result.warnings.push("Docker not available — SonarQube auto-disabled");
-      logger.warn("Preflight: Docker not found, disabling SonarQube");
+      result.ok = false;
+      result.errors.push({
+        check: "docker",
+        message: "Docker not available but SonarQube is enabled.",
+        fix: "Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+      });
+      logger.error("Preflight: Docker not found — SonarQube requires Docker");
 
       // Skip remaining sonar checks, continue to security
       if (!securityEnabled) {
         emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
-          status: "warn", message: "Preflight completed with warnings", detail: result
+          status: "fail", message: "Preflight FAILED — environment not ready", detail: result
         }));
         return result;
       }
@@ -192,7 +208,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
   }
 
   // --- 2. SonarQube reachable ---
-  if (sonarEnabled && !result.configOverrides.sonarDisabled) {
+  if (sonarEnabled && result.ok) {
     const reachableCheck = await checkSonarReachable(sonarHost);
     result.checks.push(reachableCheck);
 
@@ -201,25 +217,29 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     }
 
     emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
-      status: reachableCheck.ok ? "ok" : "warn",
+      status: reachableCheck.ok ? "ok" : "fail",
       message: `SonarQube reachability: ${reachableCheck.detail}`,
       detail: reachableCheck
     }));
 
     if (!reachableCheck.ok) {
-      result.configOverrides.sonarDisabled = true;
-      result.warnings.push("SonarQube not reachable — auto-disabled");
-      logger.warn("Preflight: SonarQube not reachable after remediation, disabling");
+      result.ok = false;
+      result.errors.push({
+        check: "sonar-reachable",
+        message: `SonarQube not reachable at ${sonarHost}.`,
+        fix: "Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+      });
+      logger.error("Preflight: SonarQube not reachable after remediation attempt");
     }
   }
 
   // --- 3. SonarQube auth/token ---
-  if (sonarEnabled && !result.configOverrides.sonarDisabled) {
+  if (sonarEnabled && result.ok) {
     const authCheck = await checkSonarAuth(config);
     result.checks.push(authCheck);
 
     emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
-      status: authCheck.ok ? "ok" : "warn",
+      status: authCheck.ok ? "ok" : "fail",
       message: `SonarQube auth: ${authCheck.detail}`,
       detail: { name: authCheck.name, ok: authCheck.ok, detail: authCheck.detail }
     }));
@@ -229,13 +249,17 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.remediations.push("Sonar token resolved and cached in KJ_SONAR_TOKEN");
       logger.info("Preflight: Sonar token resolved and cached");
     } else if (!authCheck.ok) {
-      result.configOverrides.sonarDisabled = true;
-      result.warnings.push("SonarQube auth failed — auto-disabled");
-      logger.warn("Preflight: Sonar auth failed, disabling SonarQube");
+      result.ok = false;
+      result.errors.push({
+        check: "sonar-auth",
+        message: "SonarQube authentication failed.",
+        fix: "Regenerate the SonarQube token and update it via kj_init or in kj.config.yml under sonarqube.token."
+      });
+      logger.error("Preflight: Sonar auth failed");
     }
   }
 
-  // --- 4. Security agent ---
+  // --- 4. Security agent (graceful — only warning, not blocking) ---
   if (securityEnabled) {
     const secCheck = await checkSecurityAgent(config);
     result.checks.push(secCheck);
@@ -253,12 +277,15 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     }
   }
 
+  const hasErrors = result.errors.length > 0;
   const hasWarnings = result.warnings.length > 0;
   emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
-    status: hasWarnings ? "warn" : "ok",
-    message: hasWarnings
-      ? `Preflight completed with ${result.warnings.length} warning(s)`
-      : "Preflight passed — all checks OK",
+    status: hasErrors ? "fail" : hasWarnings ? "warn" : "ok",
+    message: hasErrors
+      ? `Preflight FAILED — ${result.errors.length} blocking issue(s)`
+      : hasWarnings
+        ? `Preflight completed with ${result.warnings.length} warning(s)`
+        : "Preflight passed — all checks OK",
     detail: result
   }));
 

package/src/orchestrator.js

@@ -886,9 +886,16 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   session.preflight = preflightResult;
   await saveSession(session);
 
-  if (preflightResult.configOverrides.sonarDisabled) {
-    updatedConfig = { ...updatedConfig, sonarqube: { ...updatedConfig.sonarqube, enabled: false } };
+  // Hard fail if blocking checks failed (SonarQube enabled but not available)
+  if (!preflightResult.ok) {
+    const errorLines = (preflightResult.errors || [])
+      .map(e => `  - ${e.message}\n    Fix: ${e.fix}`)
+      .join("\n");
+    throw new Error(
+      `Preflight FAILED — environment changed during session. Fix the issues and retry:\n${errorLines}`
+    );
   }
+
   if (preflightResult.configOverrides.securityDisabled) {
     pipelineFlags.securityEnabled = false;
   }

package/src/sonar/credentials.js

@@ -0,0 +1,35 @@
+/**
+ * Load SonarQube admin credentials from ~/.karajan/sonar-credentials.json.
+ *
+ * File format:
+ * {
+ *   "user": "admin",
+ *   "password": "your-password"
+ * }
+ *
+ * Returns { user, password } or { user: null, password: null } if file missing.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const CREDENTIALS_FILENAME = "sonar-credentials.json";
+
+export async function loadSonarCredentials() {
+  try {
+    const filePath = path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+    const raw = await fs.readFile(filePath, "utf8");
+    const data = JSON.parse(raw);
+    return {
+      user: data.user || null,
+      password: data.password || null
+    };
+  } catch {
+    return { user: null, password: null };
+  }
+}
+
+export function credentialsPath() {
+  return path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+}

package/src/sonar/scanner.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { runCommand } from "../utils/process.js";
 import { sonarUp } from "./manager.js";
 import { resolveSonarProjectKey } from "./project-key.js";
+import { loadSonarCredentials } from "./credentials.js";
 
 export function buildScannerOpts(projectKey, scanner = {}) {
   const opts = [`-Dsonar.projectKey=${projectKey}`];
@@ -136,18 +137,18 @@ async function resolveSonarToken(config, apiHost) {
   const explicitToken = process.env.KJ_SONAR_TOKEN || process.env.SONAR_TOKEN || config.sonarqube.token;
   if (explicitToken) return explicitToken;
 
-  const adminUser = process.env.KJ_SONAR_ADMIN_USER || config.sonarqube.admin_user || "admin";
+  // Resolve admin credentials from: env vars → config → ~/.karajan/sonar-credentials.json
+  const fileCreds = await loadSonarCredentials() || {};
+  const adminUser = process.env.KJ_SONAR_ADMIN_USER || config.sonarqube.admin_user || fileCreds.user;
   const candidates = [
     process.env.KJ_SONAR_ADMIN_PASSWORD,
     config.sonarqube.admin_password,
-    "admin"
+    fileCreds.password
   ].filter(Boolean);
 
+  if (!adminUser || candidates.length === 0) return null;
+
   for (const password of new Set(candidates)) {
-    if (password === "admin") {
-      // eslint-disable-next-line no-console
-      console.warn("[karajan] WARNING: Using default admin/admin credentials for SonarQube. Set KJ_SONAR_TOKEN for production use.");
-    }
     const valid = await validateAdminCredentials(apiHost, adminUser, password);
     if (!valid) continue;
     const token = await generateUserToken(apiHost, adminUser, password);
@@ -224,7 +225,7 @@ export async function runSonarScan(config, projectKey = null) {
       ok: false,
       stdout: "",
       stderr:
-        "Unable to resolve Sonar token. Tried configured token/password and fallback admin/admin.",
+        "Unable to resolve Sonar token. Set KJ_SONAR_TOKEN env var, configure sonarqube.token in kj.config.yml, or save credentials in ~/.karajan/sonar-credentials.json.",
       exitCode: 1
     };
   }

package/src/utils/agent-detect.js

@@ -1,12 +1,13 @@
 import { runCommand } from "./process.js";
 import { resolveBin } from "../agents/resolve-bin.js";
+import { getInstallCommand } from "./os-detect.js";
 
 const KNOWN_AGENTS = [
-  { name: "claude", install: "npm install -g @anthropic-ai/claude-code" },
-  { name: "codex", install: "npm install -g @openai/codex" },
-  { name: "gemini", install: "npm install -g @google/gemini-cli (or check https://geminicli.com/docs/get-started/installation/)" },
-  { name: "aider", install: "pip install aider-chat" },
-  { name: "opencode", install: "curl -fsSL https://opencode.ai/install | bash (or see https://opencode.ai)" }
+  { name: "claude", install: getInstallCommand("claude") },
+  { name: "codex", install: getInstallCommand("codex") },
+  { name: "gemini", install: getInstallCommand("gemini") },
+  { name: "aider", install: getInstallCommand("aider") },
+  { name: "opencode", install: getInstallCommand("opencode") }
 ];
 
 export async function checkBinary(name, versionArg = "--version") {

package/src/utils/os-detect.js

@@ -0,0 +1,45 @@
+import os from "node:os";
+
+/**
+ * Detect platform and return OS-appropriate install commands.
+ */
+export function getPlatform() {
+  const platform = os.platform();
+  return platform === "darwin" ? "macos" : "linux";
+}
+
+const INSTALL_COMMANDS = {
+  rtk: {
+    macos: "brew install rtk && rtk init --global",
+    linux: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh && rtk init --global"
+  },
+  claude: {
+    macos: "npm install -g @anthropic-ai/claude-code",
+    linux: "npm install -g @anthropic-ai/claude-code"
+  },
+  codex: {
+    macos: "npm install -g @openai/codex",
+    linux: "npm install -g @openai/codex"
+  },
+  gemini: {
+    macos: "npm install -g @google/gemini-cli",
+    linux: "npm install -g @google/gemini-cli"
+  },
+  aider: {
+    macos: "pipx install aider-chat",
+    linux: "pipx install aider-chat || pip3 install aider-chat"
+  },
+  opencode: {
+    macos: "curl -fsSL https://opencode.ai/install | bash",
+    linux: "curl -fsSL https://opencode.ai/install | bash"
+  },
+  docker: {
+    macos: "brew install --cask docker",
+    linux: "sudo apt install docker.io docker-compose-v2 (or see https://docs.docker.com/engine/install/)"
+  }
+};
+
+export function getInstallCommand(tool) {
+  const platform = getPlatform();
+  return INSTALL_COMMANDS[tool]?.[platform] || INSTALL_COMMANDS[tool]?.linux || `Install ${tool} manually`;
+}