@event4u/agent-config 9.31.0 → 9.33.0

package/src/scripts/ai_council/session.ts

@@ -189,6 +189,17 @@ function _serialise_response(r: CouncilResponse): Record<string, unknown> {
     const payload: Record<string, unknown> = {
         provider: r.provider,
         model: r.model,
+        // `model` stays the REQUESTED id — the tier decision was made against
+        // it. `model_served` is what the provider reported answering with, so a
+        // silent alias or substitution is visible instead of being recorded as
+        // the model that never ran. Attribution-only: no consumer routes on it.
+        //
+        // Additive on the MANIFEST's own response row, which is this artefact —
+        // NOT a `cost-summary/v1` field: that contract describes
+        // `agents/cost-tracking/sessions.jsonl`, a different file with a
+        // different producer. Absent on manifests written before this, and `''`
+        // for every transport that reports no served id.
+        model_served: r.model_served,
         input_tokens: r.input_tokens,
         output_tokens: r.output_tokens,
         latency_ms: r.latency_ms,

package/src/scripts/ask_transport.ts

@@ -48,10 +48,20 @@ import type { ExternalAIClient } from './ai_council/clients.js';
 import { buildOrchestrationLine } from './_lib/orchestration_record.js';
 import { DEFAULT_DIR } from './orchestration_record.js';
 
+/**
+ * Placeholder written into `AskResult.model` when the member reported no id.
+ * Named so the audit path can recognise and refuse it rather than passing a
+ * sentinel off as a real model id.
+ */
+export const UNKNOWN_MODEL = 'unknown';
+
 export interface AskResult {
     answer: string;
     member: string;
+    /** The REQUESTED model id — what the member was configured to call. */
     model: string;
+    /** The model the provider reported serving; `''` when it reports none. */
+    model_served: string;
     input_tokens: number;
     output_tokens: number;
     latency_ms: number;
@@ -94,6 +104,14 @@ function recordAskLine(auditDir: string, result: AskResult | null, member: strin
         dispatch_tokens: result === null ? null : result.input_tokens + result.output_tokens,
         wall_clock_ms: result === null ? 0 : Math.max(0, Math.round(result.latency_ms)),
         agent_combo: [member || 'none'],
+        // `AskResult.model` substitutes an `'unknown'` SENTINEL when the member
+        // reported no id (below). That sentinel must never reach the audit line
+        // as a model_requested: `modelDivergent` treats any non-empty string as
+        // a real id, so it would fabricate a `true` on a line whose entire
+        // purpose is making real substitutions credible. null keeps the
+        // three-valued semantics — and the field's own "id only" contract.
+        model_requested: result === null || result.model === UNKNOWN_MODEL ? null : result.model,
+        model_served: result === null ? null : result.model_served,
         origin: 'dispatch-economy-2026',
         ts,
         id,
@@ -145,7 +163,8 @@ export async function askOnce(prompt: string, opts: AskOptions = {}): Promise<As
             {
                 answer: text,
                 member: provider,
-                model: r.model ?? 'unknown',
+                model: r.model ?? UNKNOWN_MODEL,
+                model_served: r.model_served ?? '',
                 input_tokens: r.input_tokens ?? 0,
                 output_tokens: r.output_tokens ?? 0,
                 latency_ms: r.latency_ms ?? 0,

package/src/scripts/cache_realization_report.ts

@@ -88,6 +88,25 @@ export interface ColdStartStats {
     first_call_cache_read_share: number;
     /** Σ(first-call cache_creation_input_tokens) / Σ(all subagent cache_creation_input_tokens) — the C-1 metric. */
     cold_start_share_of_write_volume: number;
+    /**
+     * The write-share SIGNATURE across ALL subagent records (not just first
+     * calls): how the billable input splits between cache writes, cache reads,
+     * and uncached input.
+     *
+     * The three shares are over the same denominator and sum to 1 (up to
+     * float error) whenever any billable input exists, which is what makes it
+     * a signature rather than three unrelated ratios — a workload that is
+     * mostly `write` is paying the cache premium without collecting the read
+     * discount, and that is invisible in `cold_start_share_of_write_volume`,
+     * which only says how much of the writing happened on a first call.
+     *
+     * All three are 0 when there is no billable input at all. That is the
+     * empty-corpus reading, NOT "a perfectly uncached workload" — read it
+     * beside `legs`.
+     */
+    write_share_of_billable: number;
+    read_share_of_billable: number;
+    uncached_share_of_billable: number;
 }
 
 /**
@@ -132,12 +151,22 @@ export function computeColdStarts(records: readonly TranscriptRecord[]): ColdSta
     const sumFirstCallBillable = firstCalls.reduce((s, r) => s + billableInputTokens(r.usage), 0);
     const sumFirstCallWrite = firstCalls.reduce((s, r) => s + r.usage.cache_creation_input_tokens, 0);
 
+    // Signature over ALL subagent records — the shape of the workload, where
+    // the metrics above describe only its first calls.
+    const sumBillable = subagentRecords.reduce((s, r) => s + billableInputTokens(r.usage), 0);
+    const sumWrite = totalWriteVolume;
+    const sumRead = subagentRecords.reduce((s, r) => s + r.usage.cache_read_input_tokens, 0);
+    const sumUncached = subagentRecords.reduce((s, r) => s + r.usage.input_tokens, 0);
+
     return {
         legs: firstCalls.length,
         median_first_call_written_or_uncached: median(writtenOrUncached),
         mean_first_call_written_or_uncached: mean(writtenOrUncached),
         first_call_cache_read_share: sumFirstCallBillable > 0 ? sumFirstCallRead / sumFirstCallBillable : 0,
         cold_start_share_of_write_volume: totalWriteVolume > 0 ? sumFirstCallWrite / totalWriteVolume : 0,
+        write_share_of_billable: sumBillable > 0 ? sumWrite / sumBillable : 0,
+        read_share_of_billable: sumBillable > 0 ? sumRead / sumBillable : 0,
+        uncached_share_of_billable: sumBillable > 0 ? sumUncached / sumBillable : 0,
     };
 }
 
@@ -737,6 +766,15 @@ export function renderText(r: Report): string {
     );
     out.push(`  first_call_cache_read_share=${pct(cs.first_call_cache_read_share)}`);
     out.push(`  cold_start_share_of_subagent_write_volume=${pct(cs.cold_start_share_of_write_volume)}`);
+    // Write-share signature over ALL subagent records: the three shares sum to
+    // 100% and say where the billable input actually went. A write-heavy split
+    // is paying the cache premium without collecting the read discount — which
+    // the cold-start metrics above cannot show, since they only look at first
+    // calls. All-zero means no billable input at all; read it beside legs.
+    out.push(
+        `  write_share=${pct(cs.write_share_of_billable)} read_share=${pct(cs.read_share_of_billable)}` +
+            ` uncached_share=${pct(cs.uncached_share_of_billable)} (of billable input, all subagent records)`,
+    );
     out.push('');
 
     out.push(`Per-agent breakdown: ${r.by_agent.length} distinct subagent legs (--format json carries all; top 10 by weighted_input_units below)`);

package/src/scripts/check_release_highlights.ts

@@ -114,7 +114,13 @@ export function highlight_contradictions(
     return out;
 }
 
-function main(argv: readonly string[]): number {
+/**
+ * Exported so the advisory-vs-blocking decision is a fixture, not a claim.
+ * `stale_draft_labels` firing while the exit code stays 0 is the behaviour the
+ * cadence blocker adjudicates; pinning it here makes either branch of that
+ * decision a one-line diff with a test that notices.
+ */
+export function main(argv: readonly string[]): number {
     let version: string | null = null;
     let from: string | null = null;
     let to = 'HEAD';

package/src/scripts/check_secret_leak.test.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -45,3 +46,45 @@ describe('check_secret_leak — .secret-allow', () => {
         expect(readAllowFile(tmp)).toEqual([]);
     });
 });
+
+describe('check_secret_leak — R2 review-input packages are a derived copy', () => {
+    let tmp: string;
+
+    beforeEach(() => {
+        tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'secret-review-input-')));
+        execFileSync('git', ['init', '--quiet'], { cwd: tmp, stdio: 'ignore' });
+    });
+    afterEach(() => {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    });
+
+    function track(rel: string, body: string): void {
+        const abs = path.join(tmp, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, body);
+        execFileSync('git', ['add', '--', rel], { cwd: tmp, stdio: 'ignore' });
+    }
+
+    const FAKE_KEY = 'aws = AKIA1234567890ABCDEF\n';
+
+    it('skips a diff copied into a .review-input package', () => {
+        // The dispatcher copies the branch diff VERBATIM, so a fixture-legal
+        // fake key is laundered out of the tests/ carve-out into a tracked
+        // path. Scanning the copy adds no coverage and reds the gate.
+        track('agents/evidence/reviews/branch.review-input/diff.patch', FAKE_KEY);
+        expect(scanRepo(tmp, 'all')).toEqual([]);
+    });
+
+    it('still catches the same key at a normal path — the exclusion is narrow', () => {
+        track('src/scripts/thing.ts', FAKE_KEY);
+        const hits = scanRepo(tmp, 'all');
+        expect(hits).toHaveLength(1);
+        expect(hits[0]?.file).toBe('src/scripts/thing.ts');
+    });
+
+    it('does not exclude the findings artefact itself — only the input package', () => {
+        // `<slug>.findings.md` is authored prose, not a copied diff.
+        track('agents/evidence/reviews/branch.findings.md', FAKE_KEY);
+        expect(scanRepo(tmp, 'all')).toHaveLength(1);
+    });
+});

package/src/scripts/check_secret_leak.ts

@@ -52,6 +52,18 @@ const DEFAULT_EXCLUDE: readonly RegExp[] = [
     /(^|\/)\.claude(\/|$)/,
     /(^|\/)fixtures(\/|$)/,
     /(^|\/)tests(\/|$)/, // test + golden + parity data legitimately holds secret-shaped strings
+    // R2 review-input packages: a VERBATIM copy of the branch diff, written by
+    // `dispatch_r2_reviewer`. Every byte in it already exists in the branch and
+    // is scanned at its own path under its own exclusions, so scanning the copy
+    // adds no coverage — and it DEFEATS the two carve-outs above by
+    // construction: a secret-shaped string that is legal in a test fixture gets
+    // laundered into a scanned path the moment a completion review runs. That
+    // is not hypothetical; it red this gate on the PR that added this line.
+    // What the exclusion cannot lose: content present only in the copy and
+    // nowhere else in the branch. The package is machine-generated from
+    // `git diff` and cannot invent content, and `--verify-current` re-derives
+    // its hashes, so a hand-edit is detectable rather than silent.
+    /(^|\/)[^/]+\.review-input(\/|$)/,
     /(^|\/)__[a-z_]+__(\/|$)/, // snapshot dirs (e.g. __parity_snapshots__)
     /\.test\.[a-z]+$/,
     /\.spec\.[a-z]+$/,

package/src/scripts/conformance_scan.ts

@@ -174,6 +174,79 @@ export interface ScanReport {
   rate: RateRecord;
 }
 
+export type CheckId = Violation["check"];
+
+export const CHECK_IDS: readonly CheckId[] = [
+  "language-pin",
+  "git-authorization",
+  "vacuous-evidence",
+  "evidence-steering",
+];
+
+/**
+ * What each mechanised check actually detects, in the words a reader needs in
+ * order to decide whether a hit is a defect or a false read. `--why` prints
+ * this ALONGSIDE the hits rather than instead of them: a count with no
+ * definition is the shape that let a figure like "109 divergent pairs" travel
+ * through five reviews unchallenged.
+ */
+export const CHECK_MEANINGS: Record<CheckId, string> = {
+  "language-pin":
+    "An assistant turn whose user-visible prose is not in the language that " +
+    "turn's own pin named. Carries provenance (turns_since_prompt, " +
+    "compaction_since_prompt) so a pin that was ABSENT because compaction " +
+    "removed it stays distinguishable from one that was present and ignored.",
+  "git-authorization":
+    "A gated git operation performed in a session where no authorization for " +
+    "that operation was observed. Authorization is per-operation and never " +
+    "carries from one to the next.",
+  "vacuous-evidence":
+    "A CI poll read as settled without ever observing an in-flight run — the " +
+    "poll gap that reports a green settle over a window in which nothing was " +
+    "pending yet.",
+  "evidence-steering":
+    "A self-commissioned evaluation whose prompt pre-loaded its own verdict, " +
+    "or a second self-scoped evaluation of the same subject within one turn.",
+};
+
+/**
+ * `--why <id>` — trace one conformance id: what it detects, whether it fired in
+ * this window, and every hit with its session and detail.
+ *
+ * A check that did not fire prints as *did not fire*, never as silence. Zero is
+ * a real answer, and the difference between "clean" and "not measured" is the
+ * whole reason to print it.
+ */
+export function renderWhy(report: ScanReport, id: CheckId): string {
+  const hits = report.per_session.flatMap((s) => s.violations.filter((v) => v.check === id));
+  const lines: string[] = [
+    `conformance:why · ${id} · ${report.sessions} session(s) · ${report.store}`,
+    "",
+    "  What it detects:",
+    `    ${CHECK_MEANINGS[id]}`,
+    "",
+  ];
+  if (hits.length === 0) {
+    lines.push(`  Did NOT fire in this window (0 hits over ${report.sessions} session(s)).`);
+    lines.push("  A measured zero, not an unmeasured one — the check ran.");
+    return lines.join("\n");
+  }
+  lines.push(`  Fired ${hits.length} time(s):`);
+  for (const v of hits) {
+    lines.push(`    · ${v.session} @ ${v.at}`);
+    lines.push(`      ${v.detail}`);
+    const since = (v as { turns_since_prompt?: number }).turns_since_prompt;
+    const compacted = (v as { compaction_since_prompt?: boolean }).compaction_since_prompt;
+    if (since !== undefined || compacted !== undefined) {
+      lines.push(
+        `      provenance: turns_since_prompt=${since ?? "—"} · ` +
+          `compaction_since_prompt=${compacted ?? "—"}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
 type Entry = Record<string, unknown>;
 
 function _isObject(v: unknown): v is Record<string, unknown> {
@@ -641,6 +714,7 @@ export function main(argv?: string[]): number {
   let json = false;
   let out: string | null = null;
   let record: string | null = null;
+  let why: string | null = null;
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i];
     if (a === "--store" && args[i + 1] !== undefined) {
@@ -651,6 +725,8 @@ export function main(argv?: string[]): number {
       json = true;
     } else if (a === "--output" && args[i + 1] !== undefined) {
       out = args[++i] as string;
+    } else if (a === "--why" && args[i + 1] !== undefined) {
+      why = args[++i] as string;
     } else if (a === "--record") {
       // Opt-in, and a bare `--record` takes the default path rather than
       // swallowing the next flag as a filename.
@@ -660,6 +736,13 @@ export function main(argv?: string[]): number {
           : DEFAULT_RATE_SERIES;
     }
   }
+  if (why !== null && !CHECK_IDS.includes(why as CheckId)) {
+    process.stderr.write(
+      `conformance:why: unknown check id ${JSON.stringify(why)} — known ids: ` +
+        `${CHECK_IDS.join(", ")}\n`,
+    );
+    return 2;
+  }
   const resolved = store ?? defaultStore(process.cwd());
   if (!fs.existsSync(resolved)) {
     process.stderr.write(`conformance:behavior: no transcript store at ${resolved}\n`);
@@ -675,6 +758,28 @@ export function main(argv?: string[]): number {
   // fs.writeSync, not process.stdout.write: `process.exit()` below does not
   // flush an async pipe write, so `--json | jq` reproducibly received a
   // truncated 64 KB document with no error (measured: 85,169 vs 65,536 bytes).
+  if (why !== null) {
+    const id = why as CheckId;
+    fs.writeSync(
+      1,
+      json
+        ? `${JSON.stringify(
+            {
+              check: id,
+              meaning: CHECK_MEANINGS[id],
+              store: report.store,
+              sessions: report.sessions,
+              hits: report.per_session.flatMap((s) =>
+                s.violations.filter((v) => v.check === id),
+              ),
+            },
+            null,
+            2,
+          )}\n`
+        : `${renderWhy(report, id)}\n`,
+    );
+    return 0;
+  }
   fs.writeSync(1, json ? `${JSON.stringify(report, null, 2)}\n` : `${render(report)}\n`);
   return 0;
 }

package/src/scripts/cost/track.mjs

@@ -59,6 +59,19 @@ function modelTier(model) {
 // 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.
+// A tier with no PRICING row prices at zero. That zero is indistinguishable
+// from a genuinely free message, so the ROW carries `rate_missing` and the run
+// warns once on stderr — the alternative (throwing) would lose a whole session
+// of real token counts over one unrecognised model id. Token counts are kept
+// untouched precisely so a later re-pricing pass can backfill the cost.
+// Every token class that costs money. A record where this is 0 costs 0 at any
+// rate, so a missing rate cannot understate it.
+function billableTokens(u) {
+  if (!u) return 0;
+  return (u.input_tokens || 0) + (u.output_tokens || 0)
+       + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0);
+}
+
 function costForUsage(tier, u) {
   const p = PRICING[tier];
   if (!p || !u) return 0;
@@ -163,6 +176,8 @@ function summarizeSession(files) {
   let sessionId = null, cwd = null;
   let totalSeen = 0;
   const seen = new Set();
+  // Model ids that priced at zero because no PRICING tier claimed them.
+  const rateMissingModels = new Set();
 
   for (const file of files) {
     let text;
@@ -188,6 +203,15 @@ function summarizeSession(files) {
       const tier = modelTier(model);
       const u = usageTokens(m.message.usage);
       const cost = costForUsage(tier, u);
+      // Key on the ACTUAL zero condition — `!PRICING[tier]`, what
+      // costForUsage returns 0 on — not on `tier === 'unknown'`. The two
+      // coincide only because `unknown` is today the sole tier modelTier()
+      // returns that PRICING lacks; adding a vendor family without a rate row
+      // would otherwise restore the exact silent zero this flag removes.
+      // The usage guard keeps the flag worth reading: a message with no
+      // billable tokens costs nothing at any rate, so flagging it would claim
+      // an understatement that is not there.
+      if (!PRICING[tier] && billableTokens(u) > 0) rateMissingModels.add(model);
 
       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 };
@@ -213,6 +237,12 @@ function summarizeSession(files) {
   const dedup_ratio = totalSeen > 0 ? (totalSeen - dedupedCount) / totalSeen : 0;
   return { sessionId, cwd, startedAt: firstTs, endedAt: lastTs, messageCount,
     byModel, byTier, byBucket, total_cost_usd: totalCost,
+    // `rate_missing` marks a row whose total_cost_usd is understated because
+    // at least one model priced at zero for want of a rate — never because the
+    // work was free. `rate_missing_models` carries the ids so a backfill has a
+    // shape to work against instead of re-deriving it from the transcript.
+    rate_missing: rateMissingModels.size > 0,
+    rate_missing_models: [...rateMissingModels].sort(),
     totalRecordsSeen: totalSeen, dedupedRecordsCount: dedupedCount, dedup_ratio,
     capturedAt: new Date().toISOString() };
 }
@@ -237,6 +267,15 @@ function main() {
   }
   const files = collectSessionFiles(projectDir, sessionPath);
   const summary = summarizeSession(files);
+  // ONE warning per run, before the quiet return: a suppressed report is a
+  // display choice, an understated cost figure is a data-integrity problem.
+  if (summary.rate_missing) {
+    console.error(
+      `cost-track: rate_missing — no price tier for ${summary.rate_missing_models.join(', ')}; ` +
+        `those messages priced at $0 and the session total is understated. ` +
+        `Token counts are kept, so the row can be re-priced later.`,
+    );
+  }
   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' };

package/src/scripts/cost_summary.ts

@@ -18,6 +18,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { CACHE_READ_MULTIPLIER, CACHE_WRITE_MULTIPLIER_5M } from './ai_council/pricing.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/cost_summary.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
@@ -70,6 +72,13 @@ interface KvBucket {
     cache_read_input_tokens: number;
     cache_creation_input_tokens: number;
     telegraph_delta_tokens: number;
+    // Source rows whose `total_cost_usd` is a FLOOR, not a figure: at least
+    // one message priced at $0 for want of a rate (`cost/track.mjs`
+    // `rate_missing`). Carried into every grouping because the understatement
+    // travels with the row — a summary that aggregates past it reports the
+    // silent zero one layer up, which is the defect the row-level flag exists
+    // to remove.
+    rate_missing_sessions: number;
 }
 
 function _zero_kv(): KvBucket {
@@ -81,6 +90,7 @@ function _zero_kv(): KvBucket {
         cache_read_input_tokens: 0,
         cache_creation_input_tokens: 0,
         telegraph_delta_tokens: 0,
+        rate_missing_sessions: 0,
     };
 }
 
@@ -94,6 +104,7 @@ interface ModelBucket {
     // cache itself is model-scoped — see pricing.ts), so by_model carries it.
     cache_read_input_tokens: number;
     cache_creation_input_tokens: number;
+    rate_missing_sessions: number;
 }
 
 function _zero_model(): ModelBucket {
@@ -104,15 +115,58 @@ function _zero_model(): ModelBucket {
         output_tokens: 0,
         cache_read_input_tokens: 0,
         cache_creation_input_tokens: 0,
+        rate_missing_sessions: 0,
     };
 }
 
+/**
+ * What the prompt cache bought, in INPUT-TOKEN EQUIVALENTS — not dollars.
+ *
+ * A cached read bills at `CACHE_READ_MULTIPLIER` of the input rate, so each
+ * read token saved `1 - multiplier` of one. A cache write bills at a premium,
+ * so each written token cost an extra `multiplier - 1`. Netting the two is the
+ * only honest single number here.
+ *
+ * Deliberately NOT priced in USD: the summary aggregates across models with
+ * different input rates, and `totals` carries no per-model token split to
+ * apply them to — a dollar figure would have to pick one rate and would be
+ * wrong for every other model in the row.
+ *
+ * The write premium uses the 5-minute multiplier. Rows carry no TTL split, and
+ * 5m is both Anthropic's default and the assumption `cost/track.mjs` already
+ * makes for unaccounted writes — so the two cost paths stay consistent rather
+ * than disagreeing quietly. A 1h-heavy workload therefore reads as slightly
+ * OPTIMISTIC, which is stated in the contract.
+ */
+function _cacheSavings(readTokens: number, writeTokens: number): number {
+    const saved = readTokens * (1 - CACHE_READ_MULTIPLIER);
+    const premium = writeTokens * (CACHE_WRITE_MULTIPLIER_5M - 1);
+    return Math.round(saved - premium);
+}
+
+/** UTC calendar date (`YYYY-MM-DD`) of a row, or `'unknown'`. */
+function _rowDate(row: Row): string {
+    // `startedAt` is the row's own first-message timestamp (track.mjs); the
+    // snake_case spelling is accepted for the same reason `session_id` is.
+    const raw = row['startedAt'] ?? row['started_at'];
+    if (typeof raw !== 'string' || !raw) {
+        return 'unknown';
+    }
+    const parsed = new Date(raw);
+    if (Number.isNaN(parsed.getTime())) {
+        return 'unknown';
+    }
+    return parsed.toISOString().slice(0, 10);
+}
+
 /** Aggregate rows into the cost-summary structure (PyFloat-aware output). */
 export function aggregate(rows: Row[]): Json {
     // Insertion-ordered maps to mirror Python's dict ordering + sorted().
     const by_sess = new Map<string, KvBucket>();
     const by_conv = new Map<string, KvBucket>();
     const by_model = new Map<string, ModelBucket>();
+    const by_date = new Map<string, KvBucket>();
+    const rate_missing_models = new Set<string>();
     const totals = _zero_kv();
 
     for (const row of rows) {
@@ -125,10 +179,17 @@ export function aggregate(rows: Row[]): Json {
         const cread = _int(row['cache_read_input_tokens']);
         const cwrite = _int(row['cache_creation_input_tokens']);
         const delta = _delta(row);
+        // A row is understated when its producer says so. `_pyTruthy` keeps the
+        // absent-reading identical to every other additive field: no flag → 0.
+        const rateMissing = _pyTruthy(row['rate_missing']) ? 1 : 0;
+        for (const id of _strList(row['rate_missing_models'])) {
+            rate_missing_models.add(id);
+        }
 
         const sessBucket = _getOr(by_sess, sid, _zero_kv);
         const convBucket = _getOr(by_conv, cid, _zero_kv);
-        for (const bucket of [sessBucket, convBucket, totals]) {
+        const dateBucket = _getOr(by_date, _rowDate(row), _zero_kv);
+        for (const bucket of [sessBucket, convBucket, dateBucket, totals]) {
             bucket.sessions += 1;
             bucket.total_cost_usd += cost;
             bucket.input_tokens += itok;
@@ -136,6 +197,7 @@ export function aggregate(rows: Row[]): Json {
             bucket.cache_read_input_tokens += cread;
             bucket.cache_creation_input_tokens += cwrite;
             bucket.telegraph_delta_tokens += delta;
+            bucket.rate_missing_sessions += rateMissing;
         }
         const m = _getOr(by_model, model, _zero_model);
         m.sessions += 1;
@@ -144,6 +206,7 @@ export function aggregate(rows: Row[]): Json {
         m.output_tokens += otok;
         m.cache_read_input_tokens += cread;
         m.cache_creation_input_tokens += cwrite;
+        m.rate_missing_sessions += rateMissing;
     }
 
     return {
@@ -159,6 +222,15 @@ export function aggregate(rows: Row[]): Json {
             telegraph_delta_tokens: totals.telegraph_delta_tokens,
             telegraph_multiplier_version: MULTIPLIER_VERSION,
             telegraph_multiplier_active: MULTIPLIER_ACTIVE,
+            // Additive per the schema's own rule; token-equivalents, not USD.
+            cache_savings_input_token_equivalents: _cacheSavings(
+                totals.cache_read_input_tokens,
+                totals.cache_creation_input_tokens,
+            ),
+            // The understated-cost qualification, surfaced instead of
+            // aggregated past: a non-zero count means total_cost_usd is a floor.
+            rate_missing_sessions: totals.rate_missing_sessions,
+            rate_missing_models: [...rate_missing_models].sort(),
         },
         by_session: _sortedEntries(by_sess).map(([k, v]) => ({
             key: k,
@@ -169,6 +241,7 @@ export function aggregate(rows: Row[]): Json {
             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,
+            rate_missing_sessions: v.rate_missing_sessions,
         })),
         by_conversation: _sortedEntries(by_conv).map(([k, v]) => ({
             key: k,
@@ -179,6 +252,22 @@ export function aggregate(rows: Row[]): Json {
             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,
+            rate_missing_sessions: v.rate_missing_sessions,
+        })),
+        // Ordered by date ascending — `_sortedEntries` is codepoint order, and
+        // ISO `YYYY-MM-DD` sorts chronologically under it. `'unknown'` sorts
+        // last (`u` > any digit), so a row with no timestamp never displaces a
+        // real day.
+        by_date: _sortedEntries(by_date).map(([k, v]) => ({
+            key: k,
+            sessions: v.sessions,
+            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,
+            rate_missing_sessions: v.rate_missing_sessions,
         })),
         by_model: _sortedEntries(by_model).map(([k, v]) => ({
             model: k,
@@ -188,6 +277,7 @@ export function aggregate(rows: Row[]): Json {
             output_tokens: v.output_tokens,
             cache_read_input_tokens: v.cache_read_input_tokens,
             cache_creation_input_tokens: v.cache_creation_input_tokens,
+            rate_missing_sessions: v.rate_missing_sessions,
         })),
     };
 }
@@ -219,6 +309,19 @@ function _str(value: unknown): string {
     return String(value);
 }
 
+/**
+ * Read a list-of-strings field defensively — absent, wrong-typed, or holding
+ * non-string members all read as "nothing to add" rather than throwing or
+ * coercing. A summary must never fail on a malformed source row; it skips it,
+ * exactly as `_load` skips an unparseable line.
+ */
+function _strList(value: unknown): string[] {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((v): v is string => typeof v === 'string' && v.length > 0);
+}
+
 /** Mirror `int(row.get(k) or 0)` — falsy → 0; numeric/string → truncated int. */
 function _int(value: unknown): number {
     if (!_pyTruthy(value)) {