karajan-code 1.7.0 → 1.9.0

package/README.md

@@ -42,6 +42,7 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Interactive checkpoints** — instead of killing long-running tasks, pauses every 5 minutes with a progress report and lets you decide: continue, stop, or adjust the time
 - **Task decomposition** — triage detects when tasks should be split and recommends subtasks; with Planning Game integration, creates linked cards with sequential blocking
 - **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
+- **Pipeline stage tracker** — cumulative progress view during `kj_run` showing which stages are done, running, or pending — both in CLI and via MCP events for real-time host rendering
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -447,7 +448,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1025+ tests with Vitest
+npm test              # Run 1040+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/docs/README.es.md

@@ -41,6 +41,7 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Checkpoints interactivos** — en lugar de matar tareas largas, pausa cada 5 minutos con un informe de progreso y te deja decidir: continuar, parar o ajustar el tiempo
 - **Descomposicion de tareas** — triage detecta cuando una tarea debe dividirse y recomienda subtareas; con integracion Planning Game, crea cards vinculadas con bloqueo secuencial
 - **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
+- **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -231,7 +232,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 899+ tests con Vitest
+npm test              # Ejecutar 1040+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```

package/package.json

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

package/src/agents/claude-agent.js

@@ -2,13 +2,91 @@ import { BaseAgent } from "./base-agent.js";
 import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract the final text result from stream-json NDJSON output.
+ * Each line is a JSON object. We collect assistant text content from
+ * "result" messages and fall back to accumulating "content_block_delta" text.
+ */
+function extractTextFromStreamJson(raw) {
+  const lines = (raw || "").split("\n").filter(Boolean);
+  // Try to find a "result" message with the final text
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const obj = JSON.parse(lines[i]);
+      if (obj.type === "result" && obj.result) {
+        return typeof obj.result === "string" ? obj.result : JSON.stringify(obj.result);
+      }
+      // Claude Code stream-json final message
+      if (obj.result && typeof obj.result === "string") {
+        return obj.result;
+      }
+    } catch { /* skip unparseable lines */ }
+  }
+  // Fallback: accumulate all assistant text deltas
+  const parts = [];
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type === "assistant" && obj.message?.content) {
+        for (const block of obj.message.content) {
+          if (block.type === "text" && block.text) parts.push(block.text);
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return parts.join("") || raw;
+}
+
+/**
+ * Create a wrapping onOutput that parses stream-json lines and forwards
+ * meaningful content (assistant text, tool usage) to the original callback.
+ */
+function createStreamJsonFilter(onOutput) {
+  if (!onOutput) return null;
+  return ({ stream, line }) => {
+    try {
+      const obj = JSON.parse(line);
+      // Forward assistant text messages
+      if (obj.type === "assistant" && obj.message?.content) {
+        for (const block of obj.message.content) {
+          if (block.type === "text" && block.text) {
+            onOutput({ stream, line: block.text.slice(0, 200) });
+          } else if (block.type === "tool_use") {
+            onOutput({ stream, line: `[tool: ${block.name}]` });
+          }
+        }
+        return;
+      }
+      // Forward result
+      if (obj.type === "result") {
+        const summary = typeof obj.result === "string"
+          ? obj.result.slice(0, 200)
+          : "result received";
+        onOutput({ stream, line: `[result] ${summary}` });
+        return;
+      }
+    } catch { /* not JSON, forward raw */ }
+    onOutput({ stream, line });
+  };
+}
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
     const args = ["-p", task.prompt];
     const model = this.getRoleModel(role);
     if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("claude"), args, { onOutput: task.onOutput });
+
+    // Use stream-json when onOutput is provided to get real-time feedback
+    if (task.onOutput) {
+      args.push("--output-format", "stream-json");
+      const streamFilter = createStreamJsonFilter(task.onOutput);
+      const res = await runCommand(resolveBin("claude"), args, { onOutput: streamFilter });
+      const output = extractTextFromStreamJson(res.stdout);
+      return { ok: res.exitCode === 0, output, error: res.stderr, exitCode: res.exitCode };
+    }
+
+    const res = await runCommand(resolveBin("claude"), args);
     return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
   }
 

package/src/mcp/progress.js

@@ -6,6 +6,10 @@
 export const PROGRESS_STAGES = [
   "session:start",
   "iteration:start",
+  "triage:start",
+  "triage:end",
+  "researcher:start",
+  "researcher:end",
   "planner:start",
   "planner:end",
   "coder:start",
@@ -21,14 +25,89 @@ export const PROGRESS_STAGES = [
   "solomon:escalate",
   "question",
   "session:end",
-  "dry-run:summary"
+  "dry-run:summary",
+  "pipeline:tracker",
+  "agent:heartbeat",
+  "agent:stall"
 ];
 
+const PIPELINE_ORDER = [
+  "triage", "researcher", "planner", "coder", "refactorer", "sonar", "reviewer", "tester", "security", "commiter"
+];
+
+export function buildPipelineTracker(config, emitter) {
+  const pipeline = config.pipeline || {};
+
+  const stages = PIPELINE_ORDER
+    .filter(name => {
+      if (name === "coder") return true;
+      if (name === "reviewer") return pipeline.reviewer?.enabled !== false;
+      if (name === "sonar") return pipeline.sonar?.enabled || config.sonarqube?.enabled;
+      return pipeline[name]?.enabled;
+    })
+    .map(name => ({ name, status: "pending", summary: undefined }));
+
+  const findStage = (name) => stages.find(s => s.name === name);
+
+  const emitTracker = () => {
+    emitter.emit("progress", {
+      type: "pipeline:tracker",
+      detail: { stages: stages.map(s => ({ ...s })) }
+    });
+  };
+
+  emitter.on("progress", (event) => {
+    const match = event.type?.match(/^(\w+):(start|end)$/);
+    if (!match) return;
+
+    const [, name, phase] = match;
+    const stage = findStage(name);
+    if (!stage) return;
+
+    if (phase === "start") {
+      stage.status = "running";
+      stage.summary = event.detail?.[name] || stage.summary;
+    } else {
+      stage.status = event.status === "fail" ? "failed" : "done";
+      stage.summary = event.detail?.summary || event.detail?.gateStatus || stage.summary;
+    }
+
+    emitTracker();
+  });
+
+  return { stages };
+}
+
+export function sendTrackerLog(server, stageName, status, summary) {
+  try {
+    server.sendLoggingMessage({
+      level: "info",
+      logger: "karajan",
+      data: {
+        type: "pipeline:tracker",
+        detail: {
+          stages: [{ name: stageName, status, summary: summary || undefined }]
+        }
+      }
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+function resolveLogLevel(event) {
+  if (event.type === "agent:output") return "debug";
+  if (event.type === "agent:heartbeat") return "debug";
+  if (event.type === "agent:stall") return "warning";
+  if (event.status === "fail") return "error";
+  return "info";
+}
+
 export function buildProgressHandler(server) {
   return (event) => {
     try {
       server.sendLoggingMessage({
-        level: event.type === "agent:output" ? "debug" : event.status === "fail" ? "error" : "info",
+        level: resolveLogLevel(event),
         logger: "karajan",
         data: event
       });

package/src/mcp/server-handlers.js

@@ -7,7 +7,8 @@ import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
 import { runKjCommand } from "./run-kj.js";
 import { normalizePlanArgs } from "./tool-arg-normalizers.js";
-import { buildProgressHandler, buildProgressNotifier } from "./progress.js";
+import { buildProgressHandler, buildProgressNotifier, buildPipelineTracker, sendTrackerLog } from "./progress.js";
+import { createStallDetector } from "../utils/stall-detector.js";
 import { runFlow, resumeFlow } from "../orchestrator.js";
 import { loadConfig, applyRunOverrides, validateConfig, resolveRole } from "../config.js";
 import { createLogger } from "../utils/logger.js";
@@ -19,6 +20,24 @@ import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { parseMaybeJsonString } from "../review/parser.js";
 import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
 import { resolveReviewProfile } from "../review/profiles.js";
+import { createRunLog, readRunLog } from "../utils/run-log.js";
+
+/**
+ * Resolve the user's project directory via MCP roots.
+ * Falls back to process.cwd() if roots are not available.
+ */
+async function resolveProjectDir(server) {
+  try {
+    const { roots } = await server.listRoots();
+    if (roots?.length > 0) {
+      const uri = roots[0].uri;
+      // MCP roots use file:// URIs
+      if (uri.startsWith("file://")) return new URL(uri).pathname;
+      return uri;
+    }
+  } catch { /* client may not support roots */ }
+  return process.cwd();
+}
 
 export function asObject(value) {
   if (value && typeof value === "object") return value;
@@ -147,16 +166,27 @@ export async function handleRunDirect(a, server, extra) {
   if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
   await assertAgentsAvailable(requiredProviders);
 
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_run] started — task="${a.task.slice(0, 80)}..."`);
+
   const emitter = new EventEmitter();
   emitter.on("progress", buildProgressHandler(server));
+  emitter.on("progress", (event) => runLog.logEvent(event));
   const progressNotifier = buildProgressNotifier(extra);
   if (progressNotifier) emitter.on("progress", progressNotifier);
+  buildPipelineTracker(config, emitter);
 
   const askQuestion = buildAskQuestion(server);
   const pgTaskId = a.pgTask || null;
   const pgProject = a.pgProject || config.planning_game?.project_id || null;
-  const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion, pgTaskId, pgProject });
-  return { ok: !result.paused && (result.approved !== false), ...result };
+  try {
+    const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion, pgTaskId, pgProject });
+    runLog.logText(`[kj_run] finished — ok=${!result.paused && (result.approved !== false)}`);
+    return { ok: !result.paused && (result.approved !== false), ...result };
+  } finally {
+    runLog.close();
+  }
 }
 
 export async function handleResumeDirect(a, server, extra) {
@@ -181,6 +211,20 @@ export async function handleResumeDirect(a, server, extra) {
   return { ok: true, ...result };
 }
 
+function buildDirectEmitter(server, runLog) {
+  const emitter = new EventEmitter();
+  emitter.on("progress", (event) => {
+    try {
+      const level = event.type === "agent:stall" ? "warning"
+        : event.type === "agent:heartbeat" ? "info"
+        : "debug";
+      server.sendLoggingMessage({ level, logger: "karajan", data: event });
+    } catch { /* best-effort */ }
+    if (runLog) runLog.logEvent(event);
+  });
+  return emitter;
+}
+
 export async function handlePlanDirect(a, server, extra) {
   const options = normalizePlanArgs(a);
   const config = await buildConfig(options, "plan");
@@ -189,14 +233,38 @@ export async function handlePlanDirect(a, server, extra) {
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
 
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_plan] started — provider=${plannerRole.provider}`);
+  const emitter = buildDirectEmitter(server, runLog);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
+  });
+
   const planner = createAgent(plannerRole.provider, config, logger);
   const prompt = buildPlannerPrompt({ task: a.task, context: a.context });
-  const result = await planner.runTask({ prompt, role: "planner" });
+  sendTrackerLog(server, "planner", "running", plannerRole.provider);
+  runLog.logText(`[planner] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await planner.runTask({ prompt, role: "planner", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[planner] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
 
   if (!result.ok) {
+    sendTrackerLog(server, "planner", "failed");
     throw new Error(result.error || result.output || "Planner failed");
   }
 
+  sendTrackerLog(server, "planner", "done");
   const parsed = parseMaybeJsonString(result.output);
   return { ok: true, plan: parsed || result.output, raw: result.output };
 }
@@ -208,6 +276,18 @@ export async function handleCodeDirect(a, server, extra) {
   const coderRole = resolveRole(config, "coder");
   await assertAgentsAvailable([coderRole.provider]);
 
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
+  const emitter = buildDirectEmitter(server, runLog);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "coder", message: line, detail: { stream, agent: coderRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "coder", provider: coderRole.provider
+  });
+
   const coder = createAgent(coderRole.provider, config, logger);
   let coderRules = null;
   if (config.coder_rules) {
@@ -216,12 +296,24 @@ export async function handleCodeDirect(a, server, extra) {
     } catch { /* no coder rules file */ }
   }
   const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
-  const result = await coder.runTask({ prompt, role: "coder" });
+  sendTrackerLog(server, "coder", "running", coderRole.provider);
+  runLog.logText(`[coder] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await coder.runTask({ prompt, role: "coder", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[coder] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
 
   if (!result.ok) {
+    sendTrackerLog(server, "coder", "failed");
     throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
   }
 
+  sendTrackerLog(server, "coder", "done");
   return { ok: true, output: result.output, exitCode: result.exitCode };
 }
 
@@ -232,18 +324,42 @@ export async function handleReviewDirect(a, server, extra) {
   const reviewerRole = resolveRole(config, "reviewer");
   await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
 
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
+  const emitter = buildDirectEmitter(server, runLog);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "reviewer", message: line, detail: { stream, agent: reviewerRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
+  });
+
   const reviewer = createAgent(reviewerRole.provider, config, logger);
   const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef: a.baseRef });
   const diff = await generateDiff({ baseRef: resolvedBase });
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
   const prompt = buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
-  const result = await reviewer.reviewTask({ prompt, role: "reviewer" });
+  sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
+  runLog.logText(`[reviewer] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await reviewer.reviewTask({ prompt, role: "reviewer", onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[reviewer] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
 
   if (!result.ok) {
+    sendTrackerLog(server, "reviewer", "failed");
     throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
   }
 
+  sendTrackerLog(server, "reviewer", "done");
   const parsed = parseMaybeJsonString(result.output);
   return { ok: true, review: parsed || result.output, raw: result.output };
 }
@@ -251,6 +367,12 @@ export async function handleReviewDirect(a, server, extra) {
 export async function handleToolCall(name, args, server, extra) {
   const a = asObject(args);
 
+  if (name === "kj_status") {
+    const maxLines = a.lines || 50;
+    const projectDir = await resolveProjectDir(server);
+    return readRunLog(maxLines, projectDir);
+  }
+
   if (name === "kj_init") {
     return runKjCommand({ command: "init", options: a });
   }

package/src/mcp/tools.js

@@ -165,6 +165,16 @@ export const tools = [
       }
     }
   },
+  {
+    name: "kj_status",
+    description: "Show real-time log of the current or last Karajan run. Use this to monitor progress while kj_run/kj_plan/kj_code is executing. Reads from .kj/run.log in the project directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lines: { type: "number", description: "Number of log lines to show (default 50)" }
+      }
+    }
+  },
   {
     name: "kj_plan",
     description: "Generate implementation plan for a task",

package/src/orchestrator/iteration-stages.js

@@ -11,6 +11,7 @@ import { runReviewerWithFallback } from "./reviewer-fallback.js";
 import { runCoderWithFallback } from "./agent-fallback.js";
 import { invokeSolomon } from "./solomon-escalation.js";
 import { detectRateLimit } from "../utils/rate-limit-detector.js";
+import { createStallDetector } from "../utils/stall-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration }) {
   logger.setContext({ iteration, stage: "coder" });
@@ -28,13 +29,21 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       detail: { stream, agent: coderRole.provider }
     }));
   };
-  const coderStart = Date.now();
-  const coderExecResult = await coderRoleInstance.execute({
-    task: plannedTask,
-    reviewerFeedback: session.last_reviewer_feedback,
-    sonarSummary: session.last_sonar_summary,
-    onOutput: coderOnOutput
+  const coderStall = createStallDetector({
+    onOutput: coderOnOutput, emitter, eventBase, stage: "coder", provider: coderRole.provider
   });
+  const coderStart = Date.now();
+  let coderExecResult;
+  try {
+    coderExecResult = await coderRoleInstance.execute({
+      task: plannedTask,
+      reviewerFeedback: session.last_reviewer_feedback,
+      sonarSummary: session.last_sonar_summary,
+      onOutput: coderStall.onOutput
+    });
+  } finally {
+    coderStall.stop();
+  }
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
 
   if (!coderExecResult.ok) {
@@ -130,10 +139,25 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
       detail: { refactorer: refactorerRole.provider }
     })
   );
+  const refactorerOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "refactorer" }, {
+      message: line,
+      detail: { stream, agent: refactorerRole.provider }
+    }));
+  };
+  const refactorerStall = createStallDetector({
+    onOutput: refactorerOnOutput, emitter, eventBase, stage: "refactorer", provider: refactorerRole.provider
+  });
+
   const refRole = new RefactorerRole({ config, logger, emitter, createAgentFn: createAgent });
   await refRole.init();
   const refactorerStart = Date.now();
-  const refResult = await refRole.execute(plannedTask);
+  let refResult;
+  try {
+    refResult = await refRole.execute({ task: plannedTask, onOutput: refactorerStall.onOutput });
+  } finally {
+    refactorerStall.stop();
+  }
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
   if (!refResult.ok) {
     const details = refResult.result?.error || refResult.summary || "unknown error";
@@ -392,19 +416,27 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
       detail: { stream, agent: reviewerRole.provider }
     }));
   };
-  const reviewerStart = Date.now();
-  const reviewerExec = await runReviewerWithFallback({
-    reviewerName: reviewerRole.provider,
-    config,
-    logger,
-    emitter,
-    reviewInput: { task, diff, reviewRules, onOutput: reviewerOnOutput },
-    session,
-    iteration,
-    onAttemptResult: ({ reviewer, result }) => {
-      trackBudget({ role: "reviewer", provider: reviewer, model: reviewerRole.model, result, duration_ms: Date.now() - reviewerStart });
-    }
+  const reviewerStall = createStallDetector({
+    onOutput: reviewerOnOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
   });
+  const reviewerStart = Date.now();
+  let reviewerExec;
+  try {
+    reviewerExec = await runReviewerWithFallback({
+      reviewerName: reviewerRole.provider,
+      config,
+      logger,
+      emitter,
+      reviewInput: { task, diff, reviewRules, onOutput: reviewerStall.onOutput },
+      session,
+      iteration,
+      onAttemptResult: ({ reviewer, result }) => {
+        trackBudget({ role: "reviewer", provider: reviewer, model: reviewerRole.model, result, duration_ms: Date.now() - reviewerStart });
+      }
+    });
+  } finally {
+    reviewerStall.stop();
+  }
 
   if (!reviewerExec.execResult || !reviewerExec.execResult.ok) {
     const lastAttempt = reviewerExec.attempts.at(-1);

package/src/orchestrator/pre-loop-stages.js

@@ -6,6 +6,7 @@ import { addCheckpoint, markSessionStatus } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { parsePlannerOutput } from "../prompts/planner.js";
 import { selectModelsForRoles } from "../utils/model-selector.js";
+import { createStallDetector } from "../utils/stall-detector.js";
 
 export async function runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   logger.setContext({ iteration: 0, stage: "triage" });
@@ -16,10 +17,26 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     })
   );
 
+  const triageProvider = config?.roles?.triage?.provider || coderRole.provider;
+  const triageOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "triage" }, {
+      message: line,
+      detail: { stream, agent: triageProvider }
+    }));
+  };
+  const triageStall = createStallDetector({
+    onOutput: triageOnOutput, emitter, eventBase, stage: "triage", provider: triageProvider
+  });
+
   const triage = new TriageRole({ config, logger, emitter });
   await triage.init({ task: session.task, sessionId: session.id, iteration: 0 });
   const triageStart = Date.now();
-  const triageOutput = await triage.run({ task: session.task });
+  let triageOutput;
+  try {
+    triageOutput = await triage.run({ task: session.task, onOutput: triageStall.onOutput });
+  } finally {
+    triageStall.stop();
+  }
   trackBudget({
     role: "triage",
     provider: config?.roles?.triage?.provider || coderRole.provider,
@@ -115,10 +132,26 @@ export async function runResearcherStage({ config, logger, emitter, eventBase, s
     })
   );
 
+  const researcherProvider = config?.roles?.researcher?.provider || coderRole.provider;
+  const researcherOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "researcher" }, {
+      message: line,
+      detail: { stream, agent: researcherProvider }
+    }));
+  };
+  const researcherStall = createStallDetector({
+    onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherProvider
+  });
+
   const researcher = new ResearcherRole({ config, logger, emitter });
   await researcher.init({ task: session.task });
   const researchStart = Date.now();
-  const researchOutput = await researcher.run({ task: session.task });
+  let researchOutput;
+  try {
+    researchOutput = await researcher.run({ task: session.task, onOutput: researcherStall.onOutput });
+  } finally {
+    researcherStall.stop();
+  }
   trackBudget({
     role: "researcher",
     provider: config?.roles?.researcher?.provider || coderRole.provider,
@@ -160,11 +193,26 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
     })
   );
 
+  const plannerOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "planner" }, {
+      message: line,
+      detail: { stream, agent: plannerRole.provider }
+    }));
+  };
+  const plannerStall = createStallDetector({
+    onOutput: plannerOnOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
+  });
+
   const planRole = new PlannerRole({ config, logger, emitter, createAgentFn: createAgent });
   planRole.context = { task, research: researchContext, triageDecomposition };
   await planRole.init();
   const plannerStart = Date.now();
-  const planResult = await planRole.execute(task);
+  let planResult;
+  try {
+    planResult = await planRole.execute({ task, onOutput: plannerStall.onOutput });
+  } finally {
+    plannerStall.stop();
+  }
   trackBudget({ role: "planner", provider: plannerRole.provider, model: plannerRole.model, result: planResult.result, duration_ms: Date.now() - plannerStart });
   await addCheckpoint(session, {
     stage: "planner",

package/src/roles/planner-role.js

@@ -65,15 +65,20 @@ export class PlannerRole extends BaseRole {
   }
 
   async execute(input) {
-    const task = input || this.context?.task || "";
+    const { task, onOutput } = typeof input === "string"
+      ? { task: input, onOutput: null }
+      : { task: input?.task || input || "", onOutput: input?.onOutput || null };
+    const taskStr = task || this.context?.task || "";
     const research = this.context?.research || null;
     const triageDecomposition = this.context?.triageDecomposition || null;
     const provider = resolveProvider(this.config);
 
     const agent = this._createAgent(provider, this.config, this.logger);
-    const prompt = buildPrompt({ task, instructions: this.instructions, research, triageDecomposition });
+    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition });
 
-    const result = await agent.runTask({ prompt, role: "planner" });
+    const runArgs = { prompt, role: "planner" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
 
     if (!result.ok) {
       return {

package/src/roles/refactorer-role.js

@@ -36,12 +36,15 @@ export class RefactorerRole extends BaseRole {
     const task = typeof input === "string"
       ? input
       : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
 
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
     const prompt = buildPrompt({ task, instructions: this.instructions });
-    const result = await agent.runTask({ prompt, role: "refactorer" });
+    const runArgs = { prompt, role: "refactorer" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
 
     if (!result.ok) {
       return {

package/src/roles/researcher-role.js

@@ -64,12 +64,15 @@ export class ResearcherRole extends BaseRole {
     const task = typeof input === "string"
       ? input
       : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
 
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
     const prompt = buildPrompt({ task, instructions: this.instructions });
-    const result = await agent.runTask({ prompt, role: "researcher" });
+    const runArgs = { prompt, role: "researcher" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
 
     if (!result.ok) {
       return {

package/src/roles/triage-role.js

@@ -67,12 +67,15 @@ export class TriageRole extends BaseRole {
     const task = typeof input === "string"
       ? input
       : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
 
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
     const prompt = buildPrompt({ task, instructions: this.instructions });
-    const result = await agent.runTask({ prompt, role: "triage" });
+    const runArgs = { prompt, role: "triage" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
 
     if (!result.ok) {
       return {

package/src/utils/display.js

@@ -343,6 +343,26 @@ export function printEvent(event) {
       console.log(`${ANSI.dim}Resume with: kj resume ${event.sessionId} --answer "<response>"${ANSI.reset}`);
       break;
 
+    case "pipeline:tracker": {
+      const trackerStages = event.detail?.stages || [];
+      console.log(`  ${ANSI.dim}\u250c Pipeline${ANSI.reset}`);
+      for (const stage of trackerStages) {
+        let stIcon, stColor;
+        switch (stage.status) {
+          case "done": stIcon = "\u2713"; stColor = ANSI.green; break;
+          case "running": stIcon = "\u25b6"; stColor = ANSI.cyan; break;
+          case "failed": stIcon = "\u2717"; stColor = ANSI.red; break;
+          default: stIcon = "\u00b7"; stColor = ANSI.dim; break;
+        }
+        const suffix = stage.summary
+          ? stage.status === "running" ? ` (${stage.summary})` : ` \u2192 ${stage.summary}`
+          : "";
+        console.log(`  ${ANSI.dim}\u2502${ANSI.reset} ${stColor}${stIcon} ${stage.name}${suffix}${ANSI.reset}`);
+      }
+      console.log(`  ${ANSI.dim}\u2514${ANSI.reset}`);
+      break;
+    }
+
     case "agent:output":
       console.log(`  \u2502 ${ANSI.dim}${event.message}${ANSI.reset}`);
       break;

package/src/utils/run-log.js

@@ -0,0 +1,126 @@
+/**
+ * File-based run logger.
+ *
+ * Writes progress events to a known file so that external tools
+ * (tail -f, kj_status, another Claude process) can monitor what
+ * Karajan is doing in real time.
+ *
+ * Log location: <projectDir>/.kj/run.log  (overwritten each run)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const LOG_FILENAME = "run.log";
+
+function resolveLogDir(baseDir) {
+  return path.join(baseDir || process.cwd(), ".kj");
+}
+
+function resolveLogPath(baseDir) {
+  return path.join(resolveLogDir(baseDir), LOG_FILENAME);
+}
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch { /* already exists */ }
+}
+
+function formatLine(event) {
+  const ts = new Date().toISOString().slice(11, 23);
+  const stage = event.stage || event.detail?.stage || "";
+  const type = event.type || "info";
+  const msg = event.message || "";
+  const extra = [];
+
+  if (event.detail?.provider) extra.push(`agent=${event.detail.provider}`);
+  if (event.detail?.lineCount !== undefined) extra.push(`lines=${event.detail.lineCount}`);
+  if (event.detail?.elapsedMs !== undefined) extra.push(`elapsed=${Math.round(event.detail.elapsedMs / 1000)}s`);
+  if (event.detail?.silenceMs !== undefined) extra.push(`silence=${Math.round(event.detail.silenceMs / 1000)}s`);
+  if (event.detail?.severity) extra.push(`severity=${event.detail.severity}`);
+  if (event.detail?.stream) extra.push(`stream=${event.detail.stream}`);
+
+  const extraStr = extra.length ? ` (${extra.join(", ")})` : "";
+  return `${ts} [${type}] ${stage ? `[${stage}] ` : ""}${msg}${extraStr}`;
+}
+
+export function createRunLog(projectDir) {
+  const logPath = resolveLogPath(projectDir);
+  const logDir = resolveLogDir(projectDir);
+  ensureDir(logDir);
+
+  // Truncate/create the log file
+  fs.writeFileSync(logPath, `--- Karajan run started at ${new Date().toISOString()} ---\n`);
+
+  let fd = null;
+  try {
+    fd = fs.openSync(logPath, "a");
+  } catch {
+    // If we can't open for append, use writeFile fallback
+  }
+
+  function write(line) {
+    try {
+      if (fd !== null) {
+        fs.writeSync(fd, line + "\n");
+      } else {
+        fs.appendFileSync(logPath, line + "\n");
+      }
+    } catch { /* best-effort */ }
+  }
+
+  function logEvent(event) {
+    write(formatLine(event));
+  }
+
+  function logText(text) {
+    const ts = new Date().toISOString().slice(11, 23);
+    write(`${ts} ${text}`);
+  }
+
+  function close() {
+    try {
+      if (fd !== null) {
+        fs.closeSync(fd);
+        fd = null;
+      }
+    } catch { /* best-effort */ }
+  }
+
+  return {
+    logEvent,
+    logText,
+    close,
+    get path() { return logPath; }
+  };
+}
+
+/**
+ * Read the current run log contents.
+ * Returns the last N lines (default 50).
+ */
+export function readRunLog(maxLines = 50, projectDir) {
+  const logPath = resolveLogPath(projectDir);
+  try {
+    const content = fs.readFileSync(logPath, "utf8");
+    const lines = content.split("\n").filter(Boolean);
+    const total = lines.length;
+    const shown = lines.slice(-maxLines);
+    return {
+      ok: true,
+      path: logPath,
+      totalLines: total,
+      lines: shown,
+      summary: shown.join("\n")
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      path: logPath,
+      error: err.code === "ENOENT"
+        ? "No active run log found. Start a run with kj_run first."
+        : `Failed to read log: ${err.message}`
+    };
+  }
+}

package/src/utils/stall-detector.js

@@ -0,0 +1,126 @@
+/**
+ * Stall detector for agent execution.
+ *
+ * Wraps an onOutput callback to track activity and emit heartbeat / stall
+ * warnings when an agent stops producing output for too long.
+ *
+ * Usage:
+ *   const detector = createStallDetector({ onOutput, emitter, eventBase, stage, provider, stallTimeoutMs });
+ *   // pass detector.onOutput to the agent
+ *   // when done: detector.stop();
+ */
+
+import { emitProgress, makeEvent } from "./events.js";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;   // heartbeat every 30s
+const DEFAULT_STALL_TIMEOUT_MS      = 120_000;  // warn after 2min silence
+const DEFAULT_CRITICAL_TIMEOUT_MS   = 300_000;  // critical after 5min silence
+
+export function createStallDetector({
+  onOutput,
+  emitter,
+  eventBase,
+  stage,
+  provider,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+  stallTimeoutMs      = DEFAULT_STALL_TIMEOUT_MS,
+  criticalTimeoutMs   = DEFAULT_CRITICAL_TIMEOUT_MS
+}) {
+  let lastActivityAt = Date.now();
+  let lineCount = 0;
+  let bytesReceived = 0;
+  let stallWarned = false;
+  let criticalWarned = false;
+  let heartbeatTimer = null;
+  const startedAt = Date.now();
+
+  function emitHeartbeat() {
+    const now = Date.now();
+    const silenceMs = now - lastActivityAt;
+    const elapsedMs = now - startedAt;
+
+    if (silenceMs >= criticalTimeoutMs && !criticalWarned) {
+      criticalWarned = true;
+      emitProgress(emitter, makeEvent("agent:stall", { ...eventBase, stage }, {
+        status: "critical",
+        message: `Agent ${provider} unresponsive for ${Math.round(silenceMs / 1000)}s — may be hung`,
+        detail: {
+          provider,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          severity: "critical"
+        }
+      }));
+    } else if (silenceMs >= stallTimeoutMs && !stallWarned) {
+      stallWarned = true;
+      emitProgress(emitter, makeEvent("agent:stall", { ...eventBase, stage }, {
+        status: "warning",
+        message: `Agent ${provider} silent for ${Math.round(silenceMs / 1000)}s — still waiting`,
+        detail: {
+          provider,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          severity: "warning"
+        }
+      }));
+    } else if (silenceMs < stallTimeoutMs) {
+      // Reset warning flags when activity resumes
+      stallWarned = false;
+      criticalWarned = false;
+
+      emitProgress(emitter, makeEvent("agent:heartbeat", { ...eventBase, stage }, {
+        message: `Agent ${provider} active — ${lineCount} lines, ${Math.round(elapsedMs / 1000)}s elapsed`,
+        detail: {
+          provider,
+          elapsedMs,
+          lineCount,
+          bytesReceived
+        }
+      }));
+    }
+  }
+
+  // Start periodic heartbeat
+  heartbeatTimer = setInterval(emitHeartbeat, heartbeatIntervalMs);
+
+  function wrappedOnOutput(data) {
+    lastActivityAt = Date.now();
+    lineCount++;
+    bytesReceived += data.line?.length || 0;
+
+    // Reset stall flags on new activity
+    stallWarned = false;
+    criticalWarned = false;
+
+    // Forward to the original callback
+    if (onOutput) {
+      onOutput(data);
+    }
+  }
+
+  function stop() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  function stats() {
+    return {
+      lineCount,
+      bytesReceived,
+      elapsedMs: Date.now() - startedAt,
+      lastActivityMs: Date.now() - lastActivityAt
+    };
+  }
+
+  return {
+    onOutput: wrappedOnOutput,
+    stop,
+    stats
+  };
+}