@event4u/agent-config 9.32.0 → 9.33.0

package/src/scripts/_dispatch.bash

@@ -130,7 +130,7 @@ Tier 1 — power-user (release shape, audit, migration):
                              user-authored files; persists standing consent
                              (install.auto_converge) on first use.
                              Flags: --dry-run | --yes
-  conformance:behavior       Replay local transcripts through the mechanised conformance checks
+  conformance:behavior       Replay local transcripts through the mechanised conformance checks (--why <id> traces one)
   conformance                Consumer conformance contract: doctor --ci +
                              installed-and-firing checks. Exits non-zero on
                              a failed check.
@@ -197,7 +197,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              session register). Flags: --json
   sessions:claim             Claim a roadmap for this session so other sessions skip
                              it; --release clears the claim
-  session:recycle            Validate + write the main-session recycle envelope
+  session:recycle            Validate + write the main-session recycle envelope (--verify validates only)
                              (deliberate recycle instead of auto-compact). Flags:
                              --file <json> | --template; default reads stdin
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
@@ -207,7 +207,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   gates                      Open decisions that need you, rendered as actions —
                              roadmap blockers filtered by owner, most-unblocking
                              first. Flags: --all (include maintainer/external),
-                             --json
+                             --json, --reply (reply-close form: the one blocking
+                             decision in full, the rest as a count; prints
+                             nothing when none are yours)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).

package/src/scripts/_lib/orchestration_record.ts

@@ -64,6 +64,20 @@ export interface RecordInput {
     dispatch_tokens?: number | null | undefined;
     /** The orchestrator's own tier — the baseline the downshift cost-% measures against. */
     session_tier?: string | null | undefined;
+    /**
+     * The model id that was ASKED for. `tier_chosen`, `tier_source`,
+     * `session_tier` and the downshift cost-percentage are all read off the
+     * requested tier, so on an alias or a provider substitution every one of
+     * them attributes the saving to a model that never ran. Recording the
+     * requested id beside the served one is what makes that detectable.
+     */
+    model_requested?: string | null | undefined;
+    /**
+     * The model id the provider reported SERVING. `''` / null when the
+     * transport reports none (every CLI client) — absent is honest, not a
+     * defect, and is NOT a divergence.
+     */
+    model_served?: string | null | undefined;
     dispatch_outcome?: DispatchOutcome | undefined;
     verify_mode?: VerifyMode | undefined;
     /** QUALITY: subagent return adopted without parent rework. Optional boolean (null = not measured). */
@@ -176,6 +190,23 @@ function isInt(n: unknown): n is number {
     return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n);
 }
 
+/**
+ * Did the provider answer with a different model than the one requested?
+ *
+ * `null` — not decidable — whenever either id is missing or empty. That is the
+ * common case (every CLI transport reports no served id) and it is not the
+ * same as "no divergence": a `false` here would claim a comparison that never
+ * happened, which is the exact mis-attribution this field exists to expose.
+ */
+function modelDivergent(
+    requested: string | null | undefined,
+    served: string | null | undefined,
+): boolean | null {
+    if (typeof requested !== 'string' || typeof served !== 'string') return null;
+    if (!requested || !served) return null;
+    return requested !== served;
+}
+
 /**
  * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
  * `errors` is non-empty, `line` is null and the caller must NOT write.
@@ -290,6 +321,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         errors.push(`trigger_arm_earlier must be one of ${TRIGGER_ARMS.join(' | ')} (or omitted / null when neither arm fired)`);
     }
 
+    for (const [key, v] of [
+        ['model_requested', input.model_requested],
+        ['model_served', input.model_served],
+    ] as const) {
+        if (v != null && typeof v !== 'string') errors.push(`${key} must be a string or omitted`);
+    }
+
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID or content hash) is required');
 
@@ -310,6 +348,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         tier_source: input.tier_source ?? null,
         dispatch_tokens: input.dispatch_tokens ?? null,
         session_tier: input.session_tier ?? null,
+        // Served-model attribution. `model_divergent` is DERIVED, never
+        // supplied: `null` when either id is absent — a transport that reports
+        // no served id cannot disagree with anything, and calling that `false`
+        // would read as "checked, and they matched".
+        model_requested: input.model_requested ?? null,
+        model_served: input.model_served ?? null,
+        model_divergent: modelDivergent(input.model_requested, input.model_served),
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
         agent_combo: input.agent_combo ?? [],

package/src/scripts/ai_council/clients.ts

@@ -195,10 +195,34 @@ export function assertCacheBreakpointOrder(ttls: readonly PromptCacheTtl[]): voi
     }
 }
 
+/**
+ * The model id a provider reports on its own response, or `''` when it reports
+ * none.
+ *
+ * `field` is a parameter because the name is NOT uniform across providers:
+ * Gemini reports it as `model_version`, so a literal single-field read would
+ * leave Gemini silently empty — which is indistinguishable from a transport
+ * that genuinely reports nothing. Non-string values collapse to `''` rather
+ * than being coerced: a guess is worse than an honest blank here, because the
+ * whole point of the field is detecting a substitution.
+ */
+function _servedModel(response: unknown, field = 'model'): string {
+    const value = _getattr(response, field, '');
+    return typeof value === 'string' ? value : '';
+}
+
 /** Normalised output from a single council member (dataclass `CouncilResponse`). */
 export class CouncilResponse {
     provider: string;
     model: string;
+    // The model id the provider reported serving, when it reports one. NEVER
+    // overwrites `model`: that is the REQUESTED id, and it is what the tier
+    // decision was made against — keeping both is what makes a silent alias or
+    // provider substitution detectable at all. Attribution-only; no consumer
+    // may route on it. Defaults to '' (the honest value for a transport that
+    // reports no served id, e.g. every CLI client) so existing callers and the
+    // persisted response JSON stay backward-compatible.
+    model_served: string;
     text: string;
     input_tokens: number;
     output_tokens: number;
@@ -215,6 +239,7 @@ export class CouncilResponse {
     constructor(opts: {
         provider: string;
         model: string;
+        model_served?: string;
         text: string;
         input_tokens?: number;
         output_tokens?: number;
@@ -226,6 +251,7 @@ export class CouncilResponse {
     }) {
         this.provider = opts.provider;
         this.model = opts.model;
+        this.model_served = opts.model_served ?? '';
         this.text = opts.text;
         this.input_tokens = opts.input_tokens ?? 0;
         this.output_tokens = opts.output_tokens ?? 0;
@@ -616,6 +642,7 @@ export class AnthropicClient extends ExternalAIClient {
         return new CouncilResponse({
             provider: this.name,
             model: this.model,
+            model_served: _servedModel(response),
             text,
             input_tokens: usage ? (_getattr(usage, 'input_tokens', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'output_tokens', 0) as number) : 0,
@@ -719,6 +746,7 @@ export class OpenAIClient extends ExternalAIClient {
         return new CouncilResponse({
             provider: this.name,
             model: this.model,
+            model_served: _servedModel(response),
             text: (text as string) || '',
             input_tokens: usage ? (_getattr(usage, 'prompt_tokens', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'completion_tokens', 0) as number) : 0,
@@ -796,6 +824,8 @@ export class GeminiClient extends ExternalAIClient {
         return new CouncilResponse({
             provider: this.name,
             model: this.model,
+            // Gemini names it `model_version`, not `model`.
+            model_served: _servedModel(response, 'model_version'),
             text,
             input_tokens: usage ? (_getattr(usage, 'prompt_token_count', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'candidates_token_count', 0) as number) : 0,
@@ -878,6 +908,7 @@ export class _OpenAICompatibleClient extends ExternalAIClient {
         return new CouncilResponse({
             provider: this.name,
             model: this.model,
+            model_served: _servedModel(response),
             text: (text as string) || '',
             input_tokens: usage ? (_getattr(usage, 'prompt_tokens', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'completion_tokens', 0) as number) : 0,

package/src/scripts/ai_council/events_log.ts

@@ -3,9 +3,11 @@
  *
  * Ported from the retired Python `src/scripts/ai_council/events_log.py` (ADR-200 —
  * Python→TS migration, Phase 1). Appends one JSON line per council event to
- * `<project_root>/agents/runtime/council/events.log`. Schema v1 carries the
- * minimum needed to answer the "why did the council skip / block this?"
- * question at retro time without leaking prompt content.
+ * `<project_root>/agents/runtime/council/events.log`. The schema carries the
+ * minimum needed to answer "why did the council skip / block this?" and,
+ * since v2, "who actually attended?" — at retro time, without leaking prompt
+ * content. v2 added the `quorum_result` action and nothing else; see
+ * `appendQuorumEvent`.
  *
  * Privacy floor:
  *     `original_ask` is never written verbatim — the caller passes the raw
@@ -25,14 +27,24 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export const SCHEMA_VERSION = 1;
+import { isSoloConcluded, type QuorumResult } from './quorum.js';
+import type { AbsentReason } from './transport_resolver.js';
 
-export type EventAction = 'proceed' | 'skip_necessity' | 'block_quota';
+/**
+ * v2 adds the `quorum_result` action (and nothing else) — see
+ * `appendQuorumEvent`. Every schema-v1 field keeps its name, type and
+ * position, so a v1 reader parses a v2 necessity line unchanged; only the
+ * action vocabulary widened.
+ */
+export const SCHEMA_VERSION = 2;
+
+export type EventAction = 'proceed' | 'skip_necessity' | 'block_quota' | 'quorum_result';
 
 const _VALID_ACTIONS: ReadonlySet<string> = new Set([
     'proceed',
     'skip_necessity',
     'block_quota',
+    'quorum_result',
 ]);
 
 /**
@@ -194,7 +206,7 @@ export function appendEvent(
         original_ask_hash: _hash_original_ask(rawAsk),
     };
     // Pass-through for any caller-supplied diagnostic fields that are not in
-    // the schema-v1 reserved set. The schema-v1 fields above always win on
+    // the reserved set. The reserved fields above always win on
     // collision.
     const reserved = new Set([...Object.keys(record), 'original_ask']);
     for (const [k, v] of Object.entries(event)) {
@@ -215,6 +227,116 @@ export function defaultLogPath(): string {
     return _DEFAULT_LOG_PATH;
 }
 
+// ── quorum attendance (schema v2) ───────────────────────────────────
+
+/**
+ * Which of the two `evaluateQuorum` call sites produced the record.
+ *
+ * `pre_run` is `build_members`' construction-time reading — who could be
+ * built at all. `post_run` is `_postRunQuorum`'s re-derivation over what
+ * actually returned a usable response. One pass emits BOTH, and they
+ * disagree whenever a member constructs and then fails mid-flight, so a
+ * consumer that counts attendance without splitting on this field
+ * double-counts every pass.
+ */
+export type QuorumEventPhase = 'pre_run' | 'post_run';
+
+/**
+ * One absent member, in the vocabulary the tree actually uses:
+ * `AbsentReason` plus the two runtime fallbacks the CLI writes directly —
+ * `'unavailable'` (transport resolved to ∅) and `'binary_missing'` (a CLI
+ * client refused to construct).
+ */
+export type QuorumAbsentReason = AbsentReason | 'unavailable' | 'binary_missing';
+
+export interface QuorumAbsence {
+    readonly member: string;
+    readonly reason: QuorumAbsentReason;
+}
+
+/**
+ * Which CLI path produced the line. `estimate` spends nothing — it is a cost
+ * preview — so every rate computed over these lines must exclude it, and it
+ * is recorded rather than suppressed so the exclusion is the consumer's
+ * explicit act instead of an invisible one.
+ */
+export type QuorumCommand = 'run' | 'estimate' | 'debate';
+
+/**
+ * `single` means `--single` filtered the roster down to one member BEFORE
+ * the pass ran. Without this field a deliberate solo dispatch is byte-identical
+ * to a configured one-member council, and the solo-conclusion rate cannot tell
+ * the two apart — which is the one distinction it exists to make.
+ */
+export type QuorumDispatch = 'full' | 'single';
+
+export interface QuorumEventInput {
+    readonly lens: string;
+    readonly invocation: string;
+    readonly phase: QuorumEventPhase;
+    readonly command: QuorumCommand;
+    readonly dispatch: QuorumDispatch;
+    /**
+     * Enabled members in the config, BEFORE `--single` / `--siblings`
+     * filtering and before construction failures. `result.total` is the
+     * roster that survived; when the two differ, the gap is exactly the
+     * "council degraded by configuration" case a post_run-only reading is
+     * otherwise blind to.
+     */
+    readonly configuredTotal: number;
+    readonly result: QuorumResult;
+    readonly absent: readonly QuorumAbsence[];
+}
+
+/**
+ * Append one `quorum_result` line — the attendance record that makes a
+ * solo-concluded pass distinguishable from a full-attendance one.
+ *
+ * Privacy floor, by construction: `QuorumAbsence` carries a member name and
+ * a closed-vocabulary reason and has **no field able to hold free-form
+ * content**. The CLI's own absent entries carry a `detail` string built from
+ * provider error text (which can embed paths and prompts); it is dropped
+ * here rather than scrubbed, so there is no scrubber to fail.
+ *
+ * Fail-open: attendance telemetry must never be able to kill a council
+ * pass, so every error is swallowed and reported as `false`. The reachable
+ * ones are filesystem errors from `appendEvent`'s own `mkdirSync` /
+ * `appendFileSync` — an unwritable path, ENOTDIR, a full disk. Its other
+ * throw (an invalid action) is unreachable from here, since this function
+ * supplies the action itself.
+ */
+export function appendQuorumEvent(
+    input: QuorumEventInput,
+    opts: AppendEventOptions = {},
+): boolean {
+    try {
+        return appendEvent(
+            {
+                lens: input.lens,
+                invocation: input.invocation,
+                action: 'quorum_result',
+                verdict: input.result.status,
+                phase: input.phase,
+                command: input.command,
+                dispatch: input.dispatch,
+                threshold: input.result.threshold,
+                configured_total: input.configuredTotal,
+                total: input.result.total,
+                present: input.result.present,
+                // Written by the predicate, never re-derived from the numbers
+                // downstream: one definition of "concluded on a single voice",
+                // in `quorum.ts`, so a change to it cannot leave a consumer's
+                // copy silently stale.
+                solo: isSoloConcluded(input.result),
+                absent: input.absent.map((a) => ({ member: a.member, reason: a.reason })),
+            },
+            opts,
+        );
+    } catch {
+        return false;
+    }
+}
+
 // ── helpers ─────────────────────────────────────────────────────────
 
 /**

package/src/scripts/ai_council/orchestrator.ts

@@ -70,7 +70,7 @@ import { count_dissenters, dissent_quota_met, is_near_duplicate } from './debate
 import { parse_stance_line, render_vote_tally, tally_stances } from './stance_tally.js';
 import { CHAIRMAN_FIELDS_ADDENDUM, render_deanonymization_block } from './blind_review.js';
 import type { AbsentReason } from './transport_resolver.js';
-import type { QuorumResult } from './quorum.js';
+import { isSoloConcluded, type QuorumResult } from './quorum.js';
 import { isEmptyHandoff, type HandoffEnvelope } from './handoff.js';
 
 // ── Python-format / stdlib parity helpers ────────────────────────────────
@@ -1979,10 +1979,19 @@ export function render(responses: CouncilResponse[], opts: RenderOptions = {}):
     return blocks.join('\n\n---\n\n');
 }
 
-/** One line naming the k-of-n outcome — machine-parseable, human-readable. */
+/**
+ * One line naming the k-of-n outcome — machine-parseable, human-readable.
+ *
+ * The `solo` marker is the artifact half of the signal the `quorum_result`
+ * event carries in the log: a pass concluded by ONE voice otherwise reads
+ * identically to a full-attendance one, and the reader of a rendered pass is
+ * exactly who needs to see the difference. Derived through `isSoloConcluded`
+ * so the predicate keeps one definition and the renderer does not restate it.
+ */
 function _render_quorum_line(q: QuorumResult): string {
     const verdict = q.status === 'concluded' ? 'concluded' : 'INCONCLUSIVE — release gate holds';
-    return `**Quorum:** ${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.`;
+    const solo = isSoloConcluded(q) ? ' · **solo** — one voice concluded this pass' : '';
+    return `**Quorum:** ${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${solo}`;
 }
 
 /**

package/src/scripts/ai_council/pricing.ts

@@ -49,8 +49,55 @@ export interface PriceTable {
     prices: Map<string, Price>; // keyed by priceKey(provider, model)
 }
 
+/**
+ * Price for (provider, model) — exact key first, then the longest matching
+ * key PREFIX within the same provider.
+ *
+ * Exact match stays the first hit, so no call that resolves today changes
+ * path or price. The fallback exists because vendors ship dated aliases:
+ * `claude-sonnet-4-5-20260101` missed a `claude-sonnet-4-5` row and priced at
+ * **nothing** — a silent zero, not an error. Longest-first means a more
+ * specific row always wins over a shorter one that also prefixes the id
+ * (`claude-opus-4-1` over a hypothetical `claude-opus`).
+ *
+ * The prefix must be followed by a separator (`-`, `.`, `:`, `@`) or end the
+ * id, so `claude-opus-4-1` never matches a `claude-opus-4-15` row: a bare
+ * `startsWith` would price one model at another's rate, which is worse than
+ * the zero it replaces because it looks correct.
+ *
+ * Provider is part of the composite key, so cross-provider bleed is
+ * impossible by construction.
+ */
 export function lookup(table: PriceTable, provider: string, model: string): Price | null {
-    return table.prices.get(priceKey(provider, model)) ?? null;
+    const exact = table.prices.get(priceKey(provider, model));
+    if (exact !== undefined) {
+        return exact;
+    }
+    // Derived from `priceKey`, never hand-rebuilt: it owns the composite-key
+    // encoding, and a second copy here would let a separator change follow the
+    // exact-match path while this loop silently matched nothing — regressing to
+    // the very silent zero the fallback exists to remove.
+    const prefix = priceKey(provider, '');
+    let best: Price | null = null;
+    let bestLen = -1;
+    for (const [key, price] of table.prices) {
+        if (!key.startsWith(prefix)) {
+            continue;
+        }
+        const candidate = key.slice(prefix.length);
+        if (!candidate || !model.startsWith(candidate)) {
+            continue;
+        }
+        const next = model.charAt(candidate.length);
+        if (next !== '' && next !== '-' && next !== '.' && next !== ':' && next !== '@') {
+            continue;
+        }
+        if (candidate.length > bestLen) {
+            best = price;
+            bestLen = candidate.length;
+        }
+    }
+    return best;
 }
 
 // ── token + cost arithmetic ────────────────────────────────────────

package/src/scripts/ai_council/quorum.ts

@@ -82,3 +82,23 @@ export function evaluateQuorum(
     const status: QuorumStatus = clampedPresent >= threshold ? 'concluded' : 'inconclusive';
     return { status, threshold, total, present: clampedPresent };
 }
+
+/**
+ * Did this pass conclude on a single voice?
+ *
+ * Derived — deliberately NOT a third `QuorumStatus`. `ceil(n / 2)` makes
+ * 1-of-2 a legitimate `concluded`, which is the intended behaviour (see the
+ * module header); this predicate does not dispute it, it only makes the
+ * shape visible so a reader can tell a one-member conclusion from a
+ * full-attendance one. Advisory render and telemetry only: no gate reads it,
+ * and nothing downstream may branch on it without its own decision record.
+ *
+ * `total` is deliberately NOT consulted. A council configured with a single
+ * member concludes solo by construction, and that is still a conclusion
+ * reached on one voice — collapsing it into "not solo" would hide exactly
+ * the passes a solo-conclusion rate is measured to find. A consumer that
+ * cares about the distinction reads `result.total` alongside.
+ */
+export function isSoloConcluded(result: QuorumResult): boolean {
+    return result.status === 'concluded' && result.present === 1;
+}

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