karajan-code 3.2.0 → 3.3.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.2.0 released** — Cost tracking end-to-end (epic KJC-PCS-0055 closed). Every `kj run` now records per-HU USD spend via the `BudgetTracker` cursor-snapshot pattern, persists it to `board.db.cost_usd`, and the HU Board surfaces both a per-card badge (`$0.02`) and a project-wide chip with per-plan breakdown. Null-safe: unmeasured HUs hide the badge instead of misleading "$0.00". Drop-in upgrade from v3.1.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.
 

package/package.json

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

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

@@ -40,6 +40,9 @@ async function renderBoard() {
       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
@@ -101,6 +104,7 @@ async function renderBoard() {
         ` : ''}
         <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;"
@@ -381,6 +385,13 @@ function renderStoryCard(story) {
           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

@@ -55,6 +55,26 @@ function formatCost(costUsd) {
   };
 }
 
+// Φ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);
@@ -63,6 +83,9 @@ function formatProjectCostSummary(cost) {
   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) {
@@ -70,7 +93,11 @@ function formatProjectCostSummary(cost) {
       if (!Number.isFinite(planTotal)) continue;
       const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
       const planLabel = p?.planId || "unassigned";
-      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+      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;

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

@@ -328,6 +328,13 @@ export function initDb() {
   // 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
@@ -530,6 +537,35 @@ export function setStoryCost(storyId, costUsd) {
   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
@@ -643,9 +679,13 @@ export function getProjectCost(projectId) {
     .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 FROM stories
+      `SELECT plan_id, cost_usd, cached_tokens, tokens_in FROM stories
        WHERE project_id = ? AND cost_usd IS NOT NULL`
     )
     .all(projectId);
@@ -653,24 +693,43 @@ export function getProjectCost(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 cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0 };
+    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 }))
+    .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',
   };

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

@@ -87,6 +87,42 @@ export function formatCost(costUsd) {
   };
 }
 
+/**
+ * Φ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
@@ -116,6 +152,11 @@ export function formatProjectCostSummary(cost) {
   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) {
@@ -123,7 +164,11 @@ export function formatProjectCostSummary(cost) {
       if (!Number.isFinite(planTotal)) continue;
       const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
       const planLabel = p?.planId || "unassigned";
-      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+      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;

package/src/agents/aider-agent.js

@@ -1,6 +1,46 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract token usage from Aider's stdout. Two shapes are supported:
+ *
+ *   1. LiteLLM passthrough — an OpenAI-style JSON `usage` block surfaces
+ *      `prompt_tokens_details.cached_tokens` for prompt-cache hits.
+ *   2. Aider's native footer "Tokens: <sent> sent, <received> received
+ *      [, <cached> cache hit]." (supports comma-separated and `k` suffix).
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
+ * is found (= unmeasured; callers leave the fields undefined).
+ */
+export function extractAiderUsage(text) {
+  if (!text) return null;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(t); } catch { continue; }
+    const u = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!u || typeof u.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: u.prompt_tokens,
+      tokens_out: u.completion_tokens ?? 0,
+      cached_tokens: u.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  const m = text.match(/Tokens:\s*([\d.,]+k?)\s*sent,\s*([\d.,]+k?)\s*received(?:,\s*([\d.,]+k?)\s*cache\s*hit)?/i);
+  if (!m) return null;
+  const parse = (s) => {
+    const c = s.replaceAll(",", "");
+    return c.toLowerCase().endsWith("k")
+      ? Math.round(parseFloat(c.slice(0, -1)) * 1000)
+      : Number(c);
+  };
+  const sent = parse(m[1]);
+  const recv = parse(m[2]);
+  if (!Number.isFinite(sent) || !Number.isFinite(recv)) return null;
+  return { tokens_in: sent, tokens_out: recv, cached_tokens: m[3] ? parse(m[3]) : 0 };
+}
+
 export class AiderAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -32,6 +72,7 @@ export class AiderAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractAiderUsage(res.stdout) ?? extractAiderUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/claude-agent.js

@@ -68,8 +68,16 @@ function collectAssistantText(obj) {
 /**
  * Extract usage metrics from stream-json/json NDJSON output.
  * Looks for the "result" line which contains total_cost_usd,
- * usage.input_tokens/output_tokens, and modelUsage.
- * Returns an object with tokens_in, tokens_out, cost_usd, model or null if not found.
+ * usage.input_tokens/output_tokens, cache_read_input_tokens,
+ * cache_creation_input_tokens, and modelUsage.
+ *
+ * `cached_tokens` aggregates both cache_read_input_tokens (tokens served
+ * from Anthropic's automatic prompt cache) and cache_creation_input_tokens
+ * (tokens just written to the cache during this call). The sum represents
+ * the total volume of input that benefited from prompt-caching machinery.
+ *
+ * Returns an object with tokens_in, tokens_out, cached_tokens, cost_usd,
+ * model or null if not found.
  */
 function extractUsageFromStreamJson(raw) {
   const events = parseClaudeEvents(raw);
@@ -79,11 +87,14 @@ function extractUsageFromStreamJson(raw) {
 
     const tokens_in = obj.usage?.input_tokens ?? 0;
     const tokens_out = obj.usage?.output_tokens ?? 0;
+    const cache_read = obj.usage?.cache_read_input_tokens ?? 0;
+    const cache_creation = obj.usage?.cache_creation_input_tokens ?? 0;
+    const cached_tokens = cache_read + cache_creation;
     const cost_usd = obj.total_cost_usd ?? undefined;
     const modelUsage = obj.modelUsage;
     const model = modelUsage ? Object.keys(modelUsage)[0] || null : null;
 
-    return { tokens_in, tokens_out, cost_usd, model };
+    return { tokens_in, tokens_out, cached_tokens, cost_usd, model };
   }
   return null;
 }

package/src/agents/codex-agent.js

@@ -2,18 +2,55 @@ import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
 /**
- * Extract token usage from Codex CLI stdout.
- * Codex prints "tokens used\n<number>" at the end, where number may have comma separators.
- * Returns { tokens_out } with the total token count, or null if not found.
- * Since Codex doesn't split input/output, we assign the total to tokens_out
- * as a conservative estimate for cost calculation.
+ * Try to extract an OpenAI-style `usage` JSON block from codex stdout.
+ *
+ * OpenAI's Chat Completions API exposes prompt-cache hits via
+ * `usage.prompt_tokens_details.cached_tokens` (since Aug 2024). Codex
+ * CLI doesn't surface this in its default footer, but newer flags or a
+ * wrapper may emit a JSON `usage` line. We scan stdout line-by-line and
+ * accept the first parseable object that carries `prompt_tokens`.
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when absent.
+ */
+function extractJsonUsage(stdout) {
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+    const usage = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
+/**
+ * Extract token usage from Codex CLI stdout. Two shapes are supported:
+ *
+ *   1. OpenAI-style JSON `usage` block (preferred):
+ *      `{"usage":{"prompt_tokens":N,"completion_tokens":M,
+ *                 "prompt_tokens_details":{"cached_tokens":C}}}`
+ *      → `{tokens_in:N, tokens_out:M, cached_tokens:C}`.
+ *
+ *   2. Legacy "tokens used\n<number>" footer (codex's default total,
+ *      no cache visibility) → `{tokens_in:0, tokens_out, cached_tokens:0}`.
+ *
+ * Returns null when neither shape is found.
  */
 function extractCodexTokens(stdout) {
-  const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
+  if (!stdout) return null;
+  const json = extractJsonUsage(stdout);
+  if (json) return json;
+  const match = stdout.match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
   if (!match) return null;
   const total = Number(match[1].replaceAll(/,/g, ""));
   if (!Number.isFinite(total) || total <= 0) return null;
-  return { tokens_in: 0, tokens_out: total };
+  return { tokens_in: 0, tokens_out: total, cached_tokens: 0 };
 }
 
 export class CodexAgent extends BaseAgent {

package/src/agents/gemini-agent.js

@@ -1,6 +1,41 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract Gemini's `usageMetadata` from stdout, including
+ * `cachedContentTokenCount` (Gemini's context-caching API metric,
+ * https://ai.google.dev/api/caching).
+ *
+ * The gemini CLI emits `usageMetadata` as part of its JSON response
+ * shape (today: only `--output-format json`, used in reviewTask; in
+ * plain runTask mode no usage is surfaced). When absent, returns null
+ * so the caller leaves `cached_tokens` undefined (= unmeasured,
+ * distinct from a measured 0).
+ */
+export function extractGeminiUsage(text) {
+  if (!text) return null;
+  const candidates = [];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  candidates.push(text.trim());
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const meta = obj?.usageMetadata
+      ?? obj?.usage_metadata
+      ?? obj?.response?.usageMetadata;
+    if (!meta || typeof meta.promptTokenCount !== "number") continue;
+    return {
+      tokens_in: meta.promptTokenCount,
+      tokens_out: meta.candidatesTokenCount ?? 0,
+      cached_tokens: meta.cachedContentTokenCount ?? 0
+    };
+  }
+  return null;
+}
+
 export class GeminiAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -33,6 +68,7 @@ export class GeminiAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractGeminiUsage(res.stdout) ?? extractGeminiUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/agents/opencode-agent.js

@@ -1,6 +1,38 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract OpenAI-style `usage` from OpenCode stdout. With `--format json`
+ * (used in reviewTask) the CLI emits a JSON document; with LiteLLM-backed
+ * runs that document carries `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Accepts the whole payload, individual lines, or array elements with a
+ * nested `usage` object. Returns `{tokens_in, tokens_out, cached_tokens}`
+ * or null (= unmeasured).
+ */
+export function extractOpenCodeUsage(text) {
+  if (!text) return null;
+  const candidates = [text.trim()];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const usage = obj?.usage
+      ?? obj?.result?.usage
+      ?? (Array.isArray(obj) ? obj.find((e) => e?.usage)?.usage : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -34,6 +66,7 @@ export class OpenCodeAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractOpenCodeUsage(res.stdout) ?? extractOpenCodeUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

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

@@ -316,8 +316,19 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
       await savePlanToDisk(projectDir, loadedPlan);
       if (outcome && Number.isFinite(outcome.cost_usd)) {
         try {
-          const { setStoryCost } = await import("../../../../packages/hu-board/src/db.js");
+          const { setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
           setStoryCost(huId, outcome.cost_usd);
+          // Φ0-G (KJC-TSK-0525): cached/in tokens travel in the same
+          // outcome blob as cost. Write them together so the board
+          // can render the "🎯 N% cached" badge on the same render.
+          // Either may be null (older runs, no cache) — setter handles it.
+          if (Number.isFinite(outcome.cached_tokens) || Number.isFinite(outcome.tokens_in)) {
+            setStoryCachedTokens(
+              huId,
+              Number.isFinite(outcome.cached_tokens) ? outcome.cached_tokens : null,
+              Number.isFinite(outcome.tokens_in) ? outcome.tokens_in : null,
+            );
+          }
         } catch (err) {
           logger?.warn?.(`Cost write failed for ${huId}: ${err.message}`);
         }

package/src/orchestrator/flow-runner.js

@@ -263,15 +263,23 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
 
     // --- Telemetry: anonymous pipeline_complete event (non-blocking) ---
     try {
-      const { sendTelemetryEvent } = await import("../utils/telemetry.js");
+      const { sendTelemetryEvent, computeCachedPct } = await import("../utils/telemetry.js");
       const durationS = Math.round((Date.now() - ctx.startedAt) / 1000);
       const sessionStatus = ctx.session?.status || "unknown";
+      // Φ0-H (KJC-TSK-0526): aggregate cache-hit ratios per role so we
+      // can see on the fleet how much each provider's cache is buying.
+      let cachedPct = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+      try {
+        const budgetSummary = ctx.budgetTracker?.summary?.();
+        if (budgetSummary) cachedPct = computeCachedPct(budgetSummary);
+      } catch { /* non-blocking — telemetry must never break runs */ }
       sendTelemetryEvent("pipeline_complete", {
         mode: config.review_mode,
         agent: ctx.coderRole?.provider || config.coder,
         duration_s: durationS,
         success: sessionStatus === "approved",
-        taskType: ctx.session?.resolved_policies?.taskType || null
+        taskType: ctx.session?.resolved_policies?.taskType || null,
+        ...cachedPct
       }, config).catch(() => {});
     } catch { /* non-blocking */ }
   }

package/src/orchestrator/hu-sub-pipeline.js

@@ -105,6 +105,31 @@ function sumCostUsd(entries) {
   return Math.round(total * 1e6) / 1e6;
 }
 
+/**
+ * Sum an integer token-counter field across a slice of BudgetTracker
+ * entries (Φ0-G, KJC-TSK-0525). Same null-vs-0 semantics as sumCostUsd:
+ * returns null when nothing measurable was recorded so the board can
+ * distinguish "unmeasured" from "really zero".
+ *
+ * @param {Array<object>} entries
+ * @param {string} field — entry key to sum, e.g. "cached_tokens"
+ * @returns {number|null}
+ */
+function sumTokenField(entries, field) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  let total = 0;
+  let hasAny = false;
+  for (const e of entries) {
+    const n = Number(e?.[field]);
+    if (Number.isFinite(n) && n >= 0) {
+      total += n;
+      hasAny = true;
+    }
+  }
+  if (!hasAny) return null;
+  return Math.round(total);
+}
+
 /**
  * Build the per-HU outcome blob from whatever metadata the iteration
  * loop returned. Tolerant by design — most fields are optional and we
@@ -157,6 +182,11 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
     blockers,
     summary,
     cost_usd: sumCostUsd(huBudgetEntries),
+    // Φ0-G (KJC-TSK-0525): cached/input tokens drive the "🎯 N% cached"
+    // board badge. Null when nothing measurable was recorded so the UI
+    // can hide the chip on cold runs or providers without cache.
+    cached_tokens: sumTokenField(huBudgetEntries, 'cached_tokens'),
+    tokens_in: sumTokenField(huBudgetEntries, 'tokens_in'),
     finishedAt: new Date().toISOString(),
   };
 }

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/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/telemetry.js

@@ -26,6 +26,49 @@ export function buildTelemetryPayload(eventName, data = {}) {
   };
 }
 
+/**
+ * Φ0-H (KJC-TSK-0526): aggregate cache-hit ratio per role from the budget
+ * summary the orchestrator already builds. Returns `{ cached_pct_coder,
+ * cached_pct_reviewer, cached_pct_total }` with values rounded to one
+ * decimal, or `null` per slot when there is no measurable input (rather
+ * than `0`, so the backend can distinguish "no cache" from "no signal").
+ *
+ * Provider-agnostic by design: the BudgetTracker entries already
+ * normalise `cached_tokens` for Anthropic (`cache_read_input_tokens`),
+ * OpenAI / Codex (`prompt_tokens_details.cached_tokens`), Gemini
+ * (`cachedContentTokenCount`) and the LiteLLM-routed providers
+ * (aider, opencode), so this helper does not need to know which
+ * provider produced the run.
+ *
+ * @param {{ breakdown_by_role?: object, total_cached_tokens?: number } | null | undefined} summary
+ * @returns {{ cached_pct_coder: number|null, cached_pct_reviewer: number|null, cached_pct_total: number|null }}
+ */
+export function computeCachedPct(summary) {
+  const empty = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+  if (!summary || typeof summary !== "object") return empty;
+  const ratio = (cached, tokensIn) => {
+    const c = Number(cached);
+    const t = Number(tokensIn);
+    if (!Number.isFinite(c) || !Number.isFinite(t) || t <= 0 || c < 0) return null;
+    return Math.round((c / t) * 1000) / 10;
+  };
+  const byRole = summary.breakdown_by_role || {};
+  const coder = byRole.coder || null;
+  const reviewer = byRole.reviewer || null;
+  let totalCached = 0;
+  let totalIn = 0;
+  for (const role of Object.keys(byRole)) {
+    const r = byRole[role];
+    totalCached += Number(r?.cached_tokens || 0);
+    totalIn += Number(r?.tokens_in || 0);
+  }
+  return {
+    cached_pct_coder: coder ? ratio(coder.cached_tokens, coder.tokens_in) : null,
+    cached_pct_reviewer: reviewer ? ratio(reviewer.cached_tokens, reviewer.tokens_in) : null,
+    cached_pct_total: ratio(totalCached, totalIn)
+  };
+}
+
 /**
  * Send an anonymous telemetry event. Non-blocking, fire-and-forget.
  * Never throws, never blocks the pipeline.