karajan-code 1.55.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.55.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

@@ -25,6 +25,7 @@ import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
 import { undoCommand } from "./commands/undo.js";
+import { statusCommand } from "./commands/status.js";
 
 import { printUpdateNotice } from "./utils/update-check.js";
 
@@ -39,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 });
 }
 
@@ -168,6 +175,14 @@ program
     await withConfig("doctor", {}, doctorCommand);
   });
 
+program
+  .command("status")
+  .description("Show pipeline dashboard with HU progress")
+  .option("-n, --lines <n>", "Max log lines to read", "50")
+  .action(async (flags) => {
+    await statusCommand({ lines: Number(flags.lines) });
+  });
+
 program
   .command("report")
   .description("Show latest session report")

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -330,6 +331,35 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureCoderRules(coderRulesPath, logger);
   await installSkills(logger, interactive);
 
+  // Auto-detect project stack and preconfigure
+  const stack = await detectProjectStack(process.cwd());
+  if (stack.frameworks.length > 0 || stack.language) {
+    const parts = [];
+    if (stack.frameworks.length > 0) parts.push(stack.frameworks.join(" + "));
+    if (stack.language) parts.push(stack.language);
+    const stackType = stack.isFullstack ? "fullstack" : stack.isFrontend ? "frontend" : stack.isBackend ? "backend" : "unknown";
+    logger.info(`Detected stack: ${parts.join(" / ")} (${stackType})`);
+
+    if (stack.suggestions.impeccable) {
+      config.impeccable = config.impeccable || {};
+      config.impeccable.enabled = true;
+      logger.info("  -> Impeccable design audit enabled (frontend detected)");
+    }
+
+    if (stack.suggestions.skills.length > 0) {
+      logger.info(`  -> Suggested skills: ${stack.suggestions.skills.join(", ")}`);
+    }
+
+    if (stack.language && !configExists) {
+      config.development = config.development || {};
+      config.development.methodology = config.development.methodology || "tdd";
+    }
+
+    await writeConfig(configPath, config);
+  } else {
+    logger.info("No project stack detected — using default configuration.");
+  }
+
   // Check RTK availability — auto-install if missing
   const rtk = await detectRtk();
   if (rtk.available) {
@@ -344,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/commands/status.js

@@ -0,0 +1,35 @@
+/**
+ * CLI status command — shows a terminal dashboard of the current pipeline state.
+ */
+
+import { readRunLog } from "../utils/run-log.js";
+import { loadMostRecentSession } from "../session-store.js";
+import { buildDashboard } from "../utils/status-dashboard.js";
+
+/**
+ * Run the `kj status` command: print a human-readable dashboard to stdout.
+ * @param {object} options
+ * @param {number} [options.lines=50] - Max log lines to read.
+ * @param {string} [options.projectDir] - Project directory override.
+ */
+export async function statusCommand({ lines = 50, projectDir } = {}) {
+  const dir = projectDir || process.cwd();
+  const logResult = readRunLog(dir, lines);
+
+  let session = null;
+  try {
+    session = await loadMostRecentSession();
+  } catch { /* no session available */ }
+
+  let stories = [];
+  if (session) {
+    try {
+      const { loadHuBatch } = await import("../hu/store.js");
+      const batch = await loadHuBatch(session.id);
+      if (batch?.stories) stories = batch.stories;
+    } catch { /* no HU batch */ }
+  }
+
+  const dashboard = buildDashboard(session, logResult.lines || [], { stories });
+  console.log(dashboard);
+}

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,9 @@ 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";
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
 
@@ -29,7 +31,26 @@ async function runBootstrapGate(server, a) {
 export async function handleStatus(a, server) {
   const maxLines = a.lines || 50;
   const projectDir = await resolveProjectDir(server, a.projectDir);
-  return readRunLog(projectDir, maxLines);
+  const logResult = readRunLog(projectDir, maxLines);
+
+  // Enrich with dashboard data when possible
+  try {
+    const session = await loadMostRecentSession();
+    const stories = [];
+    if (session) {
+      try {
+        const { loadHuBatch } = await import("../../hu/store.js");
+        const batch = await loadHuBatch(session.id);
+        if (batch?.stories) stories.push(...batch.stories);
+      } catch { /* no HU batch for this session */ }
+    }
+
+    const dashboard = buildDashboardJson(session, logResult.lines || [], { stories });
+    return { ...logResult, dashboard };
+  } catch {
+    // Fallback: return raw log without dashboard
+    return logResult;
+  }
 }
 
 export async function handleAgents(a) {

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/stack-detect.js

@@ -0,0 +1,135 @@
+/**
+ * Detects the project technology stack by scanning project files.
+ * Used by `kj init` to auto-configure roles, skills, and settings.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Frameworks detectable from package.json dependencies.
+ * Maps dependency name -> { name, type } where type is "frontend" | "backend" | "fullstack".
+ */
+const PKG_FRAMEWORKS = {
+  react: { name: "react", type: "frontend" },
+  "react-dom": { name: "react", type: "frontend" },
+  vue: { name: "vue", type: "frontend" },
+  svelte: { name: "svelte", type: "frontend" },
+  "@angular/core": { name: "angular", type: "frontend" },
+  astro: { name: "astro", type: "frontend" },
+  next: { name: "next", type: "fullstack" },
+  nuxt: { name: "nuxt", type: "fullstack" },
+  "solid-js": { name: "solid", type: "frontend" },
+  lit: { name: "lit", type: "frontend" },
+  express: { name: "express", type: "backend" },
+  fastify: { name: "fastify", type: "backend" },
+  "@nestjs/core": { name: "nestjs", type: "backend" },
+  hono: { name: "hono", type: "backend" },
+  koa: { name: "koa", type: "backend" },
+};
+
+/**
+ * Language markers: file presence -> { language, type }.
+ */
+const LANGUAGE_FILE_MARKERS = [
+  { file: "go.mod", language: "go", type: "backend" },
+  { file: "Cargo.toml", language: "rust", type: "backend" },
+  { file: "pom.xml", language: "java", type: "backend" },
+  { file: "build.gradle", language: "java", type: "backend" },
+  { file: "build.gradle.kts", language: "kotlin", type: "backend" },
+  { file: "pyproject.toml", language: "python", type: "backend" },
+  { file: "setup.py", language: "python", type: "backend" },
+  { file: "requirements.txt", language: "python", type: "backend" },
+  { file: "Gemfile", language: "ruby", type: "backend" },
+  { file: "composer.json", language: "php", type: "backend" },
+  { file: "pubspec.yaml", language: "dart", type: "frontend" },
+  { file: "Package.swift", language: "swift", type: "backend" },
+];
+
+/**
+ * Maps framework names to skill names for auto-install suggestions.
+ */
+const FRAMEWORK_TO_SKILL = {
+  react: "react",
+  vue: "vue",
+  svelte: "svelte",
+  angular: "angular",
+  astro: "astro",
+  next: "nextjs",
+  nuxt: "vue",
+  solid: "solid",
+  lit: "lit",
+  express: "express",
+  fastify: "fastify",
+  nestjs: "nestjs",
+};
+
+/**
+ * Detect the project technology stack.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{frameworks: string[], language: string|null, isFrontend: boolean, isBackend: boolean, isFullstack: boolean, suggestions: {impeccable: boolean, skills: string[]}}>}
+ */
+export async function detectProjectStack(projectDir) {
+  const frameworks = new Set();
+  let language = null;
+  let hasFrontend = false;
+  let hasBackend = false;
+
+  // 1. Scan package.json for known frameworks
+  try {
+    const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (!language) language = "javascript";
+
+    // Check for TypeScript
+    if (allDeps.typescript || allDeps["ts-node"]) {
+      language = "typescript";
+    }
+
+    for (const [dep, info] of Object.entries(PKG_FRAMEWORKS)) {
+      if (allDeps[dep]) {
+        frameworks.add(info.name);
+        if (info.type === "frontend" || info.type === "fullstack") hasFrontend = true;
+        if (info.type === "backend" || info.type === "fullstack") hasBackend = true;
+      }
+    }
+  } catch { /* no package.json or parse error */ }
+
+  // 2. Check language file markers
+  for (const marker of LANGUAGE_FILE_MARKERS) {
+    try {
+      await fs.access(path.join(projectDir, marker.file));
+      if (!language || language === "javascript") {
+        language = marker.language;
+      }
+      if (marker.type === "frontend") hasFrontend = true;
+      if (marker.type === "backend") hasBackend = true;
+    } catch { /* file not found */ }
+  }
+
+  const frameworkList = Array.from(frameworks);
+  const isFullstack = hasFrontend && hasBackend;
+
+  // Build suggestions
+  const skills = [];
+  for (const fw of frameworkList) {
+    const skill = FRAMEWORK_TO_SKILL[fw];
+    if (skill && !skills.includes(skill)) {
+      skills.push(skill);
+    }
+  }
+
+  return {
+    frameworks: frameworkList,
+    language,
+    isFrontend: hasFrontend,
+    isBackend: hasBackend,
+    isFullstack,
+    suggestions: {
+      impeccable: hasFrontend,
+      skills,
+    },
+  };
+}

package/src/utils/status-dashboard.js

@@ -0,0 +1,254 @@
+/**
+ * Status dashboard formatter.
+ * Builds a structured terminal dashboard from session data and run-log lines.
+ */
+
+import { HU_STATUS } from "../hu/store.js";
+
+/**
+ * Status label mapping with visual indicators for terminal output.
+ * @type {Record<string, string>}
+ */
+const STATUS_LABELS = {
+  [HU_STATUS.PENDING]:       "pending",
+  [HU_STATUS.CODING]:        "coding",
+  [HU_STATUS.REVIEWING]:     "reviewing",
+  [HU_STATUS.DONE]:          "done",
+  [HU_STATUS.FAILED]:        "failed",
+  [HU_STATUS.BLOCKED]:       "blocked",
+  [HU_STATUS.CERTIFIED]:     "certified",
+  [HU_STATUS.NEEDS_CONTEXT]: "needs_ctx",
+};
+
+/**
+ * Format a millisecond duration into a human-readable string (e.g. "3m 42s").
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (!ms || ms < 0) return "0s";
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  const parts = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+
+/**
+ * Parse the current pipeline stage from log lines.
+ * @param {string[]} lines - Raw log lines.
+ * @returns {{ currentStage: string|null, lastEvent: string|null }}
+ */
+export function parseStageFromLog(lines) {
+  let currentStage = null;
+  let lastEvent = null;
+
+  for (const line of lines) {
+    const stageStart = /\[(\w+):start\]/.exec(line);
+    if (stageStart) currentStage = stageStart[1];
+
+    const stageDone = /\[(\w+):done\]|\[(\w+)\] finished/.exec(line);
+    if (stageDone) {
+      const doneName = stageDone[1] || stageDone[2];
+      if (doneName === currentStage) currentStage = "idle";
+    }
+
+    if (line.includes("[standby]") || line.includes("standby")) {
+      currentStage = "standby";
+    }
+
+    if (line.trim()) lastEvent = line.trim();
+  }
+
+  return { currentStage, lastEvent };
+}
+
+/**
+ * Format a single HU line for the dashboard.
+ * @param {object} story - HU story object.
+ * @param {boolean} isCurrent - Whether this is the currently active HU.
+ * @returns {string}
+ */
+function formatHuLine(story, isCurrent) {
+  const id = (story.id || "???").padEnd(12);
+  const rawStatus = story.status || "pending";
+  const label = STATUS_LABELS[rawStatus] || rawStatus;
+  const statusStr = `[${label}]`.padEnd(13);
+  const title = story.title || story.original?.text || "(untitled)";
+  const truncTitle = title.length > 40 ? title.slice(0, 37) + "..." : title;
+
+  let timing = "";
+  if (story.duration_ms) {
+    timing = formatDuration(story.duration_ms);
+  }
+
+  const blockedInfo = story.blocked_by?.length
+    ? ` (needs ${story.blocked_by.join(", ")})`
+    : "";
+
+  const marker = isCurrent ? "  <-- current" : "";
+  const timingStr = timing ? `  ${timing}` : "";
+
+  return `  ${id} ${statusStr} ${truncTitle}${blockedInfo}${timingStr}${marker}`;
+}
+
+/**
+ * Build a terminal dashboard string from session data and log lines.
+ *
+ * @param {object|null} sessionData - Session JSON (from session-store) or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array (from hu batch).
+ * @returns {string}
+ */
+export function buildDashboard(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return "No active pipeline";
+  }
+
+  const lines = [];
+  const config = sessionData.config_snapshot || {};
+  const maxIter = config.max_iterations ?? "?";
+  const status = sessionData.status || "unknown";
+
+  // Parse log for current stage info
+  const logInfo = parseStageFromLog(logLines || []);
+
+  // Determine iteration from session or log
+  const iteration = sessionData.reviewer_retry_count != null
+    ? sessionData.reviewer_retry_count + 1
+    : null;
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const displayIter = iterFromLog || iteration || "?";
+
+  // Pipeline header
+  const statusUpper = status.toUpperCase();
+  lines.push(`Pipeline: ${statusUpper} (iteration ${displayIter}/${maxIter})`);
+
+  // Duration
+  const duration = computeDuration(sessionData);
+  lines.push(`Duration: ${formatDuration(duration)}`);
+
+  // Agent info
+  const coderProvider = config.coder?.provider || config.roles?.coder?.provider || "?";
+  const reviewerProvider = config.reviewer?.provider || config.roles?.reviewer?.provider || "?";
+  lines.push(`Agent: ${coderProvider} (coder) / ${reviewerProvider} (reviewer)`);
+
+  // HU stories section
+  const stories = options.stories || [];
+  if (stories.length > 0) {
+    lines.push("");
+    lines.push("HUs:");
+
+    // Determine which story is currently being worked on
+    const currentStory = stories.find(s =>
+      s.status === HU_STATUS.CODING || s.status === HU_STATUS.REVIEWING
+    );
+
+    for (const story of stories) {
+      const isCurrent = currentStory && story.id === currentStory.id;
+      lines.push(formatHuLine(story, isCurrent));
+    }
+  }
+
+  // Current stage and last event
+  lines.push("");
+  const stage = logInfo.currentStage || "idle";
+  const iterSuffix = displayIter !== "?" ? ` (iteration ${displayIter})` : "";
+  lines.push(`Current stage: ${stage}${iterSuffix}`);
+
+  if (logInfo.lastEvent) {
+    // Truncate last event for display
+    const maxLen = 120;
+    const event = logInfo.lastEvent.length > maxLen
+      ? logInfo.lastEvent.slice(0, maxLen - 3) + "..."
+      : logInfo.lastEvent;
+    lines.push(`Last event: ${event}`);
+  }
+
+  // Errors
+  if (sessionData.deferred_issues?.length) {
+    lines.push("");
+    lines.push(`Deferred issues: ${sessionData.deferred_issues.length}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build a structured JSON response for MCP consumers.
+ *
+ * @param {object|null} sessionData - Session JSON or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array.
+ * @returns {object}
+ */
+export function buildDashboardJson(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return { ok: false, message: "No active pipeline" };
+  }
+
+  const config = sessionData.config_snapshot || {};
+  const logInfo = parseStageFromLog(logLines || []);
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const iteration = iterFromLog
+    || (sessionData.reviewer_retry_count != null ? sessionData.reviewer_retry_count + 1 : null);
+
+  const stories = (options.stories || []).map(s => ({
+    id: s.id,
+    status: s.status || "pending",
+    title: s.title || s.original?.text || null,
+    blocked_by: s.blocked_by || [],
+    duration_ms: s.duration_ms || null,
+  }));
+
+  return {
+    ok: true,
+    pipeline: {
+      status: sessionData.status || "unknown",
+      iteration: iteration || null,
+      maxIterations: config.max_iterations ?? null,
+      duration_ms: computeDuration(sessionData),
+      coder: config.coder?.provider || config.roles?.coder?.provider || null,
+      reviewer: config.reviewer?.provider || config.roles?.reviewer?.provider || null,
+    },
+    hus: stories,
+    currentStage: logInfo.currentStage || "idle",
+    lastEvent: logInfo.lastEvent || null,
+  };
+}
+
+/**
+ * Parse iteration number from log lines.
+ * @param {string[]} lines
+ * @returns {number|null}
+ */
+function parseIterationFromLog(lines) {
+  let iteration = null;
+  for (const line of lines) {
+    const m = /[Ii]teration\s+(\d+)/.exec(line);
+    if (m) iteration = Number.parseInt(m[1], 10);
+  }
+  return iteration;
+}
+
+/**
+ * Compute pipeline duration in milliseconds from session timestamps.
+ * @param {object} sessionData
+ * @returns {number}
+ */
+function computeDuration(sessionData) {
+  const created = sessionData.created_at;
+  if (!created) return 0;
+  const start = new Date(created).getTime();
+  const now = sessionData.updated_at
+    ? new Date(sessionData.updated_at).getTime()
+    : Date.now();
+  return Math.max(0, now - start);
+}

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;
+}