sandoichi 0.3.0 → 0.4.0

package/README.md

@@ -24,7 +24,9 @@ Project-specific detectors can be declared in `.sando/redaction.json`:
 
 Built-ins stay enabled. Profiles are declarative and local to the current project; invalid profiles fail visibly.
 
-The library requires Node.js `>=22.22.0 <23` and has no runtime dependencies. Installing it does not install or enable the plugin.
+The library requires Node.js `>=22.22.0 <23` and has no runtime dependencies. Installing it does not install or enable the plugin. The plugin is the supported host surface; this package exports the context/history runtime, provider usage report, paired accounting, and explicit proxy API only.
+
+`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted estimates, provider-reported cost, and paired-session evidence distinct. The benchmark report adds explicit replay counterfactuals. The library does not install hooks, register MCP servers, or make routing/backoff decisions for a host.
 
 For plugin installation, see the [main project README](https://github.com/yuzushi-dev/Sando#readme).
 

package/index.mjs

@@ -8,6 +8,16 @@ export {
 export { createRedactionProfile } from './src/redaction-profile.mjs';
 export { loadProjectRedactionProfile } from './src/redaction-config.mjs';
 export { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './src/context-transform.mjs';
+export {
+  DEFAULT_ACCOUNTING_WEIGHTS,
+  PAIRED_ARMS,
+  computeWeightedUsage,
+  pairedArmFromEnv,
+  pairedExperimentFromEnv,
+  pairedWorkloadFromEnv,
+  summarizePairedSessions,
+} from './src/paired-accounting.mjs';
+export { formatAccountingReport, runAccountingCli } from './src/accounting-cli.mjs';
 export {
   buildSemanticPrompt,
   createSemanticCompactor,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sandoichi",
-  "version": "0.3.0",
-  "description": "Reduce repeated tool-output context in Claude Code and Codex.",
+  "version": "0.4.0",
+  "description": "Bound repeated tool-output context in Claude Code and Codex with deterministic local routing and provider accounting.",
   "license": "MIT",
   "author": "yuzushi",
   "repository": {

package/src/accounting-cli.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { buildProviderUsageReport, defaultProviderUsagePath, readProviderUsage } from './provider-usage.mjs';
+
+function option(argv, name) {
+  const index = argv.indexOf(`--${name}`);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+export function formatAccountingReport(report) {
+  const lines = [
+    'provider accounting',
+    `input: ${report.inputTokens}`,
+    `fresh input: ${report.freshInputTokens}`,
+    `cache read: ${report.cachedInputTokens}`,
+    `cache write: ${report.cacheWriteInputTokens}`,
+    `output: ${report.outputTokens}`,
+    `reasoning: ${report.reasoningOutputTokens}`,
+    `turns: ${report.turnCount}`,
+    `weighted estimate: ${report.weightedCost.costUnits} cost units`,
+    `provider cost: ${report.cost.status === 'provider-reported' ? `$${report.cost.totalCostUsd.toFixed(6)}` : report.cost.status}`,
+  ];
+  if (report.cost.effectiveRateUsdPerMillionTokens !== null) {
+    lines.push(`blended effective rate: $${report.cost.effectiveRateUsdPerMillionTokens.toFixed(2)}/M tokens`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function runAccountingCli({ argv = process.argv.slice(2), env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (argv.includes('--help')) {
+    stdout.write('Usage: node accounting-cli.mjs [--json] [--path ABSOLUTE_PATH] [--session SESSION_ID]\n');
+    return null;
+  }
+  try {
+    const storagePath = option(argv, 'path') || defaultProviderUsagePath(env);
+    const report = buildProviderUsageReport(readProviderUsage(storagePath), { sessionId: option(argv, 'session') });
+    stdout.write(argv.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : formatAccountingReport(report));
+    return report;
+  } catch (error) {
+    stderr.write(`sando accounting: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) runAccountingCli();

package/src/adaptive-control.mjs

@@ -0,0 +1,10 @@
+// Compatibility aliases for older direct imports. Routing no longer reads this module.
+export {
+  DEFAULT_ACCOUNTING_WEIGHTS as DEFAULT_ADAPTIVE_WEIGHTS,
+  PAIRED_ARMS as ADAPTIVE_ARMS,
+  computeWeightedUsage as computeUsageCost,
+  pairedArmFromEnv as adaptiveArmFromEnv,
+  pairedExperimentFromEnv as adaptiveExperimentFromEnv,
+  pairedWorkloadFromEnv as adaptiveWorkloadFromEnv,
+  summarizePairedSessions as summarizeAdaptiveSessions,
+} from './paired-accounting.mjs';

package/src/exec-capture.mjs

@@ -0,0 +1,94 @@
+export const MAX_EXEC_CAPTURE_BYTES = 16_777_216;
+
+function terminate(child, signal) {
+  try {
+    if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch {}
+  try { child.kill(signal); } catch {}
+}
+
+function incompleteUtf8Suffix(buffer) {
+  let index = buffer.length - 1;
+  let continuation = 0;
+  while (index >= 0 && (buffer[index] & 0xc0) === 0x80) {
+    continuation += 1;
+    index -= 1;
+  }
+  if (index < 0) return 0;
+  const lead = buffer[index];
+  const expected = lead >= 0xc2 && lead <= 0xdf ? 2
+    : lead >= 0xe0 && lead <= 0xef ? 3
+      : lead >= 0xf0 && lead <= 0xf4 ? 4 : 0;
+  return expected > continuation + 1 ? continuation + 1 : 0;
+}
+
+export function textOrBinary(buffer, { truncated = false } = {}) {
+  if (!Buffer.isBuffer(buffer)) throw new TypeError('output must be a Buffer');
+  if (buffer.includes(0)) return { binary: true, text: '', utf8Truncated: false };
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  try { return { binary: false, text: decoder.decode(buffer), utf8Truncated: false }; }
+  catch {
+    if (!truncated) return { binary: true, text: '', utf8Truncated: false };
+    const suffix = incompleteUtf8Suffix(buffer);
+    if (!suffix) return { binary: true, text: '', utf8Truncated: false };
+    try {
+      return { binary: false, text: decoder.decode(buffer.subarray(0, -suffix)), utf8Truncated: true };
+    } catch {
+      return { binary: true, text: '', utf8Truncated: false };
+    }
+  }
+}
+
+export function captureProcess(child, { maxBytes, timeoutMs, signal } = {}) {
+  if (!child || typeof child.once !== 'function' || !Number.isSafeInteger(maxBytes) || maxBytes < 1
+    || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new TypeError('capture options are invalid');
+  return new Promise((resolve, reject) => {
+    const buffers = { stdout: [], stderr: [] };
+    const captured = { stdout: 0, stderr: 0 };
+    const truncated = { stdout: false, stderr: false };
+    let timedOut = false;
+    let cancelled = false;
+    let settled = false;
+    let forceTimer;
+    let timer;
+    const collect = (name, chunk) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, maxBytes - captured[name]);
+      if (remaining) {
+        const part = buffer.subarray(0, remaining);
+        buffers[name].push(part);
+        captured[name] += part.length;
+      }
+      if (buffer.length > remaining) truncated[name] = true;
+    };
+    const stop = (signalName) => {
+      terminate(child, signalName);
+      if (signalName === 'SIGTERM' && forceTimer === undefined) {
+        forceTimer = setTimeout(() => terminate(child, 'SIGKILL'), 250);
+      }
+    };
+    const finish = (result, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      signal?.removeEventListener('abort', onAbort);
+      if (error) reject(error);
+      else resolve({
+        stdout: Buffer.concat(buffers.stdout), stderr: Buffer.concat(buffers.stderr),
+        stdoutBytes: captured.stdout, stderrBytes: captured.stderr,
+        stdoutTruncated: truncated.stdout, stderrTruncated: truncated.stderr,
+        truncated: truncated.stdout || truncated.stderr, timedOut, cancelled, ...result,
+      });
+    };
+    const onAbort = () => { cancelled = true; stop('SIGTERM'); };
+    timer = setTimeout(() => { timedOut = true; stop('SIGTERM'); }, timeoutMs);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.stdout?.on('data', (chunk) => collect('stdout', chunk));
+    child.stderr?.on('data', (chunk) => collect('stderr', chunk));
+    child.once('error', (error) => finish(null, error));
+    child.once('close', (exitCode, exitSignal) => finish({ exitCode, exitSignal }));
+    if (signal?.aborted) onAbort();
+  });
+}

package/src/metrics.mjs

@@ -375,15 +375,15 @@ function tokenLine(value) {
 
 export function formatMetricsReport(report) {
   const lines = [
-    `Sando savings (timezone: ${report.timezone})`,
+    `Sando mechanical measurement (timezone: ${report.timezone})`,
     `Current session: ${report.currentSession ? report.currentSession.id ?? 'unknown' : 'none'}`,
-    `Current session estimated transform savings: ${tokenLine(report.currentSession?.estimatedTransformSavingsTokens ?? 0)}`,
-    `Average estimated transform savings per session: ${tokenLine(report.averagePerSession.estimatedTransformSavingsTokens)} (${report.averagePerSession.sessionCount} sessions)`,
-    `Cumulative estimated transform savings: ${tokenLine(report.cumulative.estimatedTransformSavingsTokens)}`,
-    `Cumulative provider-reported savings: ${tokenLine(report.cumulative.providerReportedSavingsTokens)}`,
-    `Daily (${report.periods.daily.current.period}) estimated transform savings: ${tokenLine(report.periods.daily.current.estimatedTransformSavingsTokens)}`,
-    `ISO week (${report.periods.weekly.current.period}) estimated transform savings: ${tokenLine(report.periods.weekly.current.estimatedTransformSavingsTokens)}`,
-    `Monthly (${report.periods.monthly.current.period}) estimated transform savings: ${tokenLine(report.periods.monthly.current.estimatedTransformSavingsTokens)}`,
+    `Current session mechanical reduction: ${tokenLine(report.currentSession?.estimatedTransformSavingsTokens ?? 0)}`,
+    `Average mechanical reduction per session: ${tokenLine(report.averagePerSession.estimatedTransformSavingsTokens)} (${report.averagePerSession.sessionCount} sessions)`,
+    `Cumulative mechanical reduction: ${tokenLine(report.cumulative.estimatedTransformSavingsTokens)}`,
+    `Provider cost: unavailable here; use paired control/apply ledger evidence`,
+    `Daily (${report.periods.daily.current.period}) mechanical reduction: ${tokenLine(report.periods.daily.current.estimatedTransformSavingsTokens)}`,
+    `ISO week (${report.periods.weekly.current.period}) mechanical reduction: ${tokenLine(report.periods.weekly.current.estimatedTransformSavingsTokens)}`,
+    `Monthly (${report.periods.monthly.current.period}) mechanical reduction: ${tokenLine(report.periods.monthly.current.estimatedTransformSavingsTokens)}`,
   ];
   if (!report.cumulative.eventCount) lines.push('No Sando events recorded.');
   return `${lines.join('\n')}\n`;

package/src/paired-accounting.mjs

@@ -0,0 +1,142 @@
+const ARMS = new Set(['apply', 'control']);
+
+export const PAIRED_ARMS = Object.freeze(['apply', 'control']);
+export const DEFAULT_ACCOUNTING_WEIGHTS = Object.freeze({
+  freshInput: 1,
+  cacheRead: 0.1,
+  cacheWrite: 1.25,
+  output: 1,
+  reasoningOutput: 1,
+});
+
+function text(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function counter(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function weights(value) {
+  const result = { ...DEFAULT_ACCOUNTING_WEIGHTS, ...(value ?? {}) };
+  if (Object.keys(result).some((key) => !Object.hasOwn(DEFAULT_ACCOUNTING_WEIGHTS, key))
+    || Object.values(result).some((item) => typeof item !== 'number' || !Number.isFinite(item) || item < 0)) {
+    throw new TypeError('accounting weights are invalid');
+  }
+  return result;
+}
+
+function add(left, right, message = 'accounting aggregate overflow') {
+  const total = left + right;
+  if (!Number.isSafeInteger(total)) throw new RangeError(message);
+  return total;
+}
+
+function addCostUnits(left, right) {
+  const total = left + right;
+  if (!Number.isFinite(total)) throw new RangeError('accounting cost overflow');
+  return total;
+}
+
+function armValue(env) {
+  return env.SANDO_EXPERIMENT_ARM ?? env.SANDO_ADAPTIVE_ARM ?? 'apply';
+}
+
+export function pairedArmFromEnv(env = process.env) {
+  const value = armValue(env);
+  return ARMS.has(value) ? value : null;
+}
+
+export function pairedExperimentFromEnv(env = process.env) {
+  const value = env.SANDO_EXPERIMENT ?? env.SANDO_ADAPTIVE_EXPERIMENT ?? 'default';
+  return text(value) ? value : 'default';
+}
+
+export function pairedWorkloadFromEnv(env = process.env) {
+  const value = env.SANDO_EXPERIMENT_WORKLOAD ?? env.SANDO_ADAPTIVE_WORKLOAD;
+  return text(value) ? value : undefined;
+}
+
+export function computeWeightedUsage(record, pricing) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) throw new TypeError('usage record is invalid');
+  const inputTokens = record.inputTokens;
+  const cachedInputTokens = record.cachedInputTokens ?? 0;
+  const cacheWriteInputTokens = record.cacheWriteInputTokens ?? 0;
+  const outputTokens = record.outputTokens;
+  const reasoningOutputTokens = record.reasoningOutputTokens ?? 0;
+  if (![inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens, reasoningOutputTokens].every(counter)
+    || cachedInputTokens + cacheWriteInputTokens > inputTokens
+    || reasoningOutputTokens > outputTokens) throw new TypeError('usage counters are invalid');
+  const nonReasoningOutputTokens = outputTokens - reasoningOutputTokens;
+  const parts = {
+    inputTokens,
+    freshInputTokens: inputTokens - cachedInputTokens - cacheWriteInputTokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    outputTokens,
+    nonReasoningOutputTokens,
+    reasoningOutputTokens,
+  };
+  const prices = weights(pricing);
+  const costUnits = parts.freshInputTokens * prices.freshInput
+    + parts.cachedInputTokens * prices.cacheRead
+    + parts.cacheWriteInputTokens * prices.cacheWrite
+    + parts.nonReasoningOutputTokens * prices.output
+    + parts.reasoningOutputTokens * prices.reasoningOutput;
+  if (!Number.isFinite(costUnits)) throw new RangeError('accounting cost overflow');
+  return { ...parts, costUnits };
+}
+
+function sessionKey(item) {
+  return `${item.arm}\0${item.sessionId}`;
+}
+
+function optionalCounter(item, field) {
+  return item[field] === undefined ? undefined : counter(item[field]) ? item[field] : null;
+}
+
+export function summarizePairedSessions(records, { host, experimentId, workloadId, pricing } = {}) {
+  if (!Array.isArray(records)) throw new TypeError('usage records must be an array');
+  const groups = new Map();
+  records.forEach((item, index) => {
+    if (!item || typeof item !== 'object' || item.host !== host || !ARMS.has(item.arm)
+      || !text(item.sessionId) || (experimentId !== undefined && item.experimentId !== experimentId)
+      || (workloadId !== undefined && item.workloadId !== workloadId)) return;
+    const usage = computeWeightedUsage(item, pricing);
+    const fields = {
+      inputTokens: usage.inputTokens,
+      freshInputTokens: usage.freshInputTokens,
+      cachedInputTokens: usage.cachedInputTokens,
+      cacheWriteInputTokens: usage.cacheWriteInputTokens,
+      outputTokens: usage.outputTokens,
+      reasoningOutputTokens: usage.reasoningOutputTokens,
+      totalTokens: add(item.inputTokens, item.outputTokens),
+      costUnits: usage.costUnits,
+    };
+    const current = groups.get(sessionKey(item));
+    if (!current) {
+      groups.set(sessionKey(item), {
+        sessionId: item.sessionId, arm: item.arm, ...fields,
+        turnIds: new Set([text(item.turnId) ? item.turnId : `record:${index}`]),
+        totalToolCalls: optionalCounter(item, 'totalToolCalls') ?? null,
+        nativeToolCalls: optionalCounter(item, 'nativeToolCalls') ?? null,
+        sandoMcpCalls: optionalCounter(item, 'sandoMcpCalls') ?? null,
+        mechanicalContextTrimmedBytes: optionalCounter(item, 'mechanicalContextTrimmedBytes') ?? null,
+      });
+      return;
+    }
+    for (const field of Object.keys(fields)) current[field] = field === 'costUnits'
+      ? addCostUnits(current[field], fields[field]) : add(current[field], fields[field]);
+    current.turnIds.add(text(item.turnId) ? item.turnId : `record:${index}`);
+    for (const field of ['totalToolCalls', 'nativeToolCalls', 'sandoMcpCalls', 'mechanicalContextTrimmedBytes']) {
+      if (current[field] !== null) {
+        const value = optionalCounter(item, field);
+        current[field] = value === undefined || value === null || current[field] === null
+          ? null : add(current[field], value);
+      }
+    }
+  });
+  return [...groups.values()]
+    .map(({ turnIds, ...group }) => ({ ...group, turns: turnIds.size }))
+    .sort((left, right) => left.arm.localeCompare(right.arm) || left.sessionId.localeCompare(right.sessionId));
+}

package/src/provider-usage.mjs

@@ -3,11 +3,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { computeWeightedUsage } from './paired-accounting.mjs';
+
 const SCHEMA = 'sando-provider-usage/v1';
 const VERSION = 1;
 const LOCK_WAIT_MS = 10;
 const LOCK_ATTEMPTS = 250;
 const STALE_LOCK_MS = 30_000;
+const COST_SCOPES = new Set(['session', 'event']);
 
 export const PROVIDER_USAGE_SCHEMA = SCHEMA;
 export const PROVIDER_USAGE_VERSION = VERSION;
@@ -15,10 +18,19 @@ export const PROVIDER_USAGE_VERSION = VERSION;
 function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
 function text(value) { return typeof value === 'string' && value.length > 0; }
 function counter(value) { return Number.isSafeInteger(value) && value >= 0; }
+function usd(value) { return typeof value === 'number' && Number.isFinite(value) && value >= 0; }
+function cacheFits(inputTokens, cachedInputTokens, cacheWriteInputTokens) {
+  return cacheWriteInputTokens <= inputTokens
+    && cachedInputTokens <= inputTokens - cacheWriteInputTokens;
+}
 function safeSum(...values) {
   const total = values.reduce((sum, value) => sum + value, 0);
   return Number.isSafeInteger(total) ? total : null;
 }
+function sumUsd(values) {
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return Number.isFinite(total) ? Number(total.toFixed(12)) : null;
+}
 function sha256(value) { return `sha256:${createHash('sha256').update(value).digest('hex')}`; }
 function isoDate(value, fallback = new Date()) {
   const date = value === undefined ? new Date(fallback) : new Date(value);
@@ -39,26 +51,55 @@ function jsonLines(textValue) {
   });
 }
 
+function reportedCost(value) {
+  const candidates = [
+    value?.total_cost_usd,
+    value?.totalCostUsd,
+    value?.cost_usd,
+    value?.costUsd,
+    value?.usage?.total_cost_usd,
+    value?.usage?.totalCostUsd,
+    value?.message?.usage?.total_cost_usd,
+    value?.message?.usage?.totalCostUsd,
+    value?.cost?.total_cost_usd,
+    value?.cost?.totalCostUsd,
+    value?.cost?.usd,
+  ];
+  return candidates.find(usd);
+}
+
+function attachReportedCost(records, totalCostUsd) {
+  if (!records.length || !usd(totalCostUsd)) return records;
+  return records.map((item, index) => index === records.length - 1
+    ? { ...item, totalCostUsd, costScope: 'session' } : item);
+}
+
 function usageRecord({ host, source, sourceKey, sessionId, turnId, at, inputTokens, cachedInputTokens = 0,
-  cacheWriteInputTokens = 0, outputTokens, reasoningOutputTokens = 0 }) {
+  cacheWriteInputTokens = 0, outputTokens, reasoningOutputTokens = 0, totalCostUsd, arm, experimentId, workloadId }) {
   if (!text(host) || !text(source) || !text(sourceKey)
     || (sessionId !== null && !text(sessionId)) || (turnId !== null && !text(turnId))
     || !text(at) || !counter(inputTokens) || !counter(cachedInputTokens)
-    || !counter(cacheWriteInputTokens) || !counter(outputTokens) || !counter(reasoningOutputTokens)) return null;
+    || !counter(cacheWriteInputTokens) || !cacheFits(inputTokens, cachedInputTokens, cacheWriteInputTokens)
+    || !counter(outputTokens) || !counter(reasoningOutputTokens) || reasoningOutputTokens > outputTokens) return null;
   const totalTokens = safeSum(inputTokens, outputTokens);
   if (totalTokens === null) return null;
   const identity = JSON.stringify({ host, source, sourceKey, at, inputTokens, cachedInputTokens,
-    cacheWriteInputTokens, outputTokens, reasoningOutputTokens, totalTokens });
-  return {
+    cacheWriteInputTokens, outputTokens, reasoningOutputTokens, totalTokens, arm, experimentId, workloadId });
+  const result = {
     eventKey: `usage:${host}:${sha256(identity)}`,
     schema: SCHEMA, version: VERSION, host, source,
     sessionId: sessionId ?? null, turnId: turnId ?? null, at,
     inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens,
     reasoningOutputTokens, totalTokens,
   };
+  if (totalCostUsd !== undefined && usd(totalCostUsd)) result.totalCostUsd = totalCostUsd;
+  if (arm !== undefined) result.arm = arm;
+  if (experimentId !== undefined) result.experimentId = experimentId;
+  if (workloadId !== undefined) result.workloadId = workloadId;
+  return result;
 }
 
-function claudeRecord(value, index, { sessionId = null, turnId = null, now } = {}) {
+function claudeRecord(value, index, { sessionId = null, turnId = null, now, arm, experimentId, workloadId } = {}) {
   if (value.type !== 'assistant' || !record(value.message?.usage)) return null;
   const usage = value.message.usage;
   const inputTokens = usage.input_tokens;
@@ -74,10 +115,11 @@ function claudeRecord(value, index, { sessionId = null, turnId = null, now } = {
     host: 'claude', source: 'claude-transcript', sourceKey: value.uuid ?? value.request_id ?? value.timestamp ?? String(index),
     sessionId, turnId: value.turn_id ?? turnId, at: isoDate(value.timestamp, now),
     inputTokens: totalInputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens,
+    arm, experimentId, workloadId,
   });
 }
 
-function codexRecord(value, index, { sessionId = null, turnId = null, now } = {}) {
+function codexRecord(value, index, { sessionId = null, turnId = null, now, arm, experimentId, workloadId } = {}) {
   const usage = value.type === 'turn.completed'
     ? value.usage
     : value.type === 'event_msg' && value.payload?.type === 'token_count'
@@ -95,17 +137,24 @@ function codexRecord(value, index, { sessionId = null, turnId = null, now } = {}
   if (!counter(totalTokens) || totalTokens !== inputTokens + outputTokens) return null;
   return usageRecord({
     host: 'codex', source: 'codex-transcript', sourceKey: value.turn_id ?? value.id ?? value.timestamp ?? String(index),
-    sessionId, turnId: value.turn_id ?? turnId, at: isoDate(value.timestamp, now),
+    sessionId, turnId: value.turn_id ?? value.id ?? (value.timestamp ? `at:${value.timestamp}` : turnId), at: isoDate(value.timestamp, now),
     inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens, reasoningOutputTokens,
+    arm, experimentId, workloadId,
   });
 }
 
 export function parseClaudeTranscript(textValue, options = {}) {
-  return jsonLines(textValue).map(({ value }, index) => claudeRecord(value, index, options)).filter(Boolean);
+  const entries = jsonLines(textValue);
+  const records = entries.map(({ value }, index) => claudeRecord(value, index, options)).filter(Boolean);
+  const totalCostUsd = options.totalCostUsd ?? entries.slice().reverse().map(({ value }) => reportedCost(value)).find(usd);
+  return attachReportedCost(records, totalCostUsd);
 }
 
 export function parseCodexTranscript(textValue, options = {}) {
-  return jsonLines(textValue).map(({ value }, index) => codexRecord(value, index, options)).filter(Boolean);
+  const entries = jsonLines(textValue);
+  const records = entries.map(({ value }, index) => codexRecord(value, index, options)).filter(Boolean);
+  const totalCostUsd = options.totalCostUsd ?? entries.slice().reverse().map(({ value }) => reportedCost(value)).find(usd);
+  return attachReportedCost(records, totalCostUsd);
 }
 
 export function defaultProviderUsagePath(env = process.env) {
@@ -131,8 +180,17 @@ function validateUsage(value) {
     || !text(value.host) || !text(value.source) || !text(value.at)
     || (value.sessionId !== null && !text(value.sessionId)) || (value.turnId !== null && !text(value.turnId))
     || !counter(value.inputTokens) || !counter(value.cachedInputTokens) || !counter(value.cacheWriteInputTokens)
-    || !counter(value.outputTokens) || !counter(value.reasoningOutputTokens) || !counter(value.totalTokens)
-    || value.totalTokens !== value.inputTokens + value.outputTokens) throw new Error('provider usage record is invalid');
+    || !cacheFits(value.inputTokens, value.cachedInputTokens, value.cacheWriteInputTokens)
+    || !counter(value.outputTokens) || !counter(value.reasoningOutputTokens) || value.reasoningOutputTokens > value.outputTokens
+    || !counter(value.totalTokens)
+    || value.totalTokens !== value.inputTokens + value.outputTokens
+    || (value.arm !== undefined && !['apply', 'control'].includes(value.arm))
+    || (value.experimentId !== undefined && !text(value.experimentId))
+    || (value.workloadId !== undefined && !text(value.workloadId))
+    || (value.totalCostUsd !== undefined && !usd(value.totalCostUsd))
+    || (value.costScope !== undefined && (!COST_SCOPES.has(value.costScope) || value.totalCostUsd === undefined))) {
+    throw new Error('provider usage record is invalid');
+  }
 }
 
 function validateState(value) {
@@ -191,34 +249,92 @@ export function appendProviderUsage({ storagePath = defaultProviderUsagePath(),
   ensureDirectory(path.dirname(filePath));
   return withLock(`${filePath}.lock`, () => {
     const state = readProviderUsage(filePath);
-    const existing = new Set(state.records.map((item) => item.eventKey));
-    for (const item of records) if (!existing.has(item.eventKey)) { state.records.push(item); existing.add(item.eventKey); }
+    const existing = new Map(state.records.map((item, index) => [item.eventKey, index]));
+    for (const item of records) {
+      const index = existing.get(item.eventKey);
+      if (index === undefined) {
+        existing.set(item.eventKey, state.records.length);
+        state.records.push(item);
+      } else if (item.costScope === 'session') {
+        state.records[index] = item;
+      }
+    }
     atomicWrite(filePath, state);
     return state;
   });
 }
 
 export function collectProviderUsage({ host, transcriptPath, sessionId = null, turnId = null,
-  storagePath = defaultProviderUsagePath(), now } = {}) {
+  storagePath = defaultProviderUsagePath(), now, totalCostUsd, arm, experimentId, workloadId } = {}) {
   if (!['claude', 'codex'].includes(host) || typeof transcriptPath !== 'string' || !transcriptPath) return { records: [], state: readProviderUsage(storagePath) };
   try {
     const textValue = fs.readFileSync(transcriptPath, 'utf8');
     const parse = host === 'claude' ? parseClaudeTranscript : parseCodexTranscript;
-    const records = parse(textValue, { sessionId, turnId, now });
+    const records = parse(textValue, { sessionId, turnId, now, totalCostUsd, arm, experimentId, workloadId });
     return { records, state: appendProviderUsage({ storagePath, records }) };
   } catch {
     return { records: [], state: readProviderUsage(storagePath) };
   }
 }
 
-export function buildProviderUsageReport(state, { sessionId } = {}) {
+export function buildProviderUsageReport(state, { sessionId, pricing } = {}) {
   const records = validateState(state).records.filter((item) => sessionId === undefined || item.sessionId === sessionId);
   const sessions = new Set(records.map((item) => `${item.host}\0${item.sessionId ?? '<unknown>'}`));
+  const turns = new Set(records.map((item, index) => `${item.host}\0${item.sessionId ?? '<unknown>'}\0${item.turnId ?? `record:${index}`}`));
   const sum = (field) => records.reduce((total, item) => total + item[field], 0);
+  const weightedCostUnits = records.reduce((total, item) => total + computeWeightedUsage(item, pricing).costUnits, 0);
+  const freshInputTokens = records.reduce((total, item) => total + item.inputTokens - item.cachedInputTokens - item.cacheWriteInputTokens, 0);
+  const billing = reportedCostSummary(records);
+  const totalCostUsd = billing.complete ? billing.totalCostUsd : null;
+  const effectiveRate = totalCostUsd !== null && totalTokens(records) > 0
+    ? totalCostUsd / totalTokens(records) * 1_000_000 : null;
+  const cost = {
+    status: billing.complete ? 'provider-reported' : 'unavailable',
+    coverage: billing.complete ? 'complete' : billing.partial ? 'partial' : 'none',
+    totalCostUsd,
+    effectiveRateUsdPerMillionTokens: effectiveRate,
+  };
   return {
     eventCount: records.length, sessionCount: sessions.size,
     inputTokens: sum('inputTokens'), cachedInputTokens: sum('cachedInputTokens'),
-    cacheWriteInputTokens: sum('cacheWriteInputTokens'), outputTokens: sum('outputTokens'),
-    reasoningOutputTokens: sum('reasoningOutputTokens'), totalTokens: sum('totalTokens'),
+    cacheWriteInputTokens: sum('cacheWriteInputTokens'), freshInputTokens,
+    outputTokens: sum('outputTokens'), reasoningOutputTokens: sum('reasoningOutputTokens'), totalTokens: sum('totalTokens'),
+    turnCount: turns.size, weightedCostUnits,
+    weightedCost: { source: 'weighted-estimate', costUnits: weightedCostUnits },
+    cost,
+    totalCostUsd,
+    providerReportedCostUsd: totalCostUsd,
+    sessionBlendedEffectiveRateUsdPerMillionTokens: effectiveRate,
+    costSource: cost.status,
   };
 }
+
+function billingKey(item) {
+  return `${item.host}\0${item.sessionId ?? '<unknown>'}`;
+}
+
+function reportedCostSummary(records) {
+  const groups = new Map();
+  records.forEach((item) => {
+    const entries = groups.get(billingKey(item)) ?? [];
+    entries.push(item);
+    groups.set(billingKey(item), entries);
+  });
+  const totals = [];
+  for (const entries of groups.values()) {
+    const sessionCosts = entries.filter((item) => item.costScope === 'session' && usd(item.totalCostUsd));
+    if (sessionCosts.length) {
+      const latest = sessionCosts.reduce((left, right) => right.at >= left.at ? right : left);
+      totals.push(latest.totalCostUsd);
+      continue;
+    }
+    if (entries.every((item) => usd(item.totalCostUsd))) totals.push(sumUsd(entries.map((item) => item.totalCostUsd)));
+  }
+  const complete = groups.size > 0 && totals.length === groups.size && !totals.includes(null);
+  const totalCostUsd = complete ? sumUsd(totals) : null;
+  return { complete: complete && totalCostUsd !== null, partial: totals.length > 0, totalCostUsd };
+}
+
+function totalTokens(records) {
+  return records.reduce((total, item) => total + item.totalTokens, 0);
+}

package/src/proxy.mjs

@@ -225,14 +225,15 @@ export async function createProviderProxy({ upstream, host = '127.0.0.1', port =
               lastRequestAt = now;
               const transformed = transformProviderRequest({ provider, body: parsed, policy, idleMs });
               if (transformed.changed) body = Buffer.from(JSON.stringify(transformed.body));
+              const mechanicalContextTrimmedBytes = Math.max(0, rawBody.length - body.length);
               recordProxyTelemetry({
                 env, provider, transformed,
                 beforeText: rawBody.toString('utf8'), afterText: body.toString('utf8'),
               });
-              lastStats = { provider, ...transformed.stats, changed: transformed.changed, reasons: transformed.reasons };
+              lastStats = { provider, ...transformed.stats, mechanicalContextTrimmedBytes, changed: transformed.changed, reasons: transformed.reasons };
               recordProvider = provider;
               recordModel = typeof parsed?.model === 'string' ? parsed.model : null;
-              recordStats = transformed.stats;
+              recordStats = { ...transformed.stats, mechanicalContextTrimmedBytes };
               if (typeof semanticCompactor === 'function') {
                 const candidates = listSemanticCandidates({ provider, body: transformed.body });
                 const stats = createSemanticStats(candidates);

package/src/statusline.mjs

@@ -80,21 +80,23 @@ function compactTokens(value) {
   return `${Number((value / 1_000_000).toFixed(2))}M`;
 }
 
-// The rate is the session's own blended $/token (totalCostUsd / totalTokens),
-// so cache reads (0.1x) and cache writes (1.25x/2x) are already folded in:
-// it's the harness's real billed rate, not a reconstructed list price.
-function compactCost(tokens, effectiveRate) {
-  return `$${(tokens * effectiveRate).toFixed(2)}`;
+function compactTurns(value) {
+  return `${value} ${value === 1 ? 'turn' : 'turns'}`;
 }
 
 export function renderStatusLine({ metrics, providerUsage, totalCostUsd } = {}, _now = Date.now()) {
-  if (!metrics || !['estimate', 'provider-reported'].includes(metrics.source)
-    || !Number.isSafeInteger(metrics.savedTokens) || metrics.savedTokens <= 0) return '🥪 —';
-  const estimated = metrics.source === 'estimate';
-  const savings = `${estimated ? '~' : ''}${compactTokens(metrics.savedTokens)} token saved`;
-  const effectiveRate = Number.isFinite(totalCostUsd) && totalCostUsd > 0
-    && Number.isSafeInteger(providerUsage?.totalTokens) && providerUsage.totalTokens > 0
-    ? totalCostUsd / providerUsage.totalTokens : undefined;
-  void effectiveRate; // computed for downstream cost tracking, intentionally not shown in the status bar
-  return `🥪 ${savings}`;
+  if (!Number.isSafeInteger(providerUsage?.totalTokens) || providerUsage.totalTokens <= 0
+    || !Number.isSafeInteger(providerUsage?.turnCount) || providerUsage.turnCount <= 0) return '🥪 —';
+  const parts = [
+    `${compactTokens(providerUsage.totalTokens)} provider tokens`,
+    compactTurns(providerUsage.turnCount),
+  ];
+  if (Number.isFinite(providerUsage.weightedCostUnits) && providerUsage.weightedCostUnits >= 0) {
+    parts.push(`${compactTokens(Math.round(providerUsage.weightedCostUnits))} cost units`);
+  }
+  if (Number.isFinite(totalCostUsd) && totalCostUsd >= 0) {
+    const effectiveRate = totalCostUsd / providerUsage.totalTokens;
+    parts.push(`$${totalCostUsd.toFixed(2)}`, `$${(effectiveRate * 1_000_000).toFixed(2)}/M`);
+  }
+  return `🥪 ${parts.join(' · ')}`;
 }