@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/cost/track.mjs

@@ -6,6 +6,20 @@
 // Local-JSONL swap replaces the upstream `mcp__claude-flow__memory_store`
 // dependency. Pricing constants are kept in sync with REFERENCE.md.
 //
+// Dedup + main/subagent split, and the logic driving them, are mirrored
+// (not imported) from `src/scripts/_lib/cc_transcript.ts`: this file ships
+// to consumers as a plain `.mjs` run via bare `node` (see the `/cost:report`
+// command doc), and `tsx` — the only thing in this repo that can execute a
+// `.ts` module at runtime — is a devDependency, never shipped. A shared
+// `.ts` import here would work in this repo's own dev shell and break for
+// every consumer. On this repo's own transcripts, 50.3% of assistant/usage
+// records in a single active session file are replays (message.id +
+// requestId collide) — the resumed/compacted-session mechanic rewrites
+// prior turns back into the transcript — so an un-deduped sum overstates
+// real spend by roughly 2x, on top of never having counted subagent legs
+// (they live in a sibling `<sessionId>/subagents/agent-*.jsonl` tree the
+// old single-file read never visited).
+//
 // Env:
 //   TRACK_CWD=<path>          override which project's sessions to scan
 //   TRACK_SESSION=<file>      pin to a specific session jsonl
@@ -15,17 +29,20 @@
 //   TRACK_STORE=<path>        override (default: agents/cost-tracking/sessions.jsonl)
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 
 const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
 const DEFAULT_STORE = 'agents/cost-tracking/sessions.jsonl';
 
-// USD per 1M tokens.
+// USD per 1M tokens. cache_write_5m / cache_write_1h are Anthropic's two
+// cache-write TTL rates (1.25x / 2x of `input`) — a single flat rate here
+// previously priced every write at the 5m rate regardless of the TTL the
+// call actually used.
 const PRICING = {
-  haiku:  { input: 0.25,  output: 1.25,  cache_write: 0.30,  cache_read: 0.03 },
-  sonnet: { input: 3.00,  output: 15.00, cache_write: 3.75,  cache_read: 0.30 },
-  opus:   { input: 15.00, output: 75.00, cache_write: 18.75, cache_read: 1.50 },
+  haiku:  { input: 0.25,  output: 1.25,  cache_write_5m: 0.30,  cache_write_1h: 0.50,  cache_read: 0.03 },
+  sonnet: { input: 3.00,  output: 15.00, cache_write_5m: 3.75,  cache_write_1h: 6.00,  cache_read: 0.30 },
+  opus:   { input: 15.00, output: 75.00, cache_write_5m: 18.75, cache_write_1h: 30.00, cache_read: 1.50 },
 };
 
 function modelTier(model) {
@@ -37,16 +54,59 @@ function modelTier(model) {
   return 'unknown';
 }
 
+// A record's cache_creation_input_tokens is split into ephemeral_5m /
+// ephemeral_1h by `usage.cache_creation` (see usageTokens()). Any part of
+// cache_creation_input_tokens NOT covered by that split (older records that
+// predate the TTL breakdown) is priced at the 5m rate — Anthropic's default
+// TTL — rather than silently dropped.
 function costForUsage(tier, u) {
   const p = PRICING[tier];
   if (!p || !u) return 0;
+  const knownSplit = (u.ephemeral_5m_input_tokens || 0) + (u.ephemeral_1h_input_tokens || 0);
+  const unaccounted = Math.max(0, (u.cache_creation_input_tokens || 0) - knownSplit);
   return (u.input_tokens || 0) / 1e6 * p.input
        + (u.output_tokens || 0) / 1e6 * p.output
-       + (u.cache_creation_input_tokens || 0) / 1e6 * p.cache_write
+       + ((u.ephemeral_5m_input_tokens || 0) + unaccounted) / 1e6 * p.cache_write_5m
+       + (u.ephemeral_1h_input_tokens || 0) / 1e6 * p.cache_write_1h
        + (u.cache_read_input_tokens || 0) / 1e6 * p.cache_read;
 }
 
-function encodeProjectPath(cwd) { return cwd.replace(/\//g, '-'); }
+// Normalize a raw `message.usage` block into the flat shape costForUsage()
+// and the model-tally accumulator both consume, pulling the TTL split out
+// of the nested `cache_creation` object Anthropic ships it under.
+function usageTokens(raw) {
+  const cc = (raw && raw.cache_creation) || {};
+  return {
+    input_tokens: Number(raw?.input_tokens) || 0,
+    output_tokens: Number(raw?.output_tokens) || 0,
+    cache_creation_input_tokens: Number(raw?.cache_creation_input_tokens) || 0,
+    cache_read_input_tokens: Number(raw?.cache_read_input_tokens) || 0,
+    ephemeral_5m_input_tokens: Number(cc.ephemeral_5m_input_tokens) || 0,
+    ephemeral_1h_input_tokens: Number(cc.ephemeral_1h_input_tokens) || 0,
+  };
+}
+
+// Subagent iff a non-empty top-level agentId OR isSidechain === true —
+// both signals are checked because observed subagent transcripts carry
+// both, but a differently-shaped one could carry only one.
+function classifyBucket(rec) {
+  const hasAgentId = typeof rec.agentId === 'string' && rec.agentId.length > 0;
+  return (hasAgentId || rec.isSidechain === true) ? 'subagent' : 'main';
+}
+
+// message.id + requestId together identify one real API call; Claude Code
+// can replay the same turn into more than one transcript file (see the
+// header comment) and this is what collapses those replays back to one.
+function dedupKey(rec) {
+  const id = typeof rec.message?.id === 'string' ? rec.message.id : '';
+  const reqId = typeof rec.requestId === 'string' ? rec.requestId : '';
+  return `${id} ${reqId}`;
+}
+
+// Claude Code encodes BOTH separators and dots: `/x/.claude/y` → `-x--claude-y`.
+// Replacing only `/` never resolves a dotted path segment, so any cwd under
+// `.claude/worktrees/` silently missed its project dir and exited 2.
+function encodeProjectPath(cwd) { return cwd.replace(/[/.]/g, '-'); }
 
 function findProjectDir(cwd) {
   const c = join(PROJECTS_DIR, encodeProjectPath(cwd));
@@ -60,37 +120,101 @@ function findActiveSession(dir) {
   return e[0] ? join(dir, e[0].f) : null;
 }
 
-function summarizeSession(jsonlPath) {
-  const lines = readFileSync(jsonlPath, 'utf-8').split('\n').filter(Boolean);
+// Recursively list every *.jsonl under dir — how the sibling
+// <sessionId>/subagents/agent-*.jsonl tree gets visited without a second
+// code path.
+function walkJsonl(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = join(cur, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile() && entry.name.endsWith('.jsonl')) out.push(full);
+    }
+  }
+  return out;
+}
+
+// The active session's own file plus every transcript under its sibling
+// <sessionId>/ directory (subagent legs, and any nested sub-subagent legs).
+function collectSessionFiles(projectDir, sessionPath) {
+  const files = [sessionPath];
+  const sideDir = join(projectDir, basename(sessionPath, '.jsonl'));
+  if (existsSync(sideDir) && statSync(sideDir).isDirectory()) {
+    files.push(...walkJsonl(sideDir));
+  }
+  return files;
+}
+
+function emptyBucketSlot() {
+  return { messages: 0, input_tokens: 0, output_tokens: 0,
+    cache_creation_input_tokens: 0, cache_read_input_tokens: 0, cost_usd: 0 };
+}
+
+function summarizeSession(files) {
   const byModel = {};
   const byTier = { haiku: 0, sonnet: 0, opus: 0, unknown: 0 };
+  const byBucket = { main: emptyBucketSlot(), subagent: emptyBucketSlot() };
   let messageCount = 0, totalCost = 0, firstTs = null, lastTs = null;
   let sessionId = null, cwd = null;
-  for (const line of lines) {
-    let m; try { m = JSON.parse(line); } catch { continue; }
-    if (!sessionId && m.sessionId) sessionId = m.sessionId;
-    if (!cwd && m.cwd) cwd = m.cwd;
-    if (m.timestamp) {
-      if (!firstTs || m.timestamp < firstTs) firstTs = m.timestamp;
-      if (!lastTs || m.timestamp > lastTs) lastTs = m.timestamp;
+  let totalSeen = 0;
+  const seen = new Set();
+
+  for (const file of files) {
+    let text;
+    try { text = readFileSync(file, 'utf-8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let m; try { m = JSON.parse(line); } catch { continue; }
+      if (!sessionId && m.sessionId) sessionId = m.sessionId;
+      if (!cwd && m.cwd) cwd = m.cwd;
+      if (m.timestamp) {
+        if (!firstTs || m.timestamp < firstTs) firstTs = m.timestamp;
+        if (!lastTs || m.timestamp > lastTs) lastTs = m.timestamp;
+      }
+      if (m.type !== 'assistant' || !m.message?.usage) continue;
+
+      totalSeen++;
+      const key = dedupKey(m);
+      if (seen.has(key)) continue; // replay — see the header comment
+      seen.add(key);
+
+      const bucket = classifyBucket(m);
+      const model = m.message.model || 'unknown';
+      const tier = modelTier(model);
+      const u = usageTokens(m.message.usage);
+      const cost = costForUsage(tier, u);
+
+      const slot = byModel[model] || { tier, input_tokens: 0, output_tokens: 0,
+        cache_creation_input_tokens: 0, cache_read_input_tokens: 0, messages: 0, cost_usd: 0 };
+      slot.input_tokens += u.input_tokens;
+      slot.output_tokens += u.output_tokens;
+      slot.cache_creation_input_tokens += u.cache_creation_input_tokens;
+      slot.cache_read_input_tokens += u.cache_read_input_tokens;
+      slot.messages++; slot.cost_usd += cost;
+      byModel[model] = slot;
+
+      const bs = byBucket[bucket];
+      bs.input_tokens += u.input_tokens;
+      bs.output_tokens += u.output_tokens;
+      bs.cache_creation_input_tokens += u.cache_creation_input_tokens;
+      bs.cache_read_input_tokens += u.cache_read_input_tokens;
+      bs.messages++; bs.cost_usd += cost;
+
+      messageCount++; byTier[tier] += cost; totalCost += cost;
     }
-    if (m.type !== 'assistant' || !m.message?.usage) continue;
-    messageCount++;
-    const model = m.message.model || 'unknown';
-    const tier = modelTier(model);
-    const u = m.message.usage;
-    const cost = costForUsage(tier, u);
-    const slot = byModel[model] || { tier, input_tokens: 0, output_tokens: 0,
-      cache_creation_input_tokens: 0, cache_read_input_tokens: 0, messages: 0, cost_usd: 0 };
-    slot.input_tokens += u.input_tokens || 0;
-    slot.output_tokens += u.output_tokens || 0;
-    slot.cache_creation_input_tokens += u.cache_creation_input_tokens || 0;
-    slot.cache_read_input_tokens += u.cache_read_input_tokens || 0;
-    slot.messages++; slot.cost_usd += cost;
-    byModel[model] = slot; byTier[tier] += cost; totalCost += cost;
   }
+
+  const dedupedCount = messageCount;
+  const dedup_ratio = totalSeen > 0 ? (totalSeen - dedupedCount) / totalSeen : 0;
   return { sessionId, cwd, startedAt: firstTs, endedAt: lastTs, messageCount,
-    byModel, byTier, total_cost_usd: totalCost, capturedAt: new Date().toISOString() };
+    byModel, byTier, byBucket, total_cost_usd: totalCost,
+    totalRecordsSeen: totalSeen, dedupedRecordsCount: dedupedCount, dedup_ratio,
+    capturedAt: new Date().toISOString() };
 }
 
 function persistJsonl(summary, store) {
@@ -111,7 +235,8 @@ function main() {
   if (!sessionPath || !existsSync(sessionPath)) {
     console.error(`cost-track: no session jsonl in ${projectDir}`); process.exit(2);
   }
-  const summary = summarizeSession(sessionPath);
+  const files = collectSessionFiles(projectDir, sessionPath);
+  const summary = summarizeSession(files);
   if (process.env.TRACK_OUT) writeFileSync(process.env.TRACK_OUT, JSON.stringify(summary, null, 2));
   const store = process.env.TRACK_STORE || DEFAULT_STORE;
   let res = { ok: false, reason: 'dry-run' };
@@ -125,7 +250,9 @@ function main() {
   console.log(`| Project | \`${summary.cwd}\` |`);
   console.log(`| First message | ${summary.startedAt} |`);
   console.log(`| Last message | ${summary.endedAt} |`);
-  console.log(`| Assistant messages | ${summary.messageCount} |`);
+  console.log(`| Assistant messages (deduped) | ${summary.messageCount} |`);
+  console.log(`| Replay dedup ratio | ${(summary.dedup_ratio * 100).toFixed(1)}% (${summary.dedupedRecordsCount}/${summary.totalRecordsSeen} records kept) |`);
+  console.log(`| Transcript files scanned | ${files.length} |`);
   console.log(`| **Total cost** | **$${summary.total_cost_usd.toFixed(6)}** |`);
   console.log(`| Persisted | ${res.ok ? `\`${res.path}\`` : `**FAILED** (${res.reason})`} |`);
   console.log('\n## Per-model breakdown\n');
@@ -139,6 +266,14 @@ function main() {
   for (const [t, c] of Object.entries(summary.byTier).sort((a, b) => b[1] - a[1])) {
     if (c > 0) console.log(`| ${t} | $${c.toFixed(6)} |`);
   }
+  console.log('\n## Agent-bucket breakdown\n');
+  console.log('_main = the orchestrator session; subagent = Task-tool legs, previously uncounted or merged in._\n');
+  console.log('| Bucket | Messages | Input | Output | Cache write | Cache read | Cost |');
+  console.log('|---|---:|---:|---:|---:|---:|---:|');
+  for (const bucket of ['main', 'subagent']) {
+    const b = summary.byBucket[bucket];
+    console.log(`| ${bucket} | ${b.messages} | ${b.input_tokens} | ${b.output_tokens} | ${b.cache_creation_input_tokens} | ${b.cache_read_input_tokens} | $${b.cost_usd.toFixed(6)} |`);
+  }
 }
 
 main();

package/src/scripts/cost_summary.ts

@@ -64,6 +64,11 @@ interface KvBucket {
     total_cost_usd: number;
     input_tokens: number;
     output_tokens: number;
+    // Additive (cost-summary/v1 stays additive-only per the schema doc):
+    // absent-on-row reads as 0 via `_int`, so rows written before this
+    // extension aggregate identically to explicit zeros.
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
     telegraph_delta_tokens: number;
 }
 
@@ -73,6 +78,8 @@ function _zero_kv(): KvBucket {
         total_cost_usd: 0.0,
         input_tokens: 0,
         output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
         telegraph_delta_tokens: 0,
     };
 }
@@ -83,10 +90,21 @@ interface ModelBucket {
     total_cost_usd: number;
     input_tokens: number;
     output_tokens: number;
+    // Unlike telegraph fields, cache accounting IS model-scoped (the prompt
+    // cache itself is model-scoped — see pricing.ts), so by_model carries it.
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
 }
 
 function _zero_model(): ModelBucket {
-    return { sessions: 0, total_cost_usd: 0.0, input_tokens: 0, output_tokens: 0 };
+    return {
+        sessions: 0,
+        total_cost_usd: 0.0,
+        input_tokens: 0,
+        output_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+    };
 }
 
 /** Aggregate rows into the cost-summary structure (PyFloat-aware output). */
@@ -104,6 +122,8 @@ export function aggregate(rows: Row[]): Json {
         const cost = _float(row['total_cost_usd']);
         const itok = _int(row['input_tokens']);
         const otok = _int(row['output_tokens']);
+        const cread = _int(row['cache_read_input_tokens']);
+        const cwrite = _int(row['cache_creation_input_tokens']);
         const delta = _delta(row);
 
         const sessBucket = _getOr(by_sess, sid, _zero_kv);
@@ -113,6 +133,8 @@ export function aggregate(rows: Row[]): Json {
             bucket.total_cost_usd += cost;
             bucket.input_tokens += itok;
             bucket.output_tokens += otok;
+            bucket.cache_read_input_tokens += cread;
+            bucket.cache_creation_input_tokens += cwrite;
             bucket.telegraph_delta_tokens += delta;
         }
         const m = _getOr(by_model, model, _zero_model);
@@ -120,6 +142,8 @@ export function aggregate(rows: Row[]): Json {
         m.total_cost_usd += cost;
         m.input_tokens += itok;
         m.output_tokens += otok;
+        m.cache_read_input_tokens += cread;
+        m.cache_creation_input_tokens += cwrite;
     }
 
     return {
@@ -130,6 +154,8 @@ export function aggregate(rows: Row[]): Json {
             total_cost_usd: new PyFloat(totals.total_cost_usd),
             input_tokens: totals.input_tokens,
             output_tokens: totals.output_tokens,
+            cache_read_input_tokens: totals.cache_read_input_tokens,
+            cache_creation_input_tokens: totals.cache_creation_input_tokens,
             telegraph_delta_tokens: totals.telegraph_delta_tokens,
             telegraph_multiplier_version: MULTIPLIER_VERSION,
             telegraph_multiplier_active: MULTIPLIER_ACTIVE,
@@ -140,6 +166,8 @@ export function aggregate(rows: Row[]): Json {
             total_cost_usd: new PyFloat(v.total_cost_usd),
             input_tokens: v.input_tokens,
             output_tokens: v.output_tokens,
+            cache_read_input_tokens: v.cache_read_input_tokens,
+            cache_creation_input_tokens: v.cache_creation_input_tokens,
             telegraph_delta_tokens: v.telegraph_delta_tokens,
         })),
         by_conversation: _sortedEntries(by_conv).map(([k, v]) => ({
@@ -148,6 +176,8 @@ export function aggregate(rows: Row[]): Json {
             total_cost_usd: new PyFloat(v.total_cost_usd),
             input_tokens: v.input_tokens,
             output_tokens: v.output_tokens,
+            cache_read_input_tokens: v.cache_read_input_tokens,
+            cache_creation_input_tokens: v.cache_creation_input_tokens,
             telegraph_delta_tokens: v.telegraph_delta_tokens,
         })),
         by_model: _sortedEntries(by_model).map(([k, v]) => ({
@@ -156,6 +186,8 @@ export function aggregate(rows: Row[]): Json {
             total_cost_usd: new PyFloat(v.total_cost_usd),
             input_tokens: v.input_tokens,
             output_tokens: v.output_tokens,
+            cache_read_input_tokens: v.cache_read_input_tokens,
+            cache_creation_input_tokens: v.cache_creation_input_tokens,
         })),
     };
 }

package/src/scripts/council_cli.ts

@@ -69,7 +69,7 @@ import {
     resolve_config_path,
 } from './ai_council/config.js';
 import { AuthCache, select_solo_member } from './ai_council/solo_dispatch.js';
-import { InvalidModeError, resolve_mode } from './ai_council/modes.js';
+import { InvalidModeError, resolve_global_mode, resolve_mode } from './ai_council/modes.js';
 import { appendEvent } from './ai_council/events_log.js';
 import {
     type ClassificationResult,
@@ -444,6 +444,12 @@ function _synthesize_ai_council_block(cfg: CouncilConfig): Dict {
         if (m.model_ladder && m.model_ladder.length > 0) {
             entry['model_ladder'] = [...m.model_ladder];
         }
+        // road-to-cache-economy Phase 4: forward only an explicit override —
+        // the '5m' default needs no key, keeping the synthesized block
+        // byte-identical to pre-Phase-4 output when nobody opted in.
+        if (m.prompt_cache_ttl !== '5m') {
+            entry['prompt_cache_ttl'] = m.prompt_cache_ttl;
+        }
         members[name] = entry;
     }
     const advisors: Dict = {};
@@ -483,6 +489,7 @@ function _synthesize_ai_council_block(cfg: CouncilConfig): Dict {
             max_output_tokens: cfg.cost_budget.max_output_tokens,
             max_calls: cfg.cost_budget.max_calls,
             max_total_usd: cfg.cost_budget.max_total_usd,
+            daily_limit_usd: cfg.cost_budget.daily_limit_usd,
         },
         consensus_scoring: {
             enabled: cfg.consensus_scoring.enabled,
@@ -557,7 +564,11 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
         );
     }
     const members_cfg = (ai['members'] as Dict) || {};
-    const global_mode = ai['mode'] as string | null | undefined;
+    // Accepts BOTH the synthesized flat `mode` and the raw `defaults.mode`
+    // shape — see modes.ts::resolve_global_mode. Reading only the flat key
+    // dropped the configured default for every caller that hands this
+    // exported function a raw `.ai-council.yml` dict.
+    const global_mode = resolve_global_mode(ai);
     const cli_budget_cfg = _isDict(ai) ? ((ai['cli_call_budget'] as Dict) || {}) : {};
     const cli_caps = _isDict(cli_budget_cfg)
         ? ((cli_budget_cfg['max_calls_per_day'] as Dict) || {})
@@ -617,9 +628,16 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             // Council opts in explicitly (caching is client-default OFF): on
             // unless the operator sets `prompt_cache: false` on the member.
             const enable_prompt_cache = cfg['prompt_cache'] !== false;
+            // road-to-cache-economy Phase 4: absent → AnthropicClient's own
+            // '5m' default; only an explicit '1h' override reaches here.
+            const prompt_cache_ttl = (cfg['prompt_cache_ttl'] as '5m' | '1h' | undefined) ?? undefined;
             for (const sib_model of siblings[name] as string[]) {
                 members.push(
-                    _construct_api_member(name, sib_model, { api_key_ref, enable_prompt_cache }),
+                    _construct_api_member(name, sib_model, {
+                        api_key_ref,
+                        enable_prompt_cache,
+                        prompt_cache_ttl,
+                    }),
                 );
             }
             continue;
@@ -632,6 +650,8 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
                     // Council opts in explicitly (client-default OFF); on unless
                     // the operator sets `prompt_cache: false`.
                     enable_prompt_cache: cfg['prompt_cache'] !== false,
+                    // road-to-cache-economy Phase 4 — see the siblings branch above.
+                    prompt_cache_ttl: (cfg['prompt_cache_ttl'] as '5m' | '1h' | undefined) ?? undefined,
                 }),
             );
         } else if (mode === 'cli' && _CLI_PROVIDERS.has(name)) {
@@ -766,7 +786,11 @@ function _format_advisor_summary(
 function _construct_api_member(
     name: string,
     model: string | null,
-    opts: { api_key_ref?: string | null; enable_prompt_cache?: boolean | undefined } = {},
+    opts: {
+        api_key_ref?: string | null;
+        enable_prompt_cache?: boolean | undefined;
+        prompt_cache_ttl?: '5m' | '1h' | undefined;
+    } = {},
 ): ExternalAIClient {
     const api_key_ref = opts.api_key_ref ?? null;
     if (name === 'anthropic') {
@@ -777,6 +801,7 @@ function _construct_api_member(
             model: model || 'claude-sonnet-4-5',
             api_key,
             enable_prompt_cache: opts.enable_prompt_cache,
+            prompt_cache_ttl: opts.prompt_cache_ttl,
         });
     }
     if (name === 'openai') {
@@ -2020,6 +2045,11 @@ function cmd_run(
         max_output_tokens: _pyInt(cost_cfg['max_output_tokens'] ?? 20_000, 20_000),
         max_calls: _pyInt(cost_cfg['max_calls'] ?? 10, 10),
         max_total_usd: _pyFloat(cost_cfg['max_total_usd'] ?? 0.0, 0.0) || 0.0,
+        // Rolling 24h cap. Unwired until now: the field existed on CostBudget and
+        // gated the spend-ledger append, but no caller ever passed it, so the
+        // ledger could not be written at all — an archived acceptance criterion
+        // claimed otherwise. 0 keeps the cap disabled, which stays the default.
+        daily_limit_usd: _pyFloat(cost_cfg['daily_limit_usd'] ?? 0.0, 0.0) || 0.0,
     });
     const rounds = _resolve_rounds(args, ai_cfg);
     // Phase 1: stance tally — defensive read; malformed/absent block reads as off.
@@ -2184,6 +2214,11 @@ function _write_debate_round(
         table: PriceTable;
         prompt_mode: string | null;
         prose_synthesis: boolean | null;
+        // road-to-cache-economy Phase 4: the observed wall-clock gap (ms)
+        // between the previous round finishing and this round starting —
+        // `null`/absent on round 1, since nothing was written to the
+        // prompt cache yet. See `run_debate`'s `on_round_complete`.
+        cache_gap_ms_since_previous_round?: number | null | undefined;
     },
 ): string {
     fs.mkdirSync(_resolveTarget(out_dir), { recursive: true });
@@ -2207,6 +2242,7 @@ function _write_debate_round(
         debate_total_rounds: opts.total_planned_rounds,
         rounds: 1,
         cost_usd_actual: _pyRound(actual_total, 6),
+        prompt_cache_round_gap_ms: opts.cache_gap_ms_since_previous_round ?? null,
         responses: _serialise_responses(responses),
     };
     const out_path = path.join(_resolveTarget(out_dir), _debate_round_filename(round_number));
@@ -2410,6 +2446,11 @@ function cmd_debate(
         max_output_tokens: _pyInt(cost_cfg['max_output_tokens'] ?? 20_000, 20_000),
         max_calls: _pyInt(cost_cfg['max_calls'] ?? 10, 10),
         max_total_usd: _pyFloat(cost_cfg['max_total_usd'] ?? 0.0, 0.0) || 0.0,
+        // Rolling 24h cap. Unwired until now: the field existed on CostBudget and
+        // gated the spend-ledger append, but no caller ever passed it, so the
+        // ledger could not be written at all — an archived acceptance criterion
+        // claimed otherwise. 0 keeps the cap disabled, which stays the default.
+        daily_limit_usd: _pyFloat(cost_cfg['daily_limit_usd'] ?? 0.0, 0.0) || 0.0,
     });
 
     const out_dir = _validate_council_output_path(args.output as string, {
@@ -2427,7 +2468,11 @@ function cmd_debate(
 
     const written: string[] = [];
 
-    const _on_round_complete = (round_number: number, results: CouncilResponse[]): void => {
+    const _on_round_complete = (
+        round_number: number,
+        results: CouncilResponse[],
+        cache_gap_ms_since_previous_round?: number | null,
+    ): void => {
         const p = _write_debate_round(out_dir, round_number, results, {
             question,
             members: members as ExternalAIClient[],
@@ -2437,6 +2482,7 @@ function cmd_debate(
             table: table as PriceTable,
             prompt_mode: 'debate',
             prose_synthesis: _getattr<boolean | null>(args, 'prose_synthesis', null),
+            cache_gap_ms_since_previous_round,
         });
         written.push(p);
         const errors = results.filter((r) => r.error);