karajan-code 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.8.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",
@@ -22,7 +26,9 @@ export const PROGRESS_STAGES = [
   "question",
   "session:end",
   "dry-run:summary",
-  "pipeline:tracker"
+  "pipeline:tracker",
+  "agent:heartbeat",
+  "agent:stall"
 ];
 
 const PIPELINE_ORDER = [
@@ -89,11 +95,19 @@ export function sendTrackerLog(server, stageName, status, summary) {
   }
 }
 
+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

@@ -8,6 +8,7 @@ import fs from "node:fs/promises";
 import { runKjCommand } from "./run-kj.js";
 import { normalizePlanArgs } from "./tool-arg-normalizers.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,8 +166,13 @@ 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);
@@ -156,8 +180,13 @@ export async function handleRunDirect(a, server, extra) {
   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) {
@@ -182,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");
@@ -190,10 +233,31 @@ 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 });
   sendTrackerLog(server, "planner", "running", plannerRole.provider);
-  const result = await planner.runTask({ prompt, role: "planner" });
+  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");
@@ -212,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) {
@@ -221,7 +297,16 @@ export async function handleCodeDirect(a, server, extra) {
   }
   const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
   sendTrackerLog(server, "coder", "running", coderRole.provider);
-  const result = await coder.runTask({ prompt, role: "coder" });
+  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");
@@ -239,6 +324,18 @@ 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 });
@@ -246,7 +343,16 @@ export async function handleReviewDirect(a, server, extra) {
 
   const prompt = buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
   sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
-  const result = await reviewer.reviewTask({ prompt, role: "reviewer" });
+  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");
@@ -261,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/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
+  };
+}