session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/session-token-rollup.mjs

@@ -53,11 +53,28 @@
  * be reconstruction, not correction. Consumers comparing token totals across the
  * 2026-08-11 boundary must treat it as a series break.
  *
+ * ## Schema-version boundary — v1 and v2 token_input are different quantities (#1244)
+ *
+ * Since 2026-09-09 (`schema_version: 2`) a stop record's `token_input` is
+ * BILLABLE PROMPT VOLUME — uncached + cache_read + cache_creation — where v1
+ * held raw `usage.input_tokens` only. Under prompt caching those differ by up
+ * to five orders of magnitude (measured: 56 vs 3,676,179 on one agent), so
+ * summing them together produces a number describing neither. This module
+ * therefore sums ONLY `schema_version >= 2` token-bearing records into
+ * `total_token_*` and reports the excluded ones as `legacy_v1_records`: the
+ * boundary is DECLARED, never silent.
+ *
+ * `total_cost_usd` is computed per record via `costUsd()` and is null when ANY
+ * priced record carries a model the price table does not know — a partial cost
+ * is worse than no cost, because it reads as a complete one. `cost_records_priced`
+ * / `cost_records_total` say how much of the session the estimate covers.
+ *
  * @module session-token-rollup
  */
 
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { costUsd } from './telemetry/pricing.mjs';
 
 // ---------------------------------------------------------------------------
 // Default subagents.jsonl path (relative to cwd, mirroring the rest of the
@@ -85,12 +102,29 @@ function isTokenBearing(record) {
   return record?.subagent_transcript_found === true;
 }
 
+/**
+ * Is this record inside the schema_version 2 token contract? (#1244)
+ * @param {object} record
+ * @returns {boolean}
+ */
+function isV2(record) {
+  return typeof record?.schema_version === 'number' && record.schema_version >= 2;
+}
+
 /**
  * @typedef {Object} TokenRollupResult
  * @property {number|null} total_token_input  - Sum of token_input across TOKEN-BEARING matched records; null when none had a non-null value.
  * @property {number|null} total_token_output - Sum of token_output across TOKEN-BEARING matched records; null when none had a non-null value.
  * @property {number}      subagents_with_tokens - Count of distinct agent_ids with at least one token-bearing record. This is the numerator of the honest coverage ratio.
  * @property {number}      matched_records    - Total count of JSONL records matched by parentSessionId. Counts start records, phantom stops and pre-#949 records alike, so it is NOT the denominator for a token-coverage ratio — dividing by it is what made healthy sessions read as 12% covered.
+ * @property {number|null}  total_token_input_uncached - Sum of token_input_uncached across v2 token-bearing records.
+ * @property {number|null}  total_token_cache_read     - Sum of token_cache_read across v2 token-bearing records.
+ * @property {number|null}  total_token_cache_creation - Sum of token_cache_creation across v2 token-bearing records.
+ * @property {number|null}  total_cost_usd     - Σ costUsd() over v2 token-bearing records; null when ANY of them carries an unknown model (never 0 — see telemetry/pricing.mjs).
+ * @property {number}       cost_records_priced - How many token-bearing records the price table could price.
+ * @property {number}       cost_records_total  - How many token-bearing records were candidates for pricing.
+ * @property {number}       legacy_v1_records  - Token-bearing records EXCLUDED from every total above because their schema_version < 2 (their token_input is a different quantity).
+ * @property {2}            _token_schema      - The token contract these totals were computed under.
  */
 
 /**
@@ -112,6 +146,14 @@ export function rollupSessionTokens({
     total_token_output: null,
     subagents_with_tokens: 0,
     matched_records: 0,
+    total_token_input_uncached: null,
+    total_token_cache_read: null,
+    total_token_cache_creation: null,
+    total_cost_usd: null,
+    cost_records_priced: 0,
+    cost_records_total: 0,
+    legacy_v1_records: 0,
+    _token_schema: 2,
   };
 
   if (typeof parentSessionId !== 'string' || parentSessionId.length === 0) {
@@ -157,10 +199,21 @@ export function rollupSessionTokens({
   // Aggregate — skip null/undefined token values.
   let sumInput = null;
   let sumOutput = null;
+  let sumUncached = null;
+  let sumCacheRead = null;
+  let sumCacheCreation = null;
+  let sumCost = null;
+  let costPriced = 0;
+  let costTotal = 0;
+  let costUnknownModel = false;
+  let legacyV1 = 0;
 
   // Track distinct agent_ids that contributed at least one non-null token.
   const agentsWithTokens = new Set();
 
+  const addNonNegative = (acc, value) =>
+    typeof value === 'number' && value >= 0 ? (acc ?? 0) + value : acc;
+
   for (const record of matched) {
     // Provenance gate (#949) — a record whose tokens describe the PARENT
     // transcript, or no transcript at all, contributes nothing. Skipping it
@@ -169,24 +222,48 @@ export function rollupSessionTokens({
     // which is true, instead of a fabricated 0.
     if (!isTokenBearing(record)) continue;
 
+    // Schema gate (#1244) — a v1 record's token_input is raw uncached input,
+    // a different quantity from a v2 record's billable prompt volume. Count it
+    // so the boundary is visible, never sum it.
+    if (!isV2(record)) {
+      legacyV1 += 1;
+      continue;
+    }
+
     const inp = record.token_input;
     const out = record.token_output;
 
-    if (typeof inp === 'number' && inp >= 0) {
-      sumInput = (sumInput ?? 0) + inp;
-    }
-    if (typeof out === 'number' && out >= 0) {
-      sumOutput = (sumOutput ?? 0) + out;
-    }
+    sumInput = addNonNegative(sumInput, inp);
+    sumOutput = addNonNegative(sumOutput, out);
+    sumUncached = addNonNegative(sumUncached, record.token_input_uncached);
+    sumCacheRead = addNonNegative(sumCacheRead, record.token_cache_read);
+    sumCacheCreation = addNonNegative(sumCacheCreation, record.token_cache_creation);
 
     // Count this agent as having tokens if either field is a non-null number.
-    if (
-      (typeof inp === 'number' && inp >= 0) ||
-      (typeof out === 'number' && out >= 0)
-    ) {
+    const hasTokens =
+      (typeof inp === 'number' && inp >= 0) || (typeof out === 'number' && out >= 0);
+    if (hasTokens) {
       if (record.agent_id !== undefined && record.agent_id !== null) {
         agentsWithTokens.add(record.agent_id);
       }
+
+      // Cost: every token-bearing v2 record is a pricing candidate. One unknown
+      // model poisons the SESSION total — a cost covering some of the agents
+      // reads as covering all of them.
+      costTotal += 1;
+      const cost = costUsd({
+        model: record.model,
+        tokenInputUncached: record.token_input_uncached,
+        tokenCacheRead: record.token_cache_read,
+        tokenCacheCreation: record.token_cache_creation,
+        tokenOutput: record.token_output,
+      });
+      if (cost === null) {
+        costUnknownModel = true;
+      } else {
+        costPriced += 1;
+        sumCost = (sumCost ?? 0) + cost;
+      }
     }
   }
 
@@ -195,5 +272,13 @@ export function rollupSessionTokens({
     total_token_output: sumOutput,
     subagents_with_tokens: agentsWithTokens.size,
     matched_records: matched.length,
+    total_token_input_uncached: sumUncached,
+    total_token_cache_read: sumCacheRead,
+    total_token_cache_creation: sumCacheCreation,
+    total_cost_usd: costUnknownModel ? null : sumCost,
+    cost_records_priced: costPriced,
+    cost_records_total: costTotal,
+    legacy_v1_records: legacyV1,
+    _token_schema: 2,
   };
 }

package/scripts/lib/state-md/frontmatter-mutators.mjs

@@ -11,9 +11,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
-import { dirname, join, resolve as resolvePath } from 'node:path';
+import { dirname, resolve as resolvePath } from 'node:path';
 import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
 import { withStateMdLock } from '../session-lock.mjs';
+import { resolveStateDir } from '../platform.mjs';
 
 /**
  * Sets frontmatter.updated to the given ISO 8601 timestamp and returns the
@@ -70,33 +71,26 @@ export function updateFrontmatterFields(contents, fields) {
 // writeFileSync(STATE)` migrate to `await writeStateMd(repoRoot, contents => …)`,
 // which mechanically serialises concurrent writers via `withStateMdLock`.
 
-// Canonical STATE.md path candidates (matches harness-audit category1 order).
-const STATE_MD_CANDIDATES = [
-  '.claude/STATE.md',
-  '.codex/STATE.md',
-  '.cursor/STATE.md',
-  '.pi/STATE.md',
-];
+// Legacy fallback order; the requested artifact's active harness always wins.
+const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
 
-function preferredStateMdCandidate() {
-  const envStateDir = process.env.SO_STATE_DIR;
-  if (typeof envStateDir === 'string' && envStateDir.length > 0) {
-    return join(envStateDir, 'STATE.md');
-  }
-  switch (process.env.SO_PLATFORM) {
-    case 'codex': return '.codex/STATE.md';
-    case 'cursor': return '.cursor/STATE.md';
-    case 'pi': return '.pi/STATE.md';
-    default: return '.claude/STATE.md';
-  }
-}
-
-function orderedStateMdCandidates() {
-  const preferred = preferredStateMdCandidate();
-  return [
-    preferred,
-    ...STATE_MD_CANDIDATES.filter((candidate) => candidate !== preferred),
-  ];
+/**
+ * Resolve a state artifact independently of other files in the state directory.
+ * Check SO_STATE_DIR, the detected active harness, then legacy harness directories.
+ * If none exist, return the preferred path for create-on-first-write callers.
+ * In particular, an existing legacy STATE.md must not redirect a native scope.
+ *
+ * @param {string|undefined} repoRoot
+ * @param {string} filename - Artifact filename, such as STATE.md or wave-scope.json.
+ * @returns {string} Absolute artifact path.
+ */
+export function resolveStateArtifactPath(repoRoot, filename) {
+  const root = repoRoot ?? process.cwd();
+  const override = (process.env.SO_STATE_DIR ?? '').trim();
+  const active = resolveStateDir();
+  const directories = [...new Set([override || active, active, ...STATE_DIR_CANDIDATES])];
+  const candidates = directories.map((directory) => resolvePath(root, directory, filename));
+  return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 
 /**
@@ -110,13 +104,7 @@ function orderedStateMdCandidates() {
  * @returns {string}  Absolute path to STATE.md.
  */
 export function resolveStateMdPath(repoRoot) {
-  const root = repoRoot ?? process.cwd();
-  const candidates = orderedStateMdCandidates();
-  for (const candidate of candidates) {
-    const abs = resolvePath(join(root, candidate));
-    if (existsSync(abs)) return abs;
-  }
-  return resolvePath(join(root, candidates[0]));
+  return resolveStateArtifactPath(repoRoot, 'STATE.md');
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/state-md.mjs

@@ -23,6 +23,7 @@ export { parseStateMd, serializeStateMd } from './state-md/yaml-parser.mjs';
 export {
   touchUpdatedField,
   updateFrontmatterFields,
+  resolveStateArtifactPath,
   resolveStateMdPath,
   writeStateMd,
   updateFrontmatterFieldsOnDisk,

package/scripts/lib/subagents-schema.mjs

@@ -32,14 +32,28 @@
  * Optional:
  *   agent_type        string | null — e.g. 'explore', 'writer', 'test-writer'
  *   parent_session_id string | null — session that spawned this subagent
- *   token_input       integer | null — prompt token count for this subagent
+ *   token_input       integer | null — BILLABLE PROMPT VOLUME for this subagent.
+ *                     schema_version 1: raw `usage.input_tokens` only.
+ *                     schema_version 2 (#1244, 2026-09-09): uncached + cache_read +
+ *                     cache_creation. This is a REDEFINITION — a v1 and a v2 value
+ *                     are not comparable and must never be summed together.
+ *   token_input_uncached  integer | null — raw `usage.input_tokens` (v2+)
+ *   token_cache_read      integer | null — `usage.cache_read_input_tokens` (v2+)
+ *   token_cache_creation  integer | null — `usage.cache_creation_input_tokens` (v2+)
  *   token_output      integer | null — completion token count for this subagent
+ *   model             string  | null — model id from the transcript (v2+); null when
+ *                                      the transcript exposes none. Required to price
+ *                                      the record — see scripts/lib/telemetry/pricing.mjs.
  *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
  *                                      best-effort: null when the harness does not
  *                                      expose it; no rate table is applied)
  *
  * OTel aliases (optional, stop-only, additive — #411, schema_version=1 backwards-compat):
- *   gen_ai.usage.input_tokens   integer | null — alias of token_input
+ *   gen_ai.usage.input_tokens   integer | null — RAW UNCACHED prompt tokens (OTel
+ *                                                semantic). Under schema_version 2
+ *                                                this is deliberately ≠ token_input.
+ *   gen_ai.usage.cache_read_input_tokens      integer | null (v2+)
+ *   gen_ai.usage.cache_creation_input_tokens  integer | null (v2+)
  *   gen_ai.usage.output_tokens  integer | null — alias of token_output
  *   gen_ai.system               'anthropic'    — AI provider identifier
  */
@@ -52,8 +66,25 @@ import path from 'node:path';
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Current subagent-record schema version. */
-export const CURRENT_SCHEMA_VERSION = 1;
+/** Current subagent-record schema version (2 since #1244, 2026-09-09). */
+export const CURRENT_SCHEMA_VERSION = 2;
+
+/**
+ * Schema versions this module reads. v1 records stay valid forever — the ledger
+ * is append-only — but their `token_input` means something different (see the
+ * module header), which is why consumers gate on the version rather than trust
+ * the field name.
+ */
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([1, 2]);
+
+/**
+ * Version assumed for a record read from disk that carries none. It is 1, NOT
+ * `CURRENT_SCHEMA_VERSION`: a versionless record predates the field, so
+ * stamping it with the current version would relabel legacy token semantics as
+ * v2 and let the rollup sum a raw-input-only figure into a billable-volume
+ * total — exactly the silent mixing #1244 exists to prevent.
+ */
+export const LEGACY_SCHEMA_VERSION = 1;
 
 /** Allowed event values. */
 export const VALID_EVENTS = Object.freeze(['start', 'stop']);
@@ -102,10 +133,10 @@ export function validateSubagent(entry, options = {}) {
     throw new ValidationError('subagent record must be a non-null object');
   }
 
-  // schema_version
-  if (entry.schema_version !== CURRENT_SCHEMA_VERSION) {
+  // schema_version — v1 and v2 both validate (append-only ledger, #1244).
+  if (!SUPPORTED_SCHEMA_VERSIONS.includes(entry.schema_version)) {
     throw new ValidationError(
-      `schema_version must be ${CURRENT_SCHEMA_VERSION}, got: ${entry.schema_version}`,
+      `schema_version must be one of ${SUPPORTED_SCHEMA_VERSIONS.join('|')}, got: ${entry.schema_version}`,
       'schema_version',
     );
   }
@@ -185,6 +216,23 @@ export function validateSubagent(entry, options = {}) {
     }
   }
 
+  // Cache-bucket fields (optional, #1244 / schema_version 2). Same
+  // non-negative-integer-or-null contract as token_input above.
+  for (const field of ['token_input_uncached', 'token_cache_read', 'token_cache_creation']) {
+    const value = entry[field];
+    if (value !== undefined && value !== null) {
+      if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new ValidationError(`${field} must be a non-negative integer or null`, field);
+      }
+    }
+  }
+
+  // model (optional, #1244) — the transcript's model id; null is an honest
+  // absence and makes the record unpriceable, never free.
+  if (entry.model !== undefined && entry.model !== null && typeof entry.model !== 'string') {
+    throw new ValidationError('model must be a string or null', 'model');
+  }
+
   // total_cost_usd (optional, #624) — fractional number (not integer), best-effort.
   if (entry.total_cost_usd !== undefined && entry.total_cost_usd !== null) {
     if (typeof entry.total_cost_usd !== 'number' || !Number.isFinite(entry.total_cost_usd) || entry.total_cost_usd < 0) {
@@ -208,6 +256,19 @@ export function validateSubagent(entry, options = {}) {
     }
   }
 
+  // OTel cache aliases — #1244 additive (schema_version 2).
+  for (const field of [
+    'gen_ai.usage.cache_read_input_tokens',
+    'gen_ai.usage.cache_creation_input_tokens',
+  ]) {
+    const value = entry[field];
+    if (value !== undefined && value !== null) {
+      if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new ValidationError(`${field} must be a non-negative integer or null`, field);
+      }
+    }
+  }
+
   // OTel alias — #411 additive, schema_version=1 backwards-compat
   if (entry['gen_ai.system'] !== undefined && entry['gen_ai.system'] !== null) {
     if (typeof entry['gen_ai.system'] !== 'string') {
@@ -234,15 +295,22 @@ export function normalizeSubagent(entry) {
   if (!entry || typeof entry !== 'object') return entry;
   return {
     ...entry,
-    schema_version: entry.schema_version ?? CURRENT_SCHEMA_VERSION,
+    schema_version: entry.schema_version ?? LEGACY_SCHEMA_VERSION,
     agent_type: entry.agent_type ?? null,
     parent_session_id: entry.parent_session_id ?? null,
     token_input: entry.token_input ?? null,
     token_output: entry.token_output ?? null,
+    // #1244 additive (schema_version 2) — cache buckets + model id.
+    token_input_uncached: entry.token_input_uncached ?? null,
+    token_cache_read: entry.token_cache_read ?? null,
+    token_cache_creation: entry.token_cache_creation ?? null,
+    model: entry.model ?? null,
     // total_cost_usd — #624 additive, best-effort native cost (null when absent)
     total_cost_usd: entry.total_cost_usd ?? null,
     // OTel alias — #411 additive, schema_version=1 backwards-compat
     'gen_ai.usage.input_tokens': entry['gen_ai.usage.input_tokens'] ?? null,
+    'gen_ai.usage.cache_read_input_tokens': entry['gen_ai.usage.cache_read_input_tokens'] ?? null,
+    'gen_ai.usage.cache_creation_input_tokens': entry['gen_ai.usage.cache_creation_input_tokens'] ?? null,
     'gen_ai.usage.output_tokens': entry['gen_ai.usage.output_tokens'] ?? null,
     'gen_ai.system': entry['gen_ai.system'] ?? null,
   };
@@ -266,7 +334,7 @@ export function migrateLegacySubagent(entry) {
   if (!entry || typeof entry !== 'object') return entry;
   const out = { ...entry };
   if (out.schema_version === undefined || out.schema_version === null) {
-    out.schema_version = CURRENT_SCHEMA_VERSION;
+    out.schema_version = LEGACY_SCHEMA_VERSION;
   }
   return out;
 }

package/scripts/lib/telemetry/pricing.mjs

@@ -0,0 +1,197 @@
+/**
+ * pricing.mjs — USD price table for token-bucket cost estimation (#1244).
+ *
+ * The subagent ledger records four token buckets per stop record
+ * (`token_input_uncached`, `token_cache_read`, `token_cache_creation`,
+ * `token_output`). Each bucket is billed at its OWN rate, so a cost estimate
+ * that multiplies one blended rate by a single token total is wrong by up to
+ * an order of magnitude on a cache-heavy run — which is the whole reason this
+ * table exists rather than a single `$/token` constant.
+ *
+ * ## What is measured and what is derived
+ *
+ * `input` and `output` are the first-party Anthropic API list prices as
+ * published in the bundled model table, sourced on the date `PRICING_TABLE_DATE`
+ * carries (2026-09-09) — that constant is the SSOT, never a second date repeated
+ * in this prose. `cache_read` and `cache_creation` are DERIVED from the
+ * documented ephemeral-cache multipliers (read ≈ 0.1×, 5-minute write ≈ 1.25×
+ * the input rate) except where a row carries a documented figure — Claude Fable
+ * 5.1 publishes $0.25/MTok cache reads directly, which is NOT 0.1× its $10
+ * input rate. Every row therefore declares its own `cache_source` so a reader
+ * never has to guess which numbers were read off a price list and which were
+ * multiplied out here.
+ *
+ * A row with `verified: false` carries a PLACEHOLDER: its numbers are a
+ * best-effort stand-in, never a quoted price. `costUsd()` still prices such a
+ * row (an estimate is more useful than a null when it is labelled), but any
+ * consumer publishing a dollar figure must surface the flag.
+ *
+ * ## Null means UNKNOWN MODEL, never zero
+ *
+ * `priceFor()` and `costUsd()` return `null` for a model this table does not
+ * know. `null` is an honest absence — the same discipline the token rollup
+ * applies to `total_token_input`. Coercing it to `0` fabricates a free run and
+ * is the single most damaging misreading of this module.
+ *
+ * All rates are USD per MILLION tokens.
+ *
+ * @module telemetry/pricing
+ */
+
+/**
+ * The date the `input`/`output` rates in PRICING_TABLE were sourced.
+ * Any consumer quoting a dollar figure should quote this date beside it — a
+ * price without its measurement date ages silently.
+ * @type {string}
+ */
+export const PRICING_TABLE_DATE = '2026-09-09';
+
+/**
+ * @typedef {Object} PricingRow
+ * @property {number} input           - USD per 1M uncached prompt tokens.
+ * @property {number} cache_read      - USD per 1M tokens served from the prompt cache.
+ * @property {number} cache_creation  - USD per 1M tokens written to the prompt cache.
+ * @property {number} output          - USD per 1M completion tokens.
+ * @property {boolean} verified       - false ⇒ the row is a labelled placeholder, not a quoted price.
+ * @property {'documented'|'derived-multiplier'} cache_source - provenance of the two cache rates.
+ */
+
+/**
+ * Per-model USD-per-million-token rates.
+ * @type {Readonly<Record<string, PricingRow>>}
+ */
+export const PRICING_TABLE = Object.freeze({
+  // Claude Fable 5.1 — $10 / $50 list; cache reads documented at $0.25/MTok
+  // (NOT the usual 0.1× multiplier), cache writes derived at 1.25× input.
+  'claude-fable-5-1': Object.freeze({
+    input: 10.0,
+    cache_read: 0.25,
+    cache_creation: 12.5,
+    output: 50.0,
+    verified: true,
+    cache_source: 'documented',
+  }),
+  'claude-opus-5': Object.freeze({
+    input: 5.0,
+    cache_read: 0.5,
+    cache_creation: 6.25,
+    output: 25.0,
+    verified: true,
+    cache_source: 'derived-multiplier',
+  }),
+  'claude-sonnet-5': Object.freeze({
+    input: 2.0,
+    cache_read: 0.2,
+    cache_creation: 2.5,
+    output: 10.0,
+    verified: true,
+    cache_source: 'derived-multiplier',
+  }),
+  'claude-haiku-4-5': Object.freeze({
+    input: 1.0,
+    cache_read: 0.1,
+    cache_creation: 1.25,
+    output: 5.0,
+    verified: true,
+    cache_source: 'derived-multiplier',
+  }),
+});
+
+/**
+ * Explicit aliases for model ids that appear in transcripts but are not the
+ * canonical table key — dated snapshots and the `[1m]` context-window suffix
+ * the harness stamps on long-context sessions.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const MODEL_ALIASES = Object.freeze({
+  'claude-haiku-4-5-20251001': 'claude-haiku-4-5',
+  'claude-opus-5[1m]': 'claude-opus-5',
+  'claude-fable-5-1[1m]': 'claude-fable-5-1',
+  'claude-sonnet-5[1m]': 'claude-sonnet-5',
+});
+
+/**
+ * Look up the rate row for a model id.
+ *
+ * Resolution order: exact key → explicit alias → longest matching table key
+ * that the id starts with (so `claude-opus-5-20260401` and `claude-opus-5[1m]`
+ * both resolve to `claude-opus-5`). Longest-prefix wins so a future
+ * `claude-opus-5-1` row is never shadowed by `claude-opus-5`.
+ *
+ * @param {string|null|undefined} modelId
+ * @returns {PricingRow|null} the row, or null when the model is UNKNOWN
+ *   (never a zero-rate row — see the module header).
+ */
+export function priceFor(modelId) {
+  if (typeof modelId !== 'string') return null;
+  const id = modelId.trim();
+  if (!id) return null;
+
+  if (Object.hasOwn(PRICING_TABLE, id)) return PRICING_TABLE[id];
+
+  const aliased = MODEL_ALIASES[id];
+  if (aliased && Object.hasOwn(PRICING_TABLE, aliased)) return PRICING_TABLE[aliased];
+
+  let best = null;
+  for (const key of Object.keys(PRICING_TABLE)) {
+    if (id.startsWith(key) && (best === null || key.length > best.length)) best = key;
+  }
+  return best === null ? null : PRICING_TABLE[best];
+}
+
+/**
+ * Non-negative finite number within the exactly-representable integer range,
+ * else 0. Absent is 0 — an absent bucket costs nothing; an unknown MODEL is what
+ * yields null (in costUsd, not here).
+ *
+ * The `MAX_SAFE_INTEGER` ceiling is not pedantry: a corrupt bucket of `1e308`
+ * is finite, so it passed the old guard and multiplied out to `Infinity`, which
+ * `JSON.stringify` writes as `null` — the exact encoding this module reserves
+ * for "unknown model". A token count above 2^53 is not a measurement.
+ *
+ * @param {unknown} n
+ * @returns {number}
+ */
+function num(n) {
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= Number.MAX_SAFE_INTEGER
+    ? n
+    : 0;
+}
+
+/**
+ * Estimate the USD cost of one record's four token buckets.
+ *
+ * Each bucket is multiplied by ITS OWN rate — a cache read is ~10× cheaper
+ * than an uncached prompt token and a cache write ~1.25× more expensive, so a
+ * blended rate is not an approximation of this, it is a different number.
+ *
+ * @param {object} opts
+ * @param {string|null|undefined} opts.model            - model id from the transcript
+ * @param {number|null|undefined} opts.tokenInputUncached
+ * @param {number|null|undefined} opts.tokenCacheRead
+ * @param {number|null|undefined} opts.tokenCacheCreation
+ * @param {number|null|undefined} opts.tokenOutput
+ * @returns {number|null} USD cost, or `null` when the model is UNKNOWN.
+ *   **null means "unknown model", never 0.** A caller that coerces it to 0
+ *   reports a free run that was not free.
+ */
+export function costUsd({
+  model,
+  tokenInputUncached,
+  tokenCacheRead,
+  tokenCacheCreation,
+  tokenOutput,
+} = {}) {
+  const row = priceFor(model);
+  if (row === null) return null;
+  const perToken = 1e-6;
+  const cost =
+    num(tokenInputUncached) * row.input * perToken +
+    num(tokenCacheRead) * row.cache_read * perToken +
+    num(tokenCacheCreation) * row.cache_creation * perToken +
+    num(tokenOutput) * row.output * perToken;
+  // Belt and braces beside `num()`'s ceiling: a non-finite total would serialise
+  // as JSON `null` and be indistinguishable from "unknown model". Returning null
+  // deliberately makes that reading TRUE rather than accidental.
+  return Number.isFinite(cost) ? cost : null;
+}

package/scripts/lib/telemetry/sync.mjs

@@ -348,11 +348,46 @@ export function deriveSessionFromEvents(metricsDir) {
     let startedAt = null;
     let sessionType = null;
     let lastTs = null;
+    // `orchestrator.session.shape_resolved` (scripts/lib/session-shape.mjs) is
+    // the plan-time measurement: it fires AFTER the operator picked a mode, and
+    // it is the only event carrying `session_profile`. `session.started`'s mode
+    // predates the choice, and the STATE.md profile read below evaporates the
+    // moment STATE.md is rewritten — so when a shape record exists it wins for
+    // BOTH fields. Latest wins; absent ⇒ the pre-existing behaviour, unchanged.
+    //
+    // "Latest" is decidable only for a record carrying a parseable timestamp. An
+    // UNDATED record has no place in that order and must never displace a dated
+    // one (the earlier `ts === null` disjunct inverted exactly that). It is kept
+    // separately and used only when no dated shape record exists AND the
+    // pre-existing sources below yielded nothing.
+    let shapeType = null;
+    let shapeProfile = null;
+    let shapeTs = null;
+    let undatedShapeType = null;
+    let undatedShapeProfile = null;
 
     for (const ev of events) {
       if (!ev || typeof ev !== 'object') continue;
       const ts = typeof ev.timestamp === 'string' && !Number.isNaN(Date.parse(ev.timestamp)) ? ev.timestamp : null;
       if (ts && (lastTs === null || ts > lastTs)) lastTs = ts;
+      if (ev.event === 'orchestrator.session.shape_resolved') {
+        const type = typeof ev.session_type === 'string' && ev.session_type.trim() !== '' ? ev.session_type.trim() : null;
+        // OMITTED, never null, when the session has no profile — only a
+        // present string may overwrite an earlier reading.
+        const profile =
+          typeof ev.session_profile === 'string' && ev.session_profile.trim() !== '' ? ev.session_profile.trim() : null;
+        if (ts !== null) {
+          if (shapeTs === null || ts >= shapeTs) {
+            shapeTs = ts;
+            if (type !== null) shapeType = type;
+            if (profile !== null) shapeProfile = profile;
+          }
+        } else if (undatedShapeType === null && undatedShapeProfile === null) {
+          undatedShapeType = type;
+          undatedShapeProfile = profile;
+        }
+        continue;
+      }
       if (ev.event !== 'orchestrator.session.started') continue;
       // `mode` is what session-start writes; `session_type` is the ledger's own
       // name for the same fact. Read both — neither is guaranteed present.
@@ -364,10 +399,24 @@ export function deriveSessionFromEvents(metricsDir) {
       }
     }
 
-    if (startedAt === null && sessionType === null) return { session: {}, source: 'absent' };
+    if (shapeType !== null) sessionType = shapeType;
+    // An undated shape record is the weakest reading there is: it wins over
+    // nothing at all, and over nothing else. A dated shape record (shapeTs) or
+    // a `session.started` mode both outrank it.
+    // Type and profile are read as a PAIR from the same record, so the undated
+    // fallback is taken as a pair too — never spliced onto a type another source
+    // supplied.
+    let profile = shapeProfile;
+    if (shapeTs === null && sessionType === null) {
+      sessionType = undatedShapeType;
+      profile = undatedShapeProfile;
+    }
+
+    if (startedAt === null && sessionType === null && profile === null) return { session: {}, source: 'absent' };
 
     const session = {};
     if (sessionType !== null) session.session_type = sessionType;
+    if (profile !== null) session.session_profile = profile;
     if (startedAt !== null) session.started_at = startedAt;
     // completed_at is the last life-sign, never the wall clock — the same
     // omit-never-fabricate contract session-close-backfill.mjs uses (#914 R1).