claude-autorouter 0.3.7 → 0.5.0

package/src/savings.mjs

@@ -1,16 +1,24 @@
+import { normalizeSessionRecord, UNPRICED_REASONS } from './telemetry-event.mjs';
+
 // Published standard, global API prices in cents per million tokens. These are
 // API-equivalent estimates, not subscription charges. Exact IDs only: an
 // unfamiliar model must not inherit another model's price from its name.
-// https://platform.claude.com/docs/en/about-claude/pricing (2026-09-29)
-const HAIKU_45 = { input: 100, output: 500, write5m: 125, write1h: 200, read: 10 };
-const SONNET_5 = { input: 200, output: 1000, write5m: 250, write1h: 400, read: 20 };
-const OPUS_5 = { input: 500, output: 2500, write5m: 625, write1h: 1000, read: 50 };
-const OPUS_55 = { input: 400, output: 2000, write5m: 500, write1h: 800, read: 20 };
+// These facts retain the existing reviewed rates; a table change must publish
+// a new version so historical usage never silently receives today's prices.
+export const PRICING_VERSION = '2026-09-29.1';
+export const PRICING_DATE = '2026-09-29';
+export const PRICING_SOURCE = 'https://platform.claude.com/docs/en/about-claude/pricing';
+const HAIKU_45 = Object.freeze({ input: 100, output: 500, write5m: 125, write1h: 200, read: 10 });
+const SONNET_5 = Object.freeze({ input: 200, output: 1000, write5m: 250, write1h: 400, read: 20 });
+const OPUS_5 = Object.freeze({ input: 500, output: 2500, write5m: 625, write1h: 1000, read: 50 });
+const OPUS_55 = Object.freeze({ input: 400, output: 2000, write5m: 500, write1h: 800, read: 20 });
 const PRICES = new Map([
   ['claude-haiku-4-5', HAIKU_45], ['claude-haiku-4-5-20251001', HAIKU_45],
   ['claude-sonnet-5', SONNET_5], ['claude-sonnet-5-5', SONNET_5],
   ['claude-opus-5', OPUS_5], ['claude-opus-5-5', OPUS_55],
 ]);
+export const PRICING_FACTS = Object.freeze({ version: PRICING_VERSION, date: PRICING_DATE, source: PRICING_SOURCE,
+  currency: 'USD', unit: 'cents_per_million_tokens', models: Object.freeze(Object.fromEntries(PRICES)) });
 const OPUS_MODELS = new Set(['claude-opus-5', 'claude-opus-5-5']);
 const EVENTS = new Set(['request_start', 'route', 'upstream_response', 'upstream_model', 'upstream_usage',
   'upstream_error', 'request_complete', 'request_error', 'request_cancelled']);
@@ -83,7 +91,7 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
     }
   }
 
-  function finish(key, failed = false, partial = false) {
+  function finish(key, failed = false, partial = false, failureReason = 'request_failed') {
     const request = inflight.get(key);
     if (!request) return;
     inflight.delete(key);
@@ -93,6 +101,9 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
     if (partial) session.partial = true;
     if (failed || request.failed || request.invalid || !request.prices || !request.usage || !baseline) {
       session.unpriced_requests++;
+      const reason = failed ? failureReason : request.failed ? 'request_failed' : request.unpricedReason
+        ?? (!baseline ? 'unknown_baseline' : !request.prices ? 'missing_model' : 'missing_usage');
+      session.unpriced_reasons[reason] = Math.min(Number.MAX_SAFE_INTEGER, (session.unpriced_reasons[reason] ?? 0) + 1);
       return;
     }
     session.actual += cost(request.usage, request.prices);
@@ -107,7 +118,7 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
       sessions.set(sessionId, session);
       return session;
     }
-    session = { actual: 0n, baseline: 0n, requests: 0, unpriced_requests: 0,
+    session = { actual: 0n, baseline: 0n, requests: 0, unpriced_requests: 0, unpriced_reasons: {},
       partial: historyPartial || evictedSessions.has(sessionId) };
     sessions.set(sessionId, session);
     while (sessions.size > MAX_SESSIONS) {
@@ -135,29 +146,42 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
       if (event.event === 'request_start') {
         if (inflight.has(key) || settled.has(key)) return;
         sessionFor(sessionId);
-        while (inflight.size >= MAX_INFLIGHT) finish(inflight.keys().next().value, true, true);
-        inflight.set(key, { sessionId, invalid: !standardPricing(event.pricing_context) });
+        while (inflight.size >= MAX_INFLIGHT) finish(inflight.keys().next().value, true, true, 'request_evicted');
+        const invalid = !standardPricing(event.pricing_context);
+        inflight.set(key, { sessionId, invalid, ...(invalid ? { unpricedReason: 'unsupported_pricing' } : {}) });
         return;
       }
       const request = inflight.get(key);
       if (!request) return;
       switch (event.event) {
         case 'route':
-          if (!standardPricing(event.pricing_context)) request.invalid = true;
+          if (!standardPricing(event.pricing_context)) { request.invalid = true; request.unpricedReason ??= 'unsupported_pricing'; }
           break;
         case 'upstream_response':
           if (!Number.isInteger(event.status) || event.status < 200 || event.status >= 300) request.failed = true;
           break;
         case 'upstream_model': {
           const prices = PRICES.get(event.model);
-          if (!prices || (request.prices && request.prices !== prices)) request.invalid = true;
+          if (!prices) { request.invalid = true; request.unpricedReason ??= 'unknown_model'; }
+          // A fallback can mix usage even between models with identical rates.
+          // No aggregate can prove the attribution of all billed tokens.
+          if (request.model !== undefined && request.model !== event.model) {
+            request.invalid = true; request.unpricedReason = 'mixed_models';
+          }
+          request.model = event.model;
           request.prices = prices;
           break;
         }
         case 'upstream_usage': {
           const usage = normalizeUsage(event.usage, request.prices);
-          if (!usage || !standardPricing(event.pricing_context)) request.invalid = true;
-          else if (request.usage && Object.keys(usage).some(key => usage[key] !== request.usage[key])) request.invalid = true;
+          if (!usage || !standardPricing(event.pricing_context)) {
+            request.invalid = true;
+            request.unpricedReason ??= !standardPricing(event.pricing_context) || !standardPricing(event.usage, request.prices === HAIKU_45)
+              ? 'unsupported_pricing' : 'invalid_usage';
+          }
+          else if (request.usage && Object.keys(usage).some(key => usage[key] !== request.usage[key])) {
+            request.invalid = true; request.unpricedReason ??= 'conflicting_usage';
+          }
           else request.usage = usage;
           break;
         }
@@ -165,12 +189,14 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
           request.failed = true;
           break;
         case 'request_complete':
-          finish(key);
+          finish(key, event.completion_confirmed === false, false, 'unconfirmed_completion');
           break;
         case 'request_error':
-        case 'request_cancelled':
           finish(key, true);
           break;
+        case 'request_cancelled':
+          finish(key, true, false, 'request_cancelled');
+          break;
       }
     } catch {
       // Telemetry must never interfere with inference. A malformed event must
@@ -179,7 +205,7 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
         const sessionId = event?.session_id == null ? '' : identifier(event.session_id);
         const requestId = identifier(event?.request_id);
         const request = inflight.get(`${sessionId}\0${requestId}`);
-        if (request) request.invalid = true;
+        if (request) { request.invalid = true; request.unpricedReason ??= 'invalid_telemetry'; }
       } catch {}
     }
   }
@@ -189,12 +215,17 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
       const saved = session.baseline - session.actual;
       return [sessionId, {
         baseline_model: baselineName,
+        pricing_version: PRICING_VERSION,
+        pricing_date: PRICING_DATE,
+        pricing_source: PRICING_SOURCE,
         actual_usd: Number(session.actual) / 100000000,
         baseline_usd: Number(session.baseline) / 100000000,
         saved_usd: Number(saved) / 100000000,
         percent: session.baseline === 0n ? 0 : Number(saved) / Number(session.baseline) * 100,
         requests: session.requests,
         unpriced_requests: session.unpriced_requests,
+        unpriced_reasons: Object.fromEntries(UNPRICED_REASONS.filter(reason => session.unpriced_reasons[reason])
+          .map(reason => [reason, session.unpriced_reasons[reason]])),
         ...(session.partial || historyPartial ? { partial: true } : {}),
       }];
     }));
@@ -206,3 +237,30 @@ export function createSavingsTracker({ baselineModel = 'claude-opus-5-5' } = {})
 
   return { update, snapshot, clear };
 }
+
+// Saved history must use the recorded baseline and reviewed table version,
+// never retroactively assume the current baseline or a successful response.
+export function estimateOutcomeSavings(value) {
+  const outcome = normalizeSessionRecord(value, { includePrompts: false });
+  const unpriced = unpriced_reason => ({ priced: false, unpriced_reason });
+  if (!outcome || outcome.event !== 'outcome') return unpriced('invalid_telemetry');
+  if (outcome.status === 'cancelled') return unpriced('request_cancelled');
+  if (outcome.status === 'error') return unpriced('request_failed');
+  if (outcome.completion_confirmed !== true) return unpriced('unconfirmed_completion');
+  if (outcome.pricing_version !== PRICING_VERSION) return unpriced('unknown_pricing_version');
+  if (!OPUS_MODELS.has(outcome.baseline_model)) return unpriced('unknown_baseline');
+  if (outcome.usage_complete === false) return unpriced('incomplete_usage');
+  if (outcome.model_transitions_truncated || new Set([outcome.confirmed_model, ...(outcome.model_transitions ?? [])].filter(Boolean)).size > 1) return unpriced('mixed_models');
+  if (outcome.pricing_eligible === false) return unpriced(outcome.unpriced_reason ?? 'unsupported_pricing');
+  const tracker = createSavingsTracker({ baselineModel: outcome.baseline_model });
+  const identity = { request_id: 'outcome', session_id: 'outcome' };
+  tracker.update({ ...identity, event: 'request_start', pricing_context: outcome.pricing_context });
+  if (outcome.http_status !== undefined) tracker.update({ ...identity, event: 'upstream_response', status: outcome.http_status });
+  if (outcome.confirmed_model) tracker.update({ ...identity, event: 'upstream_model', model: outcome.confirmed_model });
+  if (outcome.usage !== undefined) tracker.update({ ...identity, event: 'upstream_usage', usage: outcome.usage });
+  tracker.update({ ...identity, event: 'request_complete' });
+  const result = tracker.snapshot().outcome;
+  if (result.unpriced_requests) return unpriced(Object.keys(result.unpriced_reasons)[0]);
+  return { priced: true, actual_usd: result.actual_usd, baseline_usd: result.baseline_usd,
+    saved_usd: result.saved_usd, percent: result.percent, baseline_model: result.baseline_model, pricing_version: result.pricing_version };
+}

package/src/server.mjs

@@ -8,6 +8,9 @@ import { prepareRequest } from './model-request.mjs';
 import { createResponseObserver } from './response-observer.mjs';
 import { createTokenCounter } from './token-counter.mjs';
 import { promptExcerpt } from './prompt-state.mjs';
+import { validateRequestShape } from './request-validation.mjs';
+import { normalizeSessionRecord } from './telemetry-event.mjs';
+import { PRICING_VERSION, estimateOutcomeSavings } from './savings.mjs';
 
 function cleanHeaders(headers) {
   const blocked = new Set(['host', 'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'content-length']);
@@ -67,6 +70,7 @@ function upstreamHeaders(incoming, config) {
 }
 
 async function forward(url, req, res, body, config, signal, log, status) {
+  let execution;
   const headers = upstreamHeaders(req.headers, config);
   if (body) headers['content-length'] = String(body.length);
   const transport = url.protocol === 'https:' ? https : http;
@@ -91,6 +95,7 @@ async function forward(url, req, res, body, config, signal, log, status) {
         onModel: ({ model }) => { log({ event: 'upstream_model', model }); status('upstream_model', { model }); },
         onError: ({ error_type }) => { log({ event: 'upstream_error', error_type }); status('upstream_error', { error_type }); },
         onUsage: ({ usage }) => { if (upstream.statusCode >= 200 && upstream.statusCode < 300) status('upstream_usage', { usage }); },
+        onComplete: evidence => { execution = evidence; },
       });
       await pipeline(upstream, observer, res, { signal });
     } else {
@@ -100,19 +105,66 @@ async function forward(url, req, res, body, config, signal, log, status) {
     if (!signal.aborted || signal.reason?.name === 'TimeoutError') status('request_error', { status: 502 });
     throw error;
   }
+  return upstream.statusCode >= 200 && upstream.statusCode < 300 ? execution : undefined;
 }
 
-export function createRouterServer(config, { router = new Router(config), tokenCounter = createTokenCounter(config), log = entry => process.stderr.write(`${JSON.stringify(entry)}\n`), onStatus = () => {}, onDecision } = {}) {
+export function createRouterServer(config, { router = new Router(config), tokenCounter = createTokenCounter(config), log = entry => process.stderr.write(`${JSON.stringify(entry)}\n`), onStatus = () => {}, onDecision, onRecord } = {}) {
   if (!config.localToken || config.localToken.length < 16) throw new Error('AUTOROUTER_TOKEN must contain at least 16 characters');
   const server = http.createServer(async (req, res) => {
     const controller = new AbortController();
     let context;
     let finished = false;
+    const startedAt = performance.now();
+    let forwardedAt;
+    const outcome = { baseline_model: config.models.opus, pricing_version: PRICING_VERSION, completion_confirmed: false };
+    const record = entry => {
+      if (!onRecord) return;
+      try {
+        const row = normalizeSessionRecord({ timestamp: new Date().toISOString(), ...context, ...entry },
+          { includePrompts: config.sessionLogMode !== 'metadata' });
+        if (row) Promise.resolve(onRecord(row)).catch(() => {});
+      } catch {}
+    };
     const status = (event, fields = {}) => {
       if (!context || finished) return;
+      if (event === 'route') Object.assign(outcome, fields, { selected_model: fields.model,
+        routing_latency_ms: fields.latency_ms, decision_latency_ms: fields.latency_ms });
+      if (event === 'upstream_response') {
+        outcome.http_status = fields.status;
+        outcome.first_response_ms = Math.round((performance.now() - (forwardedAt ?? startedAt)) * 100) / 100;
+        fields.first_response_ms = outcome.first_response_ms;
+        if (fields.status >= 400) outcome.error_type = 'http_error';
+      }
+      if (event === 'upstream_model') {
+        outcome.confirmed_model = fields.model;
+        if (outcome.model_transitions?.at(-1) !== fields.model) {
+          outcome.model_transitions ??= [];
+          if (outcome.model_transitions.length < 16) outcome.model_transitions.push(fields.model);
+          else outcome.model_transitions_truncated = true;
+        }
+      }
+      if (event === 'upstream_usage') outcome.usage = fields.usage;
+      if (['upstream_error', 'request_error'].includes(event)) {
+        outcome.error_type = fields.error_type ?? 'request_error';
+        if (fields.status) outcome.http_status = fields.status;
+      }
       if (['request_complete', 'request_error', 'request_cancelled'].includes(event)) finished = true;
+      if (finished) {
+        fields.total_latency_ms = Math.round((performance.now() - startedAt) * 100) / 100;
+        fields.completion_confirmed = outcome.completion_confirmed;
+      }
       // Optional observability must never delay or fail an inference request.
       try { Promise.resolve(onStatus({ ...context, event, ...fields })).catch(() => {}); } catch {}
+      if (finished && onRecord) {
+        const completed = { ...context, ...outcome, event: 'outcome',
+          status: outcome.error_type ? 'error' : event === 'request_cancelled' ? 'cancelled' : 'completed',
+          usage_complete: outcome.completion_confirmed === true && Number.isSafeInteger(outcome.usage?.input_tokens)
+            && outcome.usage.input_tokens >= 0 && Number.isSafeInteger(outcome.usage.output_tokens) && outcome.usage.output_tokens >= 0,
+          total_latency_ms: Math.round((performance.now() - startedAt) * 100) / 100 };
+        const estimate = estimateOutcomeSavings(completed);
+        record({ ...completed, pricing_eligible: estimate.priced,
+          ...(!estimate.priced ? { unpriced_reason: estimate.unpriced_reason } : {}) });
+      }
     };
     const rejectRequest = (code, message) => {
       status('request_error', { status: code });
@@ -154,17 +206,19 @@ export function createRouterServer(config, { router = new Router(config), tokenC
         body = await readBody(req, config.maxBodyBytes);
         let parsed;
         try { parsed = JSON.parse(body); } catch { return rejectRequest(400, 'Invalid JSON body'); }
-        if (!parsed || typeof parsed.model !== 'string' || !Array.isArray(parsed.messages) || parsed.messages.some(m => !m || !['user', 'assistant', 'system'].includes(m.role) || !(typeof m.content === 'string' || (Array.isArray(m.content) && m.content.every(b => b && typeof b.type === 'string'))))) {
+        const shape = validateRequestShape(parsed);
+        if (!shape.valid) {
           log({ event: 'invalid_request_shape', model_type: typeof parsed?.model, messages_type: Array.isArray(parsed?.messages) ? 'array' : typeof parsed?.messages,
             messages: Array.isArray(parsed?.messages) ? parsed.messages.slice(0, 10).map(m => ({
               role: ['user', 'assistant', 'system'].includes(m?.role) ? m.role : typeof m?.role,
               content_type: Array.isArray(m?.content) ? 'array' : typeof m?.content,
               blocks: Array.isArray(m?.content) ? m.content.slice(0, 10).map(b => ({ value_type: b === null ? 'null' : typeof b, type_type: typeof b?.type })) : undefined,
             })) : undefined });
-          return rejectRequest(400, 'Expected a model and Messages API messages');
+          return rejectRequest(400, shape.error);
         }
         if (inference) {
           const decision = await router.route(parsed, {
+            requestId: context.request_id,
             signal: controller.signal,
             scope: JSON.stringify([req.headers['x-claude-code-session-id'], req.headers['x-claude-code-agent-id']]),
             promptId: req.headers['x-claude-code-prompt-id'],
@@ -179,20 +233,26 @@ export function createRouterServer(config, { router = new Router(config), tokenC
           // Prompt excerpts go only to this explicit opt-in sink, never to
           // ordinary diagnostics or the status snapshot. Optional logging
           // cannot delay or fail forwarding, including an async sink failure.
-          if (onDecision) {
+          if (onDecision || onRecord) {
             try {
-              const chars = [...(!context.request_class || context.request_class === 'main' ? promptExcerpt(parsed, 501) : '')];
-              Promise.resolve(onDecision({
-                schema_version: 1, event: 'decision', timestamp: new Date().toISOString(), ...context,
-                prompt_excerpt: chars.slice(0, 500).join(''), prompt_truncated: chars.length > 500,
+              const includePrompts = config.sessionLogMode !== 'metadata';
+              const chars = [...(includePrompts && (!context.request_class || context.request_class === 'main') ? promptExcerpt(parsed, 501) : '')];
+              const row = {
+                schema_version: 2, event: 'decision', timestamp: new Date().toISOString(), ...context,
+                ...(includePrompts ? { prompt_excerpt: chars.slice(0, 500).join(''), prompt_truncated: chars.length > 500 } : {}),
                 requested_model: parsed.model, selected_model: decision.model, decision_latency_ms: decision.latency_ms,
+                routing_latency_ms: decision.latency_ms, evaluation_latency_ms: decision.evaluation_latency_ms,
                 source: decision.source, reason: decision.reason, evaluator: decision.evaluator,
                 classified_tier: decision.classified_tier, classifier_error: decision.classifier_error,
-              })).catch(() => {});
+                classifier_status: decision.classifier_status, compatibility_reason: decision.compatibility_reason,
+                continuity_state: decision.continuity_state, context_check: decision.context_check, counted_input_tokens: decision.counted_input_tokens,
+              };
+              record(row);
+              if (onDecision) Promise.resolve(onDecision(row)).catch(() => {});
             } catch {}
           }
           log({ event: 'route', requested_model: parsed.model, ...decision, request_adjustments: prepared.adjustments });
-          const { model, source, evaluator, reason, latency_ms, classifier_error, classifier_status, classified_tier, context_check, counted_input_tokens } = decision;
+          const { model, source, evaluator, reason, latency_ms, evaluation_latency_ms, classifier_error, classifier_status, classified_tier, context_check, counted_input_tokens, continuity_state, compatibility_reason } = decision;
           const pricingValue = (field, allowed, fallback) => prepared.request[field] === undefined ? fallback
             : allowed.includes(prepared.request[field]) ? prepared.request[field] : 'unknown';
           const pricing_context = {
@@ -203,12 +263,15 @@ export function createRouterServer(config, { router = new Router(config), tokenC
           if (prepared.request.fallbacks != null || prepared.request.fallback_credit_token != null
             || (Array.isArray(prepared.request.tools) && prepared.request.tools.some(tool => typeof tool?.type === 'string' && /^advisor(?:_|$)/.test(tool.type)))) pricing_context.pricing_unsupported = true;
           status('route', { requested_model: parsed.model, model, source, evaluator, reason, latency_ms, classifier_error, classifier_status,
-            classified_tier, context_check, counted_input_tokens, pricing_context });
+            evaluation_latency_ms, routing_latency_ms: latency_ms, classified_tier, context_check, counted_input_tokens, continuity_state, compatibility_reason, pricing_context });
         }
       }
       if (controller.signal.aborted) { status('request_cancelled'); return; }
       const target = new URL(`${config.upstream}${url.pathname}${url.search}`);
-      await forward(target, req, res, body, config, AbortSignal.any([controller.signal, AbortSignal.timeout(config.upstreamTimeoutMs)]), log, status);
+      forwardedAt = performance.now();
+      const execution = await forward(target, req, res, body, config, AbortSignal.any([controller.signal, AbortSignal.timeout(config.upstreamTimeoutMs)]), log, status);
+      outcome.completion_confirmed = Boolean(execution) && !controller.signal.aborted;
+      if (context) router.complete?.(context.request_id, controller.signal.aborted ? undefined : execution);
       status('request_complete');
     } catch (error) {
       if (controller.signal.aborted) { status('request_cancelled'); return; }
@@ -216,6 +279,10 @@ export function createRouterServer(config, { router = new Router(config), tokenC
       // and metadata-only, including on error paths.
       log({ event: 'proxy_error', status: error.status ?? 502 });
       rejectRequest(error.status ?? 502, error.status === 413 ? 'Request body too large' : 'Router could not complete the upstream request');
+    } finally {
+      // Release staged attempts on every early return, abort and error. This
+      // is a no-op after a successfully committed execution.
+      if (context) router.complete?.(context.request_id);
     }
   });
   server.requestTimeout = 30000;

package/src/session-history.mjs

@@ -0,0 +1,262 @@
+import { constants } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { loadUserConfig } from './user-config.mjs';
+import { parseSessionLogDir } from './config.mjs';
+import { normalizeSessionRecord } from './telemetry-event.mjs';
+import { estimateOutcomeSavings, PRICING_FACTS } from './savings.mjs';
+
+export const HISTORY_LIMITS = Object.freeze({ maxFiles: 100, maxDirectoryEntries: 10000,
+  maxFileBytes: 4 * 1024 * 1024, maxTotalBytes: 16 * 1024 * 1024, maxLineBytes: 16384,
+  maxRecords: 5000, maxLines: 10000 });
+const ID = /^autorouter-session-[A-Za-z0-9-]{1,160}$/;
+const safeText = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const increment = (counts, key) => {
+  if (key) Object.defineProperty(counts, key, { value: (Object.hasOwn(counts, key) ? counts[key] : 0) + 1,
+    enumerable: true, writable: true, configurable: true });
+};
+const sortedCounts = counts => Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+function limitsFor(overrides) {
+  const limits = { ...HISTORY_LIMITS };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!Object.hasOwn(limits, key) || !Number.isSafeInteger(value) || value < 1 || value > limits[key]) throw new Error('Invalid session-history read limit.');
+    limits[key] = value;
+  }
+  return limits;
+}
+function latencyStats(values) {
+  values.sort((a, b) => a - b);
+  return values.length ? { samples: values.length, p50: values[Math.ceil(values.length * .5) - 1],
+    p95: values[Math.ceil(values.length * .95) - 1], max: values.at(-1) } : { samples: 0 };
+}
+function summarize(id, rows, coverage) {
+  const requests = new Map(), selected = {}, confirmed = {}, sources = {}, reasons = {}, classifierErrors = {};
+  const decisionLatencies = [], totalLatencies = [], baselines = new Set(), pricingVersions = new Set();
+  let decisions = 0, outcomes = 0, legacy = 0, duplicates = 0, unversionedOutcomes = 0;
+  for (const row of rows) {
+    let request = requests.get(row.request_id);
+    if (!request) { request = {}; requests.set(row.request_id, request); }
+    if (request[row.event]) {
+      duplicates++;
+      if (JSON.stringify(request[row.event]) !== JSON.stringify(row)) request.conflicting = true;
+      continue;
+    }
+    request[row.event] = row;
+    if (row.event === 'decision') {
+      decisions++;
+      if (row.schema_version === 1) legacy++;
+      increment(selected, row.selected_model); increment(sources, row.source); increment(reasons, row.reason);
+      increment(classifierErrors, row.classifier_error);
+      if (Number.isFinite(row.decision_latency_ms)) decisionLatencies.push(row.decision_latency_ms);
+    } else {
+      outcomes++;
+      increment(confirmed, row.confirmed_model);
+      if (row.baseline_model) baselines.add(row.baseline_model);
+      if (row.pricing_version) pricingVersions.add(row.pricing_version); else unversionedOutcomes++;
+      if (Number.isFinite(row.total_latency_ms)) totalLatencies.push(row.total_latency_ms);
+    }
+  }
+  let completed = 0, failed = 0, cancelled = 0, pending = 0, unconfirmed = 0, outcomeOnly = 0, conflicting = 0;
+  const savings = { basis: 'API-equivalent estimate, not subscription charges', actual_usd: 0, baseline_usd: 0,
+    saved_usd: 0, percent: 0, priced_requests: 0, unpriced_requests: 0, unpriced_reasons: {} };
+  for (const request of requests.values()) {
+    const { decision, outcome } = request;
+    if (request.conflicting) conflicting++;
+    const estimate = request.conflicting ? { priced: false, unpriced_reason: 'invalid_telemetry' }
+      : outcome ? estimateOutcomeSavings(outcome) : { priced: false, unpriced_reason: 'missing_outcome' };
+    if (estimate.priced) {
+      savings.priced_requests++;
+      for (const field of ['actual_usd', 'baseline_usd', 'saved_usd']) savings[field] += estimate[field];
+    } else { savings.unpriced_requests++; increment(savings.unpriced_reasons, estimate.unpriced_reason); }
+    if (!outcome) { pending++; continue; }
+    if (!decision) outcomeOnly++;
+    if (outcome.status === 'cancelled') cancelled++;
+    else if (outcome.status === 'error' || (outcome.http_status !== undefined && (outcome.http_status < 200 || outcome.http_status >= 300))) failed++;
+    else if (outcome.completion_confirmed === true && !request.conflicting) completed++;
+    else unconfirmed++;
+  }
+  savings.percent = savings.baseline_usd === 0 ? 0 : savings.saved_usd / savings.baseline_usd * 100;
+  savings.unpriced_reasons = sortedCounts(savings.unpriced_reasons);
+  const timestamps = rows.map(row => row.timestamp).sort();
+  return { id, ...(rows[0]?.session_id ? { session_id: rows[0].session_id } : {}),
+    started_at: timestamps[0] ?? null, updated_at: timestamps.at(-1) ?? null,
+    requests: requests.size, decisions, outcomes, completed, failed, cancelled, pending, unconfirmed, outcome_only: outcomeOnly,
+    selected_models: sortedCounts(selected), confirmed_models: sortedCounts(confirmed), sources: sortedCounts(sources),
+    routing_reasons: sortedCounts(reasons), classifier_errors: sortedCounts(classifierErrors),
+    fallbacks: sources.fallback ?? 0, fallback_rate: decisions ? (sources.fallback ?? 0) / decisions : 0,
+    decision_latency_ms: latencyStats(decisionLatencies), total_latency_ms: latencyStats(totalLatencies),
+    baseline_models: [...baselines].sort(), mixed_baselines: baselines.size > 1,
+    pricing_versions: [...pricingVersions].sort(), mixed_pricing_versions: pricingVersions.size > 1,
+    pricing_facts: pricingVersions.has(PRICING_FACTS.version)
+      ? [{ version: PRICING_FACTS.version, date: PRICING_FACTS.date, source: PRICING_FACTS.source }] : [],
+    unversioned_outcomes: unversionedOutcomes, savings,
+    coverage: { ...coverage, legacy_decisions: legacy, duplicate_records: duplicates, conflicting_requests: conflicting,
+      partial: coverage.partial || duplicates > 0 },
+  };
+}
+
+async function sameDirectory(root, identity) {
+  const current = await fs.lstat(root);
+  if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== identity.dev || current.ino !== identity.ino) {
+    throw new Error('Session log directory changed or is not a regular directory.');
+  }
+}
+
+async function readSession(root, identity, id, limits, remainingBytes) {
+  let handle;
+  try {
+    await sameDirectory(root, identity);
+    // Nonblocking open also prevents a replaced FIFO/device from hanging the
+    // local inspection before we can verify that it is a regular file.
+    handle = await fs.open(join(root, `${id}.jsonl`), constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1) throw new Error('Session log is not a regular private file.');
+    await sameDirectory(root, identity);
+    const capacity = Math.min(stat.size, limits.maxFileBytes, remainingBytes);
+    const buffer = Buffer.alloc(capacity);
+    let bytesRead = 0;
+    while (bytesRead < capacity) {
+      const result = await handle.read(buffer, bytesRead, capacity - bytesRead, bytesRead);
+      if (!result.bytesRead) break;
+      bytesRead += result.bytesRead;
+    }
+    const coverage = { bytes_read: bytesRead, file_bytes: stat.size, lines_read: 0, invalid_records: 0,
+      oversized_lines: 0, mixed_session_records: 0, truncated: bytesRead < stat.size, incomplete_tail: false, partial: false };
+    const rows = [];
+    let offset = 0, sessionIdentity;
+    while (offset < bytesRead) {
+      if (rows.length >= limits.maxRecords || coverage.lines_read >= limits.maxLines) { coverage.truncated = true; break; }
+      const end = buffer.indexOf(10, offset);
+      if (end < 0 || end >= bytesRead) { coverage.incomplete_tail = true; break; }
+      const length = end - offset;
+      coverage.lines_read++;
+      if (length > limits.maxLineBytes) { coverage.oversized_lines++; offset = end + 1; continue; }
+      try {
+        const entry = JSON.parse(buffer.toString('utf8', offset, end));
+        if (!object(entry) || ![1, 2].includes(entry.schema_version)
+          || (entry.schema_version === 1 && entry.event !== 'decision')
+          || typeof entry.timestamp !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(entry.timestamp)
+          || !Number.isFinite(Date.parse(entry.timestamp))) throw new Error('Invalid record');
+        const row = normalizeSessionRecord(entry, { includePrompts: Object.hasOwn(entry, 'prompt_excerpt') });
+        if (!row) throw new Error('Invalid record');
+        const rowSession = row.session_id ?? '';
+        if (sessionIdentity === undefined) sessionIdentity = rowSession;
+        if (rowSession !== sessionIdentity) coverage.mixed_session_records++;
+        else rows.push({ ...row, schema_version: entry.schema_version });
+      } catch { coverage.invalid_records++; }
+      offset = end + 1;
+    }
+    coverage.partial = coverage.truncated || coverage.incomplete_tail || coverage.invalid_records > 0
+      || coverage.oversized_lines > 0 || coverage.mixed_session_records > 0;
+    return { summary: summarize(id, rows, coverage), records: rows };
+  } finally { if (handle) await handle.close(); }
+}
+
+/** Reads only bounded, recognized JSONL files; never modifies or deletes logs. */
+export async function readSessionHistory(directory, { id, limits: overrides = {} } = {}) {
+  const limits = limitsFor(overrides);
+  if (id !== undefined && (typeof id !== 'string' || !ID.test(id))) throw new Error('Use an exact session ID from sessions list.');
+  if (typeof directory !== 'string' || !directory.trim() || typeof constants.O_NOFOLLOW !== 'number') throw new Error('A regular session log directory is required.');
+  const root = resolve(directory);
+  let identity;
+  try { identity = await fs.lstat(root); }
+  catch (error) {
+    if (error.code === 'ENOENT' && id === undefined) return { schema_version: 1, type: 'session_history', sessions: [], limits, coverage: { partial: false, directory_missing: true } };
+    throw new Error('Could not read the session log directory.');
+  }
+  if (!identity.isDirectory() || identity.isSymbolicLink()) throw new Error('Session logs must be read from a regular directory, not a symbolic link.');
+  if (id !== undefined) {
+    try {
+      const result = await readSession(root, identity, id, limits, limits.maxTotalBytes);
+      return { schema_version: 1, type: 'session_history', ...result, limits };
+    } catch { throw new Error('Could not read that session as a regular log file. Use sessions list for available IDs.'); }
+  }
+  const ids = [], coverage = { partial: false, directory_entries: 0, matching_files: 0, skipped_files: 0,
+    unreadable_files: 0, bytes_read: 0, directory_scan_truncated: false, byte_limit_reached: false };
+  let directoryHandle;
+  try {
+    directoryHandle = await fs.opendir(root);
+    for await (const entry of directoryHandle) {
+      if (++coverage.directory_entries > limits.maxDirectoryEntries) { coverage.directory_scan_truncated = true; break; }
+      if (!entry.name.endsWith('.jsonl')) continue;
+      const candidate = entry.name.slice(0, -6);
+      if (!ID.test(candidate)) continue;
+      if (!entry.isFile()) { coverage.skipped_files++; continue; }
+      coverage.matching_files++;
+      ids.push(candidate);
+      ids.sort().reverse();
+      if (ids.length > limits.maxFiles) ids.pop();
+    }
+    await sameDirectory(root, identity);
+  } catch { throw new Error('Could not safely list the session log directory.'); }
+  const sessions = [];
+  for (const candidate of ids) {
+    if (coverage.bytes_read >= limits.maxTotalBytes) { coverage.byte_limit_reached = true; break; }
+    try {
+      const result = await readSession(root, identity, candidate, limits, limits.maxTotalBytes - coverage.bytes_read);
+      coverage.bytes_read += result.summary.coverage.bytes_read;
+      sessions.push(result.summary);
+    } catch { coverage.unreadable_files++; }
+  }
+  coverage.skipped_files += coverage.matching_files - sessions.length - coverage.unreadable_files;
+  coverage.partial = coverage.directory_scan_truncated || coverage.byte_limit_reached || coverage.skipped_files > 0
+    || coverage.unreadable_files > 0 || sessions.some(session => session.coverage.partial);
+  return { schema_version: 1, type: 'session_history', sessions, limits, coverage };
+}
+
+const modelsText = models => Object.entries(models).map(([name, count]) => `${name} (${count})`).join(', ') || 'none';
+function printSummary(summary, write) {
+  write(`ID: ${summary.id}`);
+  write(`Session: ${summary.session_id ?? 'anonymous'}; ${summary.started_at ?? 'no valid records'} to ${summary.updated_at ?? 'unknown'}`);
+  write(`Observed: ${summary.decisions} selections; ${summary.completed} confirmed completed; ${summary.failed} failed; ${summary.cancelled} cancelled; ${summary.pending} without outcome; ${summary.unconfirmed} unconfirmed outcomes.`);
+  write(`Selected models: ${modelsText(summary.selected_models)}`);
+  write(`Response models observed: ${modelsText(summary.confirmed_models)}`);
+  write(`Fallbacks: ${summary.fallbacks} of ${summary.decisions} selections (${(summary.fallback_rate * 100).toFixed(1)}%); routing reasons: ${modelsText(summary.routing_reasons)}`);
+  const saved = summary.savings.priced_requests ? `$${summary.savings.saved_usd.toFixed(4)}` : 'unavailable';
+  write(`API-equivalent savings: ${saved}; priced ${summary.savings.priced_requests}/${summary.requests} observed requests; ${summary.savings.unpriced_requests} unpriced. These are not subscription charges.`);
+  if (summary.baseline_models.length) write(`Recorded Opus baseline${summary.mixed_baselines ? 's (mixed)' : ''}: ${summary.baseline_models.join(', ')}`);
+  write(`Recorded pricing version${summary.mixed_pricing_versions ? 's (mixed)' : ''}: ${summary.pricing_versions.join(', ') || 'not recorded'}${summary.unversioned_outcomes ? `; ${summary.unversioned_outcomes} outcomes without a recorded version` : ''}.`);
+  for (const facts of summary.pricing_facts) write(`Pricing facts ${facts.version}, reviewed ${facts.date}: ${facts.source}`);
+  if (summary.savings.unpriced_requests) write(`Unpriced reasons: ${modelsText(summary.savings.unpriced_reasons)}`);
+  if (summary.decision_latency_ms.samples) write(`Decision latency: p50 ${summary.decision_latency_ms.p50} ms; p95 ${summary.decision_latency_ms.p95} ms (${summary.decision_latency_ms.samples} samples).`);
+  if (summary.coverage.partial) write('Partial history: limits, incomplete writes, duplicate or unreadable records affect these observed counts.');
+  if (summary.coverage.legacy_decisions) write(`${summary.coverage.legacy_decisions} legacy decisions record selection only; no successful response is implied.`);
+}
+
+export async function sessionsCommand(args, { env = process.env, write = console.log } = {}) {
+  const operation = args[0], json = args.includes('--json');
+  const positional = args.slice(1).filter(arg => arg !== '--json');
+  if (!['list', 'show'].includes(operation) || positional.some(arg => arg.startsWith('--'))
+    || (operation === 'list' ? positional.length !== 0 : positional.length !== 1)) {
+    throw new Error('Usage: claude-autorouter sessions list [--json] | sessions show ID [--json]');
+  }
+  // History needs only the log directory; never prompt for keychain access.
+  const loaded = loadUserConfig(env, { allowMissing: true, readSecrets: false });
+  const directory = parseSessionLogDir(loaded.env.AUTOROUTER_SESSION_LOG_DIR);
+  if (!directory) {
+    const report = { schema_version: 1, type: 'session_history', logging_enabled: false, sessions: [],
+      message: 'Session logging is disabled. Set AUTOROUTER_SESSION_LOG_DIR to record future sessions.' };
+    write(json ? JSON.stringify(report, null, 2) : report.message);
+    return operation === 'list';
+  }
+  const report = await readSessionHistory(directory, operation === 'show' ? { id: positional[0] } : {});
+  if (json) write(JSON.stringify({ ...report, logging_enabled: true }, null, 2));
+  else {
+    if (operation === 'list') {
+      if (!report.sessions.length) write('No readable session logs found.');
+      for (const summary of report.sessions) printSummary(summary, write);
+      if (report.coverage.partial) write('Partial scan: displayed sessions or counts are limited; use sessions show ID for an individual file.');
+    } else {
+      printSummary(report.summary, write);
+      for (const row of report.records) {
+        const description = row.event === 'decision'
+          ? `selected ${row.selected_model}; ${row.source ?? 'unknown source'}; ${row.reason ?? 'unspecified reason'}`
+          : `${row.status}${row.http_status ? ` (HTTP ${row.http_status})` : ''}${row.error_type ? `; ${row.error_type}` : ''}; response model ${row.confirmed_model ?? 'not observed'}; completion ${row.completion_confirmed ? 'confirmed' : 'unconfirmed'}`;
+        write(`${row.timestamp} ${row.request_id}: ${description}`);
+        if (row.prompt_excerpt) write(`  Prompt excerpt: ${safeText(row.prompt_excerpt)}${row.prompt_truncated ? '… [truncated]' : ''}`);
+      }
+    }
+  }
+  return true;
+}