karajan-code 1.33.0 → 1.34.2

package/package.json

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

package/src/cli.js

@@ -23,6 +23,7 @@ import { triageCommand } from "./commands/triage.js";
 import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
+import { boardCommand } from "./commands/board.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -305,6 +306,17 @@ program
     }
   });
 
+program
+  .command("board [action]")
+  .description("Manage HU Board (start|stop|status|open)")
+  .option("--port <number>", "Port (default: 4000)", "4000")
+  .action(async (action = "start", opts) => {
+    await withConfig("board", opts, async ({ config, logger }) => {
+      const port = Number(opts.port) || config.hu_board?.port || 4000;
+      await boardCommand({ action, port, logger });
+    });
+  });
+
 const sonar = program.command("sonar").description("Manage SonarQube container");
 sonar.command("status").action(async () => sonarCommand({ action: "status" }));
 sonar.command("start").action(async () => sonarCommand({ action: "start" }));

package/src/commands/board.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { getKarajanHome } from "../utils/paths.js";
+
+const BOARD_DIR = path.resolve(import.meta.dirname, "../../packages/hu-board");
+const PID_FILE = path.join(getKarajanHome(), "hu-board.pid");
+
+function readPid() {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startBoard(port = 4000) {
+  const existingPid = readPid();
+  if (existingPid && isProcessAlive(existingPid)) {
+    return { ok: true, alreadyRunning: true, pid: existingPid, url: `http://localhost:${port}` };
+  }
+
+  const serverPath = path.join(BOARD_DIR, "src/server.js");
+  const karajanHome = getKarajanHome();
+  fs.mkdirSync(karajanHome, { recursive: true });
+
+  const child = spawn("node", [serverPath], {
+    env: { ...process.env, PORT: String(port) },
+    detached: true,
+    stdio: "ignore",
+    cwd: BOARD_DIR
+  });
+  child.unref();
+
+  fs.writeFileSync(PID_FILE, String(child.pid));
+  return { ok: true, alreadyRunning: false, pid: child.pid, url: `http://localhost:${port}` };
+}
+
+export async function stopBoard() {
+  const pid = readPid();
+  if (!pid || !isProcessAlive(pid)) {
+    try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+    return { ok: true, wasRunning: false };
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // already dead
+  }
+  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+  return { ok: true, wasRunning: true, pid };
+}
+
+export async function boardStatus(port = 4000) {
+  const pid = readPid();
+  const running = pid !== null && isProcessAlive(pid);
+  return {
+    ok: true,
+    running,
+    pid: running ? pid : null,
+    url: running ? `http://localhost:${port}` : null
+  };
+}
+
+export async function boardCommand({ action = "start", port = 4000, logger }) {
+  switch (action) {
+    case "start": {
+      const result = await startBoard(port);
+      if (result.alreadyRunning) {
+        logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
+      } else {
+        logger.info(`HU Board started (PID ${result.pid}) at ${result.url}`);
+      }
+      return result;
+    }
+    case "stop": {
+      const result = await stopBoard();
+      if (result.wasRunning) {
+        logger.info(`HU Board stopped (PID ${result.pid})`);
+      } else {
+        logger.info("HU Board was not running");
+      }
+      return result;
+    }
+    case "status": {
+      const result = await boardStatus(port);
+      if (result.running) {
+        logger.info(`HU Board is running (PID ${result.pid}) at ${result.url}`);
+      } else {
+        logger.info("HU Board is not running");
+      }
+      return result;
+    }
+    case "open": {
+      const status = await boardStatus(port);
+      if (!status.running) {
+        logger.info("HU Board is not running. Starting it first...");
+        await startBoard(port);
+      }
+      const url = `http://localhost:${port}`;
+      const { default: open } = await import("open").catch(() => ({ default: null }));
+      if (open) {
+        await open(url);
+        logger.info(`Opened ${url}`);
+      } else {
+        logger.info(`Open in browser: ${url}`);
+      }
+      return { ok: true, url };
+    }
+    default:
+      logger.error(`Unknown board action: ${action}. Use start|stop|status|open`);
+      return { ok: false, error: `Unknown action: ${action}` };
+  }
+}

package/src/commands/init.js

@@ -70,6 +70,15 @@ async function runWizard(config, logger) {
     config.sonarqube.enabled = enableSonar;
     logger.info(`  -> SonarQube: ${enableSonar ? "enabled" : "disabled"}`);
 
+    const enableHuBoard = await wizard.confirm("Enable HU Board for story tracking?", false);
+    config.hu_board = config.hu_board || {};
+    config.hu_board.enabled = enableHuBoard;
+    if (enableHuBoard) {
+      config.hu_board.port = 4000;
+      config.hu_board.auto_start = true;
+    }
+    logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
+
     const methodology = await wizard.select("Development methodology:", [
       { label: "TDD (test-driven development)", value: "tdd", available: true },
       { label: "Standard (no TDD enforcement)", value: "standard", available: true }

package/src/config.js

@@ -118,6 +118,11 @@ const DEFAULTS = {
       test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
     }
   },
+  hu_board: {
+    enabled: false,
+    port: 4000,
+    auto_start: false
+  },
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
@@ -420,6 +425,34 @@ export function applyRunOverrides(config, flags) {
   return out;
 }
 
+/**
+ * Check if a model string is compatible with an agent provider.
+ * Only returns false when the model clearly belongs to a DIFFERENT provider.
+ * Returns true if we can't determine or if the model is ambiguous.
+ */
+const AGENT_MODEL_SIGNATURES = {
+  claude: ["claude", "sonnet", "opus", "haiku"],
+  codex: ["o4-", "o3-", "gpt-", "codex"],
+  gemini: ["gemini", "flash-"]
+};
+
+export function isModelCompatible(agent, model) {
+  if (!model || !agent) return true;
+  const lower = model.toLowerCase();
+
+  // Check if model clearly belongs to a different provider
+  for (const [provider, signatures] of Object.entries(AGENT_MODEL_SIGNATURES)) {
+    if (provider === agent) continue;
+    if (signatures.some(s => lower.includes(s))) {
+      // Model belongs to a different provider — incompatible
+      return false;
+    }
+  }
+
+  // Model doesn't clearly belong to any other provider — allow it
+  return true;
+}
+
 export function resolveRole(config, role) {
   const roles = config?.roles || {};
   const roleConfig = roles[role] || {};
@@ -434,10 +467,17 @@ export function resolveRole(config, role) {
   }
 
   let model = roleConfig.model ?? null;
+  let modelIsInherited = false;
   if (!model && role === "coder") model = config?.coder_options?.model ?? null;
   if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
   if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "hu_reviewer" || role === "hu-reviewer")) {
     model = config?.coder_options?.model ?? null;
+    modelIsInherited = !!model;
+  }
+
+  // Drop inherited model if incompatible with the resolved provider
+  if (modelIsInherited && provider && model && !isModelCompatible(provider, model)) {
+    model = null;
   }
 
   return { provider, model };

package/src/mcp/server-handlers.js

@@ -790,7 +790,10 @@ async function handleRun(a, server, extra) {
     }
   }
   if (!isPreflightAcked()) {
-    return buildPreflightRequiredResponse("kj_run");
+    // Auto-acknowledge with defaults for autonomous operation
+    ackPreflight({});
+    const logger = createLogger("info", "mcp");
+    logger.info("Preflight auto-acknowledged with default agent config");
   }
   applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
   return handleRunDirect(a, server, extra);
@@ -801,7 +804,10 @@ async function handleCode(a, server, extra) {
     return failPayload("Missing required field: task");
   }
   if (!isPreflightAcked()) {
-    return buildPreflightRequiredResponse("kj_code");
+    // Auto-acknowledge with defaults for autonomous operation
+    ackPreflight({});
+    const logger = createLogger("info", "mcp");
+    logger.info("Preflight auto-acknowledged with default agent config");
   }
   applySessionOverrides(a, ["coder"]);
   return handleCodeDirect(a, server, extra);
@@ -857,6 +863,20 @@ async function handleAudit(a, server, extra) {
   return handleAuditDirect(a, server, extra);
 }
 
+async function handleBoard(a) {
+  const action = a.action || "status";
+  const { loadConfig: lc } = await import("../config.js");
+  const { config } = await lc();
+  const port = a.port || config.hu_board?.port || 4000;
+  const { startBoard, stopBoard, boardStatus } = await import("../commands/board.js");
+  switch (action) {
+    case "start": return startBoard(port);
+    case "stop": return stopBoard();
+    case "status": return boardStatus(port);
+    default: return failPayload(`Unknown board action: ${action}`);
+  }
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -878,7 +898,8 @@ const toolHandlers = {
   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_audit:       (a, server, extra) => handleAudit(a, server, extra),
+  kj_board:       (a) => handleBoard(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -306,5 +306,16 @@ export const tools = [
         kjHome: { type: "string" }
       }
     }
+  },
+  {
+    name: "kj_board",
+    description: "Start, stop, or check status of the HU Board dashboard",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["start", "stop", "status"], description: "Action to perform (default: status)" },
+        port: { type: "number", description: "Port (default: 4000)" }
+      }
+    }
   }
 ];

package/src/orchestrator.js

@@ -156,8 +156,10 @@ function createBudgetManager({ config, emitter, eventBase }) {
     return s;
   }
 
-  function trackBudget({ role, provider, model, result, duration_ms }) {
-    const metrics = extractUsageMetrics(result, model);
+  function trackBudget({ role, provider, model, result, duration_ms, promptSize }) {
+    // Attach promptSize to result if provided, so extractUsageMetrics can estimate tokens
+    const enrichedResult = promptSize && result ? { ...result, promptSize } : result;
+    const metrics = extractUsageMetrics(enrichedResult, model);
     budgetTracker.record({ role, provider, ...metrics, duration_ms, stage_index: stageCounter++ });
 
     if (!hasBudgetLimit) return;
@@ -1124,6 +1126,26 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
     }));
   }
 
+  // --- HU Board auto-start ---
+  if (config.hu_board?.enabled && config.hu_board?.auto_start) {
+    try {
+      const { startBoard } = await import("./commands/board.js");
+      const boardPort = config.hu_board.port || 4000;
+      const boardResult = await startBoard(boardPort);
+      if (boardResult.alreadyRunning) {
+        logger.info(`HU Board already running at ${boardResult.url}`);
+      } else {
+        logger.info(`HU Board started at ${boardResult.url}`);
+      }
+      emitProgress(emitter, makeEvent("board:started", ctx.eventBase, {
+        message: `HU Board running at ${boardResult.url}`,
+        detail: { pid: boardResult.pid, port: boardPort }
+      }));
+    } catch (err) {
+      logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
+    }
+  }
+
   // --- Product Context ---
   const ctxProjectDir = config.projectDir || process.cwd();
   const { content: productContext, source: productContextSource } = await loadProductContext(ctxProjectDir);

package/src/prompts/audit.js

@@ -1,3 +1,5 @@
+import { extractFirstJson } from "../utils/json-extract.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -154,16 +156,8 @@ function parseRecommendation(raw) {
 }
 
 export function parseAuditOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonMatch[0]);
-  } catch {
-    return null;
-  }
+  const parsed = extractFirstJson(raw);
+  if (!parsed) return null;
 
   // Handle both wrapped (result.summary) and flat structures
   const resultObj = parsed.result || parsed;

package/src/prompts/coder.js

@@ -31,7 +31,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null }) {
+export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -52,6 +52,10 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (plan) {
+    sections.push(`## Implementation Plan (from planner)\nFollow these steps:\n${plan}`);
+  }
+
   if (coderRules) {
     sections.push(`Coder rules (MUST follow):\n${coderRules}`);
   }

package/src/prompts/discover.js

@@ -1,3 +1,5 @@
+import { extractFirstJson } from "../utils/json-extract.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -205,16 +207,8 @@ function parseJtbds(rawJtbds) {
 }
 
 export function parseDiscoverOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonMatch[0]);
-  } catch {
-    return null;
-  }
+  const parsed = extractFirstJson(raw);
+  if (!parsed) return null;
 
   return {
     verdict: VALID_VERDICTS.has(parsed.verdict) ? parsed.verdict : "ready",

package/src/prompts/hu-reviewer.js

@@ -1,3 +1,5 @@
+import { extractFirstJson } from "../utils/json-extract.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -135,16 +137,8 @@ export function normalizeAcceptanceCriteria(criteria) {
  * @returns {object|null} Parsed result with evaluations and batch_summary, or null.
  */
 export function parseHuReviewerOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonMatch[0]);
-  } catch {
-    return null;
-  }
+  const parsed = extractFirstJson(raw);
+  if (!parsed) return null;
 
   if (!Array.isArray(parsed.evaluations)) return null;
 

package/src/review/parser.js

@@ -3,23 +3,11 @@
  * Extracted from orchestrator.js to improve testability and reduce complexity.
  */
 
+import { extractFirstJson } from "../utils/json-extract.js";
+
 export function parseMaybeJsonString(value) {
   if (typeof value !== "string") return null;
-  try {
-    return JSON.parse(value);
-  } catch {
-    const start = value.indexOf("{");
-    const end = value.lastIndexOf("}");
-    if (start >= 0 && end > start) {
-      const candidate = value.slice(start, end + 1);
-      try {
-        return JSON.parse(candidate);
-      } catch {
-        return null;
-      }
-    }
-    return null;
-  }
+  return extractFirstJson(value);
 }
 
 function isReviewPayload(obj) {

package/src/roles/security-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -38,10 +39,7 @@ function buildPrompt({ task, diff, instructions }) {
 }
 
 function parseSecurityOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 function buildSummary(parsed) {

package/src/roles/tester-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -42,10 +43,7 @@ function buildPrompt({ task, diff, sonarIssues, instructions }) {
 }
 
 function parseTesterOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 export class TesterRole extends BaseRole {

package/src/roles/triage-role.js

@@ -2,6 +2,7 @@ import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { buildTriagePrompt } from "../prompts/triage.js";
 import { VALID_TASK_TYPES } from "../guards/policy-resolver.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
 const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security", "impeccable"]);
@@ -16,10 +17,7 @@ function resolveProvider(config) {
 }
 
 function parseTriageOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 function normalizeRoles(roles) {

package/src/utils/budget.js

@@ -1,5 +1,17 @@
 import { calculateUsageCostUsd, DEFAULT_MODEL_PRICING, mergePricing } from "./pricing.js";
 
+/**
+ * Estimate token counts from character lengths when CLIs don't report usage.
+ * Rough heuristic: ~4 characters per token for English text.
+ */
+export function estimateTokens(promptLength, responseLength) {
+  return {
+    tokens_in: Math.ceil((promptLength || 0) / 4),
+    tokens_out: Math.ceil((responseLength || 0) / 4),
+    estimated: true
+  };
+}
+
 export function extractUsageMetrics(result, defaultModel = null) {
   const usage = result?.usage || result?.metrics || {};
   const tokens_in =
@@ -27,7 +39,22 @@ export function extractUsageMetrics(result, defaultModel = null) {
     defaultModel ??
     null;
 
-  return { tokens_in, tokens_out, cost_usd, model };
+  // If no real token data AND no explicit cost, estimate from prompt/output sizes.
+  // Estimation is opt-in: only triggered when result.promptSize is explicitly provided.
+  let estimated = false;
+  let finalTokensIn = tokens_in;
+  let finalTokensOut = tokens_out;
+  const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
+  if (!tokens_in && !tokens_out && !hasExplicitCost && result?.promptSize > 0) {
+    const promptSize = result.promptSize;
+    const outputSize = (result?.output || result?.summary || "").length;
+    const est = estimateTokens(promptSize, outputSize);
+    finalTokensIn = est.tokens_in;
+    finalTokensOut = est.tokens_out;
+    estimated = true;
+  }
+
+  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cost_usd, model, estimated };
 }
 
 function toSafeNumber(value) {
@@ -63,7 +90,7 @@ export class BudgetTracker {
     this.pricing = mergePricing(DEFAULT_MODEL_PRICING, options.pricing || {});
   }
 
-  record({ role, provider, model, tokens_in, tokens_out, cost_usd, duration_ms, stage_index } = {}) {
+  record({ role, provider, model, tokens_in, tokens_out, cost_usd, duration_ms, stage_index, estimated } = {}) {
     const safeTokensIn = toSafeNumber(tokens_in);
     const safeTokensOut = toSafeNumber(tokens_out);
     const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
@@ -89,6 +116,9 @@ export class BudgetTracker {
     if (stage_index !== undefined && stage_index !== null) {
       entry.stage_index = Number(stage_index);
     }
+    if (estimated) {
+      entry.estimated = true;
+    }
     this.entries.push(entry);
     return entry;
   }
@@ -133,26 +163,33 @@ export class BudgetTracker {
       addToBreakdown(byRole, entry.role, entry);
     }
 
-    return {
+    const hasEstimates = this.entries.some(e => e.estimated);
+    const result = {
       total_tokens: totals.tokens_in + totals.tokens_out,
       total_cost_usd: totals.cost_usd,
       breakdown_by_role: byRole,
       entries: [...this.entries],
       usage_available: this.hasUsageData()
     };
+    if (hasEstimates) result.includes_estimates = true;
+    return result;
   }
 
   trace() {
-    return this.entries.map((entry, index) => ({
-      index: entry.stage_index ?? index,
-      role: entry.role,
-      provider: entry.provider,
-      model: entry.model,
-      timestamp: entry.timestamp,
-      duration_ms: entry.duration_ms ?? null,
-      tokens_in: entry.tokens_in,
-      tokens_out: entry.tokens_out,
-      cost_usd: entry.cost_usd
-    }));
+    return this.entries.map((entry, index) => {
+      const item = {
+        index: entry.stage_index ?? index,
+        role: entry.role,
+        provider: entry.provider,
+        model: entry.model,
+        timestamp: entry.timestamp,
+        duration_ms: entry.duration_ms ?? null,
+        tokens_in: entry.tokens_in,
+        tokens_out: entry.tokens_out,
+        cost_usd: entry.cost_usd
+      };
+      if (entry.estimated) item.estimated = true;
+      return item;
+    });
   }
 }

package/src/utils/display.js

@@ -225,11 +225,13 @@ function printSessionBudget(budget) {
     console.log(`  ${ANSI.dim}\ud83d\udcb0 Budget: N/A (provider does not report usage)${ANSI.reset}`);
     return;
   }
-  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total tokens: ${budget.total_tokens ?? 0}${ANSI.reset}`);
-  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total cost: $${Number(budget.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`);
+  const estPrefix = budget.includes_estimates ? "~" : "";
+  const estNote = budget.includes_estimates ? " (includes estimates)" : "";
+  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total tokens: ${estPrefix}${budget.total_tokens ?? 0}${estNote}${ANSI.reset}`);
+  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total cost: ${estPrefix}$${Number(budget.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`);
   for (const [role, metrics] of Object.entries(budget.breakdown_by_role || {})) {
     console.log(
-      `  ${ANSI.dim}   - ${role}: ${metrics.total_tokens ?? 0} tokens, $${Number(metrics.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`
+      `  ${ANSI.dim}   - ${role}: ${estPrefix}${metrics.total_tokens ?? 0} tokens, ${estPrefix}$${Number(metrics.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`
     );
   }
 }

package/src/utils/json-extract.js

@@ -0,0 +1,64 @@
+/**
+ * Robust JSON extraction from agent output.
+ * Extracts the first complete JSON object from a string,
+ * ignoring any trailing text that would cause parse errors.
+ */
+
+/**
+ * Extract the first valid JSON object from a raw string.
+ * Handles cases where agents output valid JSON followed by extra text.
+ * @param {string} raw - Raw agent output.
+ * @returns {object|null} Parsed JSON object, or null if no valid JSON found.
+ */
+export function extractFirstJson(raw) {
+  if (!raw) return null;
+  const str = typeof raw === "string" ? raw.trim() : String(raw).trim();
+  if (!str) return null;
+
+  // Fast path: try parsing the whole string first
+  try {
+    return JSON.parse(str);
+  } catch { /* fall through to extraction */ }
+
+  // Find the first '{' and match to its closing '}'
+  const start = str.indexOf("{");
+  if (start === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < str.length; i++) {
+    const ch = str[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) continue;
+
+    if (ch === "{") depth++;
+    if (ch === "}") depth--;
+
+    if (depth === 0) {
+      try {
+        return JSON.parse(str.substring(start, i + 1));
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  return null;
+}

package/templates/roles/coder.md

@@ -21,6 +21,13 @@ Before reporting done, verify that ALL parts of the task are addressed:
 - Run the test suite after implementation to verify nothing is broken.
 - An incomplete implementation is worse than an error — never report success if parts are missing.
 
+## Implementation Rules
+- NEVER generate placeholder, stub, or TODO code. Every function must be fully implemented.
+- If the task says "create X", create the complete working implementation, not a skeleton.
+- If tests exist, the implementation MUST make all tests pass.
+- If you write tests first (TDD), the implementation MUST make those tests pass.
+- Do NOT commit code that doesn't compile or doesn't pass tests.
+
 ## File modification safety
 
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.

package/templates/skills/kj-board.md

@@ -0,0 +1,16 @@
+# kj-board — HU Board Dashboard
+
+Manage the Karajan HU Board for visualizing user stories and sessions.
+
+## Your task
+
+$ARGUMENTS
+
+## Actions
+
+- **Start**: Run `kj board start` to launch the dashboard
+- **Stop**: Run `kj board stop` to stop it
+- **Status**: Run `kj board status` to check if running
+- **Open**: Run `kj board open` to open in browser
+
+The board auto-syncs with KJ pipeline data. No manual refresh needed.

package/templates/skills/kj-run.md

@@ -61,6 +61,10 @@ If all steps pass:
 2. Commit with conventional commit message: `feat:`, `fix:`, `refactor:`, etc.
 3. Do NOT push unless the user explicitly asks
 
+## HU Board Integration
+If HU Board is enabled (`hu_board.enabled: true` in config), stories and sessions
+are automatically tracked and visible at the board URL. Run `kj board` to start it.
+
 ## Important rules
 
 - **Never skip steps** — execute all applicable steps in order