karajan-code 3.1.0 → 3.2.0

package/src/commands/audit.js

@@ -216,7 +216,7 @@ function loadAuditHistoryContext(projectDir, currentHarness, { showTrend = false
   finally { try { db?.close(); } catch { /* noop */ } }
 }
 
-function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }) {
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }) {
   const parts = ["kj audit"];
   if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
   if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
@@ -224,13 +224,14 @@ function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHar
   if (noOsv) parts.push("--no-osv");
   if (noSemgrep) parts.push("--no-semgrep");
   if (noHarness) parts.push("--no-harness");
+  if (noAiSlop) parts.push("--no-ai-slop");
   if (deterministicOnly) parts.push("--deterministic-only");
   if (yes) parts.push("--yes");
   if (json) parts.push("--json");
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -269,6 +270,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       noSonar,
       noOsv,
       noSemgrep,
+      noAiSlop,
     };
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);
@@ -324,7 +326,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
         if (reportPath.endsWith(".json")) {
           payload = JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2);
         } else {
-          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }));
           payload = `${header}${deterministicMd}\n${harnessMd}${historyMd}`;
         }
         await fs.writeFile(reportPath, payload, "utf8");
@@ -385,7 +387,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
           : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
         payload = JSON.stringify(jsonPayload, null, 2);
       } else {
-        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, noAiSlop, json, deterministicOnly, yes }));
         payload = header + stdoutContent + "\n";
       }
       await fs.writeFile(reportPath, payload, "utf8");

package/src/commands/board.js

@@ -122,6 +122,29 @@ export function waitForEarlyExit(child, logPath) {
   });
 }
 
+// KJC-BUG-0080: waitForEarlyExit only catches an exit, not a hung
+// daemon that survived the window without ever bind()ing the port.
+// Poll /api/dashboard until it answers or the readiness budget runs
+// out, so we never announce "HU Board started" for an unreachable
+// server. Overridable with KJ_BOARD_READY_TIMEOUT_MS (tests set it
+// low to stay fast).
+export async function waitForBoardReachable(port, totalTimeoutMs) {
+  const envTimeout = Number(process.env.KJ_BOARD_READY_TIMEOUT_MS);
+  const budget = Number.isFinite(envTimeout) && envTimeout >= 0
+    ? envTimeout
+    : (Number.isFinite(totalTimeoutMs) ? totalTimeoutMs : 5000);
+  const intervalMs = budget <= 200 ? Math.max(10, Math.floor(budget / 5)) : 200;
+  const deadline = Date.now() + budget;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const probeTimeout = Math.min(750, Math.max(50, remaining));
+    if (await isBoardReachable(port, probeTimeout)) return true;
+    const wait = Math.min(intervalMs, deadline - Date.now());
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+  }
+  return false;
+}
+
 export async function startBoard(desiredPort = 4000, opts = {}) {
   const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
@@ -199,6 +222,17 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   if (failure) {
     throw new Error(failure);
   }
+  // KJC-BUG-0080: even after a clean window, the server may have
+  // failed to bind (e.g. port race vs the parent's findAvailablePort)
+  // or be still booting. Probe /api/dashboard before announcing
+  // success — without this the CLI used to print "HU Board started
+  // at http://localhost:4000" while :4000 actually returned nothing.
+  const reachable = await waitForBoardReachable(port);
+  if (!reachable) {
+    throw new Error(
+      `HU Board daemon spawned (PID ${child.pid}) but did not answer on http://localhost:${port} in time. See ${logPath} for the cause.`
+    );
+  }
   fs.writeFileSync(PID_FILE, String(child.pid));
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference

package/src/commands/doctor.js

@@ -22,6 +22,9 @@ import { getOllamaChecks } from "../checks/ollama.js";
 import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
+import { getSqueezrChecks } from "../checks/squeezr.js";
+import { getAiTrashChecks } from "../checks/ai-trash.js";
+import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
@@ -64,6 +67,9 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSkillsChecks(),
     ...getCiChecks(),
     ...getRtkChecks(),
+    ...getSqueezrChecks(),
+    ...getAiTrashChecks(),
+    ...getQmdChecks(),
     ...getProjectChecks({ projectDir }),
   ];
 }

package/src/commands/init.js

@@ -15,6 +15,12 @@ import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { buildTelemetryPayload, sendTelemetryEvent } from "../utils/telemetry.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
+import { detectSqueezr } from "../utils/squeezr-detect.js";
+import { installSqueezr } from "../utils/squeezr-install.js";
+import { detectAiTrash, installAiTrashHook } from "../utils/ai-trash.js";
+import { detectQmd } from "../utils/qmd-detect.js";
+import { installQmd } from "../utils/qmd-install.js";
+import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
 import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
 
@@ -754,15 +760,74 @@ export async function initCommand({ logger, flags = {} }) {
     logger.info("No project stack detected — using default configuration.");
   }
 
-  // Check RTK availability — auto-install if missing
-  const rtk = await detectRtk();
-  if (rtk.available) {
-    logger.info(`RTK ${rtk.version || ""} detected.`);
+  // Check RTK availability — auto-install if missing (opt-out: --no-rtk)
+  const skipRtk = flags?.noRtk === true || flags?.rtk === false;
+  if (skipRtk) {
+    logger.info("RTK setup skipped (--no-rtk). Bash outputs will not be token-optimized.");
   } else {
-    const installResult = await installRtk(logger);
-    if (!installResult.ok) {
-      logger.warn("RTK is optional but recommended for 60-90% token savings.");
-      logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+    const rtk = await detectRtk();
+    if (rtk.available) {
+      logger.info(`RTK ${rtk.version || ""} detected.`);
+    } else {
+      const installResult = await installRtk(logger);
+      if (!installResult.ok) {
+        logger.warn("RTK install failed — Bash outputs will not be token-optimized.");
+        logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+      }
+    }
+  }
+
+  // Check Squeezr availability — auto-install if missing (opt-out: --no-squeezr)
+  const skipSqueezr = flags?.noSqueezr === true || flags?.squeezr === false;
+  if (skipSqueezr) {
+    logger.info("Squeezr setup skipped (--no-squeezr). Tool outputs will not be compressed.");
+  } else {
+    const squeezr = await detectSqueezr();
+    if (squeezr.available) {
+      logger.info(`Squeezr ${squeezr.version || ""} detected.`);
+    } else {
+      const installResult = await installSqueezr(logger);
+      if (!installResult.ok) {
+        logger.warn("Squeezr install failed — tool outputs will not be compressed.");
+        logger.warn(`  Manual install: ${getInstallCommand("squeezr")}`);
+      }
+    }
+  }
+
+  // Check ai-trash availability — register PreToolUse hook if binary present
+  // (opt-out: --no-ai-trash). The binary itself ships with karajan-code.
+  const skipAiTrash = flags?.noAiTrash === true || flags?.aiTrash === false;
+  if (skipAiTrash) {
+    logger.info("ai-trash setup skipped (--no-ai-trash). Destructive ops will run unprotected.");
+  } else {
+    const aiTrash = await detectAiTrash();
+    if (aiTrash.available) {
+      await installAiTrashHook(logger);
+    } else {
+      logger.warn("ai-trash kj-trash binary not found — destructive ops unprotected.");
+      logger.warn("  Reinstall karajan-code so kj-trash is on PATH.");
+    }
+  }
+
+  // Check QMD availability — auto-install if missing and register project
+  // collections (docs/, .reviews/, .karajan/plans/). Opt-out: --no-qmd.
+  const skipQmd = flags?.noQmd === true || flags?.qmd === false;
+  if (skipQmd) {
+    logger.info("QMD setup skipped (--no-qmd). Semantic wiki indexing disabled.");
+  } else {
+    const qmd = await detectQmd();
+    if (qmd.available) {
+      logger.info(`QMD ${qmd.version || ""} detected.`);
+    } else {
+      const installResult = await installQmd(logger);
+      if (!installResult.ok) {
+        logger.warn("QMD install failed — semantic wiki unavailable.");
+        logger.warn(`  Manual install: ${getInstallCommand("qmd")}`);
+      }
+    }
+    const recheck = await detectQmd();
+    if (recheck.available) {
+      await registerQmdCollections(process.cwd(), logger);
     }
   }
 

package/src/commands/qmd.js

@@ -0,0 +1,86 @@
+// KJC-TSK-0509 — `kj qmd query` CLI wrapper. Auto-resolves the project's QMD
+// collection (`<projectSlug>-<suffix>`) so users do not have to remember it.
+// Mirrors `kj rag query`'s friendly-error shape on missing binary/collection.
+// Distinction: rag = agent context (code+plans); qmd = human wiki (docs/*.md).
+import { runCommand } from "../utils/process.js";
+import { projectSlug } from "../utils/qmd-collection.js";
+
+const QMD_NOT_INSTALLED = /command not found|ENOENT|not recognized as/i;
+const COLLECTION_MISSING = /no such collection|collection .* not found|unknown collection/i;
+const INSTALL_HINT = "qmd not installed. Install it with: npm install -g @tobilu/qmd";
+const INIT_HINT = "Collection not registered for this project. Run `kj init` to register the wiki collection.";
+
+function suffixFor(scope) {
+  if (!scope || scope === "docs") return "docs";
+  if (scope === "reviews" || scope === ".reviews") return "reviews";
+  if (scope === "plans" || scope === ".karajan/plans" || scope === "karajan-plans") return "karajan-plans";
+  return scope;
+}
+
+function resolveCollection({ flags, projectDir }) {
+  if (flags.collection) return String(flags.collection).trim();
+  return `${projectSlug(projectDir)}-${suffixFor(flags.scope)}`;
+}
+
+function notInstalled(logger) {
+  logger.error?.(`[qmd] ${INSTALL_HINT}`);
+  process.exitCode = 127;
+  return { ok: false, error: "qmd not installed", installable: true };
+}
+
+export async function qmdQueryCommand({ text, config, logger, flags = {} }) {
+  if (!text || !String(text).trim()) throw new Error("kj qmd query: text argument required");
+  const projectDir = config?.projectDir || process.cwd();
+  const collection = resolveCollection({ flags, projectDir });
+  const limit = Math.min(Math.max(Number(flags.topK) || 10, 1), 50);
+  const args = ["query", String(text), "--format", "json", "-c", collection, "-n", String(limit)];
+  if (flags.fast) args.push("--no-rerank");
+
+  let out;
+  try {
+    out = await runCommand("qmd", args, { timeout: 120_000 });
+  } catch (err) {
+    if (err?.code === "ENOENT") return notInstalled(logger);
+    throw err;
+  }
+
+  const stderr = out.stderr || "";
+  if (out.exitCode === 127 || QMD_NOT_INSTALLED.test(stderr)) return notInstalled(logger);
+  if (COLLECTION_MISSING.test(stderr)) {
+    logger.error?.(`[qmd] ${INIT_HINT}`);
+    process.exitCode = 1;
+    return { ok: false, error: "collection not registered", collection };
+  }
+  if (out.exitCode !== 0) {
+    const msg = (stderr || out.stdout || `qmd exit ${out.exitCode}`).trim();
+    logger.error?.(`[qmd] ${msg}`);
+    process.exitCode = out.exitCode || 1;
+    return { ok: false, error: msg };
+  }
+
+  let results;
+  try { results = JSON.parse(out.stdout || "[]"); }
+  catch {
+    logger.error?.("[qmd] qmd output is not valid JSON");
+    process.exitCode = 1;
+    return { ok: false, error: "qmd output is not valid JSON" };
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(results)}\n`);
+    return { ok: true, results };
+  }
+  if (!Array.isArray(results) || results.length === 0) {
+    logger.info(`[qmd] no hits for "${text}" in collection ${collection}`);
+    return { ok: true, results: [] };
+  }
+  logger.info(`[qmd] ${results.length} hit(s) in ${collection}:`);
+  for (const h of results) {
+    const src = h.source || h.path || h.file || "?";
+    const score = typeof h.score === "number" ? ` · score=${h.score.toFixed(4)}` : "";
+    const snippet = h.snippet || h.text || h.body || "";
+    logger.info(`  - ${src}${score}`);
+    if (snippet) logger.info(`    ${snippet.length > 200 ? `${snippet.slice(0, 200)}…` : snippet}`);
+  }
+  return { ok: true, results };
+}

package/src/commands/resume.js

@@ -1,53 +1,10 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { registerRun, unregisterRun } from "../utils/run-registry.js";
-
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Mirror the run.js logic: route to the board via the file-based
-    // bridge when there's no TTY; otherwise prompt the local terminal.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
@@ -88,7 +45,11 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
       }
     });
 
-    const askQuestion = createCliAskQuestion();
+    // KJC-BUG-0081 round 2 — propagate `flags` so the helper honours
+    // `--yes` here too. Before this fix, `kj resume <id> --yes` in
+    // non-TTY mode still routed every prompt to the HU Board bridge
+    // and hung, exactly the bug the original PR #995 fixed for `kj run`.
+    const askQuestion = createCliAskQuestion({ sessionId, flags });
     const result = await resumeFlow({
       sessionId,
       answer: answer || null,

package/src/commands/run.js

@@ -1,5 +1,4 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
@@ -14,54 +13,11 @@ import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
 import { maybeAutoUpdate } from "../rag/auto-update.js";
 
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Two paths:
-    //   - Interactive TTY: prompt via readline (the developer's terminal).
-    //   - No TTY (board's \u25b6 Run plan with stdio=ignore, CI, etc.): publish
-    //     the prompt through the file-based bridge so the HU Board can
-    //     surface it as a modal. The runner blocks on the bridge until
-    //     the user answers (or times out / kills the run). Pre-v2.7.5
-    //     this path just bailed; now the question actually gets answered.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer.\n"
-        + "  This process is now waiting; closing the board does NOT cancel the run."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+// Re-export the shared helper so existing imports (tests, MCP wrappers)
+// keep working. KJC-BUG-0081 round 2 split the body into utils/ because
+// resume.js also needs the same contract.
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+export { createCliAskQuestion };
 
 export async function runCommandHandler({ task, config, logger, flags }) {
   // PR-F (cwd confirmation): when launching from an interactive
@@ -171,7 +127,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
       printHeader({ task: task, config });
     }
 
-    const askQuestion = createCliAskQuestion();
+    const askQuestion = createCliAskQuestion({ flags });
 
     // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
     // anything else — surfaces ambiguity / missing scope / missing AC

package/src/git/hu-snapshot.js

@@ -1,105 +1,10 @@
-// KJC-TSK-0408: snapshots de ficheros por HU para soportar Undo.
-//
-// Antes de ejecutar una HU, guardamos un ref git apuntando al HEAD
-// actual (`refs/kj-snapshots/<huId>`). Si el usuario hace Undo después,
-// hacemos `git reset --hard <ref>` para volver al estado pre-run.
-//
-// Por qué refs en lugar de stash/tarball:
-//   - Refs son objetos git nativos. No mueven blobs (todos compartidos
-//     con HEAD), así que crear el snapshot es O(1).
-//   - El snapshot persiste a través de checkouts y rebases.
-//   - Si el ref ya apunta al SHA correcto, restore es no-op.
-//
-// El runner es inyectable para que los tests no necesiten un repo git real.
-
-import { runCommand } from "../utils/process.js";
-
-const REF_PREFIX = "refs/kj-snapshots/";
-
-/**
- * Sanitiza un huId para uso como nombre de ref. Git rechaza:
- *   - `..`, `:`, `~`, `^`, `?`, `*`, `[`, `\`, espacios, control chars
- *   - segmentos que empiecen por `.` o terminen en `.lock`
- * Reemplazamos cualquier no [a-zA-Z0-9_-] por `_`.
- */
-export function snapshotRefForHu(huId) {
-  if (!huId) throw new Error("huId requerido");
-  const safe = String(huId).replaceAll(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
-  return REF_PREFIX + safe;
-}
-
-async function defaultRunner(args, opts = {}) {
-  return runCommand("git", args, opts);
-}
-
-/**
- * Crea (o actualiza) el ref del snapshot apuntando al HEAD actual.
- *
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner] - sustituye git CLI en tests
- * @returns {Promise<{ ok: boolean, ref?: string, sha?: string, error?: string }>}
- */
-export async function createHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const head = await run(["rev-parse", "HEAD"], { cwd: projectDir });
-  if (head.exitCode !== 0) {
-    return { ok: false, error: `rev-parse HEAD failed: ${(head.stderr || "").trim()}` };
-  }
-  const sha = (head.stdout || "").trim();
-  if (!sha) return { ok: false, error: "HEAD vacío" };
-  const update = await run(["update-ref", ref, sha], { cwd: projectDir });
-  if (update.exitCode !== 0) {
-    return { ok: false, error: `update-ref falló: ${(update.stderr || "").trim()}` };
-  }
-  return { ok: true, ref, sha };
-}
-
-/**
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner]
- * @returns {Promise<{ ok: boolean, sha?: string }>}
- */
-export async function hasHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["rev-parse", "--verify", "--quiet", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) return { ok: false };
-  return { ok: true, sha: (r.stdout || "").trim() };
-}
-
-/**
- * Restaura el workspace al snapshot. DESTRUCTIVO: hace `git reset --hard`,
- * lo que descarta cambios no committeados. Caller debe avisar al usuario.
- *
- * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
- */
-export async function restoreHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const has = await hasHuSnapshot({ projectDir, huId, runner: run });
-  if (!has.ok) return { ok: false, error: `snapshot no encontrado para HU ${huId}` };
-  const r = await run(["reset", "--hard", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `reset --hard falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true, sha: has.sha };
-}
-
-/**
- * Borra el ref del snapshot. Idempotente: si no existe, devuelve ok:true.
- */
-export async function removeHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["update-ref", "-d", ref], { cwd: projectDir });
-  // git update-ref -d devuelve 0 incluso si el ref no existía.
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `update-ref -d falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true };
-}
+// Shim de compatibilidad: hu-snapshot vive ahora en @karajan/core.
+// Mantenemos esta ruta para que callers internos del CLI (orchestrator,
+// runners) sigan funcionando sin tocar imports.
+export {
+  snapshotRefForHu,
+  createHuSnapshot,
+  hasHuSnapshot,
+  restoreHuSnapshot,
+  removeHuSnapshot,
+} from "@karajan/core/hu-snapshot";

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -302,10 +302,26 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
   // PR3: per-HU outcome. Stamped once per HU at runSingleHu's exit
   // so the board can show the 📄 indicator as soon as each HU
   // finishes (iterations / duration / commits / blockers / summary).
+  //
+  // Cost D (KJC-TSK-0515): the outcome may carry `cost_usd` (USD
+  // spent on this HU). When present and finite, also persist it to
+  // board.db so the per-card badge (Cost F) and the project total
+  // chip (Cost G) have data to show — without this write, the
+  // `cost_usd` column would always stay NULL and the UI would render
+  // nothing. Lazy-import to keep the pre-loop phase free of board
+  // deps until we actually need them.
   setLiveOutcomeUpdater(session, async (huId, outcome) => {
     try {
       if (!setHuOutcomeFn(loadedPlan, huId, outcome)) return;
       await savePlanToDisk(projectDir, loadedPlan);
+      if (outcome && Number.isFinite(outcome.cost_usd)) {
+        try {
+          const { setStoryCost } = await import("../../../../packages/hu-board/src/db.js");
+          setStoryCost(huId, outcome.cost_usd);
+        } catch (err) {
+          logger?.warn?.(`Cost write failed for ${huId}: ${err.message}`);
+        }
+      }
     } catch (err) {
       logger?.warn?.(`Live outcome update failed for ${huId}: ${err.message}`);
     }

package/src/orchestrator/drivers/run-hu-batch.js

@@ -360,7 +360,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
     onStatusChange: ctx.session?._liveStatusUpdater || null,
     // PR3 (per-HU outcome): same pattern, but for the rich
     // outcome blob written ONCE per HU at the end of runSingleHu.
-    onOutcome: ctx.session?._liveOutcomeUpdater || null
+    onOutcome: ctx.session?._liveOutcomeUpdater || null,
+    // Cost D (KJC-TSK-0515): the sub-pipeline slices BudgetTracker
+    // entries per HU and stamps `outcome.cost_usd` so the board can
+    // show per-HU spend. Without this the tracker is invisible to it.
+    budgetTracker: ctx.budgetTracker || null
   });
 
   emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {