karajan-code 1.56.0 → 1.57.0

package/README.md

@@ -264,6 +264,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

@@ -237,6 +237,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.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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

@@ -374,4 +374,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,

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.

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

@@ -7,7 +7,7 @@ import { handleSuggestion } from "../suggest-handler.js";
 import {
   resolveProjectDir,
   failPayload,
-} from "../server-handlers.js";
+} from "../shared-helpers.js";
 
 export async function handleHu(a, server) {
   const action = a.action;

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

@@ -13,7 +13,7 @@ import {
   failPayload,
   responseText,
   buildConfig,
-} from "../server-handlers.js";
+} from "../shared-helpers.js";
 import { buildDashboardJson } from "../../utils/status-dashboard.js";
 import { loadMostRecentSession } from "../../session-store.js";
 

package/src/mcp/handlers/run-handler.js

@@ -21,7 +21,7 @@ import {
   buildConfig,
   buildAskQuestion,
   enrichedFailPayload,
-} from "../server-handlers.js";
+} from "../shared-helpers.js";
 
 const MAX_AUTO_RESUMES = 2;
 const NON_RECOVERABLE_CATEGORIES = new Set([
@@ -154,8 +154,10 @@ export async function handleRunDirect(a, server, extra) {
 }
 
 export async function handleResumeDirect(a, server, extra) {
-  const config = await buildConfig(a);
-  const logger = createLogger(config.output.log_level, "mcp");
+  // Use a minimal config only for the logger; let resumeFlow use the session's
+  // config_snapshot so that flags like --no-sonar from the original run are preserved.
+  const freshConfig = await buildConfig(a);
+  const logger = createLogger(freshConfig.output.log_level, "mcp");
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
@@ -172,7 +174,7 @@ export async function handleResumeDirect(a, server, extra) {
     const result = await resumeFlow({
       sessionId: a.sessionId,
       answer: a.answer || null,
-      config,
+      config: null,  // Use session.config_snapshot (preserves --no-sonar, etc.)
       logger,
       flags: a,
       emitter,

package/src/mcp/orphan-guard.js

@@ -1,4 +1,9 @@
-import { readFileSync, watch } from "node:fs";
+import { readFileSync, writeFileSync, unlinkSync, watch, mkdirSync, existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const RESTART_MARKER_DIR = path.join(os.homedir(), ".kj");
+const RESTART_MARKER_PATH = path.join(RESTART_MARKER_DIR, ".mcp-restart");
 
 const DEFAULT_INTERVAL_MS = 5000;
 
@@ -69,14 +74,46 @@ export function setupMemoryWatchdog({
   return { timer };
 }
 
-export function setupVersionWatcher({ pkgPath, currentVersion, exitFn = () => process.exit(0) } = {}) {
+const DEFAULT_GRACE_MS = 2000;
+
+export function writeRestartMarker(version, markerPath = RESTART_MARKER_PATH) {
+  try {
+    mkdirSync(path.dirname(markerPath), { recursive: true });
+    writeFileSync(markerPath, version, "utf8");
+  } catch { /* best-effort */ }
+}
+
+export function readAndDeleteRestartMarker(markerPath = RESTART_MARKER_PATH) {
+  try {
+    if (!existsSync(markerPath)) return null;
+    const version = readFileSync(markerPath, "utf8").trim();
+    unlinkSync(markerPath);
+    return version || null;
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function setupVersionWatcher({
+  pkgPath,
+  currentVersion,
+  gracePeriodMs = DEFAULT_GRACE_MS,
+  exitFn = () => process.exit(0),
+  markerPath = RESTART_MARKER_PATH
+} = {}) {
   if (!pkgPath) return null;
 
+  let _gracePeriodMs = gracePeriodMs;
+
   function checkVersion() {
     try {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
       if (pkg.version !== currentVersion) {
-        exitFn();
+        const newVersion = pkg.version;
+        process.stderr.write(
+          `[karajan-mcp] Karajan MCP updated (v${currentVersion} → v${newVersion}). Restarting...\n`
+        );
+        writeRestartMarker(newVersion, markerPath);
+        setTimeout(() => exitFn(), _gracePeriodMs);
         return true;
       }
     } catch { /* ignore read errors */ }
@@ -90,5 +127,5 @@ export function setupVersionWatcher({ pkgPath, currentVersion, exitFn = () => pr
     });
   } catch { /* ignore watch errors */ }
 
-  return { watcher, checkVersion };
+  return { watcher, checkVersion, get gracePeriodMs() { return _gracePeriodMs; }, set gracePeriodMs(v) { _gracePeriodMs = v; } };
 }

package/src/mcp/server-handlers.js

@@ -1,16 +1,23 @@
 /**
  * MCP server handler logic.
- * Shared helpers remain here; handler implementations are in ./handlers/*.
- * Re-exports everything so existing imports continue to work.
+ * Shared helpers live in ./shared-helpers.js (to avoid circular imports).
+ * Handler implementations are in ./handlers/*.
+ * This module re-exports everything so existing imports continue to work.
  */
 
-import { EventEmitter } from "node:events";
-import fs from "node:fs/promises";
-import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
-import { currentBranch } from "../utils/git.js";
-import { buildProgressNotifier } from "./progress.js";
-import { compressResponse, compactStringify } from "./response-compressor.js";
-import { withDocLink } from "../utils/doc-links.js";
+// ── Shared helpers (re-exported from shared-helpers.js) ──────────────
+export {
+  resolveProjectDir,
+  asObject,
+  responseText,
+  failPayload,
+  assertNotOnBaseBranch,
+  enrichedFailPayload,
+  buildConfig,
+  buildAskQuestion,
+  buildDirectEmitter,
+  classifyError
+} from "./shared-helpers.js";
 
 // ── Sub-module re-exports ────────────────────────────────────────────
 export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
@@ -18,199 +25,9 @@ export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverD
 export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
 export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
-// ── Shared helpers (used by sub-modules and external consumers) ──────
-
-/**
- * Resolve the user's project directory.
- * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
- */
-export async function resolveProjectDir(server, explicitProjectDir) {
-  // 1. Explicit projectDir from tool parameter — always wins
-  if (explicitProjectDir) return explicitProjectDir;
-
-  // 2. MCP roots (host-provided workspace directory)
-  try {
-    const { roots } = await server.listRoots();
-    if (roots?.length > 0) {
-      const uri = roots[0].uri;
-      if (uri.startsWith("file://")) return new URL(uri).pathname;
-      return uri;
-    }
-  } catch { /* client may not support roots */ }
-
-  // 3. Check if process.cwd() looks like a real project (has package.json or .git)
-  const cwd = process.cwd();
-  try {
-    const hasGit = await fs.access(`${cwd}/.git`).then(() => true).catch(() => false);
-    const hasPkg = await fs.access(`${cwd}/package.json`).then(() => true).catch(() => false);
-    if (hasGit || hasPkg) return cwd;
-  } catch { /* ignore */ }
-
-  // 4. No valid project directory — fail with clear instructions
-  throw new Error(
-    `Cannot determine project directory. The MCP server is running from "${cwd}" which does not appear to be your project. ` +
-    `Fix: pass the "projectDir" parameter with the absolute path to your project (e.g., projectDir: "/home/user/my-project"), ` +
-    `or run "kj init" inside your project directory.`
-  );
-}
-
-export function asObject(value) {
-  if (value && typeof value === "object") return value;
-  return {};
-}
-
-export function responseText(payload) {
-  const compressed = compressResponse(payload);
-  return {
-    content: [{ type: "text", text: compactStringify(compressed) }]
-  };
-}
-
-export function failPayload(message, details = {}) {
-  return {
-    ok: false,
-    error: message,
-    ...details
-  };
-}
-
-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 };
-}
-
-export async function assertNotOnBaseBranch(config) {
-  const baseBranch = config?.base_branch || "main";
-  let branch;
-  try {
-    branch = await currentBranch();
-  } catch {
-    return; // not a git repo or detached HEAD — let downstream handle it
-  }
-  if (branch === baseBranch) {
-    throw new Error(
-      `You are on the base branch '${baseBranch}'. Karajan needs a feature branch to compute the diff for review. ` +
-      `Create a new branch first (e.g. 'git checkout -b feat/<task-description>') and then run this command again. ` +
-      `Do NOT run kj_code directly — create the branch first so the full pipeline (code + review) works correctly.`
-    );
-  }
-}
-
-export function enrichedFailPayload(error, toolName) {
-  const msg = error?.message || String(error);
-  const { category, suggestion } = classifyError(error);
-  const payload = {
-    ok: false,
-    error: msg,
-    tool: toolName,
-    category
-  };
-  if (suggestion) payload.suggestion = suggestion;
-  return payload;
-}
-
-export async function buildConfig(options, commandName = "run") {
-  const { config } = await loadConfig();
-  const merged = applyRunOverrides(config, options || {});
-  validateConfig(merged, commandName);
-  return merged;
-}
-
-export function buildAskQuestion(server) {
-  return async (question) => {
-    try {
-      const result = await server.elicitInput({
-        message: question,
-        requestedSchema: {
-          type: "object",
-          properties: {
-            answer: { type: "string", description: "Your response" }
-          },
-          required: ["answer"]
-        }
-      });
-      return result.action === "accept" ? result.content?.answer || null : null;
-    } catch { /* elicitInput not supported by client */
-      return null;
-    }
-  };
-}
-
-const EVENT_LOG_LEVELS = {
-  "agent:stall": "warning",
-  "agent:heartbeat": "info"
-};
-
-export function buildDirectEmitter(server, runLog, extra) {
-  const emitter = new EventEmitter();
-  emitter.on("progress", (event) => {
-    try {
-      const level = EVENT_LOG_LEVELS[event.type] || "debug";
-      server.sendLoggingMessage({ level, logger: "karajan", data: event });
-    } catch { /* best-effort */ }
-    if (runLog) runLog.logEvent(event);
-  });
-  const progressNotifier = buildProgressNotifier(extra);
-  if (progressNotifier) emitter.on("progress", progressNotifier);
-  return emitter;
-}
-
-// ── Handler dispatch map (imports from sub-modules) ──────────────────
+// ── Handler dispatch ─────────────────────────────────────────────────
 
+import { asObject, failPayload } from "./shared-helpers.js";
 import { handleRun, handleResume } from "./handlers/run-handler.js";
 import {
   handleCode, handleReview, handlePlan, handleDiscover,
@@ -223,36 +40,34 @@ import {
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
-const toolHandlers = {
-  kj_status:      (a, server) => handleStatus(a, server),
-  kj_init:        (a) => handleInit(a),
-  kj_doctor:      (a) => handleDoctor(a),
-  kj_agents:      (a) => handleAgents(a),
-  kj_preflight:   (a) => handlePreflight(a),
-  kj_config:      (a) => handleConfig(a),
-  kj_scan:        (a, server) => handleScan(a, server),
-  kj_roles:       (a) => handleRoles(a),
-  kj_report:      (a) => handleReport(a),
-  kj_resume:      (a, server, extra) => handleResume(a, server, extra),
-  kj_run:         (a, server, extra) => handleRun(a, server, extra),
-  kj_code:        (a, server, extra) => handleCode(a, server, extra),
-  kj_review:      (a, server, extra) => handleReview(a, server, extra),
-  kj_plan:        (a, server, extra) => handlePlan(a, server, extra),
-  kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
-  kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
-  kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
-  kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
-  kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
-  kj_board:       (a) => handleBoard(a),
-  kj_hu:          (a, server) => handleHu(a, server),
-  kj_suggest:     (a) => handleSuggest(a),
-  kj_skills:      (a) => handleSkills(a),
-  kj_undo:        (a, server) => handleUndo(a, server)
-};
-
 export async function handleToolCall(name, args, server, extra) {
   const a = asObject(args);
-  const handler = toolHandlers[name];
+  const handler = {
+    kj_status:      (a, server) => handleStatus(a, server),
+    kj_init:        (a) => handleInit(a),
+    kj_doctor:      (a) => handleDoctor(a),
+    kj_agents:      (a) => handleAgents(a),
+    kj_preflight:   (a) => handlePreflight(a),
+    kj_config:      (a) => handleConfig(a),
+    kj_scan:        (a, server) => handleScan(a, server),
+    kj_roles:       (a) => handleRoles(a),
+    kj_report:      (a) => handleReport(a),
+    kj_resume:      (a, server, extra) => handleResume(a, server, extra),
+    kj_run:         (a, server, extra) => handleRun(a, server, extra),
+    kj_code:        (a, server, extra) => handleCode(a, server, extra),
+    kj_review:      (a, server, extra) => handleReview(a, server, extra),
+    kj_plan:        (a, server, extra) => handlePlan(a, server, extra),
+    kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
+    kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
+    kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
+    kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
+    kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
+    kj_board:       (a) => handleBoard(a),
+    kj_hu:          (a, server) => handleHu(a, server),
+    kj_suggest:     (a) => handleSuggest(a),
+    kj_skills:      (a) => handleSkills(a),
+    kj_undo:        (a, server) => handleUndo(a, server)
+  }[name];
   if (handler) {
     return handler(a, server, extra);
   }

package/src/mcp/server.js

@@ -50,7 +50,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 });
 
 // --- Orphan process protection + version watcher ---
-import { setupOrphanGuard, setupVersionWatcher, setupMemoryWatchdog } from "./orphan-guard.js";
+import { setupOrphanGuard, setupVersionWatcher, setupMemoryWatchdog, readAndDeleteRestartMarker } from "./orphan-guard.js";
+
+// Check if this is a restart after update
+const restartedVersion = readAndDeleteRestartMarker();
+if (restartedVersion) {
+  process.stderr.write(`[karajan-mcp] MCP server restarted after update to v${restartedVersion}\n`);
+}
+
 setupOrphanGuard();
 setupVersionWatcher({ pkgPath: PKG_PATH, currentVersion: LOADED_VERSION });
 setupMemoryWatchdog();

package/src/mcp/shared-helpers.js

@@ -0,0 +1,144 @@
+/**
+ * Shared helpers used by MCP handler sub-modules.
+ * Extracted from server-handlers.js to break circular import chains
+ * (server-handlers.js ↔ handlers/*.js).
+ *
+ * Sub-handlers MUST import from here, NOT from server-handlers.js.
+ * server-handlers.js re-exports everything for external consumers.
+ */
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs/promises";
+import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
+import { currentBranch } from "../utils/git.js";
+import { buildProgressNotifier } from "./progress.js";
+import { compressResponse, compactStringify } from "./response-compressor.js";
+import { classifyError } from "./error-classifiers.js";
+
+export { classifyError } from "./error-classifiers.js";
+
+/**
+ * Resolve the user's project directory.
+ * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
+ */
+export async function resolveProjectDir(server, explicitProjectDir) {
+  if (explicitProjectDir) return explicitProjectDir;
+
+  try {
+    const { roots } = await server.listRoots();
+    if (roots?.length > 0) {
+      const uri = roots[0].uri;
+      if (uri.startsWith("file://")) return new URL(uri).pathname;
+      return uri;
+    }
+  } catch { /* client may not support roots */ }
+
+  const cwd = process.cwd();
+  try {
+    const hasGit = await fs.access(`${cwd}/.git`).then(() => true).catch(() => false);
+    const hasPkg = await fs.access(`${cwd}/package.json`).then(() => true).catch(() => false);
+    if (hasGit || hasPkg) return cwd;
+  } catch { /* ignore */ }
+
+  throw new Error(
+    `Cannot determine project directory. The MCP server is running from "${cwd}" which does not appear to be your project. ` +
+    `Fix: pass the "projectDir" parameter with the absolute path to your project (e.g., projectDir: "/home/user/my-project"), ` +
+    `or run "kj init" inside your project directory.`
+  );
+}
+
+export function asObject(value) {
+  if (value && typeof value === "object") return value;
+  return {};
+}
+
+export function responseText(payload) {
+  const compressed = compressResponse(payload);
+  return {
+    content: [{ type: "text", text: compactStringify(compressed) }]
+  };
+}
+
+export function failPayload(message, details = {}) {
+  return {
+    ok: false,
+    error: message,
+    ...details
+  };
+}
+
+export async function assertNotOnBaseBranch(config) {
+  const baseBranch = config?.base_branch || "main";
+  let branch;
+  try {
+    branch = await currentBranch();
+  } catch {
+    return;
+  }
+  if (branch === baseBranch) {
+    throw new Error(
+      `You are on the base branch '${baseBranch}'. Karajan needs a feature branch to compute the diff for review. ` +
+      `Create a new branch first (e.g. 'git checkout -b feat/<task-description>') and then run this command again. ` +
+      `Do NOT run kj_code directly — create the branch first so the full pipeline (code + review) works correctly.`
+    );
+  }
+}
+
+export function enrichedFailPayload(error, toolName) {
+  const msg = error?.message || String(error);
+  const { category, suggestion } = classifyError(error);
+  const payload = {
+    ok: false,
+    error: msg,
+    tool: toolName,
+    category
+  };
+  if (suggestion) payload.suggestion = suggestion;
+  return payload;
+}
+
+export async function buildConfig(options, commandName = "run") {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, options || {});
+  validateConfig(merged, commandName);
+  return merged;
+}
+
+export function buildAskQuestion(server) {
+  return async (question) => {
+    try {
+      const result = await server.elicitInput({
+        message: question,
+        requestedSchema: {
+          type: "object",
+          properties: {
+            answer: { type: "string", description: "Your response" }
+          },
+          required: ["answer"]
+        }
+      });
+      return result.action === "accept" ? result.content?.answer || null : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+const EVENT_LOG_LEVELS = {
+  "agent:stall": "warning",
+  "agent:heartbeat": "info"
+};
+
+export function buildDirectEmitter(server, runLog, extra) {
+  const emitter = new EventEmitter();
+  emitter.on("progress", (event) => {
+    try {
+      const level = EVENT_LOG_LEVELS[event.type] || "debug";
+      server.sendLoggingMessage({ level, logger: "karajan", data: event });
+    } catch { /* best-effort */ }
+    if (runLog) runLog.logEvent(event);
+  });
+  const progressNotifier = buildProgressNotifier(extra);
+  if (progressNotifier) emitter.on("progress", progressNotifier);
+  return emitter;
+}

package/src/orchestrator.js

@@ -1613,6 +1613,20 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         logger.warn(`Skill cleanup failed (non-blocking): ${err.message}`);
       }
     }
+
+    // --- Telemetry: anonymous pipeline_complete event (non-blocking) ---
+    try {
+      const { sendTelemetryEvent } = await import("./utils/telemetry.js");
+      const durationS = Math.round((Date.now() - ctx.startedAt) / 1000);
+      const sessionStatus = ctx.session?.status || "unknown";
+      sendTelemetryEvent("pipeline_complete", {
+        mode: config.review_mode,
+        agent: ctx.coderRole?.provider || config.coder,
+        duration_s: durationS,
+        success: sessionStatus === "approved",
+        taskType: ctx.session?.resolved_policies?.taskType || null
+      }, config).catch(() => {});
+    } catch { /* non-blocking */ }
   }
 }
 

package/src/utils/telemetry.js

@@ -0,0 +1,47 @@
+const TELEMETRY_ENDPOINT = "https://karajan-code.web.app/api/telemetry";
+
+/**
+ * Send an anonymous telemetry event. Non-blocking, fire-and-forget.
+ * Never throws, never blocks the pipeline.
+ *
+ * @param {string} eventName - Event name (e.g. "install", "pipeline_complete", "cli_command")
+ * @param {object} data - Event-specific data
+ * @param {object} [config] - Karajan config (checked for telemetry opt-out)
+ */
+export async function sendTelemetryEvent(eventName, data, config) {
+  if (!isTelemetryEnabled(config)) return;
+
+  try {
+    const payload = {
+      event: eventName,
+      v: data.version || "unknown",
+      os: process.platform,
+      node: process.version,
+      ts: Date.now(),
+      ...data
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    try {
+      await fetch(TELEMETRY_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch { /* never block, never fail */ }
+}
+
+/**
+ * Check if telemetry is enabled (opt-out model).
+ * Returns false only when the user explicitly sets telemetry: false.
+ *
+ * @param {object} [config] - Karajan config
+ * @returns {boolean}
+ */
+export function isTelemetryEnabled(config) {
+  return config?.telemetry !== false;
+}