@dzhechkov/harness-core 0.8.46 → 0.8.47

package/src/run-records.ts

@@ -13,11 +13,28 @@
  * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
  */
 
+import { createHash } from 'node:crypto';
 import { matchCodexRollouts } from './codex-rollouts.js';
 import type { CodexRollout } from './codex-rollouts.js';
-import { redactTrainingPayload } from './feature-adr-checkpoints.js';
+import { fnv1a64, redactTrainingPayload } from './feature-adr-checkpoints.js';
 import { validateExperimentEnvelope } from './feature-adr-envelope.js';
 
+// Capture contract: ordered named fields, with absent distinct from explicit null.
+// Kept private at producer/reader boundaries; both use this exact sha256 representation.
+function capturedPayload(evidence: Record<string, unknown>): string {
+  const value = (v: unknown) => v === undefined ? { absent: true } : v;
+  const receipts = Array.isArray(evidence['receipts']) ? evidence['receipts'] : [];
+  return JSON.stringify([
+    ...['schema', 'sessionId', 'turnId', 'sourcePath', 'matchBasis', 'capturedFrom', 'capturedTo', 'model', 'cwd', 'reportedTotalBasis', 'inputCacheSemantics'].map((k) => [k, value(evidence[k])]),
+    ['owner', ...['runId', 'taskId', 'stage', 'attempt', 'role'].map((k) => [k, value((evidence['owner'] as Record<string, unknown> | undefined)?.[k])])],
+    receipts.map((raw) => {
+      const r = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {}; const t = r['totals'] as Record<string, unknown> | undefined;
+      return [...['key', 'responseId', 'turnId', 'turnIndex', 'timestamp', 'payloadDigest', 'source'].map((k) => [k, value(r[k])]),
+        ['totals', ...['input', 'output', 'cachedInput', 'cachedWrite', 'reasoning', 'total'].map((k) => [k, value(t?.[k])])]];
+    }),
+  ]);
+}
+
 /** Structural — a caller passes `cost-scoring.ts`'s `ModelPricing`; kept local so `run-records.ts`
  *  does not have to import `cost-scoring.ts` just to name a type.
  *
@@ -86,6 +103,44 @@ export function parseModelSpec(spec: unknown): ParsedModelSpec | null {
   return null;
 }
 
+/** Internal shared ledger authority resolver; not a package-public barrel API.
+ * Capture/source values are comparison targets and never participate in claimant resolution. */
+export function resolveLedgerModelProvenance(row: Readonly<Record<string, unknown>>) {
+  const diagnostics: string[] = [];
+  const canonicalFamily = (v: string) => v === 'openai' ? 'codex' : v;
+  const direct = typeof row['model'] === 'string' && row['model'].length <= 128 && /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?$/.test(row['model']) ? row['model'] : null;
+  if (row['model'] != null && direct === null) diagnostics.push('model-invalid-direct');
+  const family = typeof row['family'] === 'string' && SPEC_PART.test(row['family']) ? row['family'] : null;
+  if (row['family'] != null && family === null) diagnostics.push('model-invalid-family');
+  const specs: ParsedModelSpec[] = []; const familyHints: string[] = [];
+  for (const key of ['coder', 'reviewer']) {
+    const raw = row[key]; if (raw == null) continue;
+    if (raw === 'codex' || raw === 'claude') { familyHints.push(raw); continue; }
+    const spec = parseModelSpec(raw);
+    const parts = typeof raw === 'string' ? raw.trim().split(':') : [];
+    if (!spec || !SPEC_PART.test(spec.model) || (parts[0] === 'claude' && parts.length !== 2)) {
+      diagnostics.push('model-invalid-executor:' + key); continue;
+    }
+    specs.push(spec); familyHints.push(spec.family);
+  }
+  const models = new Set(specs.map((v) => v.model)); const families = new Set(familyHints);
+  if (models.size > 1 || families.size > 1) diagnostics.push('model-executor-conflict');
+  const unique = models.size === 1 ? specs[0]! : null;
+  if (direct !== null && unique && direct !== unique.model) diagnostics.push('model-direct-executor-conflict');
+  if (family !== null && [...families].some((v) => canonicalFamily(family) !== v)) diagnostics.push('model-family-conflict');
+  const declaredProvenance = row['modelProvenance'];
+  const validProvenance = new Set(['caller-recorded', 'executor-spec', 'provider-reported', 'dispatcher-reported', 'probed-request', 'not-recorded']);
+  if (declaredProvenance != null && (typeof declaredProvenance !== 'string' || !validProvenance.has(declaredProvenance))) diagnostics.push('model-invalid-provenance');
+  if (declaredProvenance === 'executor-spec' && (!unique || (direct !== null && direct !== unique.model))) diagnostics.push('model-provenance-conflict');
+  if (declaredProvenance != null && declaredProvenance !== 'executor-spec' && declaredProvenance !== 'not-recorded' && direct === null) diagnostics.push('model-provenance-conflict');
+  const conflict = diagnostics.some((d) => /invalid|conflict/.test(d));
+  const model = conflict ? null : direct ?? unique?.model ?? null;
+  if (model === null && !conflict) diagnostics.push('model-not-recorded');
+  const resolvedFamily = family ?? (families.size === 1 ? [...families][0]! : null);
+  return { model, family: resolvedFamily, modelProvenance: model === null ? 'not-recorded' : direct !== null
+    ? typeof declaredProvenance === 'string' ? declaredProvenance : 'caller-recorded' : 'executor-spec', diagnostics };
+}
+
 /** measurement-integrity FR-5/FR-6: enrichment the WRITER supplies at write time — the rollout logs
  *  it already read (I/O lives in the CLI; this stays pure) and the price table snapshot. Absent
  *  entirely ⇒ zero behavior change from before this feature (NFR-1). */
@@ -93,6 +148,9 @@ export interface LedgerEnrichInput {
   /** Parsed Codex rollout logs for the window the CLI read — usually every rollout from the days the
    *  window spans. Pure data; the CLI is the one that walked `~/.codex/sessions`. */
   readonly rollouts?: readonly CodexRollout[];
+  readonly rolloutId?: string;
+  readonly turnId?: string;
+  readonly discoveryDiagnostics?: readonly string[];
   /** The stage's own time window — usually [the previous ledger row's `ts`, this write's `ts`], or
    *  an explicit `--window-from/--window-to`. Omitted ⇒ no rollout match is even attempted. */
   readonly window?: { readonly from: string; readonly to: string };
@@ -492,32 +550,29 @@ export function decideRecordWrite(input: {
     // one that already has a token figure, is left untouched. The loose `/codex/i` check below only
     // decides whether this row is WORTH TRYING at all.
     const tokensIsNull = stamped['tokens'] === null;
-    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']);
-    if (tokensIsNull && looksCodexFamily) {
-      // measurement-integrity fix-round-1/F4 (Codex r1 HIGH #4): the matcher REQUIRES a reliable
-      // model, parsed the same way FR-7's price lookup parses one — never `/codex/i` alone. If
-      // `coder`/`reviewer` do not resolve to exactly ONE codex model between them (a bare `'codex'`
-      // with no model at all, or the two fields naming DIFFERENT codex models), the matcher is never
-      // even called with an unreliable/omitted model filter — a lone rollout in the window would
-      // otherwise be accepted as `'one'` on time+cwd alone and its tokens misattributed to the wrong
-      // model's stage.
-      const codexModels = new Set(
-        [parseModelSpec(stamped['coder']), parseModelSpec(stamped['reviewer'])]
-          .filter((s): s is ParsedModelSpec => s !== null && s.family === 'codex')
-          .map((s) => s.model),
-      );
-      if (codexModels.size !== 1) {
+    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']) || stamped['family'] === 'codex' || stamped['family'] === 'openai';
+    if (enrich.discoveryDiagnostics?.length) {
+      stamped['usageDiagnostics'] = enrich.discoveryDiagnostics;
+      stamped['tokensSource'] = 'codex-rollout:source-discovery-unavailable';
+    } else if ((tokensIsNull || enrich.rolloutId !== undefined || enrich.turnId !== undefined) && looksCodexFamily) {
+      // Use the same authority contract as the readonly source comparison and normalized report.
+      // A direct model or unique agreeing executor specs supply authority; a source never does.
+      const identity = resolveLedgerModelProvenance(stamped);
+      if (identity.model === null || !['codex', 'openai'].includes(identity.family ?? '')) {
         stamped['tokensSource'] = 'codex-rollout:no-model';
-      } else if (enrich.window !== undefined) {
-        const model = [...codexModels][0]!;
+        stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), ...identity.diagnostics];
+      } else if (enrich.window !== undefined || enrich.rolloutId !== undefined || enrich.turnId !== undefined) {
+        const model = identity.model;
         const match = matchCodexRollouts(enrich.rollouts ?? [], {
-          from: enrich.window.from,
-          to: enrich.window.to,
+          ...(enrich.window !== undefined ? { from: enrich.window.from, to: enrich.window.to } : {}),
           model,
+          ...(enrich.rolloutId !== undefined ? { rolloutId: enrich.rolloutId } : {}),
+          ...(enrich.turnId !== undefined ? { turnId: enrich.turnId } : {}),
           ...(enrich.cwd !== undefined ? { cwd: enrich.cwd } : {}),
         });
         if (match.status === 'one') {
-          stamped['tokens'] = match.rollout.totals.total;
+          if (tokensIsNull || stamped['tokens'] === undefined) stamped['tokens'] = match.rollout.totals.total;
+          else if (stamped['tokens'] !== match.rollout.totals.total) stamped['usageDiagnostics'] = ['caller-source-total-mismatch'];
           const startMs = match.rollout.startedAt !== null ? Date.parse(match.rollout.startedAt) : NaN;
           const endMs = match.rollout.endedAt !== null ? Date.parse(match.rollout.endedAt) : NaN;
           // measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): fill-ONLY-null — an existing
@@ -528,9 +583,26 @@ export function decideRecordWrite(input: {
           }
           stamped['tokensSource'] = 'codex-rollout';
           stamped['rolloutId'] = match.rollout.id;
+          const found = match.rollout;
+          for (const [key, value] of Object.entries({ tokensTotal: found.totals.total, tokensIn: found.totals.input,
+            tokensOut: found.totals.output, tokensCacheRead: found.totals.cachedInput, tokensCacheWrite: found.totals.cachedWrite ?? null,
+            tokensReasoning: found.totals.reasoning, reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            usageDiagnostics: found.diagnostics ?? [] })) if (stamped[key] === undefined || stamped[key] === null) stamped[key] = value;
+          const receipts = (found.receipts ?? []).map((receipt) => ({ ...receipt, key: JSON.stringify([found.id, receipt.key]) }));
+          const usageEvidence: Record<string, unknown> = { schema: 'codex-rollout-scope-1', sessionId: found.id, turnId: found.turnId ?? null,
+            sourcePath: found.sourcePath ?? null, matchBasis: enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact' : 'legacy-window',
+            capturedFrom: found.startedAt, capturedTo: found.endedAt, receipts, model: found.model, cwd: found.cwd,
+            owner: Object.fromEntries(['runId', 'taskId', 'stage', 'attempt', 'role'].map((key) => [key, stamped[key] ?? null])),
+            reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            payloadDigest: fnv1a64(JSON.stringify(receipts.map((r) => [r.key, r.payloadDigest]))) };
+          usageEvidence['captureSha256'] = createHash('sha256').update(capturedPayload(usageEvidence)).digest('hex');
+          if (JSON.stringify(usageEvidence).length <= 16000) {
+            if (stamped['usageEvidence'] === undefined || stamped['usageEvidence'] === null) stamped['usageEvidence'] = usageEvidence;
+          } else stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), 'source-scope-over-record-limit'];
+
         } else {
           // `none` or `ambiguous` — NFR-3: an explicit status, never a guessed number.
-          stamped['tokensSource'] = `codex-rollout:${match.status}`;
+          stamped['tokensSource'] = `codex-rollout:${enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact-' : ''}${match.status}`;
         }
       } else {
         // Eligible in principle (codex family, one reliable model, tokens null) but no window was
@@ -544,6 +616,7 @@ export function decideRecordWrite(input: {
     // above (a Claude row gets priced too; only tokens enrichment is codex-specific).
     if (enrich.prices !== undefined) {
       const modelIds = new Set<string>();
+      if (typeof stamped['model'] === 'string' && stamped['model'].trim()) modelIds.add(stamped['model'].trim());
       for (const v of [stamped['coder'], stamped['reviewer']]) {
         if (typeof v === 'string' && v.trim() !== '') modelIds.add(v.trim());
       }
@@ -566,7 +639,13 @@ export function decideRecordWrite(input: {
         if (price === null) unknown.push(modelId);
         else table[modelId] = { prompt: price.prompt, completion: price.completion, cachedInput: price.cachedInput, cacheCreation: price.cacheCreation };
       }
+      const matches = Object.fromEntries([...modelIds].map((id) => {
+        const parsed = parseModelSpec(id); const normalized = parsed?.family === 'claude' ? 'claude-' + parsed.model : parsed?.model ?? id;
+        const key = Object.keys(enrich.prices ?? {}).filter((k) => normalized.toLowerCase().startsWith(k)).sort((a,b) => b.length-a.length)[0] ?? null;
+        return [id, { tableKey: key, kind: key !== null && key === normalized && !key.includes('claude') ? 'exact' : key !== null ? 'family-estimate' : 'unknown' }];
+      }));
       const computedPrices = {
+        matches,
         snapshotAt: input.timestamp ?? null,
         table,
         ...(unknown.length > 0 ? { unknown } : {}),

package/src/stage-usage.ts

@@ -0,0 +1,191 @@
+/** Derived stage usage only. Source IO and independent witnesses belong to cost-ledger.ts. */
+import { MODEL_PRICES } from './cost-scoring.js';
+import { canonicalStage } from './feature-adr-stage-canon.js';
+import { fnv1a64 } from './feature-adr-checkpoints.js';
+import { parseModelSpec, resolveLedgerModelProvenance } from './run-records.js';
+
+type RecordRow = Record<string, unknown>;
+const record = (v: unknown): v is RecordRow => !!v && typeof v === 'object' && !Array.isArray(v);
+const count = (v: unknown): number | null => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : null;
+const text = (v: unknown): string | null => typeof v === 'string' && v.trim() ? v : null;
+const tokenFields = ['tokensTotal', 'tokensIn', 'tokensOut', 'tokensCacheRead', 'tokensCacheWrite', 'tokensReasoning'] as const;
+
+function price(row: RecordRow, dimensions: Record<typeof tokenFields[number], number | null>) {
+  const model = text(row['model']); const normalized = model?.toLowerCase().replace(/^[a-z0-9-]+\//, '') ?? '';
+  let tableKey = Object.keys(MODEL_PRICES).filter((key) => normalized.startsWith(key)).sort((a, b) => b.length - a.length)[0] ?? null;
+  if (!tableKey && ['sonnet', 'opus', 'haiku'].includes(normalized)) tableKey = 'claude-' + normalized;
+  let matchKind: 'exact' | 'family-estimate' | 'unknown' = tableKey === null ? 'unknown'
+    : tableKey === normalized && !tableKey.includes('claude') ? 'exact' : 'family-estimate';
+  let rate = tableKey === null ? null : MODEL_PRICES[tableKey]!;
+  let source = 'MODEL_PRICES static snapshot';
+  const prices = record(row['prices']) ? row['prices'] : null;
+  const matches = prices && record(prices['matches']) ? prices['matches'] : null;
+  const table = prices && record(prices['table']) ? prices['table'] : null;
+  if (prices) {
+    // Never silently reprice a historical snapshot using today's table or its alias spelling.
+    rate = null; matchKind = 'unknown'; tableKey = null; source = 'persisted snapshot lacking applicable match provenance';
+    for (const alias of [model, text(row['coder']), text(row['reviewer'])]) {
+      if (!alias || !model || !table || !matches || !record(table[alias]) || !record(matches[alias])) continue;
+      const aliasModel = parseModelSpec(alias)?.model ?? alias;
+      if (aliasModel !== model) continue;
+      const proposed = table[alias]; const match = matches[alias];
+      const key = text(match['tableKey']); const kind = match['kind'];
+      if (key === null || !['exact', 'family-estimate'].includes(String(kind))) continue;
+      if (kind === 'exact' && (key !== model || key.includes('claude'))) continue;
+      if (kind === 'family-estimate' && !(normalized.startsWith(key) || ('claude-' + normalized).startsWith(key))) continue;
+      if (['prompt', 'completion', 'cachedInput', 'cacheCreation'].every((field) => typeof proposed[field] === 'number' && Number.isFinite(proposed[field]) && (proposed[field] as number) >= 0)) {
+        rate = proposed as unknown as NonNullable<typeof rate>; matchKind = kind as 'exact' | 'family-estimate'; tableKey = key; source = 'persisted declared ' + matchKind + ' snapshot'; break;
+      }
+    }
+  }
+  const { tokensIn: input, tokensOut: output, tokensCacheRead: read, tokensCacheWrite: write } = dimensions;
+  const semantics = row['inputCacheSemantics'];
+  let amount: number | null = null;
+  if (rate && input !== null && output !== null && read !== null && write !== null) {
+    const plainInput = semantics === 'includes-cache-read-write' ? input - read - write
+      : semantics === 'excludes-cache-read-write' ? input : null;
+    if (plainInput !== null && plainInput >= 0) amount = plainInput * rate.prompt + output * rate.completion + read * rate.cachedInput + write * rate.cacheCreation;
+  }
+  if (amount !== null && (!Number.isFinite(amount) || (Array.isArray(row['usageDiagnostics']) && row['usageDiagnostics'].some((v) => typeof v === 'string' && /invalid|mismatch|conflict|exceeds|overflow/.test(v))))) amount = null;
+  return { estimatedCostUsd: matchKind === 'exact' ? amount : null, familyEstimatedCostUsd: matchKind === 'family-estimate' ? amount : null,
+    pricingKnown: matchKind === 'exact' && amount !== null,
+    pricingReason: matchKind === 'unknown' ? 'unknown-model-rate' : amount === null ? 'incomplete-priceable-mix' : matchKind === 'family-estimate' ? 'family-rate-is-not-exact-model' : null,
+    priceMatch: { tableKey, matchKind, source, version: text(prices?.['version']) ?? (prices ? 'persisted-version-not-recorded' : 'MODEL_PRICES-unversioned'),
+      capturedAt: text(prices?.['snapshotAt']), fingerprint: fnv1a64(JSON.stringify(prices ?? MODEL_PRICES)), current: false, billed: false } };
+}
+
+/** All amounts remain source-specific; inventory never substitutes for a numeric witness. */
+export function buildStageUsageReport(input: {
+  sourceKind: string; sourcePath: string; runId: string | null; rows: readonly RecordRow[];
+  expected?: readonly RecordRow[]; witnesses?: readonly RecordRow[]; moneyObservations?: readonly RecordRow[];
+  diagnostics?: readonly string[]; sourceDiagnostics?: readonly string[]; maxRecords?: number;
+}) {
+  const diagnostics = [...(input.diagnostics ?? [])]; const sourceDiagnostics = [...(input.sourceDiagnostics ?? [])];
+  const maximum = input.maxRecords ?? 100000;
+  if (input.rows.length > maximum) diagnostics.push('inventory-truncated');
+  const originalKeys = new Set(input.rows.map((v) => text(v['evidenceKey']) ?? (count(v['dispatchSeq']) !== null ? JSON.stringify(['wf-dispatch', v['runId'], v['dispatchSeq']]) : null)));
+  const witnessOnly: RecordRow[] = (input.witnesses ?? []).filter((v) => !originalKeys.has(text(v['evidenceKey']))).map((v) => ({ ...v, runId: input.runId, stage: null, phase: null, stepId: null, unassignedSource: true }));
+  const normalized = [...input.rows, ...witnessOnly].slice(0, maximum).map((raw, index) => {
+    const identity = resolveLedgerModelProvenance(raw);
+    const { model, family } = identity;
+    diagnostics.push(...identity.diagnostics);
+    const phase = text(raw['phase']);
+    const stage = input.sourceKind === 'workflow-budget' ? phase ?? text(raw['stage']) ?? text(raw['stepId']) : text(raw['stage']) ?? phase ?? text(raw['stepId']);
+    const dimensions = Object.fromEntries(tokenFields.map((key) => [key, count(raw[key])])) as Record<typeof tokenFields[number], number | null>;
+    if (raw['tokensTotal'] === undefined && raw['tokens'] !== undefined) dimensions.tokensTotal = count(raw['tokens']);
+    for (const key of tokenFields) if (raw[key] != null && count(raw[key]) === null) diagnostics.push('invalid-count:' + index + ':' + key);
+    const dispatchSeq = count(raw['dispatchSeq']);
+    const evidenceKey = text(raw['evidenceKey']) ?? (input.sourceKind === 'workflow-budget' && dispatchSeq !== null
+      ? JSON.stringify(['wf-dispatch', raw['runId'], dispatchSeq]) : null);
+    const metadata = { phase, role: text(raw['role']), attempt: count(raw['attempt']), dispatchSeq, itemKey: text(raw['itemKey']),
+      stepId: text(raw['stepId']), tier: text(raw['tier']), mode: text(raw['mode']) };
+    const missingReasons = Object.entries({ model, family, stage, evidenceKey, ...metadata }).filter(([, value]) => value === null).map(([key]) => key + ':not-recorded');
+    const basis = text(raw['reportedTotalBasis']) ?? (raw['tokensOutSource'] === 'budget.spent' ? 'output-only' : 'unknown');
+    const priced = price({ ...raw, model, usageDiagnostics: [...(Array.isArray(raw['usageDiagnostics']) ? raw['usageDiagnostics'] : []), ...identity.diagnostics] }, dimensions);
+    const reportedCostUsd = typeof raw['reportedCostUsd'] === 'number' && Number.isFinite(raw['reportedCostUsd']) && raw['reportedCostUsd'] >= 0 ? raw['reportedCostUsd'] : null;
+    const usageDiagnostics = Array.isArray(raw['usageDiagnostics']) ? raw['usageDiagnostics'].filter((v): v is string => typeof v === 'string') : [];
+    diagnostics.push(...usageDiagnostics.map((v) => 'usage:' + v));
+    const rawSource = record(raw['usageSource']) ? raw['usageSource'] : null;
+    const usageSource = rawSource ? Object.fromEntries(['schema', 'scope', 'threadId', 'turnId', 'receiptId'].map((key) => [key, text(rawSource[key])])) : null;
+    const estimate = record(raw['estimate']) ? { tokens: count(raw['estimate']['tokens']),
+      costUsd: typeof raw['estimate']['costUsd'] === 'number' && Number.isFinite(raw['estimate']['costUsd']) ? raw['estimate']['costUsd'] : null,
+      method: text(raw['estimate']['method']), source: text(raw['estimate']['source']), capturedAt: text(raw['estimate']['capturedAt']) } : null;
+    return { sourceKind: input.sourceKind, evidenceKey, runId: text(raw['runId']), stage, stageCanonical: canonicalStage(stage ?? '').stage,
+      model, family, modelProvenance: identity.modelProvenance, requestedModel: text(raw['requestedModel']), totalDerivation: text(raw['totalDerivation']) ?? 'not-recorded', ...metadata, ...dimensions, reportedTotalBasis: basis, inputCacheSemantics: text(raw['inputCacheSemantics']) ?? 'unknown',
+      usageSource, reportedCostUsd, billedCostUsd: null, billedCostReason: 'not-observed',
+      estimate, estimateReason: estimate === null ? 'not-recorded' : null,
+      ...priced, missingReasons, outcome: text(raw['outcome']), usageDiagnostics, unassignedSource: raw['unassignedSource'] === true };
+  });
+  type Normalized = typeof normalized[number];
+  const unique = new Map<string, Normalized>(); const owners = new Map<string, Set<string>>(); const conflicts = new Set<string>();
+  const unkeyed: Normalized[] = [];
+  const payload = (row: Normalized) => JSON.stringify([row.model, row.family, ...tokenFields.map((k) => row[k]), row.reportedTotalBasis, row.inputCacheSemantics, row.reportedCostUsd]);
+  for (const row of normalized) {
+    if (input.runId !== null && row.runId !== input.runId) { diagnostics.push('foreign-run'); continue; }
+    if (row.evidenceKey === null) { diagnostics.push('missing-evidence-identity'); unkeyed.push(row); continue; }
+    const prior = unique.get(row.evidenceKey);
+    if (prior && payload(prior) !== payload(row)) { conflicts.add(row.evidenceKey); diagnostics.push('conflicting-duplicate:' + row.evidenceKey); }
+    else unique.set(row.evidenceKey, prior ?? row);
+    const claim = JSON.stringify([row.stage, row.attempt, row.stepId, row.itemKey, row.role]);
+    const set = owners.get(row.evidenceKey) ?? new Set<string>(); set.add(claim); owners.set(row.evidenceKey, set);
+  }
+  const expected = input.expected === undefined ? null : new Map(input.expected.map((v) => [text(v['evidenceKey']) ?? JSON.stringify(['wf-dispatch', v['runId'], v['dispatchSeq']]), v]));
+  const rows = [...unique.values()].filter((row) => {
+    if (expected && !expected.has(row.evidenceKey!)) { diagnostics.push('foreign-evidence:' + row.evidenceKey); return false; }
+    const trace = expected?.get(row.evidenceKey!);
+    if (trace) for (const key of ['runId', 'stepId', 'itemKey', 'attempt', 'model', 'phase'] as const) {
+      if (trace[key] != null && trace[key] !== (key === 'model' ? (row.requestedModel ?? row.model) : row[key])) diagnostics.push('inventory-identity-mismatch:' + key);
+    }
+    return !conflicts.has(row.evidenceKey!);
+  }).concat(unkeyed);
+  const sum = (values: readonly number[]): number | null => {
+    const total = values.reduce((n, v) => n + v, 0); if (!Number.isSafeInteger(total)) { diagnostics.push('aggregate-overflow'); return null; } return total;
+  };
+  const bases = [...new Set(rows.filter((row) => row.tokensTotal !== null).map((row) => row.reportedTotalBasis))];
+  const compatible = bases.length <= 1;
+  if (!compatible) diagnostics.push('incompatible-total-bases');
+  const metric = bases[0] === 'raw-inclusive' ? 'raw-tokens' : bases[0] === 'uncached-display' ? 'uncached-display-tokens' : bases[0] === 'weighted-input-equivalent' ? 'weighted-input-equivalent' : 'source-reported-total';
+  const known = compatible ? sum(rows.map((row) => row.tokensTotal).filter((v): v is number => v !== null)) : null;
+  const expectedMissing = expected ? [...expected.keys()].filter((key) => !originalKeys.has(key) || conflicts.has(key)) : [];
+  const missingTotals = rows.filter((row) => row.tokensTotal === null).length + expectedMissing.length;
+  const inventoryComplete = expected !== null && expectedMissing.length === 0 && unkeyed.length === 0
+    && !diagnostics.some((d) => /inventory|foreign|malformed|truncated|unreadable|missing-source/.test(d));
+  const witnesses = new Map((input.witnesses ?? []).map((v) => [text(v['evidenceKey']), v]));
+  let witnessComplete = rows.length > 0 && rows.every((row) => row.evidenceKey !== null && witnesses.has(row.evidenceKey));
+  for (const row of rows) {
+    const witness = witnesses.get(row.evidenceKey); if (!witness) continue;
+    if (count(witness['tokensTotal']) !== row.tokensTotal || witness['reportedTotalBasis'] !== row.reportedTotalBasis) sourceDiagnostics.push('source-amount-mismatch:' + row.evidenceKey);
+  }
+  if (sourceDiagnostics.length) witnessComplete = false;
+  const sourceVerification = { status: sourceDiagnostics.length ? 'defect' : witnessComplete ? 'verified' : 'unavailable', diagnostics: sourceDiagnostics,
+    reason: witnessComplete ? null : sourceDiagnostics.length ? 'source-conflict' : 'no-independent-same-scope-amount-witness' };
+  const accounted = compatible ? sum(rows.filter((row) => row.stage !== null).map((row) => row.tokensTotal).filter((v): v is number => v !== null)) : null;
+  const unaccounted = compatible && known !== null && accounted !== null ? known - accounted : null;
+  const doubled = compatible ? sum(rows.map((row) => (owners.get(row.evidenceKey ?? '')?.size ?? 1) > 1 ? (row.tokensTotal ?? 0) : 0)) : null;
+  if (doubled !== null && doubled > 0) diagnostics.push('double-attribution');
+  // Monetary scope is independent of token expansion: never allocate a parent amount to responses.
+  const moneyInputs = input.moneyObservations ?? rows.map((row) => ({ id: row.evidenceKey,
+    runId: row.runId, scope: JSON.stringify([input.sourceKind, row.runId, row.evidenceKey]), basis: 'provider-reported', amount: row.reportedCostUsd }));
+  const money = new Map<string, { id: string; runId: string | null; scope: string; basis: string; amount: number | null }>();
+  const moneyConflicts = new Set<string>(); let moneyUnknown = moneyInputs.length === 0;
+  for (const raw of moneyInputs.slice(0, maximum)) {
+    const id = text(raw['id']); const scope = text(raw['scope']); const basis = text(raw['basis']); const runId = text(raw['runId']);
+    if (input.runId !== null && runId !== input.runId) { diagnostics.push('money-foreign-run'); moneyUnknown = true; continue; }
+    const amount = typeof raw['amount'] === 'number' && Number.isFinite(raw['amount']) && raw['amount'] >= 0 ? raw['amount'] : null;
+    if (raw['amount'] != null && amount === null) diagnostics.push('money-invalid-amount');
+    if (!id || !scope || !basis) { diagnostics.push('money-identity-unavailable'); moneyUnknown = true; continue; }
+    const observation = { id, runId, scope, basis, amount }; const prior = money.get(id);
+    if (prior && JSON.stringify(prior) !== JSON.stringify(observation)) { diagnostics.push('money-conflict:' + id); moneyConflicts.add(id); }
+    else money.set(id, prior ?? observation);
+  }
+  if (moneyInputs.length > maximum) { diagnostics.push('money-inventory-truncated'); moneyUnknown = true; }
+  const moneyObservations = [...money.values()].filter((v) => !moneyConflicts.has(v.id));
+  moneyUnknown ||= moneyObservations.some((v) => v.amount === null);
+  const knownReported = moneyObservations.reduce((n, v) => n + (v.amount ?? 0), 0);
+  if (!Number.isFinite(knownReported)) { diagnostics.push('money-overflow'); moneyUnknown = true; }
+  const moneyDefect = diagnostics.some((d) => /^money-(conflict|foreign|invalid|overflow)/.test(d));
+  const reportedCostCoverage = { status: moneyDefect ? 'defect' : moneyUnknown ? 'unavailable' : 'complete',
+    reason: moneyDefect ? 'conflicting-or-invalid-money-observation' : moneyUnknown ? 'reported-money-or-scope-not-recorded' : null };
+  const quantitativeDefect = diagnostics.some((d) => /conflict|foreign|mismatch|invalid|overflow|double-attribution|malformed|exceeds|cumulative-reset/.test(d)) || sourceDiagnostics.length > 0;
+  const totalComplete = compatible && missingTotals === 0 && inventoryComplete && rows.length > 0 && !quantitativeDefect;
+  const moneySum = (values: readonly number[]): number | null => { const total = values.reduce((n,v) => n + v, 0); return Number.isFinite(total) ? total : null; };
+  const knownEstimated = moneySum(rows.map((r) => r.estimatedCostUsd).filter((n): n is number => n !== null));
+  const pricingComplete = rows.length > 0 && rows.every((r) => r.pricingKnown) && totalComplete;
+  const conservation = { status: quantitativeDefect ? 'DEFECT' : totalComplete ? 'BALANCED' : 'INSUFFICIENT_DATA', scope: 'reported receipt attribution; not independent source verification', metric };
+  const dimensionCoverage = Object.fromEntries(tokenFields.map((key) => [key, { known: rows.filter((r) => r[key] !== null).length, unknown: rows.filter((r) => r[key] === null).length + expectedMissing.length }]));
+  return { schema: 'stage-usage-1', sourceKind: input.sourceKind, sourcePath: input.sourcePath, runId: input.runId, metric: compatible ? metric : 'incompatible-metrics',
+    rows, verdict: conservation.status, complete: totalComplete && witnessComplete && pricingComplete,
+    knownRunTotalTokens: known, knownAccountedTokens: accounted, knownUnaccountedTokens: unaccounted,
+    stageTokensSum: accounted !== null && doubled !== null ? accounted + doubled : null, doubleAttributedTokens: doubled,
+    runTotalTokens: totalComplete ? known : null, sourceVerifiedTotalTokens: witnessComplete && totalComplete ? known : null,
+    conservation, reconciliation: conservation, inventory: { status: inventoryComplete ? 'complete' : expected === null ? 'unavailable' : 'incomplete', expected: expected?.size ?? null, missing: expectedMissing, observed: rows.length },
+    sourceVerification, dimensionCoverage, pricingCoverage: { complete: pricingComplete, unknown: rows.filter((r) => !r.pricingKnown).length },
+    estimatedCostUsd: pricingComplete ? knownEstimated : null, knownEstimatedCostUsd: knownEstimated,
+    familyEstimatedCostUsd: rows.length > 0 && rows.every((r) => r.familyEstimatedCostUsd !== null) ? moneySum(rows.map((r) => r.familyEstimatedCostUsd!)) : null,
+    knownFamilyEstimatedCostUsd: moneySum(rows.map((r) => r.familyEstimatedCostUsd).filter((v): v is number => v !== null)),
+    moneyObservations, reportedCostCoverage, knownReportedCostUsd: Number.isFinite(knownReported) ? knownReported : null,
+    reportedCostUsd: reportedCostCoverage.status === 'complete' ? knownReported : null,
+    billedCostUsd: null, billedCostReason: 'not-observed', diagnostics: [...new Set(diagnostics)],
+    metrics: Object.fromEntries(bases.map((basis) => [basis, { knownSubtotal: sum(rows.filter((r) => r.reportedTotalBasis === basis).map((r) => r.tokensTotal).filter((v): v is number => v !== null)) }])),
+    scope: 'observed local receipts; static estimates are not current prices or billed amounts' };
+}

package/src/statusline.ts

@@ -14,7 +14,7 @@
  * @packageDocumentation
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 
@@ -165,6 +165,154 @@ export function featureAdrStatePath(projectRoot: string, slug?: string): string
     : join(featureAdrStateDir(projectRoot), `${featureAdrStateSlug(slug)}.json`);
 }
 
+/** Exact content selectors; slot filenames alone never establish run identity. */
+export interface FeatureAdrSelector {
+  readonly slug?: string;
+  readonly runId?: string;
+}
+
+/** Diagnostic observation, separate from the legacy active-only statusline DTO. */
+export interface FeatureAdrObservation {
+  readonly status: 'missing' | 'fresh' | 'stale' | 'expired' | 'completed' | 'unreadable' | 'limited-search';
+  readonly state?: Omit<FeatureAdrState, 'pool' | 'recalled' | 'stored'> & {
+    readonly pool?: number;
+    readonly recalled?: number;
+    readonly stored?: number;
+  };
+  readonly ageMs?: number;
+  readonly reason?: string;
+  readonly limitedSearch?: boolean;
+}
+
+/**
+ * Read bounded, regular local slots without writing or borrowing a different selected run.
+ * A deliberate symlink project root is resolved once; state ancestors/slots cannot be symlinks.
+ * These checks prevent accidental escapes/blocking files, not hostile concurrent replacement.
+ */
+export function readFeatureAdrObservation(
+  projectRoot: string,
+  selector: FeatureAdrSelector = {},
+  now: number = Date.now(),
+): FeatureAdrObservation {
+  const failure = (reason: string): FeatureAdrObservation => ({ status: 'unreadable', reason });
+  const missing = (): FeatureAdrObservation => ({ status: 'missing' });
+  const absent = (error: unknown): boolean => (error as { code?: string })?.code === 'ENOENT';
+  const limit = 256 * 1024;
+  let root: string;
+  try {
+    root = realpathSync(resolve(projectRoot));
+    for (const path of [join(root, '.dz'), join(root, '.dz', 'feature-adr'), featureAdrStateDir(root)]) {
+      try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) return failure('state ancestor is not a regular directory');
+      } catch (error) { if (!absent(error)) return failure('state directory unavailable'); }
+    }
+  } catch (error) { return absent(error) ? missing() : failure('project root unavailable'); }
+
+  const read = (path: string): FeatureAdrObservation => {
+    let fd: number | undefined;
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.isSymbolicLink()) return failure('slot is not a regular file');
+      if (stat.size > limit) return failure('slot exceeds 256 KiB');
+      // NONBLOCK also keeps a replacement FIFO from blocking between lstat and open.
+      fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      const opened = fstatSync(fd);
+      if (!opened.isFile() || opened.size > limit) return failure('slot is not a bounded regular file');
+      const buffer = Buffer.alloc(limit + 1);
+      let bytes = 0;
+      while (bytes <= limit) {
+        const count = readSync(fd, buffer, bytes, buffer.length - bytes, null);
+        if (count === 0) break;
+        bytes += count;
+        if (bytes > limit) return failure('slot exceeds 256 KiB');
+      }
+      const value: unknown = JSON.parse(buffer.subarray(0, bytes).toString('utf8'));
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) return failure('invalid slot object');
+      const parsed = value as Record<string, unknown>;
+      if (typeof parsed['slug'] !== 'string' || parsed['slug'].trim() === ''
+        || typeof parsed['step'] !== 'string' || parsed['step'].trim() === ''
+        || typeof parsed['ts'] !== 'string') return failure('invalid slot identity or timestamp');
+      const tsMs = Date.parse(parsed['ts']);
+      if (!Number.isFinite(now) || !Number.isFinite(tsMs) || tsMs > now) return failure('invalid or future report timestamp');
+      for (const field of ['pool', 'recalled', 'stored', 'reinforced']) {
+        const count = parsed[field];
+        if (count !== undefined && (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0)) {
+          return failure(`invalid ${field} counter`);
+        }
+      }
+      for (const field of ['runId', 'mode', 'tier', 'phaseStartTs']) {
+        if (parsed[field] !== undefined && (typeof parsed[field] !== 'string' || (parsed[field] as string).trim() === '')) {
+          return failure(`invalid ${field}`);
+        }
+      }
+      if (parsed['tier'] !== undefined && !FEATURE_ADR_TIERS.has(parsed['tier'] as string)) return failure('invalid tier');
+      if (parsed['kind'] !== undefined && parsed['kind'] !== 'feature-adr' && parsed['kind'] !== 'loop') return failure('invalid producer kind');
+      if (typeof parsed['phaseStartTs'] === 'string') {
+        const start = Date.parse(parsed['phaseStartTs']);
+        if (!Number.isFinite(start) || start > tsMs) return failure('invalid phase start timestamp');
+      }
+      const state: NonNullable<FeatureAdrObservation['state']> = {
+        slug: parsed['slug'], step: parsed['step'], ts: parsed['ts'],
+        kind: parsed['kind'] === 'loop' ? 'loop' : 'feature-adr',
+        ...(parsed['pool'] === undefined ? {} : { pool: parsed['pool'] as number }),
+        ...(parsed['recalled'] === undefined ? {} : { recalled: parsed['recalled'] as number }),
+        ...(parsed['stored'] === undefined ? {} : { stored: parsed['stored'] as number }),
+        ...(parsed['reinforced'] === undefined ? {} : { reinforced: parsed['reinforced'] as number }),
+        ...(parsed['runId'] === undefined ? {} : { runId: parsed['runId'] as string }),
+        ...(parsed['mode'] === undefined ? {} : { mode: parsed['mode'] as string }),
+        ...(parsed['tier'] === undefined ? {} : { tier: parsed['tier'] as string }),
+        ...(parsed['phaseStartTs'] === undefined ? {} : { phaseStartTs: parsed['phaseStartTs'] as string }),
+      };
+      const ageMs = now - tsMs;
+      const status = state.step.trim() === 'done' ? 'completed'
+        : ageMs >= FEATURE_ADR_FRESH_MS ? 'expired' : ageMs >= FEATURE_ADR_WARN_MS ? 'stale' : 'fresh';
+      return { status, state, ageMs };
+    } catch (error) { return absent(error) ? missing() : failure('slot unreadable or invalid JSON'); }
+    finally { if (fd !== undefined) closeSync(fd); }
+  };
+  const matches = (observation: FeatureAdrObservation): boolean => observation.state !== undefined
+    && (selector.slug === undefined || observation.state.slug === selector.slug)
+    && (selector.runId === undefined || observation.state.runId === selector.runId);
+  if (selector.slug !== undefined) {
+    const direct = read(featureAdrStatePath(root, selector.slug));
+    if (direct.status !== 'missing') return direct.status === 'unreadable' ? direct : matches(direct) ? direct : missing();
+    const legacy = read(featureAdrStatePath(root));
+    return legacy.status === 'unreadable' ? legacy : matches(legacy) ? legacy : missing();
+  }
+
+  const candidates: Array<{ path: string; mtime: number }> = [];
+  try {
+    const legacy = featureAdrStatePath(root);
+    try { candidates.push({ path: legacy, mtime: lstatSync(legacy).mtimeMs }); }
+    catch (error) { if (!absent(error)) return failure('legacy slot unavailable'); }
+    let names: string[] = [];
+    try { names = readdirSync(featureAdrStateDir(root)); }
+    catch (error) { if (!absent(error)) return failure('state discovery unavailable'); }
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      const path = join(featureAdrStateDir(root), name);
+      let mtime = -Infinity;
+      try { mtime = lstatSync(path).mtimeMs; } catch { /* read reports a racing entry */ }
+      candidates.push({ path, mtime });
+    }
+  } catch { return failure('state discovery unavailable'); }
+  candidates.sort((a, b) => b.mtime - a.mtime || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const limitedSearch = candidates.length > 64;
+  const observations = candidates.slice(0, 64).map(({ path }) => read(path));
+  const eligible = observations.filter(matches);
+  if (eligible.length > 0) {
+    eligible.sort((a, b) => {
+      const rank = (o: FeatureAdrObservation): number => (o.status === 'fresh' || o.status === 'stale')
+        ? o.state?.kind === 'loop' ? 1 : 2 : 0;
+      return rank(b) - rank(a) || (a.ageMs ?? Infinity) - (b.ageMs ?? Infinity);
+    });
+    return { ...eligible[0]!, ...(limitedSearch ? { limitedSearch: true } : {}) };
+  }
+  if (limitedSearch) return { status: 'limited-search', reason: 'only 64 candidates searched', limitedSearch: true };
+  return observations.find((o) => o.status === 'unreadable') ?? missing();
+}
+
 /**
  * Freshness window for the `/feature-adr` panel: a run older than this is considered finished, so
  * its state must NOT keep showing a stale panel in the status bar. 90 minutes (in ms).