karajan-code 3.1.0 → 3.3.0

package/src/rag/vec-store.js

@@ -1,253 +1,17 @@
-// KJC-PCS-0049 Step 1 — Vector store sobre better-sqlite3 + sqlite-vec.
-// El RAG indexer (Step 4) escribe; el retriever (Step 5) lee. Una sola
-// DB en `~/.karajan/rag.db` por instalación.
-import { mkdirSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import Database from "better-sqlite3";
-import * as sqliteVec from "sqlite-vec";
-
-import { getKarajanHome } from "../utils/paths.js";
-
-const DEFAULT_DIM = 768;
-
-export function dbPath() {
-  return process.env.KJ_RAG_DB || join(getKarajanHome(), "rag.db");
-}
-
-/**
- * Open the rag.db, load the sqlite-vec extension, and ensure the
- * chunks + vec_chunks tables exist. Idempotent: a second call against
- * the same file is a no-op past the schema creation.
- *
- * Returns the open Database handle. Caller owns close().
- *
- * @param {Object} [opts]
- * @param {number} [opts.dim=768] — embedding dimension. Must match
- *   the embedder configured for the project (Step 2). Changing it
- *   later requires a fresh DB; the constant is captured in the
- *   virtual table DDL.
- */
-export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
-  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true });
-  const db = new Database(path);
-  sqliteVec.load(db);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS chunks (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      source TEXT NOT NULL,
-      kind TEXT NOT NULL CHECK (kind IN ('plan', 'code', 'onboarding')),
-      text TEXT NOT NULL,
-      metadata TEXT,
-      created_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-    CREATE INDEX IF NOT EXISTS chunks_by_source ON chunks(source);
-    CREATE INDEX IF NOT EXISTS chunks_by_kind ON chunks(kind);
-  `);
-  // KJC-TSK-0438 — Project isolation. project_slug = basename of projectDir
-  // normalized; chunks indexed before the migration carry NULL and remain
-  // queryable when `--project all` (or no slug detected at query time).
-  const cols = db.prepare("PRAGMA table_info(chunks)").all().map((c) => c.name);
-  if (!cols.includes("project_slug")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN project_slug TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_project ON chunks(project_slug);");
-  }
-  // KJC-TSK-0484 — Content-hash dedup. SHA-256 of the chunk text lets the
-  // indexer skip embedding bodies it has already seen for the same project.
-  // Older rows keep NULL; the lookup ignores NULLs so they neither dedup
-  // nor get deduped until they are re-indexed and stamped.
-  if (!cols.includes("content_hash")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN content_hash TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_hash ON chunks(content_hash, project_slug);");
-  }
-  // KJC-TSK-0455 — Auto-update by commit diff. Per-project metadata tracks
-  // the last commit whose changes were reflected in the index, so subsequent
-  // `kj rag index --since auto` invocations (and the post-merge hook / pre-run
-  // drift check landed in PR2) only re-embed the actual delta instead of the
-  // whole project.
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS vec_store_meta (
-      project_slug TEXT PRIMARY KEY,
-      last_indexed_commit TEXT,
-      last_indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-  db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}]);`);
-  // KJC-TSK-0443 — FTS5 keyword index for BM25 hybrid scoring. content='chunks'
-  // makes it a contentless mirror linked by id (no double storage); triggers
-  // sync the FTS5 rows on insert/update/delete. Rebuilds idempotently when
-  // the FTS5 table exists but is empty (e.g. created post-migration on a
-  // DB with pre-v2.28 chunks).
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(text, content='chunks', content_rowid='id');
-    CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-  `);
-  const ftsCount = db.prepare("SELECT COUNT(*) AS n FROM chunks_fts").get().n;
-  const chunksCount = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-  if (ftsCount === 0 && chunksCount > 0) {
-    db.exec("INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');");
-  }
-  return db;
-}
-
-/**
- * Persist one chunk. The chunks.id and vec_chunks.rowid stay in sync
- * because the virtual table rowid is set explicitly to the freshly
- * minted chunks.id. Returns that id.
- */
-export function insertChunk(db, { source, kind, text, metadata = null, embedding, project = null, contentHash = null }) {
-  if (!Array.isArray(embedding) && !ArrayBuffer.isView(embedding)) {
-    throw new Error("insertChunk: embedding must be an array or typed array of floats");
-  }
-  const meta = metadata == null ? null : (typeof metadata === "string" ? metadata : JSON.stringify(metadata));
-  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata, project_slug, content_hash) VALUES (?, ?, ?, ?, ?, ?)");
-  const info = ins.run(source, kind, text, meta, project, contentHash);
-  // sqlite-vec's vec0 virtual table requires the rowid to arrive as a BigInt
-  // even for values that comfortably fit in a Number. Better-sqlite3 returns
-  // lastInsertRowid as BigInt only when safeIntegers mode is on; force it.
-  const id = typeof info.lastInsertRowid === "bigint" ? info.lastInsertRowid : BigInt(info.lastInsertRowid);
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  db.prepare("INSERT INTO vec_chunks(rowid, embedding) VALUES (?, ?)").run(id, Buffer.from(buf.buffer));
-  return Number(id);
-}
-
-/**
- * Cosine-ordered nearest-neighbour search. Returns `[{ id, source, kind,
- * text, metadata, distance }]` for the topK best matches; lower
- * distance = closer. Returns `[]` when the store is empty.
- */
-export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, v.distance
-    FROM vec_chunks v
-    JOIN chunks c ON c.id = v.rowid
-    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY v.distance
-  `;
-  const params = [Buffer.from(buf.buffer), topK];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  const rows = db.prepare(sql).all(...params);
-  return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-}
-
-/**
- * Normalize a projectDir into a stable slug used for project isolation.
- * Basename → lowercased → non-alphanumeric stripped to dashes.
- * KJC-TSK-0438.
- */
-export function projectSlug(projectDir) {
-  if (!projectDir) return null;
-  const base = String(projectDir).replace(/\/+$/, "").split("/").pop();
-  if (!base) return null;
-  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-}
-
-function safeParse(s) { try { return JSON.parse(s); } catch { return s; } }
-
-/**
- * Remove every chunk that came from a given source path. Both tables
- * are touched explicitly because vec0 virtual tables do not honour
- * SQLite foreign-key cascades.
- */
-export function deleteChunksBySource(db, source) {
-  const ids = db.prepare("SELECT id FROM chunks WHERE source = ?").all(source).map((r) => r.id);
-  if (ids.length === 0) return 0;
-  const placeholders = ids.map(() => "?").join(",");
-  db.prepare(`DELETE FROM vec_chunks WHERE rowid IN (${placeholders})`).run(...ids);
-  db.prepare(`DELETE FROM chunks WHERE id IN (${placeholders})`).run(...ids);
-  return ids.length;
-}
-
-// KJC-TSK-0455 — Per-project commit watermark for `kj rag index --since auto`
-// and the post-merge / pre-run drift hooks landing in PR2.
-export function getLastIndexedCommit(db, projectSlug) {
-  if (!projectSlug) return null;
-  const row = db.prepare("SELECT last_indexed_commit FROM vec_store_meta WHERE project_slug = ?").get(projectSlug);
-  return row?.last_indexed_commit ?? null;
-}
-
-export function setLastIndexedCommit(db, projectSlug, commit) {
-  if (!projectSlug || !commit) return;
-  db.prepare(`
-    INSERT INTO vec_store_meta (project_slug, last_indexed_commit, last_indexed_at)
-    VALUES (?, ?, datetime('now'))
-    ON CONFLICT(project_slug) DO UPDATE SET
-      last_indexed_commit = excluded.last_indexed_commit,
-      last_indexed_at = excluded.last_indexed_at
-  `).run(projectSlug, commit);
-}
-
-// KJC-TSK-0484 PR-B — Bulk fetch embeddings for an explicit set of chunk ids.
-// Returns Map<id, Float32Array>. Used by MMR diversification in retriever.js.
-export function getEmbeddingsByIds(db, ids) {
-  const out = new Map();
-  if (!ids?.length) return out;
-  const placeholders = ids.map(() => "?").join(",");
-  const rows = db.prepare(`SELECT rowid AS id, embedding FROM vec_chunks WHERE rowid IN (${placeholders})`).all(...ids);
-  for (const row of rows) {
-    if (!row.embedding) continue;
-    const buf = Buffer.isBuffer(row.embedding) ? row.embedding : Buffer.from(row.embedding);
-    out.set(Number(row.id), new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
-  }
-  return out;
-}
-
-// KJC-TSK-0484 — Lookup an already-indexed chunk by content_hash. Scoped to a
-// project so two repos with the same boilerplate file don't cross-pollute.
-// Returns `{ id, source }` or null. Pass `project=null` to match NULL slugs.
-export function findChunkByHash(db, hash, project = null) {
-  if (!hash) return null;
-  const sql = project
-    ? "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug = ? LIMIT 1"
-    : "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug IS NULL LIMIT 1";
-  const row = project ? db.prepare(sql).get(hash, project) : db.prepare(sql).get(hash);
-  return row || null;
-}
-
-export function countChunks(db, { kind = null } = {}) {
-  if (kind) return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE kind = ?").get(kind).n;
-  return db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-}
-
-/**
- * KJC-TSK-0443 — BM25 keyword search over chunks_fts. Returns
- * [{ id, source, kind, text, metadata, project_slug, bm25 }] ordered by
- * relevance (lower bm25 = better in SQLite FTS5). `query` is sanitized for
- * the FTS5 grammar: special chars are stripped, words split on whitespace.
- */
-export function searchBM25(db, queryText, topK = 10, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const cleaned = String(queryText || "").replace(/["'()]/g, " ").split(/\s+/).filter(Boolean).join(" OR ");
-  if (!cleaned) return [];
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, bm25(chunks_fts) AS bm25
-    FROM chunks_fts JOIN chunks c ON c.id = chunks_fts.rowid
-    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY bm25 LIMIT ?
-  `;
-  const params = [cleaned];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  params.push(topK);
-  try {
-    const rows = db.prepare(sql).all(...params);
-    return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-  } catch { return []; }
-}
+// Shim: vec-store primitives now live in @karajan/core/vec-store so
+// the hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR4.
+export {
+  dbPath,
+  openVecStore,
+  insertChunk,
+  searchSimilar,
+  projectSlug,
+  deleteChunksBySource,
+  getLastIndexedCommit,
+  setLastIndexedCommit,
+  getEmbeddingsByIds,
+  findChunkByHash,
+  countChunks,
+  searchBM25,
+} from "@karajan/core/vec-store";

package/src/roles/audit-role.js

@@ -9,6 +9,7 @@ import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
+import { collectAiSlop } from "../audit/ai-slop-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -53,6 +54,7 @@ export class AuditRole extends AgentRole {
     const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
     const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
     const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
+    const noAiSlop = typeof input === "object" ? Boolean(input?.noAiSlop) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -64,6 +66,7 @@ export class AuditRole extends AgentRole {
     let circularDeps = null;
     let deadExports = null;
     let injectionFindings = null;
+    let aiSlop = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -116,7 +119,14 @@ export class AuditRole extends AgentRole {
         injectionFindings = await collectInjectionFindings(projectDir, this.logger);
       } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings };
+    // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
+    // Local equivalent of Deslopify-style review. Best-effort.
+    if (!noAiSlop) {
+      try {
+        aiSlop = await collectAiSlop(projectDir);
+      } catch { /* ai-slop scan is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, aiSlop };
   }
 
   /**

package/src/session/journal/summary-writer.js

@@ -18,7 +18,7 @@ import path from "node:path";
  * @property {"APPROVED"|"REJECTED"|"PAUSED"|"FAILED"|string} result
  * @property {number} iterations
  * @property {number} durationMs
- * @property {{ total_cost_usd?: number, total_tokens?: number, breakdown_by_role?: Object }} [budget]
+ * @property {{ total_cost_usd?: number, total_tokens?: number, total_cached_tokens?: number, breakdown_by_role?: Object }} [budget]
  * @property {Record<string, { ok?: boolean, summary?: string }>} [stages]
  * @property {Array<{ hash?: string, message?: string, date?: string, author?: string }>} [commits]
  * @property {string[]} [files]                    - names of other journal files in the same dir
@@ -107,6 +107,55 @@ function renderBreakdownByRole(breakdown) {
   return ["| Role | Tokens | Cost |", "|---|---|---|", ...rows].join("\n");
 }
 
+/**
+ * Render the Cache hits section (Φ0-F, KJC-TSK-0524). Shows how many input
+ * tokens were served from provider-side prompt caches, per role, plus a
+ * conservative dollar savings estimate.
+ *
+ * Savings formula: cached tokens are billed at ~10% of the input rate (the
+ * Anthropic/OpenAI convention). Per role:
+ *   savings_usd ≈ cost_usd * (cached_tokens / tokens_in) * 0.9
+ * The estimate is approximate (output tokens also contribute to cost_usd)
+ * and labelled with `~$` so users don't read it as exact.
+ *
+ * Returns:
+ *   - null when no budget data is available
+ *   - "cold run" placeholder when cached == 0 across all roles
+ *   - Markdown table sorted by cached tokens desc when there is cache activity
+ */
+function renderCacheHits(budget) {
+  if (!budget) return null;
+  const totalCached = Number(budget.total_cached_tokens ?? 0);
+  const breakdown = budget.breakdown_by_role || {};
+  const entries = Object.entries(breakdown)
+    .map(([role, m]) => ({
+      role,
+      cached: Number(m?.cached_tokens || 0),
+      tokens_in: Number(m?.tokens_in || 0),
+      cost: Number(m?.total_cost_usd || 0),
+    }))
+    .filter((e) => e.cached > 0);
+
+  if (totalCached === 0 && entries.length === 0) {
+    return "_Cache hits: 0 tokens (cold run)._";
+  }
+
+  const rows = entries
+    .sort((a, b) => b.cached - a.cached)
+    .map((e) => {
+      const ratio = e.tokens_in > 0 ? (e.cached / e.tokens_in) * 100 : 0;
+      const savings = e.tokens_in > 0 ? e.cost * (e.cached / e.tokens_in) * 0.9 : 0;
+      return `| \`${esc(e.role)}\` | ${e.cached.toLocaleString("en-US")} | ${ratio.toFixed(1)}% | ~$${savings.toFixed(4)} |`;
+    });
+  const header = "| Role | Cached tokens | Ratio (cached/in) | Est. savings |\n|---|---|---|---|";
+  return [
+    `**Total cached**: ${totalCached.toLocaleString("en-US")} tokens`,
+    "",
+    header,
+    ...rows,
+  ].join("\n");
+}
+
 /**
  * Render the Skills section: which process skills (addyosmani) were resolved
  * for the task, which OpenSkills were installed, and which skills would have
@@ -192,6 +241,11 @@ export function buildSummaryMarkdown(input) {
     sections.push("", "## Budget breakdown (by role)", "", breakdown);
   }
 
+  const cacheHitsSection = renderCacheHits(input.budget);
+  if (cacheHitsSection) {
+    sections.push("", "## Cache hits", "", cacheHitsSection);
+  }
+
   const skillsSection = renderSkills(input.skills);
   if (skillsSection) {
     sections.push("", "## Skills Used", "", skillsSection);

package/src/utils/ai-trash.js

@@ -0,0 +1,48 @@
+// ai-trash detection + Claude Code hook install (KJC-TSK-0391).
+// `kj-trash` is the binary shipped by the @karajan/ai-trash workspace.
+// detectAiTrash() probes the binary; installAiTrashHook() invokes
+// `kj-trash install --claude-code`, which idempotently patches
+// ~/.claude/settings.json to register the PreToolUse hook.
+
+import { runCommand } from "./process.js";
+
+/**
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectAiTrash() {
+  try {
+    const res = await runCommand("kj-trash", ["--help"]);
+    if (res.exitCode === 0 || res.exitCode === 2) {
+      return { available: true, version: "0.0.0" };
+    }
+    return { available: false, version: null };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+/**
+ * Register the kj-trash PreToolUse hook in ~/.claude/settings.json.
+ * Idempotent: second run reports "already installed" without rewriting.
+ *
+ * @param {object} logger - logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, mutated: boolean, error: string|null }>}
+ */
+export async function installAiTrashHook(logger) {
+  logger.info("Registering ai-trash Claude Code hook...");
+  try {
+    const res = await runCommand("kj-trash", ["install", "--claude-code"], { timeout: 30_000 });
+    if (res.exitCode !== 0) {
+      const error = (res.stderr || "").trim() || `exit code ${res.exitCode}`;
+      logger.warn(`ai-trash hook install failed: ${error}`);
+      return { ok: false, mutated: false, error };
+    }
+    const mutated = !(res.stdout || "").includes("already installed");
+    logger.info(mutated ? "ai-trash hook installed." : "ai-trash hook already installed.");
+    return { ok: true, mutated, error: null };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`ai-trash hook install failed: ${error}`);
+    return { ok: false, mutated: false, error };
+  }
+}

package/src/utils/atomic-write.js

@@ -1,43 +1,6 @@
-// Atomic JSON writes for persistent state (resilience audit, Phase 2).
-//
-// A plain `writeFile(path, JSON.stringify(...))` truncates the live file
-// before the new content lands. If the process is killed mid-write
-// (SIGKILL, crash, power loss) the file is left truncated and the only
-// good copy is already gone — the plan / session / standby JSON
-// silently corrupts.
-//
-// write-temp + rename fixes it: `rename` is atomic on the same
-// filesystem, so a reader sees either the old file or the complete new
-// one, never a half-written one. The temp file sits next to the target
-// (same dir → same FS) and is uniquely named so concurrent writers do
-// not clobber each other's temp. A crash before the rename leaves an
-// orphan `.tmp` but never a corrupt target.
-
-import { writeFileSync, renameSync } from "node:fs";
-import { writeFile, rename } from "node:fs/promises";
-
-function tempPath(target) {
-  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (synchronous).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export function writeJsonAtomicSync(target, obj) {
-  const tmp = tempPath(target);
-  writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  renameSync(tmp, target);
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (async).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export async function writeJsonAtomic(target, obj) {
-  const tmp = tempPath(target);
-  await writeFile(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  await rename(tmp, target);
-}
+// Shim — the real implementation now lives in @karajan/core/atomic-write.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "#utils/atomic-write.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export { writeJsonAtomic, writeJsonAtomicSync } from "@karajan/core/atomic-write";

package/src/utils/budget.js

@@ -26,6 +26,13 @@ export function extractUsageMetrics(result, defaultModel = null) {
     usage?.output_tokens ??
     usage?.completion_tokens ??
     0;
+  const cached_tokens =
+    result?.cached_tokens ??
+    usage?.cached_tokens ??
+    usage?.cache_read_input_tokens ??
+    usage?.prompt_tokens_details?.cached_tokens ??
+    usage?.cachedContentTokenCount ??
+    0;
   const cost_usd =
     result?.cost_usd ??
     usage?.cost_usd ??
@@ -58,7 +65,7 @@ export function extractUsageMetrics(result, defaultModel = null) {
     }
   }
 
-  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cost_usd, model, estimated };
+  return { tokens_in: finalTokensIn, tokens_out: finalTokensOut, cached_tokens, cost_usd, model, estimated };
 }
 
 function toSafeNumber(value) {
@@ -79,9 +86,10 @@ function normalizeLimit(limit) {
 }
 
 function addToBreakdown(map, key, entry) {
-  const current = map[key] || { tokens_in: 0, tokens_out: 0, total_tokens: 0, total_cost_usd: 0, count: 0 };
+  const current = map[key] || { tokens_in: 0, tokens_out: 0, cached_tokens: 0, total_tokens: 0, total_cost_usd: 0, count: 0 };
   current.tokens_in += entry.tokens_in;
   current.tokens_out += entry.tokens_out;
+  current.cached_tokens += entry.cached_tokens || 0;
   current.total_tokens += entry.tokens_in + entry.tokens_out;
   current.total_cost_usd = roundUsd(current.total_cost_usd + entry.cost_usd);
   current.count += 1;
@@ -94,9 +102,10 @@ 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, estimated } = {}) {
+  record({ role, provider, model, tokens_in, tokens_out, cached_tokens, cost_usd, duration_ms, stage_index, estimated } = {}) {
     const safeTokensIn = toSafeNumber(tokens_in);
     const safeTokensOut = toSafeNumber(tokens_out);
+    const safeCached = toSafeNumber(cached_tokens);
     const hasExplicitCost = cost_usd !== undefined && cost_usd !== null && cost_usd !== "";
     const modelName = model || provider || null;
     const computedCost = calculateUsageCostUsd({
@@ -113,6 +122,7 @@ export class BudgetTracker {
       timestamp: new Date().toISOString(),
       tokens_in: safeTokensIn,
       tokens_out: safeTokensOut,
+      cached_tokens: safeCached,
       cost_usd: roundUsd(hasExplicitCost ? cost_usd : computedCost)
     };
     if (duration_ms !== undefined && duration_ms !== null) {
@@ -129,19 +139,36 @@ export class BudgetTracker {
   }
 
   total() {
+    return this._aggregate(this.entries);
+  }
+
+  _aggregate(entries) {
     let tokensIn = 0;
     let tokensOut = 0;
+    let cached = 0;
     let totalCost = 0;
-    for (const entry of this.entries) {
+    for (const entry of entries) {
       tokensIn += entry.tokens_in;
       tokensOut += entry.tokens_out;
+      cached += entry.cached_tokens || 0;
       totalCost = roundUsd(totalCost + entry.cost_usd);
     }
-    return {
-      tokens_in: tokensIn,
-      tokens_out: tokensOut,
-      cost_usd: totalCost
-    };
+    return { tokens_in: tokensIn, tokens_out: tokensOut, cached_tokens: cached, cost_usd: totalCost };
+  }
+
+  /**
+   * Snapshot cursor (Φ0-E). Returns an opaque marker pointing at the current
+   * end of the entries log. Pair with `since(cursor)` to compute per-HU deltas
+   * without resetting global accumulators (per-HU isolation).
+   */
+  cursor() {
+    return this.entries.length;
+  }
+
+  since(cursor = 0) {
+    const start = Number.isFinite(cursor) && cursor >= 0 ? Math.min(cursor, this.entries.length) : 0;
+    const slice = this.entries.slice(start);
+    return { ...this._aggregate(slice), count: slice.length };
   }
 
   remaining(limit) {
@@ -171,6 +198,7 @@ export class BudgetTracker {
     const hasEstimates = this.entries.some(e => e.estimated);
     const result = {
       total_tokens: totals.tokens_in + totals.tokens_out,
+      total_cached_tokens: totals.cached_tokens,
       total_cost_usd: totals.cost_usd,
       breakdown_by_role: byRole,
       entries: [...this.entries],
@@ -191,6 +219,7 @@ export class BudgetTracker {
         duration_ms: entry.duration_ms ?? null,
         tokens_in: entry.tokens_in,
         tokens_out: entry.tokens_out,
+        cached_tokens: entry.cached_tokens || 0,
         cost_usd: entry.cost_usd
       };
       if (entry.estimated) item.estimated = true;

package/src/utils/cli-ask-question.js

@@ -0,0 +1,76 @@
+import readline from "node:readline";
+
+/**
+ * Shared askQuestion factory used by `kj run` and `kj resume`.
+ *
+ * Pre-fix (KJC-BUG-0081 round 1), `src/commands/run.js` got the guard
+ * but `src/commands/resume.js` kept its own copy without the guard, so
+ * `kj resume --yes` in non-TTY mode still hung on the HU Board bridge.
+ * Centralising the three paths here means both commands honour the
+ * same contract and a future fix only needs to land in one place.
+ *
+ * Three paths:
+ *   1. Interactive TTY: prompt via readline (developer terminal).
+ *   2. No TTY + `flags.yes`: caller asked NOT to be prompted → write
+ *      question + context to stderr, return null so the run aborts
+ *      fast and loud (CI / scripted / `kj audit --yes` desatendido).
+ *   3. No TTY without `flags.yes` (HU Board ▶ Run plan with
+ *      `stdio=ignore`): publish through the file-based bridge so the
+ *      board can surface a modal; block until the user answers.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.sessionId]
+ * @param {object} [opts.flags]
+ * @returns {(question: string, context?: object) => Promise<string|null>}
+ */
+export function createCliAskQuestion(opts = {}) {
+  const { sessionId = null, flags = {} } = opts;
+  return async (question, context) => {
+    const stdinReadable = process.stdin && process.stdin.readable !== false;
+    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
+    if (!isInteractive) {
+      if (flags?.yes) {
+        process.stderr.write(
+          `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
+          + `  ❓ ${question}\n`
+          + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
+          + `  Stopping the session. Re-run without --yes (TTY or HU Board) to answer it,\n`
+          + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
+        );
+        return null;
+      }
+      const { askThroughBoard } = await import("./board-prompt-bridge.js");
+      console.log(`\n❓ ${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 — 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} — stopping the session.`);
+        return null;
+      }
+    }
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n❓ ${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());
+        }
+      });
+    });
+  };
+}