@event4u/agent-config 9.32.0 → 9.34.0

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/build_discovery_manifest.ts

@@ -38,6 +38,7 @@
  *
  * Schema: docs/contracts/discovery-manifest.schema.json
  */
+import * as child_process from 'node:child_process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -83,6 +84,7 @@ interface ModuleConfig {
     DEFAULT_DEPRECATION_REPORT: string;
     DEFAULT_TRUST_REPORT: string;
     DEFAULT_ORPHAN_REPORT: string;
+    DEFAULT_DORMANCY_REPORT: string;
     DEFAULT_WORKSPACES_JSON: string;
     DEFAULT_PACKS_JSON: string;
     // Patchable seams (Python monkeypatches these module attributes).
@@ -101,6 +103,7 @@ function _deriveConfig(root: string): ModuleConfig {
         DEFAULT_DEPRECATION_REPORT: path.join(disc, 'deprecation-report.md'),
         DEFAULT_TRUST_REPORT: path.join(disc, 'trust-report.md'),
         DEFAULT_ORPHAN_REPORT: path.join(disc, 'orphan-report.md'),
+        DEFAULT_DORMANCY_REPORT: path.join(disc, 'dormancy-report.md'),
         DEFAULT_WORKSPACES_JSON: path.join(disc, 'workspaces.json'),
         DEFAULT_PACKS_JSON: path.join(disc, 'packs.json'),
         artefact_roots: _artefact_roots,
@@ -937,6 +940,156 @@ function _deprecation_report(manifest: JsonObject): string {
     return lines.join('\n') + '\n';
 }
 
+/** Dormancy window, in months. `docs/governance.md` § Skill lifecycle policy. */
+const _DORMANCY_MONTHS = 6;
+
+/**
+ * What the dormancy report could actually establish from git in this checkout.
+ *
+ * `ok: false` is a first-class outcome, not an error: a shallow clone or a
+ * repository younger than the window cannot distinguish "untouched for six
+ * months" from "history truncated three months ago", and CI clones are shallow
+ * by default. The report NAMES that instead of emitting a list built on it.
+ */
+export interface DormancyProbe {
+    ok: boolean;
+    /** Why the signal is unavailable — set iff `ok` is false. */
+    reason?: string;
+    /** Repo-relative paths with at least one commit inside the window. */
+    touched: Set<string>;
+}
+
+function _git(root: string, args: readonly string[]): string | null {
+    try {
+        return child_process.execFileSync('git', [...args], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Probe git once for the whole estate: one bounded `--since` walk, exactly the
+ * command `governance.md` names, rather than one `git log` per artefact.
+ */
+function _dormancy_probe(root: string, now: Date = new Date()): DormancyProbe {
+    const since = `${String(_DORMANCY_MONTHS)} months ago`;
+    if (_git(root, ['rev-parse', '--git-dir']) === null) {
+        return { ok: false, reason: 'not a git checkout — commit history is unavailable', touched: new Set() };
+    }
+    if ((_git(root, ['rev-parse', '--is-shallow-repository']) ?? '').trim() === 'true') {
+        return {
+            ok: false,
+            reason:
+                'shallow clone — a truncated history is indistinguishable from a dormant artefact. ' +
+                'Re-run after `git fetch --unshallow`.',
+            touched: new Set(),
+        };
+    }
+    const oldest = (_git(root, ['log', '--reverse', '--format=%cI', '--max-count=1']) ?? '').trim();
+    if (oldest !== '') {
+        const cutoff = new Date(now);
+        cutoff.setMonth(cutoff.getMonth() - _DORMANCY_MONTHS);
+        if (new Date(oldest) > cutoff) {
+            return {
+                ok: false,
+                reason:
+                    `repository history starts ${oldest.slice(0, 10)}, inside the ` +
+                    `${String(_DORMANCY_MONTHS)}-month window — every artefact would read as dormant`,
+                touched: new Set(),
+            };
+        }
+    }
+    const out = _git(root, ['log', `--since=${since}`, '--name-only', '--format=']);
+    if (out === null) {
+        return { ok: false, reason: 'git log failed', touched: new Set() };
+    }
+    const touched = new Set(out.split('\n').map((l) => l.trim()).filter((l) => l !== ''));
+    return { ok: true, touched };
+}
+
+/**
+ * The unit dormancy is measured over. A skill is a directory (governance names
+ * `git log -- src/skills/<name>/`), so a commit touching its `reference.md`
+ * keeps the skill alive; every other artefact is its own file.
+ */
+function _dormancy_unit(artefactPath: string): string {
+    return path.basename(artefactPath) === 'SKILL.md' ? path.dirname(artefactPath) : artefactPath;
+}
+
+/**
+ * Artefacts with no commit inside the dormancy window.
+ *
+ * Report-only by construction: `governance.md` § Skill lifecycle policy says
+ * dormancy triggers review, never auto-deprecation — and a finished artefact is
+ * indistinguishable from an abandoned one from commit dates, so the
+ * false-positive class is not empty and no argument makes it so.
+ */
+function _dormant_artefacts(manifest: JsonObject, probe: DormancyProbe): JsonObject[] {
+    if (!probe.ok) {
+        return [];
+    }
+    const alive = new Set<string>();
+    for (const p of probe.touched) {
+        alive.add(p);
+        // A touched file keeps its containing directory-shaped artefact alive.
+        for (let d = path.dirname(p); d !== '.' && d !== path.sep; d = path.dirname(d)) {
+            alive.add(d);
+        }
+    }
+    const out: JsonObject[] = [];
+    for (const a of manifest['artefacts'] as JsonObject[]) {
+        const unit = _dormancy_unit(a['path'] as string);
+        if (!alive.has(unit)) {
+            out.push({ path: a['path'], unit, category: a['category'] });
+        }
+    }
+    out.sort((a, b) => _cmpStr(a['path'] as string, b['path'] as string));
+    return out;
+}
+
+/** The dormancy section of the discovery report family (governance.md § Skill lifecycle policy). */
+function _dormancy_report(manifest: JsonObject, probe: DormancyProbe): string {
+    const lines = ['# Discovery — Dormancy Report', ''];
+    lines.push(`- Generated: \`${String(manifest['generated_at'])}\``);
+    lines.push(`- Window: **${String(_DORMANCY_MONTHS)} months** without a commit`);
+    lines.push('');
+    lines.push('> Dormancy triggers **review, never auto-deprecation**');
+    lines.push('> (`docs/governance.md` § Skill lifecycle policy). A finished artefact and an');
+    lines.push('> abandoned one look identical from commit dates, so this is a prompt to ask');
+    lines.push('> "still earning its slot?" — never a removal list, and never a gate.');
+    lines.push('');
+    if (!probe.ok) {
+        lines.push('## Signal unavailable');
+        lines.push('');
+        lines.push(`**No dormancy list is published**: ${String(probe.reason)}`);
+        lines.push('');
+        lines.push('An empty section here would read as "nothing is dormant", which is a');
+        lines.push('different claim from "the signal could not be computed".');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    const items = _dormant_artefacts(manifest, probe);
+    lines.push(`- Dormant artefacts: **${items.length}**`);
+    lines.push('');
+    if (items.length === 0) {
+        lines.push('_None. Every artefact was touched inside the window._');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('| Path | Unit | Category |');
+    lines.push('|---|---|---|');
+    for (const a of items) {
+        lines.push(`| \`${String(a['path'])}\` | \`${String(a['unit'])}\` | ${String(a['category'])} |`);
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
 /** Trust-level breakdown by workspace + human-review sanity flag. Mirrors `_trust_report`. */
 function _trust_report(manifest: JsonObject): string {
     const byWs = new Map<string, JsonObject>();
@@ -1195,6 +1348,7 @@ interface ParsedArgs {
     deprecation_report: string;
     trust_report: string;
     orphan_report: string;
+    dormancy_report: string;
     workspaces_json: string;
     packs_json: string;
     strict: boolean;
@@ -1231,6 +1385,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         deprecation_report: _config.DEFAULT_DEPRECATION_REPORT,
         trust_report: _config.DEFAULT_TRUST_REPORT,
         orphan_report: _config.DEFAULT_ORPHAN_REPORT,
+        dormancy_report: _config.DEFAULT_DORMANCY_REPORT,
         workspaces_json: _config.DEFAULT_WORKSPACES_JSON,
         packs_json: _config.DEFAULT_PACKS_JSON,
         strict: false,
@@ -1242,6 +1397,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '                                   [--deprecation-report DEPRECATION_REPORT]\n' +
         '                                   [--trust-report TRUST_REPORT]\n' +
         '                                   [--orphan-report ORPHAN_REPORT]\n' +
+        '                                   [--dormancy-report DORMANCY_REPORT]\n' +
         '                                   [--workspaces-json WORKSPACES_JSON]\n' +
         '                                   [--packs-json PACKS_JSON] [--strict]\n' +
         '                                   [--quiet]\n';
@@ -1252,6 +1408,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '--deprecation-report': 'deprecation_report',
         '--trust-report': 'trust_report',
         '--orphan-report': 'orphan_report',
+        '--dormancy-report': 'dormancy_report',
         '--workspaces-json': 'workspaces_json',
         '--packs-json': 'packs_json',
     };
@@ -1324,6 +1481,10 @@ function main(argv: readonly string[]): number {
         _writeFileMkdir(args.deprecation_report, _deprecation_report(manifest));
         _writeFileMkdir(args.trust_report, _trust_report(manifest));
         _writeFileMkdir(args.orphan_report, _orphan_report(manifest));
+        _writeFileMkdir(
+            args.dormancy_report,
+            _dormancy_report(manifest, _dormancy_probe(_config.ROOT)),
+        );
         // Phase 5 sub-views.
         _writeFileMkdir(
             args.workspaces_json,
@@ -1425,6 +1586,10 @@ export {
     _trust_report,
     _orphan_artefacts,
     _orphan_report,
+    _dormancy_probe,
+    _dormancy_unit,
+    _dormant_artefacts,
+    _dormancy_report,
     _workspaces_view,
     _packs_view,
     _summary,

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_claims.ts

@@ -55,7 +55,14 @@ const LEDGER_REL = 'docs/CLAIMS.md';
 const SURFACE_ROOTS = ['README.md', 'docs'];
 
 const CLAIM_MARKER = /<!--\s*claim:([A-Za-z0-9._-]+)\s*-->/g;
-const URL_DATED = /^https?:\/\/\S+\(\d{4}-\d{2}-\d{2}\)\s*$/;
+// The documented grammar is `https://… (YYYY-MM-DD)` — with a space, in both
+// docs/CLAIMS.md § Evidence-pointer grammar and this file's own header. The
+// original pattern required the stamp to abut the URL (`\S+\(`), so every
+// pointer written the documented way was rejected. That went unnoticed because
+// the form had zero usage until the external research citations were bound;
+// the space is now optional, which accepts both spellings and keeps the
+// enforcement matching the spec rather than the other way round.
+const URL_DATED = /^https?:\/\/\S+\s*\(\d{4}-\d{2}-\d{2}\)\s*$/;
 
 /** Witness sweep (P1.2) — marketing-class surfaces where a bare number must
  *  not appear as a capability claim. docs/proof.md and docs/comparison.yaml
@@ -118,6 +125,17 @@ export interface LedgerEntry {
     evidence: string;
     status: string;
     last_verified: string;
+    /**
+     * Optional forward link on a `resolved-null` entry: the id of the claim that
+     * reopened the same question by a different mechanism. The retire-never-delete
+     * lifecycle keeps the null readable forever, but a reader arriving at a closed
+     * question has no way to learn it was later reopened — this is that link.
+     *
+     * Parsed and gated rather than merely documented: an unparsed field would be a
+     * documented claim the code does not honour, which is the defect class this
+     * ledger exists to make impossible.
+     */
+    superseded_by: string;
 }
 
 interface Args {
@@ -158,6 +176,7 @@ function load_ledger(): Map<string, LedgerEntry> {
                 evidence: cur.evidence ?? '',
                 status: cur.status ?? '',
                 last_verified: cur.last_verified ?? '',
+                superseded_by: cur.superseded_by ?? '',
             });
         }
         cur = {};
@@ -170,7 +189,7 @@ function load_ledger(): Map<string, LedgerEntry> {
             continue;
         }
         if (!cur.id) continue;
-        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified):\s*(.*)$/);
+        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified|superseded_by):\s*(.*)$/);
         if (field) {
             const key = field[1] as keyof LedgerEntry;
             (cur as Record<string, string>)[key] = (field[2] ?? '').trim();
@@ -320,6 +339,36 @@ function main(argv: string[] = process.argv.slice(2)): number {
         if (un) findings.push({ id: entry.id, file: LEDGER_REL, reason: `backed entry has dangling evidence — ${un}` });
     }
 
+    // 2b. Successor pointers: a `superseded_by` must name a real ledger entry,
+    //     and only a closed question can have a successor. The field exists so a
+    //     reader arriving at a `resolved-null` learns the question was reopened
+    //     by a different mechanism — a dangling id would send them nowhere, and
+    //     the field on a live entry would claim a closure that never happened.
+    for (const entry of ledger.values()) {
+        if (!entry.superseded_by) continue;
+        if (entry.status !== 'resolved-null') {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by is only meaningful on a resolved-null entry (status: ${entry.status || 'missing'})`,
+            });
+            continue;
+        }
+        if (!ledger.has(entry.superseded_by)) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by names claim:${entry.superseded_by}, which is not in the ledger`,
+            });
+        } else if (entry.superseded_by === entry.id) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: 'superseded_by points at its own entry',
+            });
+        }
+    }
+
     // 3. Witness sweep (road-to-opt-subagent-harvest P1.2): a QUANTIFIED
     //    capability claim on a marketing-class surface must be witnessed — a
     //    `<!-- claim:ID -->` marker on the same line, or an explicit

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/ci_time_ratio.ts

@@ -20,7 +20,9 @@
  * - Median ratio < 3× across all classes      → structural overhead acceptable
  *
  * Output: human-readable table on stdout + JSON to
- * `agents/runtime/reports/ci-time-ratio.json`.
+ * `agents/reports/ci-time-ratio.json` — the tracked report directory, and
+ * the path `DEFAULT_OUT` has always written. This docstring named a
+ * different, untracked directory until 2026-08-11; the code never did.
  *
  * Usage:
  *   node ci_time_ratio.js --limit 30

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' };