karajan-code 3.1.0 → 3.3.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.1.0 released** — first minor on v3. Bundles tool-correctness judge and TDD-discipline as new quality gates, `kj clean --all/--vector-stores/--repo` for housekeeping, `kj sync --apply` closing the SPDD loop, semantic test-diet auditor (498 test files, 0 loss-of-meaning findings), HU Board structural refactor (17 PRs), and a batch of security + flake fixes. No breaking changes; drop-in upgrade from v3.0.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.3.0 released** — Cross-provider cache observability (epic KJC-PCS-0056 / Phase 0 closed). Every `kj run` now measures provider-level prompt-cache hits end-to-end across Anthropic, OpenAI/Codex, Gemini, aider and opencode — same `cached_tokens` field flows from agent → BudgetTracker → `summary.md` → `board.db` → HU Board badge `🎯 N%` → telemetry `pipeline_complete`. Real data: Claude cold→hot 47.2% → 94.3% cache_pct (**76.4% cost savings on a single HU**), Gemini 87.9% → 96.8%. Null-safe: badge hides when unmeasured. Drop-in upgrade from v3.2.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -121,7 +121,7 @@ pip install .
 
 Both options expect the `kj` binary to be on your `PATH` (via one of the methods above) — the Python wrapper does not vendor it.
 
-That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
+That's it. `kj init` auto-detects your installed agents and installs the bundled integrations (RTK + Squeezr for token optimization; QMD for the per-project semantic wiki).
 
 ### Optional scanners for `kj audit` + `kj webperf`
 
@@ -366,14 +366,22 @@ Karajan auto-detects and auto-configures everything it can:
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
+## Bundled integrations
+
+These ship with Karajan and `kj init` installs them as part of setup. They're token-efficiency layers the pipeline depends on — not nice-to-haves.
+
+| Tool | Invoked by | Why |
+|------|-----------|-----|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
+| [**Squeezr**](https://www.npmjs.com/package/squeezr-ai) | Karajan (auto, on agent tool outputs) | Compresses verbose tool results before they reach the agent context |
+| [**QMD**](https://github.com/manufosela/qmd) | Karajan (`kj init` auto-registers `docs/`, `.reviews/`, `.karajan/plans/`); you (via `kj qmd query`) | Per-project semantic wiki for **humans**. Complements the **agent-facing** RAG index — `kj rag query` is what the pipeline reads; `kj qmd query` is what you read |
+
 ## Recommended companions
 
 None of these are required. Karajan runs fine on its own. They're tools that, when present, Karajan can take advantage of — or that help *you* work better around Karajan.
 
 | Tool | Invoked by | Why |
 |------|-----------|-----|
-| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**QMD**](https://github.com/manufosela/qmd) | You (CLI / MCP), complementary to RAG | Semantic search engine over Markdown corpora — works alongside `kj rag query` when you want a richer index over your own docs |
 | [**GitHub MCP**](https://github.com/github/github-mcp-server) | Your AI agent (via MCP) | Create PRs, manage issues directly from the agent |
 | [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Your AI agent (via MCP) | Verify UI changes visually after frontend modifications |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -26,6 +26,11 @@
   "engines": {
     "node": ">=22.22.1"
   },
+  "workspaces": [
+    "packages/ai-trash",
+    "packages/core",
+    "packages/hu-board"
+  ],
   "imports": {
     "#utils/*": "./src/utils/*",
     "#session/*": "./src/session/*",

package/packages/hu-board/package.json

@@ -13,11 +13,13 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@karajan/core": "*",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
-    "helmet": "^8.1.0"
+    "helmet": "^8.1.0",
+    "js-yaml": "^4.2.0"
   },
   "devDependencies": {
     "supertest": "^7.1.0",

package/packages/hu-board/public/index.html

@@ -26,6 +26,7 @@
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
       <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
+      <a class="nav-btn" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
       <select class="project-select" id="project-select">
         <option value="">All Projects</option>
       </select>

package/packages/hu-board/public/styles.css

@@ -244,6 +244,17 @@ a:hover {
   font-family: var(--font-mono);
 }
 
+.section-header__cost {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+  padding: 2px 8px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary, transparent);
+  cursor: help;
+}
+
 /* ---- Kanban Board ---- */
 .kanban {
   display: grid;
@@ -341,6 +352,12 @@ a:hover {
 .story-card__score--ok { color: var(--color-yellow); }
 .story-card__score--bad { color: var(--color-red); }
 
+.story-card__cost {
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
 .quality-bar {
   display: inline-flex;
   gap: 1px;
@@ -939,3 +956,18 @@ body.scoped-mode .header__nav a[href="/pipeline.html"] {
 .rag-bar__label { color: var(--text-secondary, #cbd5e1); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .rag-bar__fill { display: block; height: 14px; background: linear-gradient(90deg, #7c3aed, #a78bfa); border-radius: 3px; }
 .rag-bar__value { text-align: right; color: var(--text-primary, #f8fafc); font-variant-numeric: tabular-nums; }
+
+/* KJC-TSK-0508 — Wiki panel (QMD semantic search) */
+.wiki-search { padding: 1rem; }
+.wiki-form { display: grid; grid-template-columns: 1fr 220px auto auto; gap: .5rem; align-items: center; }
+.wiki-form input[type="search"], .wiki-form input[type="text"] { padding: .5rem .75rem; border-radius: 6px; border: 1px solid var(--border, #334155); background: var(--bg-secondary, #1e1e2e); color: var(--text-primary, #f8fafc); font-size: .9rem; }
+.wiki-fast { display: flex; align-items: center; gap: .35rem; font-size: .85rem; color: var(--text-secondary, #94a3b8); }
+.wiki-hint { margin: .5rem 0 0; font-size: .8rem; color: var(--text-secondary, #94a3b8); font-style: italic; }
+.wiki-results { display: grid; gap: .75rem; padding: 0 1rem 1rem; }
+.wiki-hit { background: var(--bg-secondary, #1e1e2e); border-radius: 8px; padding: .9rem 1rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+.wiki-hit__head { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: .4rem; }
+.wiki-hit__src { font-family: ui-monospace, monospace; font-size: .85rem; color: #a78bfa; }
+.wiki-hit__score { font-size: .75rem; color: var(--text-secondary, #94a3b8); font-variant-numeric: tabular-nums; }
+.wiki-hit__snip { margin: 0; font-family: ui-monospace, monospace; font-size: .82rem; line-height: 1.45; color: var(--text-primary, #f8fafc); white-space: pre-wrap; word-break: break-word; }
+.wiki-code { background: #0f172a; color: #e2e8f0; padding: .5rem .75rem; border-radius: 6px; font-family: ui-monospace, monospace; font-size: .85rem; margin: .5rem 0; }
+@media (max-width: 720px) { .wiki-form { grid-template-columns: 1fr; } }

package/packages/hu-board/public/utils/board-view.js

@@ -35,7 +35,14 @@ async function renderBoard() {
       return;
     }
 
-    const stories = await api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`);
+    const [stories, projectCost] = await Promise.all([
+      api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`),
+      api(`/api/projects/${encodeURIComponent(selectedProject)}/cost`).catch(() => null),
+    ]);
+    const costSummary = projectCost ? formatProjectCostSummary(projectCost) : null;
+    // Φ0-G (KJC-TSK-0525): aggregated cache-hit badge at the project
+    // header, rendered alongside the project cost chip.
+    const cacheSummary = projectCost ? formatCacheRatio(projectCost.cachedTokens, projectCost.tokensIn) : null;
 
     // Pre-resolve project initials + name for every distinct project_id in
     // the fetched stories so `renderStoryCard` is synchronous and the header
@@ -96,6 +103,8 @@ async function renderBoard() {
                   onclick="event.stopPropagation(); window.renameProjectModal('${esc(selectedProject)}', '${esc(projectDisplayName.replace(/'/g, '&#39;'))}');">✎</button>
         ` : ''}
         <span class="section-header__count">${stories.length} stories</span>
+        ${costSummary ? `<span class="section-header__cost" title="${esc(costSummary.tooltip)}">💵 ${esc(costSummary.label)}</span>` : ''}
+        ${cacheSummary ? `<span class="section-header__cache" title="${esc(cacheSummary.tooltip)}">${esc(cacheSummary.label)}</span>` : ''}
         ${isRunning ? `
           <button id="running-badge-btn" class="section-header__badge"
                 style="margin-left:auto;padding:4px 10px;font-size:0.8rem;background:var(--color-yellow,#eab308);color:#000;border-radius:var(--radius-sm);font-weight:600;border:none;cursor:pointer;"
@@ -372,6 +381,17 @@ function renderStoryCard(story) {
             ${story.quality_total}/60 ${qualityBar(story.quality_total)}
           </span>
         ` : ''}
+        ${(() => {
+          const c = formatCost(story.cost_usd);
+          return c ? `<span class="story-card__cost" title="${esc(c.tooltip)}">💵 ${esc(c.label)}</span>` : '';
+        })()}
+        ${(() => {
+          // Φ0-G (KJC-TSK-0525): per-HU cache hit badge. Rendered next to
+          // the cost so users can correlate "this run cost $X and 73% of
+          // input was served from cache" in one glance.
+          const r = formatCacheRatio(story.cached_tokens, story.tokens_in);
+          return r ? `<span class="story-card__cache" title="${esc(r.tooltip)}">${esc(r.label)}</span>` : '';
+        })()}
       </div>
       ${missingTestContract ? `
         <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--color-yellow,#eab308);font-weight:600" title="This HU has no acceptance_tests declared — Run plan will reject it until you add at least one.">

package/packages/hu-board/public/utils/formatters.js

@@ -45,6 +45,74 @@ function formatSessionLabel(session) {
   };
 }
 
+function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+// Φ0-G (KJC-TSK-0525): mirror of formatCacheRatio in src/format.js.
+// Kept duplicated because this file is a classic script loaded into
+// the browser, while src/format.js uses ES modules and is consumed by
+// Node tests. See KJC-TSK-0501 header notes above.
+function formatCacheRatio(cachedTokens, tokensIn) {
+  if (cachedTokens === null || cachedTokens === undefined) return null;
+  if (tokensIn === null || tokensIn === undefined) return null;
+  const c = Number(cachedTokens);
+  const t = Number(tokensIn);
+  if (!Number.isFinite(c) || !Number.isFinite(t)) return null;
+  if (t <= 0 || c < 0) return null;
+  const pct = Math.round((c / t) * 1000) / 10;
+  const num = c.toLocaleString("en-US");
+  const den = t.toLocaleString("en-US");
+  return {
+    label: `🎯 ${pct}%`,
+    tooltip: `Cache hits: ${num} / ${den} input tokens (${pct}%)`,
+  };
+}
+
+function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  // Φ0-G (KJC-TSK-0525): aggregate cache hits line + per-plan suffix.
+  const projCache = formatCacheRatio(cost.cachedTokens, cost.tokensIn);
+  if (projCache) lines.push(`Cache: ${projCache.tooltip.split(": ")[1]}`);
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      const cachePct = p?.cachedRatioPct;
+      const cacheSuffix = (cachePct !== null && cachePct !== undefined && Number.isFinite(Number(cachePct)))
+        ? ` 🎯 ${cachePct}%`
+        : "";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})${cacheSuffix}`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
 function humaniseProjectName(id) {
   if (!id || typeof id !== 'string') return id || '';
   const tail = id.split(/[/_]/).filter(Boolean).pop() || id;

package/packages/hu-board/public/wiki.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Karajan Wiki · QMD semantic search</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header class="header">
+    <div class="header__logo"><div><div class="header__title">Karajan Wiki</div><div class="header__subtitle">QMD semantic search</div></div></div>
+    <nav class="header__nav">
+      <a class="nav-btn" href="/">← Board</a>
+      <a class="nav-btn" href="/rag.html">RAG</a>
+      <button class="nav-btn active">Wiki</button>
+    </nav>
+  </header>
+  <main class="main" id="wiki-app">
+    <section class="wiki-search">
+      <form id="wiki-form" class="wiki-form" autocomplete="off">
+        <input id="wiki-q" type="search" placeholder="Search the project wiki…" aria-label="Query" required>
+        <input id="wiki-collection" type="text" placeholder="collection (optional)" aria-label="Collection">
+        <label class="wiki-fast"><input id="wiki-fast" type="checkbox"> fast (no rerank)</label>
+        <button type="submit" class="control-btn" id="wiki-go">Search</button>
+      </form>
+      <p class="wiki-hint">QMD runs locally — 0 tokens, ~60s with rerank, ~5s in fast mode.</p>
+    </section>
+    <section id="wiki-results" class="wiki-results"></section>
+  </main>
+  <script src="/wiki.js"></script>
+</body>
+</html>

package/packages/hu-board/public/wiki.js

@@ -0,0 +1,53 @@
+// KJC-TSK-0508 — HU Board Wiki panel frontend. Calls POST /api/wiki/query
+// (server-side spawns `qmd query --format json`) and renders the hits.
+// A 503 with `installable:true` triggers an "Install QMD" CTA instead of
+// a generic error so the user can act on the missing binary.
+const TOKEN = new URLSearchParams(location.search).get("token") || localStorage.getItem("kj_board_token") || "";
+const HEADERS = { "Content-Type": "application/json", ...(TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {}) };
+const ESC = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+function renderInstallCTA(root) {
+  root.innerHTML = `<div class="rag-card rag-card--error">
+    <h3>QMD not installed</h3>
+    <p>The semantic wiki engine is not available on this host. Install it once:</p>
+    <pre class="wiki-code">npm install -g @tobilu/qmd</pre>
+    <p class="rag-stat-sub">Then re-run <code>kj init</code> in this project to register the wiki collection.</p>
+  </div>`;
+}
+
+function renderHits(root, results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    root.innerHTML = '<p class="rag-empty">no hits — try a broader query or run <code>qmd update</code>.</p>';
+    return;
+  }
+  root.innerHTML = results.map((r) => {
+    const src = r.source || r.path || r.file || "(unknown source)";
+    const snip = r.snippet || r.text || r.content || "";
+    const score = typeof r.score === "number" ? r.score.toFixed(3) : "";
+    return `<article class="wiki-hit">
+      <header class="wiki-hit__head"><span class="wiki-hit__src">${ESC(src)}</span>${score ? `<span class="wiki-hit__score">${ESC(score)}</span>` : ""}</header>
+      <pre class="wiki-hit__snip">${ESC(snip)}</pre>
+    </article>`;
+  }).join("");
+}
+
+async function runSearch(ev) {
+  ev?.preventDefault();
+  const root = document.getElementById("wiki-results");
+  const query = document.getElementById("wiki-q").value.trim();
+  if (!query) return;
+  const collection = document.getElementById("wiki-collection").value.trim() || undefined;
+  const fast = document.getElementById("wiki-fast").checked;
+  root.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Searching the wiki…</p></div>';
+  try {
+    const res = await fetch("/api/wiki/query", { method: "POST", headers: HEADERS, body: JSON.stringify({ query, collection, fast }) });
+    const data = await res.json().catch(() => ({}));
+    if (res.status === 503 && data.installable) { renderInstallCTA(root); return; }
+    if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+    renderHits(root, data.results);
+  } catch (err) {
+    root.innerHTML = `<div class="rag-card rag-card--error"><strong>Error:</strong> ${ESC(err.message || String(err))}</div>`;
+  }
+}
+
+document.getElementById("wiki-form").addEventListener("submit", runSearch);

package/packages/hu-board/src/db.js

@@ -323,6 +323,18 @@ export function initDb() {
   // unconditionally so solo devs who later promote a plan don't lose
   // values they typed pre-share.
   try { db.exec('ALTER TABLE stories ADD COLUMN assignee TEXT'); } catch { /* already migrated */ }
+  // KJC-TSK-0514 (Cost C): persisted USD cost of running this HU. NULL
+  // until the orchestrator (Cost D) calls setStoryCost on HU close. UI
+  // renders "—" while NULL. Stored as REAL so the SQL aggregations in
+  // Cost E (/api/projects/:id/cost) can SUM directly without parsing.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cost_usd REAL'); } catch { /* already migrated */ }
+  // KJC-TSK-0525 (Φ0-G): persisted cached/input tokens per HU so the
+  // board can render the "🎯 N% cached" badge without re-parsing the
+  // session summary. NULL = unmeasured (older runs, cold runs without
+  // cache support). INTEGER because providers report token counts as
+  // ints. Ratio is computed at read time as cached_tokens / tokens_in.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cached_tokens INTEGER'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN tokens_in INTEGER'); } catch { /* already migrated */ }
   try { db.exec('CREATE INDEX IF NOT EXISTS idx_stories_plan ON stories(plan_id)'); } catch { /* ignore */ }
 
   // is_test (KJC-TSK-0371 — board polish #3): per-project flag that
@@ -499,6 +511,61 @@ export function updateStoryStatus(storyId, status) {
   return res.changes > 0;
 }
 
+/**
+ * Persist the USD cost of a HU. Called by the orchestrator (Cost D) once
+ * the HU finishes — the value comes from `aggregateRunCost(events).totalUsd`
+ * (Cost B). `null` clears the cell so the UI renders "—" again. Other
+ * numeric inputs are coerced via `Number`; non-finite values reject with
+ * an explicit throw so callers don't silently NULL-out real cost rows.
+ *
+ * @param {string} storyId
+ * @param {number|null} costUsd
+ * @returns {boolean} true when the row existed and was updated
+ */
+export function setStoryCost(storyId, costUsd) {
+  let value = null;
+  if (costUsd !== null && costUsd !== undefined) {
+    const n = Number(costUsd);
+    if (!Number.isFinite(n)) {
+      throw new Error(`setStoryCost: costUsd must be a finite number or null (got ${costUsd})`);
+    }
+    value = n;
+  }
+  const res = getDb()
+    .prepare('UPDATE stories SET cost_usd = ?, updated_at = ? WHERE id = ?')
+    .run(value, new Date().toISOString(), storyId);
+  return res.changes > 0;
+}
+
+/**
+ * Persist cached/input tokens for a HU (KJC-TSK-0525, Φ0-G). Called by
+ * the orchestrator alongside `setStoryCost` once the HU finishes. Both
+ * values come from `BudgetTracker.since(huCursor)` (Φ0-E). Pass `null`
+ * to clear either cell. Non-finite numbers throw so callers don't
+ * silently null-out real telemetry.
+ *
+ * @param {string} storyId
+ * @param {number|null} cachedTokens
+ * @param {number|null} tokensIn
+ * @returns {boolean} true when the row existed and was updated
+ */
+export function setStoryCachedTokens(storyId, cachedTokens, tokensIn) {
+  const coerce = (v, name) => {
+    if (v === null || v === undefined) return null;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0) {
+      throw new Error(`setStoryCachedTokens: ${name} must be a non-negative finite number or null (got ${v})`);
+    }
+    return Math.round(n);
+  };
+  const cached = coerce(cachedTokens, 'cachedTokens');
+  const tin = coerce(tokensIn, 'tokensIn');
+  const res = getDb()
+    .prepare('UPDATE stories SET cached_tokens = ?, tokens_in = ?, updated_at = ? WHERE id = ?')
+    .run(cached, tin, new Date().toISOString(), storyId);
+  return res.changes > 0;
+}
+
 /**
  * List every distinct `plan_id` stamped on the stories of a given project.
  * Used by "mark plan ready" so the board can act on each plan of a project
@@ -598,6 +665,76 @@ export function getStoriesByProject(projectId) {
   `).all(projectId);
 }
 
+/**
+ * Aggregate $ cost for a project (KJC-TSK-0516, Cost E).
+ * Sums stories.cost_usd, groups by plan_id ('unassigned' for NULL).
+ * Returns null if project does not exist; otherwise an object with
+ * totalUsd=0 and byPlan=[] when no stories carry cost_usd yet.
+ * @param {string} projectId
+ * @returns {{ totalUsd:number, byPlan:Array<{planId:string,totalUsd:number,huCount:number}>, unknownModelTokens:object, currency:string } | null}
+ */
+export function getProjectCost(projectId) {
+  const project = getDb()
+    .prepare('SELECT id FROM projects WHERE id = ?')
+    .get(projectId);
+  if (!project) return null;
+
+  // Φ0-G: cached_tokens / tokens_in are nullable independently of
+  // cost_usd, so we read all three columns but keep cost as the
+  // primary filter (a row with only cache telemetry but no $ should
+  // not appear in the per-plan totals — cost rules the byPlan list).
+  const rows = getDb()
+    .prepare(
+      `SELECT plan_id, cost_usd, cached_tokens, tokens_in FROM stories
+       WHERE project_id = ? AND cost_usd IS NOT NULL`
+    )
+    .all(projectId);
+
+  const round4 = (n) => Math.round(n * 10000) / 10000;
+  const byPlanMap = new Map();
+  let totalUsd = 0;
+  let totalCached = 0;
+  let totalTokensIn = 0;
+  for (const r of rows) {
+    const planId = r.plan_id || 'unassigned';
+    const cost = Number(r.cost_usd);
+    if (!Number.isFinite(cost)) continue;
+    totalUsd += cost;
+    const cached = Number(r.cached_tokens);
+    const tin = Number(r.tokens_in);
+    if (Number.isFinite(cached) && cached >= 0) totalCached += cached;
+    if (Number.isFinite(tin) && tin >= 0) totalTokensIn += tin;
+    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0, cachedTokens: 0, tokensIn: 0 };
+    cur.totalUsd += cost;
+    cur.huCount += 1;
+    if (Number.isFinite(cached) && cached >= 0) cur.cachedTokens += cached;
+    if (Number.isFinite(tin) && tin >= 0) cur.tokensIn += tin;
+    byPlanMap.set(planId, cur);
+  }
+
+  const ratio = (cached, tin) => tin > 0 ? Math.round((cached / tin) * 1000) / 10 : null;
+  const byPlan = Array.from(byPlanMap.values())
+    .map((p) => ({
+      planId: p.planId,
+      totalUsd: round4(p.totalUsd),
+      huCount: p.huCount,
+      cachedTokens: p.cachedTokens,
+      tokensIn: p.tokensIn,
+      cachedRatioPct: ratio(p.cachedTokens, p.tokensIn),
+    }))
+    .sort((a, b) => b.totalUsd - a.totalUsd);
+
+  return {
+    totalUsd: round4(totalUsd),
+    byPlan,
+    cachedTokens: totalCached,
+    tokensIn: totalTokensIn,
+    cachedRatioPct: ratio(totalCached, totalTokensIn),
+    unknownModelTokens: { tokensIn: 0, tokensOut: 0, models: [] },
+    currency: 'USD',
+  };
+}
+
 /**
  * Returns full story detail including context requests.
  * @param {string} storyId

package/packages/hu-board/src/format.js

@@ -60,6 +60,130 @@ export function shortTask(text, max = MAX_TASK_CHARS) {
  *           created_at?: string|null }} session
  * @returns {{ title: string, subtitle: string, idChip: string }}
  */
+/**
+ * Format a per-HU cost (USD) for the card badge. Cost F (KJC-TSK-0517).
+ *
+ * Two outputs in one call so the UI can render both at once:
+ *   - `label`: 2-decimal "$X.XX" shown on the card (compact).
+ *   - `tooltip`: 4-decimal "Estimated cost: $X.XXXX" shown on hover
+ *     (matches the precision aggregated by Cost B/C/D, see
+ *     `packages/core/src/cost/index.js`).
+ *
+ * Returns `null` for null/undefined/non-finite inputs so the caller
+ * skips the badge entirely (rendering "$0.00" for an unknown cost
+ * would be misleading — there is a real difference between "we know it
+ * was free" and "we haven't measured it yet").
+ *
+ * @param {number|null|undefined} costUsd
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+/**
+ * Φ0-G (KJC-TSK-0525): per-HU and per-plan cached-tokens badge.
+ *
+ * Returns `{ label, tooltip }` for "🎯 23%" with a tooltip showing the
+ * exact numerator/denominator. Same "don't render 0% when there is no
+ * data" stance as formatCost — returns null when:
+ *   - either arg is null/undefined/non-finite,
+ *   - tokens_in is 0 (no input → ratio undefined, not zero),
+ *   - cached is negative (would only happen from corrupted telemetry).
+ *
+ * The badge intentionally shows 1 decimal to keep narrow runs (e.g.
+ * a 73-token cache out of 1 200) readable without rounding to 0%.
+ *
+ * @param {number|null|undefined} cachedTokens
+ * @param {number|null|undefined} tokensIn
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCacheRatio(cachedTokens, tokensIn) {
+  // Reject null/undefined explicitly — Number(null) coerces to 0,
+  // which would otherwise render an honest-looking "🎯 0%" badge for
+  // runs where we simply have no telemetry. Same stance as formatCost.
+  if (cachedTokens === null || cachedTokens === undefined) return null;
+  if (tokensIn === null || tokensIn === undefined) return null;
+  const c = Number(cachedTokens);
+  const t = Number(tokensIn);
+  if (!Number.isFinite(c) || !Number.isFinite(t)) return null;
+  if (t <= 0 || c < 0) return null;
+  const pct = Math.round((c / t) * 1000) / 10;
+  const num = c.toLocaleString("en-US");
+  const den = t.toLocaleString("en-US");
+  return {
+    label: `🎯 ${pct}%`,
+    tooltip: `Cache hits: ${num} / ${den} input tokens (${pct}%)`,
+  };
+}
+
+/**
+ * Format the aggregated project-level cost chip rendered in the board
+ * header. Cost G (KJC-TSK-0518). Consumes the shape returned by
+ * `GET /api/projects/:id/cost` (Cost E):
+ *   { totalUsd, byPlan: [{planId, totalUsd, huCount}, …],
+ *     unknownModelTokens: { tokensIn, tokensOut, models }, currency }
+ *
+ * Returns `{ label, tooltip }` where:
+ *   - `label` is the compact "Total: $X.XX" shown in the header.
+ *   - `tooltip` is a multi-line string with full precision, the
+ *     per-plan breakdown, and a note when some tokens used a model we
+ *     don't price (they aren't included in the total — surfacing the
+ *     skip is more honest than silently swallowing it).
+ *
+ * Returns `null` when there is nothing to show (no input, or no
+ * measured cost yet and no plans). The chip is then hidden — same
+ * reasoning as `formatCost`: "$0.00" with no data is misleading.
+ *
+ * @param {{totalUsd:number, byPlan?:Array, unknownModelTokens?:object}|null|undefined} cost
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  // Φ0-G (KJC-TSK-0525): when the API includes project-level cache
+  // counters, show the aggregate cached% line right under the total
+  // so users can see at a glance how much was served from cache.
+  const projCache = formatCacheRatio(cost.cachedTokens, cost.tokensIn);
+  if (projCache) lines.push(`Cache: ${projCache.tooltip.split(": ")[1]}`);
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      const cachePct = p?.cachedRatioPct;
+      const cacheSuffix = (cachePct !== null && cachePct !== undefined && Number.isFinite(Number(cachePct)))
+        ? ` 🎯 ${cachePct}%`
+        : "";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})${cacheSuffix}`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
 export function formatSessionLabel(session) {
   if (!session || !session.id) {
     return { title: "(no session)", subtitle: "", idChip: "" };