karajan-code 1.34.0 → 1.34.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.34.0",
+  "version": "1.34.3",
   "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/doctor.js

@@ -162,23 +162,23 @@ async function checkBecariaSecrets() {
     const { detectRepo } = await import("../becaria/repo.js");
     const repo = await detectRepo();
     if (!repo) return null;
+
     const secretsRes = await runCommand("gh", ["api", `repos/${repo}/actions/secrets`, "--jq", ".secrets[].name"]);
     if (secretsRes.exitCode !== 0) return null;
+
     const names = new Set(secretsRes.stdout.split("\n").map((s) => s.trim()));
     const hasAppId = names.has("BECARIA_APP_ID");
     const hasKey = names.has("BECARIA_APP_PRIVATE_KEY");
     const secretsOk = hasAppId && hasKey;
+    const missing = [!hasAppId && "BECARIA_APP_ID", !hasKey && "BECARIA_APP_PRIVATE_KEY"].filter(Boolean).join(" ");
     return {
       name: "becaria:secrets",
       label: "BecarIA: GitHub secrets",
       ok: secretsOk,
-      detail: secretsOk
-        ? "BECARIA_APP_ID + BECARIA_APP_PRIVATE_KEY found"
-        : `Missing: ${[!hasAppId && "BECARIA_APP_ID", !hasKey && "BECARIA_APP_PRIVATE_KEY"].filter(Boolean).join(" ")}`,
+      detail: secretsOk ? "BECARIA_APP_ID + BECARIA_APP_PRIVATE_KEY found" : `Missing: ${missing}`,
       fix: secretsOk ? null : "Add BECARIA_APP_ID and BECARIA_APP_PRIVATE_KEY as GitHub repository secrets"
     };
   } catch {
-    // Skip secrets check if we can't access the API
     return null;
   }
 }
@@ -205,33 +205,15 @@ async function checkBecariaInfra(config) {
 }
 
 async function checkRtk() {
+  const NOT_FOUND_DETAIL = "Not found — install for 60-90% token savings: brew install rtk";
+  let detail = NOT_FOUND_DETAIL;
   try {
     const res = await runCommand("rtk", ["--version"]);
     if (res.exitCode === 0) {
-      return {
-        name: "rtk",
-        label: "RTK (Rust Token Killer)",
-        ok: true,
-        detail: `${res.stdout.trim()} — token savings active`,
-        fix: null
-      };
+      detail = `${res.stdout.trim()} — token savings active`;
     }
-    return {
-      name: "rtk",
-      label: "RTK (Rust Token Killer)",
-      ok: true,
-      detail: "Not found — install for 60-90% token savings: brew install rtk",
-      fix: null
-    };
-  } catch {
-    return {
-      name: "rtk",
-      label: "RTK (Rust Token Killer)",
-      ok: true,
-      detail: "Not found — install for 60-90% token savings: brew install rtk",
-      fix: null
-    };
-  }
+  } catch { /* not installed */ }
+  return { name: "rtk", label: "RTK (Rust Token Killer)", ok: true, detail, fix: null };
 }
 
 async function checkRuleFiles(config) {

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/commands/report.js

@@ -155,50 +155,49 @@ async function buildReport(dir, sessionId) {
   return report;
 }
 
-function printTextReport(report) {
-  let budgetText = "N/A";
-  if (typeof report.budget_consumed?.consumed_usd === "number") {
-    const limitSuffix = typeof report.budget_consumed?.limit_usd === "number"
-      ? ` / $${report.budget_consumed.limit_usd.toFixed(2)}`
-      : "";
-    budgetText = `$${report.budget_consumed.consumed_usd.toFixed(2)}${limitSuffix}`;
-  }
+function formatBudgetText(budget) {
+  if (typeof budget?.consumed_usd !== "number") return "N/A";
+  const limitSuffix = typeof budget.limit_usd === "number" ? ` / $${budget.limit_usd.toFixed(2)}` : "";
+  return `$${budget.consumed_usd.toFixed(2)}${limitSuffix}`;
+}
 
-  const planText = report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A";
-  const iterationText =
-    report.iterations.length > 0
-      ? report.iterations
-          .map(
-            (item) =>
-              `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`
-          )
-          .join("\n")
-      : "N/A";
-  const commitsText =
-    report.commits_generated.ids.length > 0
-      ? `${report.commits_generated.count} (${report.commits_generated.ids.join(", ")})`
-      : String(report.commits_generated.count);
+function formatIterationsText(iterations) {
+  if (iterations.length === 0) return "N/A";
+  return iterations
+    .map((item) => `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`)
+    .join("\n");
+}
+
+function formatCommitsText(commits) {
+  return commits.ids.length > 0
+    ? `${commits.count} (${commits.ids.join(", ")})`
+    : String(commits.count);
+}
+
+function printPgCardLine(report) {
+  if (!report.pg_task_id) return;
+  const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
+  console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
+}
+
+function printTextReport(report) {
+  const sonar = report.sonar_issues_resolved;
 
   console.log(`Session: ${report.session_id}`);
-  if (report.pg_task_id) {
-    const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
-    console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
-  }
+  printPgCardLine(report);
   console.log(`Status: ${report.status}`);
   console.log("Task Description:");
   console.log(report.task_description || "N/A");
   console.log("Plan Executed:");
-  console.log(planText);
+  console.log(report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A");
   console.log("Iterations (Coder/Reviewer):");
-  console.log(iterationText);
+  console.log(formatIterationsText(report.iterations));
   console.log("Sonar Issues Resolved:");
-  console.log(
-    `initial=${report.sonar_issues_resolved.initial_open_issues ?? "N/A"} final=${report.sonar_issues_resolved.final_open_issues ?? "N/A"} resolved=${report.sonar_issues_resolved.resolved}`
-  );
+  console.log(`initial=${sonar.initial_open_issues ?? "N/A"} final=${sonar.final_open_issues ?? "N/A"} resolved=${sonar.resolved}`);
   console.log("Budget Consumed:");
-  console.log(budgetText);
+  console.log(formatBudgetText(report.budget_consumed));
   console.log("Commits Generated:");
-  console.log(commitsText);
+  console.log(formatCommitsText(report.commits_generated));
 }
 
 function formatDuration(ms) {
@@ -329,10 +328,7 @@ async function resolveTraceOptions(currency) {
 
 function printTraceReport(report, currency, exchangeRate) {
   console.log(`Session: ${report.session_id}`);
-  if (report.pg_task_id) {
-    const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
-    console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
-  }
+  printPgCardLine(report);
   console.log(`Status: ${report.status}`);
   console.log(`Task: ${report.task_description || "N/A"}`);
   console.log("");

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 },
@@ -448,27 +453,39 @@ export function isModelCompatible(agent, model) {
   return true;
 }
 
+// Roles that inherit provider/model from the coder when not explicitly configured
+const CODER_INHERITED_ROLES = new Set([
+  "planner", "refactorer", "solomon", "researcher", "tester", "security",
+  "impeccable", "triage", "discover", "architect", "audit", "hu_reviewer", "hu-reviewer"
+]);
+
+function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {
+  if (roleConfig.provider) return roleConfig.provider;
+  if (role === "coder") return legacyCoder;
+  if (role === "reviewer") return legacyReviewer;
+  if (CODER_INHERITED_ROLES.has(role)) return roles.coder?.provider || legacyCoder;
+  return null;
+}
+
+function resolveModel(roleConfig, role, config) {
+  if (roleConfig.model) return { model: roleConfig.model, inherited: false };
+  if (role === "coder") return { model: config?.coder_options?.model ?? null, inherited: false };
+  if (role === "reviewer") return { model: config?.reviewer_options?.model ?? null, inherited: false };
+  if (CODER_INHERITED_ROLES.has(role)) {
+    const model = config?.coder_options?.model ?? null;
+    return { model, inherited: !!model };
+  }
+  return { model: null, inherited: false };
+}
+
 export function resolveRole(config, role) {
   const roles = config?.roles || {};
   const roleConfig = roles[role] || {};
   const legacyCoder = config?.coder || null;
   const legacyReviewer = config?.reviewer || null;
 
-  let provider = roleConfig.provider ?? null;
-  if (!provider && role === "coder") provider = legacyCoder;
-  if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "audit" || role === "hu_reviewer" || role === "hu-reviewer")) {
-    provider = roles.coder?.provider || legacyCoder;
-  }
-
-  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;
-  }
+  const provider = resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer);
+  let { model, inherited: modelIsInherited } = resolveModel(roleConfig, role, config);
 
   // Drop inherited model if incompatible with the resolved provider
   if (modelIsInherited && provider && model && !isModelCompatible(provider, model)) {

package/src/mcp/server-handlers.js

@@ -252,6 +252,31 @@ async function attemptAutoResume({ err, config, logger, emitter, askQuestion, ru
   }
 }
 
+const PIPELINE_PROVIDER_ROLES = [
+  ["triage", true],
+  ["planner", true],
+  ["refactorer", true],
+  ["researcher", true],
+  ["tester", true],
+  ["security", true]
+];
+
+function collectRequiredProviders(config) {
+  const providers = [
+    resolveRole(config, "coder").provider,
+    config.reviewer_options?.fallback_reviewer
+  ];
+  if (config.pipeline?.reviewer?.enabled !== false) {
+    providers.push(resolveRole(config, "reviewer").provider);
+  }
+  for (const [role, requireEnabled] of PIPELINE_PROVIDER_ROLES) {
+    if (requireEnabled && config.pipeline?.[role]?.enabled) {
+      providers.push(resolveRole(config, role).provider);
+    }
+  }
+  return providers;
+}
+
 export async function handleRunDirect(a, server, extra) {
   const config = await buildConfig(a);
   await assertNotOnBaseBranch(config);
@@ -263,20 +288,7 @@ export async function handleRunDirect(a, server, extra) {
     await cleanupExpiredSessions({ logger });
   } catch { /* non-blocking */ }
 
-  const requiredProviders = [
-    resolveRole(config, "coder").provider,
-    config.reviewer_options?.fallback_reviewer
-  ];
-  if (config.pipeline?.reviewer?.enabled !== false) {
-    requiredProviders.push(resolveRole(config, "reviewer").provider);
-  }
-  if (config.pipeline?.triage?.enabled) requiredProviders.push(resolveRole(config, "triage").provider);
-  if (config.pipeline?.planner?.enabled) requiredProviders.push(resolveRole(config, "planner").provider);
-  if (config.pipeline?.refactorer?.enabled) requiredProviders.push(resolveRole(config, "refactorer").provider);
-  if (config.pipeline?.researcher?.enabled) requiredProviders.push(resolveRole(config, "researcher").provider);
-  if (config.pipeline?.tester?.enabled) requiredProviders.push(resolveRole(config, "tester").provider);
-  if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
-  await assertAgentsAvailable(requiredProviders);
+  await assertAgentsAvailable(collectRequiredProviders(config));
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
@@ -343,13 +355,16 @@ export async function handleResumeDirect(a, server, extra) {
   }
 }
 
+const EVENT_LOG_LEVELS = {
+  "agent:stall": "warning",
+  "agent:heartbeat": "info"
+};
+
 function buildDirectEmitter(server, runLog, extra) {
   const emitter = new EventEmitter();
   emitter.on("progress", (event) => {
     try {
-      let level = "debug";
-      if (event.type === "agent:stall") level = "warning";
-      else if (event.type === "agent:heartbeat") level = "info";
+      const level = EVENT_LOG_LEVELS[event.type] || "debug";
       server.sendLoggingMessage({ level, logger: "karajan", data: event });
     } catch { /* best-effort */ }
     if (runLog) runLog.logEvent(event);
@@ -863,6 +878,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 = {
@@ -884,7 +913,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;
@@ -474,7 +476,7 @@ async function checkBudgetExceeded({ budgetTracker, config, session, emitter, ev
 }
 
 async function handleStandbyResult({ stageResult, session, emitter, eventBase, i, stage, logger }) {
-  if (!stageResult?.action || stageResult.action !== "standby") {
+  if (stageResult?.action !== "standby") {
     return { handled: false };
   }
 
@@ -509,6 +511,47 @@ async function handleStandbyResult({ stageResult, session, emitter, eventBase, i
   return { handled: true, action: "retry" };
 }
 
+function formatCommitList(commits) {
+  return commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+}
+
+async function becariaIncrementalPush({ config, session, gitCtx, task, logger, repo, dispatchComment }) {
+  const pushResult = await incrementalPush({ gitCtx, task, logger, session });
+  if (!pushResult) return;
+
+  session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
+  await saveSession(session);
+
+  if (!repo) return;
+  const feedback = session.last_reviewer_feedback || "N/A";
+  await dispatchComment({
+    repo, prNumber: session.becaria_pr_number, agent: "Coder",
+    body: `Issues corregidos:\n${feedback}\n\nCommits:\n${formatCommitList(pushResult.commits)}`,
+    becariaConfig: config.becaria
+  });
+}
+
+async function becariaCreateEarlyPr({ config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i, repo, dispatchComment }) {
+  const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
+  if (!earlyPr) return;
+
+  session.becaria_pr_number = earlyPr.prNumber;
+  session.becaria_pr_url = earlyPr.prUrl;
+  session.becaria_commits = earlyPr.commits;
+  await saveSession(session);
+  emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
+    message: `Early PR created: #${earlyPr.prNumber}`,
+    detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
+  }));
+
+  if (!repo) return;
+  await dispatchComment({
+    repo, prNumber: earlyPr.prNumber, agent: "Coder",
+    body: `Iteración ${i} completada.\n\nCommits:\n${formatCommitList(earlyPr.commits)}`,
+    becariaConfig: config.becaria
+  });
+}
+
 async function handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i }) {
   if (!becariaEnabled) return;
 
@@ -518,48 +561,26 @@ async function handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emi
     const repo = await detectRepo();
 
     if (session.becaria_pr_number) {
-      const pushResult = await incrementalPush({ gitCtx, task, logger, session });
-      if (pushResult) {
-        session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
-        await saveSession(session);
-
-        if (repo) {
-          const feedback = session.last_reviewer_feedback || "N/A";
-          const commitList = pushResult.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-          await dispatchComment({
-            repo, prNumber: session.becaria_pr_number, agent: "Coder",
-            body: `Issues corregidos:\n${feedback}\n\nCommits:\n${commitList}`,
-            becariaConfig: config.becaria
-          });
-        }
-      }
+      await becariaIncrementalPush({ config, session, gitCtx, task, logger, repo, dispatchComment });
     } else {
-      const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
-      if (earlyPr) {
-        session.becaria_pr_number = earlyPr.prNumber;
-        session.becaria_pr_url = earlyPr.prUrl;
-        session.becaria_commits = earlyPr.commits;
-        await saveSession(session);
-        emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
-          message: `Early PR created: #${earlyPr.prNumber}`,
-          detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
-        }));
-
-        if (repo) {
-          const commitList = earlyPr.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-          await dispatchComment({
-            repo, prNumber: earlyPr.prNumber, agent: "Coder",
-            body: `Iteración ${i} completada.\n\nCommits:\n${commitList}`,
-            becariaConfig: config.becaria
-          });
-        }
-      }
+      await becariaCreateEarlyPr({ config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i, repo, dispatchComment });
     }
   } catch (err) {
     logger.warn(`BecarIA early PR/push failed (non-blocking): ${err.message}`);
   }
 }
 
+function emitSolomonAlerts(alerts, emitter, eventBase, logger) {
+  for (const alert of alerts) {
+    emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
+      status: alert.severity === "critical" ? "fail" : "warn",
+      message: alert.message,
+      detail: alert.detail
+    }));
+    logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
+  }
+}
+
 async function handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, becariaEnabled, blockingIssues }) {
   if (config.pipeline?.solomon?.enabled === false) return { action: "continue" };
 
@@ -569,15 +590,7 @@ async function handleSolomonCheck({ config, session, emitter, eventBase, logger,
     const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
 
     if (rulesResult.alerts.length > 0) {
-      for (const alert of rulesResult.alerts) {
-        emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
-          status: alert.severity === "critical" ? "fail" : "warn",
-          message: alert.message,
-          detail: alert.detail
-        }));
-        logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
-      }
-
+      emitSolomonAlerts(rulesResult.alerts, emitter, eventBase, logger);
       const pauseResult = await checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i });
       if (pauseResult) return pauseResult;
     }
@@ -621,6 +634,27 @@ async function checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i
   return null;
 }
 
+function formatBlockingIssues(issues) {
+  return issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+}
+
+function formatSuggestions(suggestions) {
+  return suggestions?.map((s) => {
+    const detail = typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`;
+    return `- ${detail}`;
+  }).join("\n") || "";
+}
+
+function buildReviewCommentBody(review, i) {
+  const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
+  const blocking = formatBlockingIssues(review.blocking_issues);
+  const suggestions = formatSuggestions(review.non_blocking_suggestions);
+  let body = `Review iteración ${i}: ${status}`;
+  if (blocking) body += `\n\n**Blocking:**\n${blocking}`;
+  if (suggestions) body += `\n\n**Suggestions:**\n${suggestions}`;
+  return body;
+}
+
 async function handleBecariaReviewDispatch({ becariaEnabled, config, session, review, i, logger }) {
   if (!becariaEnabled || !session.becaria_pr_number) return;
 
@@ -631,33 +665,19 @@ async function handleBecariaReviewDispatch({ becariaEnabled, config, session, re
     if (!repo) return;
 
     const bc = config.becaria;
-    if (review.approved) {
-      await dispatchReview({
-        repo, prNumber: session.becaria_pr_number,
-        event: "APPROVE", body: review.summary || "Approved", agent: "Reviewer", becariaConfig: bc
-      });
-    } else {
-      const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-      await dispatchReview({
-        repo, prNumber: session.becaria_pr_number,
-        event: "REQUEST_CHANGES",
-        body: blocking || review.summary || "Changes requested",
-        agent: "Reviewer", becariaConfig: bc
-      });
-    }
+    const reviewEvent = review.approved ? "APPROVE" : "REQUEST_CHANGES";
+    const reviewBody = review.approved
+      ? (review.summary || "Approved")
+      : (formatBlockingIssues(review.blocking_issues) || review.summary || "Changes requested");
+
+    await dispatchReview({
+      repo, prNumber: session.becaria_pr_number,
+      event: reviewEvent, body: reviewBody, agent: "Reviewer", becariaConfig: bc
+    });
 
-    const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
-    const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-    const suggestions = review.non_blocking_suggestions?.map((s) => {
-      const detail = typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`;
-      return `- ${detail}`;
-    }).join("\n") || "";
-    let reviewBody = `Review iteración ${i}: ${status}`;
-    if (blocking) reviewBody += `\n\n**Blocking:**\n${blocking}`;
-    if (suggestions) reviewBody += `\n\n**Suggestions:**\n${suggestions}`;
     await dispatchComment({
       repo, prNumber: session.becaria_pr_number, agent: "Reviewer",
-      body: reviewBody, becariaConfig: bc
+      body: buildReviewCommentBody(review, i), becariaConfig: bc
     });
 
     logger.info(`BecarIA: dispatched review for PR #${session.becaria_pr_number}`);
@@ -1093,6 +1113,24 @@ async function handleMaxIterationsReached({ session, budgetSummary, emitter, eve
   return { approved: false, sessionId: session.id, reason: "max_iterations" };
 }
 
+async function tryAutoStartBoard(config, logger, emitter, eventBase) {
+  if (!config.hu_board?.enabled || !config.hu_board?.auto_start) return;
+
+  try {
+    const { startBoard } = await import("./commands/board.js");
+    const boardPort = config.hu_board.port || 4000;
+    const boardResult = await startBoard(boardPort);
+    const status = boardResult.alreadyRunning ? "already running" : "started";
+    logger.info(`HU Board ${status} at ${boardResult.url}`);
+    emitProgress(emitter, makeEvent("board:started", 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}`);
+  }
+}
+
 async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
   const ctx = new PipelineContext({ config, session: null, logger, emitter, task, flags });
   ctx.askQuestion = askQuestion;
@@ -1124,6 +1162,9 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
     }));
   }
 
+  // --- HU Board auto-start ---
+  await tryAutoStartBoard(config, logger, emitter, ctx.eventBase);
+
   // --- Product Context ---
   const ctxProjectDir = config.projectDir || process.cwd();
   const { content: productContext, source: productContextSource } = await loadProductContext(ctxProjectDir);

package/src/utils/display.js

@@ -219,9 +219,14 @@ function printSessionGit(git) {
   }
 }
 
+function isBudgetUnavailable(budget) {
+  return budget.usage_available === false ||
+    (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
+}
+
 function printSessionBudget(budget) {
   if (!budget) return;
-  if (budget.usage_available === false || (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0)) {
+  if (isBudgetUnavailable(budget)) {
     console.log(`  ${ANSI.dim}\ud83d\udcb0 Budget: N/A (provider does not report usage)${ANSI.reset}`);
     return;
   }
@@ -381,12 +386,13 @@ const EVENT_HANDLERS = {
   },
 
   "budget:update": (event, icon) => {
-    const total = Number(event.detail?.total_cost_usd || 0);
-    const totalTokens = Number(event.detail?.total_tokens || 0);
-    const max = Number(event.detail?.max_budget_usd);
-    const pct = Number(event.detail?.pct_used ?? 0);
-    const warn = Number(event.detail?.warn_threshold_pct ?? 80);
-    const hasEntries = (event.detail?.entries?.length ?? 0) > 0 || Object.keys(event.detail?.breakdown_by_role || {}).length > 0;
+    const d = event.detail || {};
+    const total = Number(d.total_cost_usd || 0);
+    const totalTokens = Number(d.total_tokens || 0);
+    const max = Number(d.max_budget_usd);
+    const pct = Number(d.pct_used ?? 0);
+    const warn = Number(d.warn_threshold_pct ?? 80);
+    const hasEntries = (d.entries?.length ?? 0) > 0 || Object.keys(d.breakdown_by_role || {}).length > 0;
     if (hasEntries && totalTokens === 0 && total === 0) {
       console.log(`  \u251c\u2500 ${icon} Budget: ${ANSI.dim}N/A (provider does not report usage)${ANSI.reset}`);
       return;

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