karajan-code 1.56.0 → 1.57.2

package/README.md

@@ -60,8 +60,7 @@ npm install -g karajan-code
 
 **Homebrew** (macOS):
 ```bash
-brew tap manufosela/tap
-brew install karajan-code
+brew install manufosela/tap/karajan-code
 ```
 
 **One-liner** (detects OS, installs via npm):
@@ -264,6 +263,14 @@ npm run validate      # Lint + test
 
 Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues). That's the most useful contribution at this stage.
 
+## Telemetry
+
+Karajan collects anonymous usage statistics to improve the tool:
+version, OS, command used, pipeline duration and success rate.
+No code, task descriptions, or personal data is ever sent.
+
+Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
+
 ## Links
 
 - [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))

package/docs/README.es.md

@@ -60,8 +60,7 @@ npm install -g karajan-code
 
 **Homebrew** (macOS):
 ```bash
-brew tap manufosela/tap
-brew install karajan-code
+brew install manufosela/tap/karajan-code
 ```
 
 **One-liner** (detecta SO, instala via npm):
@@ -237,6 +236,14 @@ npm run validate      # Lint + test
 
 Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [abre un issue](https://github.com/manufosela/karajan-code/issues). Es la contribucion mas util en esta fase.
 
+## Telemetria
+
+Karajan recopila estadisticas de uso anonimas para mejorar la herramienta:
+version, sistema operativo, comando utilizado, duracion del pipeline y tasa de exito.
+No se envia nunca codigo, descripciones de tareas ni datos personales.
+
+Desactivar: establece `telemetry: false` en `~/.karajan/kj.config.yml`
+
 ## Enlaces
 
 - [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))

package/package.json

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

package/scripts/ai-attribution-guard.yml

@@ -0,0 +1,77 @@
+# AI Attribution Guard — GitHub Action
+#
+# Copy this file to .github/workflows/ai-attribution-guard.yml in any repo.
+# Blocks PRs that contain AI attribution comments or Co-Authored-By lines.
+# No dependencies, no Node.js required. Pure bash + grep.
+
+name: AI Attribution Guard
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  scan:
+    name: Scan for AI attribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check PR diff for AI attribution
+        run: |
+          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD \
+            -- ':!*.png' ':!*.jpg' ':!*.svg' ':!*.ico' \
+               ':!*.lock' ':!package-lock.json' ':!yarn.lock' \
+               ':!*.min.js' ':!*.min.css' \
+               ':!.githooks/*' \
+            | grep '^+' \
+            | grep -v '^+++' \
+            || true)
+
+          [ -z "$DIFF" ] && echo "No diff to scan" && exit 0
+
+          # Attribution patterns (not functional references like provider: "claude")
+          ATTR='(Generated|Created|Written|Made|Built|Authored|Assisted|Powered|Produced) (by|with|using|via) .*(Claude|Anthropic|OpenAI|ChatGPT|GPT-[0-9]|Copilot|Gemini|Cursor|Windsurf|Codeium)'
+          COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
+          COMMENT='(//|#|/\*|\*|<!--|--)\s*.*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini).*(generated|assisted|helped|created|wrote|built|made)'
+
+          FOUND=""
+          for PAT in "$ATTR" "$COAUTH" "$COMMENT"; do
+            MATCH=$(echo "$DIFF" | grep -i -E "$PAT" || true)
+            [ -n "$MATCH" ] && FOUND="${FOUND}${MATCH}\n"
+          done
+
+          if [ -n "$FOUND" ]; then
+            echo "::error::AI attribution detected in PR diff"
+            echo -e "$FOUND"
+            echo ""
+            echo "Remove AI attribution comments/lines and push again."
+            exit 1
+          fi
+
+          echo "AI attribution guard: clean"
+
+      - name: Check commit messages
+        run: |
+          COMMITS=$(git log --format='%s%n%b' origin/${{ github.base_ref }}...HEAD)
+
+          COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
+          ATTR='(Generated|Created|Written|Built|Authored) (by|with|using) .*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)'
+
+          FOUND=""
+          for PAT in "$COAUTH" "$ATTR"; do
+            MATCH=$(echo "$COMMITS" | grep -i -E "$PAT" || true)
+            [ -n "$MATCH" ] && FOUND="${FOUND}${MATCH}\n"
+          done
+
+          if [ -n "$FOUND" ]; then
+            echo "::error::AI attribution detected in commit messages"
+            echo -e "$FOUND"
+            echo ""
+            echo "Amend commits to remove AI attribution and force-push."
+            exit 1
+          fi
+
+          echo "Commit messages: clean"

package/scripts/esbuild-sea.config.mjs

@@ -2,9 +2,90 @@
  * esbuild configuration for Node.js SEA (Single Executable Application) bundle.
  *
  * Bundles the entire CLI into a single CJS file suitable for SEA injection.
- * SEA requires CJS format — ESM entry points are transpiled by esbuild.
+ * A plugin handles:
+ *   1. import.meta.url / import.meta.dirname -> CJS equivalents
+ *   2. Top-level await in cli.js -> async IIFE wrapper
+ *   3. Runtime package.json reads -> inlined version string
  */
 
+import path from "node:path";
+import fs from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PKG_VERSION = JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8")).version;
+
+const seaTransformPlugin = {
+  name: "sea-transform",
+  setup(build) {
+    build.onLoad({ filter: /\.m?js$/ }, async (args) => {
+      let contents = await fs.readFile(args.path, "utf8");
+      let modified = false;
+
+      // Replace import.meta.dirname with __dirname
+      if (contents.includes("import.meta.dirname")) {
+        contents = contents.replaceAll("import.meta.dirname", "__dirname");
+        modified = true;
+      }
+
+      // Replace import.meta.url with CJS equivalent
+      if (contents.includes("import.meta.url")) {
+        contents = contents.replaceAll(
+          "import.meta.url",
+          'require("node:url").pathToFileURL(__filename).href'
+        );
+        modified = true;
+      }
+
+      // Inline version: replace any pattern that reads ../../package.json or ../package.json
+      // to extract the version, with the hardcoded version string.
+      // Covers cli.js, display.js, doctor.js, bootstrap.js, init.js, server.js
+      if (contents.includes("package.json") && contents.match(/["']\.\.\/.*package\.json/)) {
+        // Pattern: const X = path.resolve(..., "../../package.json");
+        //          const Y = JSON.parse(readFileSync(X, "utf8")).version;
+        // Replace both lines with: const Y = "1.57.0";
+        contents = contents.replace(
+          /const (\w+) = (?:path\.resolve|resolve)\(.*?["']\.\.\/.*?package\.json["']\);\s*\n\s*(?:const|return) (\w+) = JSON\.parse\(.*?readFileSync\(\1.*?\).*?\.version;/g,
+          `const $2 = ${JSON.stringify(PKG_VERSION)};`
+        );
+        // Single-line pattern: return JSON.parse(readFileSync(pkgPath...)).version
+        contents = contents.replace(
+          /const (\w+) = (?:path\.resolve|resolve)\(.*?["']\.\.\/.*?package\.json["']\);\s*\n\s*return JSON\.parse\(.*?readFileSync\(\1.*?\).*?\.version;/g,
+          `return ${JSON.stringify(PKG_VERSION)};`
+        );
+        // Pattern in cli.js: const PKG_PATH = ...; const PKG_VERSION = ...;
+        contents = contents.replace(
+          /const PKG_PATH = .*?package\.json.*?;\s*\nconst PKG_VERSION = .*?\.version;/,
+          `const PKG_VERSION = ${JSON.stringify(PKG_VERSION)};`
+        );
+        // Pattern in display.js: const DISPLAY_PKG_PATH = ...; const DISPLAY_VERSION = ...;
+        contents = contents.replace(
+          /const DISPLAY_PKG_PATH = .*?package\.json.*?;\s*\nconst DISPLAY_VERSION = .*?\.version;/,
+          `const DISPLAY_VERSION = ${JSON.stringify(PKG_VERSION)};`
+        );
+        // Pattern in server.js: const PKG_PATH = ...; (used later to read version)
+        contents = contents.replace(
+          /const PKG_PATH = .*?package\.json.*?;\s*\nconst PKG = JSON\.parse\(readFileSync\(PKG_PATH.*?\)\);/,
+          `const PKG = { version: ${JSON.stringify(PKG_VERSION)}, name: "karajan-code" };`
+        );
+        modified = true;
+      }
+
+      // Wrap top-level await in cli.js inside an async IIFE
+      if (args.path.endsWith("src/cli.js") || args.path.endsWith("src\\cli.js")) {
+        contents = contents.replace(
+          /^(try\s*\{[\s\S]*?await\s+program\.parseAsync\(\)[\s\S]*?^\})\s*$/m,
+          "(async () => {\n$1\n})();"
+        );
+        modified = true;
+      }
+
+      return modified ? { contents, loader: "js" } : undefined;
+    });
+  }
+};
+
 /** @type {import('esbuild').BuildOptions} */
 export const seaBuildOptions = {
   entryPoints: ["src/cli.js"],
@@ -14,20 +95,7 @@ export const seaBuildOptions = {
   target: "node20",
   bundle: true,
   minify: false,
-  // Bundle everything — no externals. The binary must be fully self-contained.
   external: [],
-  // Shim for CJS compatibility in the SEA context.
-  banner: {
-    js: [
-      "/* Karajan Code — SEA bundle */",
-      "/* eslint-disable */",
-      'const __importMetaUrl = require("node:url").pathToFileURL(__filename).href;',
-    ].join("\n"),
-  },
-  // Replace import.meta.url references with the CJS-compatible shim variable.
-  define: {
-    "import.meta.url": "__importMetaUrl",
-  },
-  // Log level for debugging build issues.
+  plugins: [seaTransformPlugin],
   logLevel: "info",
 };

package/scripts/install-guard-all-repos.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+#
+# Installs the AI Attribution Guard workflow in all repos of a GitHub user.
+# Requires: gh CLI authenticated with admin/push permissions.
+#
+# Usage:
+#   ./scripts/install-guard-all-repos.sh              # dry-run
+#   ./scripts/install-guard-all-repos.sh --apply       # install in all repos
+#
+# What it does:
+#   - Creates .github/workflows/ai-attribution-guard.yml in each repo
+#   - Skips repos that already have the file
+#   - Skips archived repos
+
+set -euo pipefail
+
+OWNER="${GH_OWNER:-manufosela}"
+APPLY=false
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WORKFLOW_FILE="$SCRIPT_DIR/ai-attribution-guard.yml"
+
+if [[ "${1:-}" == "--apply" ]]; then
+  APPLY=true
+fi
+
+if [[ ! -f "$WORKFLOW_FILE" ]]; then
+  echo "ERROR: $WORKFLOW_FILE not found"
+  exit 1
+fi
+
+CONTENT=$(base64 -w 0 "$WORKFLOW_FILE")
+
+echo "=== Install AI Attribution Guard in all repos of $OWNER ==="
+echo ""
+
+if [[ "$APPLY" == false ]]; then
+  echo "  DRY RUN mode. Use --apply to actually install."
+  echo ""
+fi
+
+REPOS=$(gh repo list "$OWNER" --limit 500 --json name,isArchived \
+  --jq '.[] | select(.isArchived == false) | .name')
+
+TOTAL=0
+INSTALLED=0
+SKIPPED=0
+FAILED=0
+
+while read -r REPO; do
+  [ -z "$REPO" ] && continue
+  TOTAL=$((TOTAL + 1))
+
+  # Check if workflow already exists
+  EXISTS=$(gh api "repos/$OWNER/$REPO/contents/.github/workflows/ai-attribution-guard.yml" --jq '.sha' 2>/dev/null || echo "")
+
+  if [[ -n "$EXISTS" ]]; then
+    echo "  SKIP  $REPO — workflow already exists"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [[ "$APPLY" == false ]]; then
+    echo "  WOULD $REPO"
+    continue
+  fi
+
+  if gh api "repos/$OWNER/$REPO/contents/.github/workflows/ai-attribution-guard.yml" -X PUT \
+    -f message="chore: add AI attribution guard workflow" \
+    -f content="$CONTENT" \
+    --jq '.commit.sha' 2>/dev/null; then
+    echo "  OK    $REPO"
+    INSTALLED=$((INSTALLED + 1))
+  else
+    echo "  FAIL  $REPO — check permissions"
+    FAILED=$((FAILED + 1))
+  fi
+
+done <<< "$REPOS"
+
+echo ""
+echo "=== Summary ==="
+echo "  Total:     $TOTAL"
+echo "  Installed: $INSTALLED"
+echo "  Skipped:   $SKIPPED"
+echo "  Failed:    $FAILED"

package/scripts/protect-all-repos.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+#
+# Configures branch protection on all repos of a GitHub user.
+# Requires: gh CLI authenticated with admin permissions.
+#
+# Usage:
+#   ./scripts/protect-all-repos.sh              # dry-run (shows what it would do)
+#   ./scripts/protect-all-repos.sh --apply      # apply protection rules
+#
+# What it does:
+#   - Require PRs before merging (no direct push to default branch)
+#   - Block force push
+#   - Block branch deletion
+#
+# Skips repos where branch protection is already configured.
+
+set -euo pipefail
+
+OWNER="${GH_OWNER:-manufosela}"
+APPLY=false
+
+if [[ "${1:-}" == "--apply" ]]; then
+  APPLY=true
+fi
+
+echo "=== Branch Protection for all repos of $OWNER ==="
+echo ""
+
+if [[ "$APPLY" == false ]]; then
+  echo "  DRY RUN mode. Use --apply to actually configure."
+  echo ""
+fi
+
+REPOS=$(gh repo list "$OWNER" --limit 500 --json name,defaultBranchRef,isArchived \
+  --jq '.[] | select(.isArchived == false) | "\(.name)\t\(.defaultBranchRef.name // "main")"')
+
+TOTAL=0
+PROTECTED=0
+SKIPPED=0
+FAILED=0
+
+while IFS=$'\t' read -r REPO BRANCH; do
+  TOTAL=$((TOTAL + 1))
+
+  # Check if already protected
+  STATUS=$(gh api "repos/$OWNER/$REPO/branches/$BRANCH/protection" --jq '.required_pull_request_reviews.required_approving_review_count // 0' 2>/dev/null || echo "none")
+
+  if [[ "$STATUS" != "none" ]]; then
+    echo "  SKIP  $REPO ($BRANCH) — already protected"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [[ "$APPLY" == false ]]; then
+    echo "  WOULD $REPO ($BRANCH)"
+    continue
+  fi
+
+  # Apply protection
+  if gh api "repos/$OWNER/$REPO/branches/$BRANCH/protection" -X PUT \
+    --input - <<EOF 2>/dev/null; then
+{
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 0,
+    "dismiss_stale_reviews": false
+  },
+  "enforce_admins": false,
+  "required_status_checks": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+    echo "  OK    $REPO ($BRANCH)"
+    PROTECTED=$((PROTECTED + 1))
+  else
+    echo "  FAIL  $REPO ($BRANCH) — check permissions"
+    FAILED=$((FAILED + 1))
+  fi
+
+done <<< "$REPOS"
+
+echo ""
+echo "=== Summary ==="
+echo "  Total:     $TOTAL"
+echo "  Protected: $PROTECTED"
+echo "  Skipped:   $SKIPPED"
+echo "  Failed:    $FAILED"

package/src/bootstrap.js

@@ -130,12 +130,16 @@ async function checkSonarQubeReady(config) {
     return { name: "sonarqube", ok: true, detail: `Reachable at ${host}`, fix: null };
   }
 
-  // Auto-remediation: try to start
+  // Auto-remediation: start and wait up to 60s for SonarQube to be ready
   try {
     await sonarUp(host);
-    reachable = await isSonarReachable(host);
-    if (reachable) {
-      return { name: "sonarqube", ok: true, detail: `Started and reachable at ${host}`, fix: null };
+    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 */ }
 

package/src/cli.js

@@ -40,6 +40,12 @@ async function withConfig(commandName, flags, fn) {
   const merged = applyRunOverrides(config, flags || {});
   validateConfig(merged, commandName);
   const logger = createLogger(merged.output.log_level);
+
+  // Telemetry: anonymous cli_command event (non-blocking)
+  import("./utils/telemetry.js")
+    .then(({ sendTelemetryEvent }) => sendTelemetryEvent("cli_command", { command: commandName, version: PKG_VERSION }, merged))
+    .catch(() => {});
+
   await fn({ config: merged, logger, flags });
 }
 

package/src/commands/init.js

@@ -305,6 +305,35 @@ async function installSkills(logger, interactive) {
   }
 }
 
+const GITIGNORE_ENTRIES = [
+  { pattern: ".kj/", comment: "Karajan runtime (logs, worktrees)" },
+  { pattern: ".agent/", comment: "Agent skills (OpenSkills)" },
+  { pattern: ".scannerwork/", comment: "SonarQube scanner temp" },
+];
+
+async function ensureGitignoreEntries(projectDir, logger) {
+  const gitignorePath = path.join(projectDir, ".gitignore");
+  let content;
+  try {
+    content = await fs.readFile(gitignorePath, "utf8");
+  } catch {
+    // No .gitignore yet — will create one
+  }
+  if (!content) content = "";
+
+  const missing = GITIGNORE_ENTRIES.filter(e => !content.includes(e.pattern));
+  if (missing.length === 0) return;
+
+  const block = [
+    "",
+    "# Karajan Code",
+    ...missing.map(e => e.pattern)
+  ].join("\n") + "\n";
+
+  await fs.appendFile(gitignorePath, block, "utf8");
+  logger.info(`Added to .gitignore: ${missing.map(e => e.pattern).join(", ")}`);
+}
+
 export async function initCommand({ logger, flags = {} }) {
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
@@ -329,6 +358,7 @@ export async function initCommand({ logger, flags = {} }) {
   await handleConfigSetup({ config, configExists, interactive, configPath, logger });
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);
+  await ensureGitignoreEntries(process.cwd(), logger);
   await installSkills(logger, interactive);
 
   // Auto-detect project stack and preconfigure
@@ -374,4 +404,15 @@ export async function initCommand({ logger, flags = {} }) {
 
   await setupSonarQube(config, logger);
   await scaffoldBecariaGateway(config, flags, logger);
+
+  // Telemetry: anonymous install event (non-blocking)
+  const { sendTelemetryEvent } = await import("../utils/telemetry.js");
+  const { readFileSync } = await import("node:fs");
+  const { resolve, dirname } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  try {
+    const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+    const version = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+    sendTelemetryEvent("install", { version }, config).catch(() => {});
+  } catch { /* non-blocking */ }
 }

package/src/config.js

@@ -171,6 +171,7 @@ const DEFAULTS = {
     devtools_mcp: false,
     thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
   },
+  telemetry: true,
   guards: {
     output: {
       enabled: true,
@@ -220,7 +221,7 @@ export async function loadProjectConfig(projectDir = process.cwd()) {
     return null;
   }
   const raw = await fs.readFile(projectConfigPath, "utf8");
-  return yaml.load(raw) || {};
+  return yaml.load(raw, { json: true }) || {};
 }
 
 async function loadProjectPricingOverrides(projectDir = process.cwd()) {
@@ -230,7 +231,7 @@ async function loadProjectPricingOverrides(projectDir = process.cwd()) {
   }
 
   const raw = await fs.readFile(projectConfigPath, "utf8");
-  const parsed = yaml.load(raw) || {};
+  const parsed = yaml.load(raw, { json: true }) || {};
   const pricing = parsed?.budget?.pricing;
   if (!pricing || typeof pricing !== "object") {
     return null;
@@ -248,7 +249,7 @@ export async function loadConfig(projectDir) {
   const globalExists = await exists(configPath);
   if (globalExists) {
     const raw = await fs.readFile(configPath, "utf8");
-    globalConfig = yaml.load(raw) || {};
+    globalConfig = yaml.load(raw, { json: true }) || {};
   }
 
   // Load project config (.karajan/kj.config.yml)
@@ -468,6 +469,13 @@ const CODER_INHERITED_ROLES = new Set([
 
 function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {
   if (roleConfig.provider) return roleConfig.provider;
+
+  // If model has "provider/model" format (e.g. "gemini/pro"), extract the provider
+  if (roleConfig.model && roleConfig.model.includes("/")) {
+    const inferredProvider = roleConfig.model.split("/")[0].toLowerCase();
+    if (AGENT_MODEL_SIGNATURES[inferredProvider]) return inferredProvider;
+  }
+
   if (role === "coder") return legacyCoder;
   if (role === "reviewer") return legacyReviewer;
   if (CODER_INHERITED_ROLES.has(role)) return roles.coder?.provider || legacyCoder;
@@ -475,7 +483,13 @@ function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {
 }
 
 function resolveModel(roleConfig, role, config) {
-  if (roleConfig.model) return { model: roleConfig.model, inherited: false };
+  if (roleConfig.model) {
+    // Strip "provider/" prefix from models like "gemini/pro" → "pro"
+    const model = roleConfig.model.includes("/")
+      ? roleConfig.model.split("/").slice(1).join("/")
+      : roleConfig.model;
+    return { model, inherited: false };
+  }
   if (role === "coder") return { model: config?.coder_options?.model ?? null, inherited: false };
   if (role === "reviewer") return { model: config?.reviewer_options?.model ?? null, inherited: false };
   if (CODER_INHERITED_ROLES.has(role)) {
@@ -494,8 +508,8 @@ export function resolveRole(config, role) {
   const provider = resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer);
   let { model, inherited: modelIsInherited } = resolveModel(roleConfig, role, config);
 
-  // Drop inherited model if incompatible with the resolved provider
-  if (modelIsInherited && provider && model && !isModelCompatible(provider, model)) {
+  // Drop model if incompatible with the resolved provider (inherited or explicit)
+  if (provider && model && !isModelCompatible(provider, model)) {
     model = null;
   }
 

package/src/mcp/error-classifiers.js

@@ -0,0 +1,66 @@
+/**
+ * Error classification for MCP tool responses.
+ * Extracted to its own module to avoid circular import TDZ issues
+ * (server-handlers.js ↔ handlers/*.js circular chain).
+ */
+
+import { withDocLink } from "../utils/doc-links.js";
+
+const ERROR_CLASSIFIERS = [
+  {
+    test: (lower) => lower.includes("without output") || lower.includes("silent for") || lower.includes("unresponsive") || lower.includes("exceeded max silence"),
+    category: "agent_stall",
+    suggestion: "Agent output stalled. Check live details with kj_status, then retry with a smaller prompt or increase session.max_agent_silence_minutes if needed."
+  },
+  {
+    test: (lower) => lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running")),
+    category: "sonar_unavailable",
+    suggestion: withDocLink("SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube.", "sonar_docker")
+  },
+  {
+    test: (lower) => lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token"),
+    category: "auth_error",
+    suggestion: withDocLink("Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token.", "sonar_token")
+  },
+  {
+    test: (lower) => lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid")),
+    category: "config_error",
+    suggestion: withDocLink("Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config.", "config_missing")
+  },
+  {
+    test: (lower) => lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider")),
+    category: "agent_missing",
+    suggestion: withDocLink("Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions.", "agent_not_found")
+  },
+  {
+    test: (lower) => lower.includes("timed out") || lower.includes("timeout"),
+    category: "timeout",
+    suggestion: "The agent did not complete in time. Try: (1) increase --max-iteration-minutes (default: 5), (2) split the task into smaller pieces, (3) use kj_code for single-agent tasks. If a SonarQube scan timed out, check Docker health."
+  },
+  {
+    test: (lower) => lower.includes("you are on the base branch"),
+    category: "branch_error",
+    suggestion: withDocLink("Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch.", "branch_error")
+  },
+  {
+    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: withDocLink("Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly.", "bootstrap_failed")
+  }
+];
+
+export function classifyError(error) {
+  const msg = error?.message || String(error);
+  const lower = msg.toLowerCase();
+
+  const match = ERROR_CLASSIFIERS.find(c => c.test(lower));
+  if (match) {
+    return { category: match.category, suggestion: match.suggestion };
+  }
+  return { category: "unknown", suggestion: null };
+}

package/src/mcp/handlers/direct-handlers.js

@@ -28,7 +28,7 @@ import {
   assertNotOnBaseBranch,
   buildConfig,
   buildDirectEmitter,
-} from "../server-handlers.js";
+} from "../shared-helpers.js";
 
 /**
  * Run bootstrap gate: validate all environment prerequisites before execution.