session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/subagents-schema.mjs

@@ -42,8 +42,16 @@
  *   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.
+ *                                      the transcript exposes none, or when its token-
+ *                                      bearing turns used two or more models or one turn
+ *                                      named none (#1470). Required to price the record —
+ *                                      see scripts/lib/telemetry/pricing.mjs.
+ *   models_usage      array   | absent — per-model breakdown of a record whose token-
+ *                                      bearing turns used two or more models, every
+ *                                      one named (#1470): [{ model, token_input_uncached,
+ *                                      token_cache_read, token_cache_creation,
+ *                                      token_output }], one entry per model. The session
+ *                                      rollup prices each part; absent on every other record.
  *   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)
@@ -115,7 +123,8 @@ export class ValidationError extends Error {
  *
  * Required fields: timestamp, event, agent_id, schema_version.
  * Additional requirement when event='stop': duration_ms (integer or null).
- * Optional: agent_type, parent_session_id, token_input, token_output.
+ * Optional: agent_type, parent_session_id, token_input, token_output, the cache
+ * buckets, model, models_usage, total_cost_usd and the OTel aliases.
  *
  * @param {object} entry
  * @param {object} [options]
@@ -233,6 +242,24 @@ export function validateSubagent(entry, options = {}) {
     throw new ValidationError('model must be a string or null', 'model');
   }
 
+  // models_usage (optional, #1470) — per-model parts of a mixed-model record.
+  // Each part is priced on its own, so each needs a model and four buckets.
+  if (entry.models_usage !== undefined && entry.models_usage !== null) {
+    if (!Array.isArray(entry.models_usage)) {
+      throw new ValidationError('models_usage must be an array or null', 'models_usage');
+    }
+    for (const part of entry.models_usage) {
+      const bucketsValid = ['token_input_uncached', 'token_cache_read', 'token_cache_creation', 'token_output']
+        .every((field) => Number.isInteger(part?.[field]) && part[field] >= 0);
+      if (typeof part?.model !== 'string' || part.model.length === 0 || !bucketsValid) {
+        throw new ValidationError(
+          'models_usage entries must carry a model string and four non-negative integer token buckets',
+          'models_usage'
+        );
+      }
+    }
+  }
+
   // 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) {

package/scripts/lib/tail-window.mjs

@@ -16,6 +16,18 @@
 
 import fs from 'node:fs';
 
+/**
+ * `open(2)` flags of a `noFollow` read. `O_NOFOLLOW` refuses a symlink as the
+ * last path component (ELOOP) in the open itself; `O_NONBLOCK` makes the
+ * read-side open of a FIFO return at once instead of blocking until a writer
+ * appears (a plain `'r'` open of a planted FIFO blocked a detached scan child
+ * for good — reproduced 2026-10-02, #1487). On a regular file `O_NONBLOCK`
+ * changes nothing. Both are POSIX-only; Node leaves them undefined on Windows,
+ * where the read degrades to a plain open.
+ */
+const NO_FOLLOW_READ_FLAGS = fs.constants.O_RDONLY
+  | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+
 /**
  * Read the last `maxBytes` of `file` as UTF-8.
  *
@@ -28,14 +40,26 @@ import fs from 'node:fs';
  * THROWS on any fs error (ENOENT, EACCES, …) — mapping the failure is the
  * caller's decision.
  *
+ * `opts.noFollow` is for a file a hostile local writer may have replaced: it
+ * opens with {@link NO_FOLLOW_READ_FLAGS} and then refuses anything the
+ * descriptor's `fstat` does not call a regular file (FIFO, directory, device),
+ * so a symlink throws ELOOP and every other non-regular file throws
+ * `ERR_NOT_REGULAR_FILE` — never a blocked open, never a read of a link
+ * target. The default (`false`) is the plain `'r'` open every other caller uses.
+ *
  * @param {string} file
  * @param {number} maxBytes  window size in bytes (> 0)
+ * @param {{noFollow?: boolean}} [opts]
  * @returns {{ text: string, cut: boolean, size: number }}  `size` is the file size at open time
  */
-export function readTailWindow(file, maxBytes) {
-  const fd = fs.openSync(file, 'r');
+export function readTailWindow(file, maxBytes, { noFollow = false } = {}) {
+  const fd = fs.openSync(file, noFollow ? NO_FOLLOW_READ_FLAGS : 'r');
   try {
-    const size = fs.fstatSync(fd).size;
+    const stats = fs.fstatSync(fd);
+    if (noFollow && !stats.isFile()) {
+      throw Object.assign(new Error('not a regular file'), { code: 'ERR_NOT_REGULAR_FILE' });
+    }
+    const size = stats.size;
     const want = Math.min(size, maxBytes);
     const start = size - want;
     const buf = Buffer.allocUnsafe(want);

package/scripts/lib/telemetry/pricing.mjs

@@ -1,5 +1,5 @@
 /**
- * pricing.mjs — USD price table for token-bucket cost estimation (#1244).
+ * pricing.mjs — USD price table for token-bucket cost estimation (#1244, #1470).
  *
  * The subagent ledger records four token buckets per stop record
  * (`token_input_uncached`, `token_cache_read`, `token_cache_creation`,
@@ -8,23 +8,39 @@
  * 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
+ * ## Every rate is a documented figure
  *
- * `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.
+ * All four rates of every row are first-party Anthropic API list prices, read
+ * off the price page each row names in `source_url` on the date
+ * `PRICING_TABLE_DATE` carries — that constant is the SSOT, never a second date
+ * repeated in this prose. Nothing here is multiplied out. `cache_read` in
+ * particular is never derived from `input`: the ratio is not a constant (Opus
+ * 5.5 reads at 0.05× its input rate, Fable 5.1 at 0.025×, Fable 5 at 0.1×), so
+ * a multiplier would misprice exactly the cache-heavy runs this table exists
+ * for. Each row carries its own provenance fields, so a consumer quoting a
+ * dollar figure can cite where it came from without reading this file.
  *
- * 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.
+ * `verified: false` would mark a PLACEHOLDER row — a best-effort stand-in,
+ * never a quoted price. No current row carries it; a consumer publishing a
+ * dollar figure must still surface the flag.
+ *
+ * ## Only exact ids resolve
+ *
+ * `priceFor()` accepts an exact table key or an explicit `MODEL_ALIASES` entry
+ * and nothing else. Until #1470 it fell back to the longest table key an id
+ * started with, which handed an unlisted generation the rates of its nearest
+ * neighbour, marked verified.
+ *
+ * ## Series break (#1470, 2026-09-29)
+ *
+ * Session reports written before this fix priced records through that
+ * fallback: `claude-opus-5-5` at `claude-opus-5` rates, `claude-sonnet-5-5` at
+ * `claude-sonnet-5` rates (identical numbers, by coincidence rather than
+ * evidence), and `claude-fable-5` / `claude-opus-4-8` not at all. Nothing
+ * rewrites that history — the metrics ledgers are append-only. Measured
+ * 2026-09-29: 0 of the 9 priced sessions.jsonl reports in this repo contained
+ * such records (the first one reached subagents.jsonl after the last priced
+ * report was written).
  *
  * ## Null means UNKNOWN MODEL, never zero
  *
@@ -39,68 +55,96 @@
  */
 
 /**
- * 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.
+ * The date the rates in PRICING_TABLE were read off the price page. Every row's
+ * `checked_at` equals it. 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';
+export const PRICING_TABLE_DATE = '2026-09-29';
 
 /**
  * @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} cache_creation  - USD per 1M tokens written to the prompt cache
+ *   (the `cache_write_ttl` rate).
  * @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.
+ *   Every current row is 'documented'; 'derived-multiplier' is kept for a future row whose cache
+ *   rates are multiplied out and must say so.
+ * @property {string} source_url      - the page all four rates were read from.
+ * @property {string} checked_at      - ISO date the rates were read; equals PRICING_TABLE_DATE.
+ * @property {'anthropic'} provider
+ * @property {'5m'} cache_write_ttl   - which cache-write rate `cache_creation` is.
+ * @property {string} unit            - 'USD per 1M tokens'.
+ * @property {string} surface         - the billing surface and speed the rates apply to.
+ * @property {'standard'} tier        - the service tier the rates apply to.
+ */
+
+/** Provenance shared by every current row — all read off one page on one date. */
+const PROVENANCE = Object.freeze({
+  verified: true,
+  cache_source: 'documented',
+  source_url: 'https://platform.claude.com/docs/en/about-claude/pricing',
+  checked_at: PRICING_TABLE_DATE,
+  provider: 'anthropic',
+  cache_write_ttl: '5m',
+  unit: 'USD per 1M tokens',
+  surface: 'Claude API (first-party), standard speed',
+  tier: 'standard',
+});
+
+/**
+ * One frozen documented row: four USD rates plus the shared provenance. The
+ * rates are spread last, so provenance can never overwrite a price.
+ * @param {{input: number, cache_read: number, cache_creation: number, output: number}} rates
+ * @returns {PricingRow}
  */
+function usd(rates) {
+  return Object.freeze({ ...PROVENANCE, ...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',
-  }),
+  // Ceiling: only the 5-minute cache-write rate is priced; a 1-hour write costs 2× input
+  // (Opus 5.5: $8/MTok) and would be under-priced here. Measured 2026-09-29 over 803,788
+  // assistant usage blocks in 10,745 subagent transcripts: `usage.cache_creation
+  // .ephemeral_1h_input_tokens > 0` on 0 blocks. Revisit when the first such block appears.
+  //
+  // Ceiling: list price only — fast mode, `inference_geo: "us"` (1.1×) and batch discounts are
+  // not modelled. Measured 2026-09-29: `usage.speed` = "fast" on 0 of the 374,331 blocks that
+  // carry the field; `inference_geo` = "not_available" on 803,479 and no other value seen.
+  // Revisit when either field shows another value.
+  //
+  // Ceiling: a model absent from this table prices as null, never at a neighbour's rate, so the
+  // rollup reports `total_cost_usd: null` and `cost_records_priced < cost_records_total` — the
+  // intended way missing evidence shows up. That ratio also drops below 1 for agents no row can
+  // fix: a token-less record (transcript over the hook's size cap, without usage turns, or
+  // unreadable), a record with a token-bearing turn that names no model (#1475), a started agent
+  // whose stop found no transcript of its own, and an agent seen only in schema_version 1 records
+  // (#1487 Pkt 1). The one complete list is the `session-token-rollup.mjs` module doc — the code
+  // that decides; this comment and `emit-session.mjs` only point at it (#1498). Revisit when
+  // an unpriced record names a model id absent from this table: add that model as its own
+  // evidenced row, never as a family prefix or an alias to another generation.
+  'claude-fable-5-1': usd({ input: 10.0, cache_read: 0.25, cache_creation: 12.5, output: 50.0 }),
+  'claude-fable-5': usd({ input: 10.0, cache_read: 1.0, cache_creation: 12.5, output: 50.0 }),
+  'claude-opus-5-5': usd({ input: 4.0, cache_read: 0.2, cache_creation: 5.0, output: 20.0 }),
+  'claude-opus-5': usd({ input: 5.0, cache_read: 0.5, cache_creation: 6.25, output: 25.0 }),
+  'claude-opus-4-8': usd({ input: 5.0, cache_read: 0.5, cache_creation: 6.25, output: 25.0 }),
+  'claude-sonnet-5-5': usd({ input: 2.0, cache_read: 0.2, cache_creation: 2.5, output: 10.0 }),
+  'claude-sonnet-5': usd({ input: 2.0, cache_read: 0.2, cache_creation: 2.5, output: 10.0 }),
+  'claude-haiku-4-5': usd({ input: 1.0, cache_read: 0.1, cache_creation: 1.25, output: 5.0 }),
 });
 
 /**
  * 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.
+ * canonical table key — a dated snapshot of the SAME model and the `[1m]`
+ * context-window suffix the harness stamps on long-context sessions. An alias
+ * never points at another generation.
  * @type {Readonly<Record<string, string>>}
  */
 export const MODEL_ALIASES = Object.freeze({
@@ -113,10 +157,19 @@ export const MODEL_ALIASES = Object.freeze({
 /**
  * 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`.
+ * Resolution: exact `PRICING_TABLE` key → explicit `MODEL_ALIASES` entry → `null`,
+ * after trimming surrounding whitespace.
+ * Nothing else resolves — no prefix, no pattern, no family fallback — so
+ * `claude-opus-5-20260401`, `claude-opus-5-99` and `claude-haiku-4-5-20251002` are
+ * all UNKNOWN even though each starts with a table key.
+ *
+ * Why no prefix: from the 4.6 generation on, Anthropic ships dateless pinned
+ * model ids (https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions,
+ * retrieved 2026-09-29). The ids that extend a current table key are therefore
+ * other generations, not snapshots of it — `claude-opus-5-5` extends
+ * `claude-opus-5` — and a prefix match priced them at another generation's
+ * rates, marked verified (#1470). A future generation gets its own evidenced
+ * row, never a family prefix.
  *
  * @param {string|null|undefined} modelId
  * @returns {PricingRow|null} the row, or null when the model is UNKNOWN
@@ -129,14 +182,10 @@ export function priceFor(modelId) {
 
   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;
+  if (Object.hasOwn(MODEL_ALIASES, id) && Object.hasOwn(PRICING_TABLE, MODEL_ALIASES[id])) {
+    return PRICING_TABLE[MODEL_ALIASES[id]];
   }
-  return best === null ? null : PRICING_TABLE[best];
+  return null;
 }
 
 /**
@@ -161,9 +210,10 @@ function num(n) {
 /**
  * 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.
+ * Each bucket is multiplied by ITS OWN rate — depending on the row, a cache
+ * read costs a tenth to a fortieth of an uncached prompt token and a 5-minute
+ * cache write 1.25× as much, 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

package/scripts/lib/telemetry/sync.mjs

@@ -312,6 +312,23 @@ export function readSessionProfileForMetricsDir(metricsDir) {
   }
 }
 
+/**
+ * Events window this reader needs retained (#1401 part 3), in days — a CHOSEN
+ * ceiling, not a derived value. `deriveSessionFromEvents` loads the whole
+ * rotated ledger (no time filter) and keeps the LATEST
+ * `orchestrator.session.started`, so what it needs retained is that one
+ * record; 1 day is the assumed maximum age of that record when a flush reads
+ * it. Nothing in this module bounds that age: `buildBatch`'s
+ * `[now - DAILY_FLUSH_MS, now]` cutoff filters `skill-invocations.jsonl`, not
+ * the events ledger. CEILING (BV-004): a latest `session.started` older than a
+ * day at flush time (a session running longer than that) is found only if
+ * retention happens to reach it; revisit if that becomes common. Read by
+ * `scripts/lib/events-retention-banner.mjs`.
+ *
+ * @type {number}
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = 1;
+
 /**
  * Reconstruct the session facts a ping needs (`session_type`, `started_at`,
  * `completed_at`) from `<metricsDir>/events.jsonl` when `sessions.jsonl` has no