@dzhechkov/harness-core 0.8.45 → 0.8.47

package/src/sign.ts

@@ -46,6 +46,13 @@ export interface VerifyFailure {
 export interface VerifyResult {
   readonly ok: boolean;
   readonly failures: readonly VerifyFailure[];
+  /**
+   * Paths that failed the sweep with {@link OUTSIDE_FILES_REASON}: present in the DIRECTORY, not in
+   * the manifest, and outside `package.json.files` — the packer would never ship them. They are still
+   * failures (AM-1: nothing is skipped); this list only lets a caller say how many of the failures
+   * describe the directory rather than the pack. Absent when there are none.
+   */
+  readonly outsideFiles?: readonly string[];
 }
 
 
@@ -371,6 +378,121 @@ export function listSignablePackFiles(root: string): string[] {
   return out.sort();
 }
 
+/**
+ * The wording for a swept path that `package.json.files` would keep OUT of the tarball (feature
+ * verify-pack-sweep-respects-files, AM-1). MEASURED 2026-09-20 (backlog 338a3b59c878430c): right after
+ * `dz sign`, `dz verify-pack` over harness-core's directory named `coverage/coverage-final.json` and
+ * `CHANGELOG.md` as «present in the pack but not signed», while `npm pack --dry-run` shipped 922 files,
+ * ZERO of them coverage and no CHANGELOG — `files` limits the tarball to six entries. The sweep walks the
+ * DIRECTORY (by decision — see `verifyManifest`), so the reason must say so instead of saying PACK.
+ */
+export const OUTSIDE_FILES_REASON =
+  'present in the directory but not signed — outside package.json.files, the packer would not ship it';
+
+/**
+ * npm's always-included ROOT files, MEASURED from npm's own packer rather than its docs
+ * (`/usr/lib/node_modules/npm/node_modules/npm-packlist/lib/index.js:283-286`, fix round 1, 2026-09-25):
+ *   `readme{,.*[^~$]}`, `copying{,.*[^~$]}`, `license{,.*[^~$]}`, `licence{,.*[^~$]}` — case-insensitive.
+ * That is the BARE name or `name.<ext>` where the extension does not end in `~` or `$` (editor backups and
+ * lock-style droppings). So `README.md`, `readme.txt`, `COPYING`, `LICENCE.md` are inside; `README-old`
+ * (no dot), `LICENSE.md~`, `README.` (empty extension) are NOT. Plus `package.json`, which npm always ships.
+ * NOT `CHANGELOG*`: MEASURED 2026-09-20, pnpm pack of harness-core omitted `CHANGELOG.md` while `files` did
+ * not name it — the npm docs list CHANGES/CHANGELOG/HISTORY, the packer does not; we follow the packer.
+ */
+export const NPM_ALWAYS_INCLUDED = /^(package\.json|(readme|copying|licen[cs]e)(\..*[^~$])?)$/i;
+
+/** What `package.json` says the tarball contains: normalised `files` entries plus `main` and the bin targets. */
+export interface PackAllowlist {
+  readonly entries: readonly string[];
+  readonly main: string | null;
+  readonly bins: readonly string[];
+}
+
+/**
+ * POSIX separators, no leading `./`, no trailing `/`. Every trailing slash goes — MEASURED fix round 1:
+ * `'.//'` used to survive as `'/'` (a phantom entry) because the strip kept one character; an entry that is
+ * nothing but slashes is empty after normalisation and must be dropped (AM-2).
+ */
+function normalisePackPath(p: string): string {
+  let s = p.replace(/\\/g, '/');
+  while (s.startsWith('./')) s = s.slice(2);
+  while (s.endsWith('/')) s = s.slice(0, -1);
+  return s;
+}
+
+/**
+ * `null` unless `pkg.files` is a non-empty array of strings — and `null` means «no allowlist, behaviour
+ * unchanged», never «everything is outside». Pure: the caller reads and parses `package.json`.
+ */
+export function packAllowlistFromPackageJson(pkg: unknown): PackAllowlist | null {
+  if (!pkg || typeof pkg !== 'object') return null;
+  const { files, main, bin } = pkg as { files?: unknown; main?: unknown; bin?: unknown };
+  if (!Array.isArray(files) || files.length === 0 || !files.every((f) => typeof f === 'string')) return null;
+  const entries = (files as string[]).map(normalisePackPath).filter((e) => e.length > 0);
+  if (entries.length === 0) return null;
+  const binValues: string[] =
+    typeof bin === 'string' ? [bin]
+    : bin && typeof bin === 'object' ? Object.values(bin as Record<string, unknown>).filter((v): v is string => typeof v === 'string')
+    : [];
+  return {
+    entries,
+    main: typeof main === 'string' ? normalisePackPath(main) : null,
+    bins: binValues.map(normalisePackPath),
+  };
+}
+
+const GLOB_CHARS = /[*?[]/;
+
+/**
+ * Minimal `*`-only matcher over the WHOLE relative path: `*` matches any run of characters, `/` included
+ * (so `types/**` and `types/*` both cover `types/deep/x.d.ts`). `?`, `[…]` and `{a,b}` are NOT interpreted —
+ * an entry carrying them falls back to a literal comparison, which can only UNDER-match (⇒ the plain pack
+ * wording, never a false «outside»). Kept deliberately small (NFR-2): this is a wording aid, not a packer.
+ */
+function globStarMatch(pattern: string, rel: string): boolean {
+  const parts = pattern.split('*');
+  if (parts.length === 1) return pattern === rel;
+  if (!rel.startsWith(parts[0]!)) return false;
+  let pos = parts[0]!.length;
+  for (let i = 1; i < parts.length - 1; i += 1) {
+    const at = rel.indexOf(parts[i]!, pos);
+    if (at < 0) return false;
+    pos = at + parts[i]!.length;
+  }
+  const last = parts[parts.length - 1]!;
+  return last === '' || (rel.endsWith(last) && rel.length - last.length >= pos);
+}
+
+/**
+ * Would the packer ship `rel`? True when `rel` equals an entry, sits under an entry directory, matches a
+ * `*` glob entry, equals `main` or a bin target, or is a ROOT-level always-included file. `docs/README.md`
+ * is not root-level and is therefore outside unless `docs` is an entry.
+ */
+export function isInsidePackAllowlist(rel: string, allow: PackAllowlist): boolean {
+  const p = normalisePackPath(rel);
+  if (!p.includes('/') && NPM_ALWAYS_INCLUDED.test(p)) return true;
+  if (allow.main === p || allow.bins.includes(p)) return true;
+  for (const entry of allow.entries) {
+    if (GLOB_CHARS.test(entry)) {
+      if (globStarMatch(entry, p)) return true;
+      continue;
+    }
+    if (p === entry || p.startsWith(entry + '/')) return true;
+  }
+  return false;
+}
+
+/** `<root>/package.json` → allowlist; absent, symlinked, unreadable or invalid JSON ⇒ `null` (unchanged behaviour). */
+function readPackAllowlist(root: string): PackAllowlist | null {
+  try {
+    const bytes = readRegularFileNoFollow(join(root, 'package.json'));
+    if (bytes === null) return null;
+    return packAllowlistFromPackageJson(JSON.parse(bytes.toString('utf8')));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The bytes that get signed (FR-7). Sorted by path, LF endings, no trailing whitespace, and no
  * dependence on JSON key order — a signature must not depend on how a serialiser felt that day.
@@ -533,7 +655,20 @@ export function verifyManifest(
     if (!listed.has(p)) failures.push({ path: p, reason: 'present in the pack but not signed' });
   }
 
-  return { ok: failures.length === 0, failures };
+  // AM-1 (feature verify-pack-sweep-respects-files): the sweep above is the recorded decision and stays
+  // byte-identical — every visible path participates, nothing is skipped, the verdict is unchanged. This
+  // pass changes WORDING only: a swept path that `package.json.files` keeps out of the tarball is reported
+  // as «present in the directory …» (OUTSIDE_FILES_REASON) instead of «present in the pack …», because it
+  // never was going to be in the pack. No `files` (or an unreadable package.json) ⇒ nothing is relabelled.
+  const allow = readPackAllowlist(root);
+  const outside: string[] = [];
+  const reported: VerifyFailure[] = allow === null ? failures : failures.map((f) => {
+    if (f.reason !== 'present in the pack but not signed' || isInsidePackAllowlist(f.path, allow)) return f;
+    outside.push(f.path);
+    return { path: f.path, reason: OUTSIDE_FILES_REASON };
+  });
+
+  return { ok: reported.length === 0, failures: reported, ...(outside.length > 0 ? { outsideFiles: outside } : {}) };
 }
 
 /**

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).