sandoichi 0.4.1 → 0.5.0

package/README.md

@@ -24,9 +24,13 @@ 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 plugin remains the supported host surface; this package exports the context/history runtime, provider usage report, paired accounting, and explicit proxy API only.
+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 remains the supported host surface; this package exports the bounded output/disclosure runtime, context footprint audit, F1/F3/F4 evidence APIs, provider usage report, paired accounting, and explicit proxy API. Host hooks and MCP registration remain outside the package API.
 
-`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted estimates, provider-reported cost, and paired-session evidence separate. The benchmark report adds explicit replay counterfactuals. The library does not install hooks, register MCP servers, or make routing/backoff decisions for a host.
+The provider proxy is pass-through unless request transformation is explicitly enabled.
+
+The recoverable-history strategy is opt-in and keeps eligible results inline when they are below 3,072 bytes by default. Provider-boundary replay measurements are diagnostic paired evidence; they do not predict end-to-end agent behavior or provider billing across workloads.
+
+`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted cost units, and paired-session evidence separate from the provider-usage report's reported cost provenance and coverage. Host-reported list estimates are not billed-cost records. 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

@@ -56,7 +56,82 @@ export {
   PROVIDER_USAGE_VERSION,
 } from './src/provider-usage.mjs';
 export { planToolRoute, ROUTING_POLICY_VERSION } from './src/routing.mjs';
+export {
+  CONTEXT_CAPTURE_SCHEMA,
+  CONTEXT_CATEGORIES,
+  CONTEXT_FOOTPRINT_SCHEMA,
+  CONTEXT_FOOTPRINT_VERSION,
+  buildContextFootprintReport,
+  detectToolSearchState,
+  serializeContextFootprint,
+} from './src/context-footprint.mjs';
+export { classifyContextRequest } from './src/context-classifier.mjs';
+export { formatContextFootprintReport, runContextAuditCli } from './src/context-audit-cli.mjs';
+export {
+  CONTEXT_CAPTURE_RECORD_SCHEMA,
+  CONTEXT_CAPTURE_RECORD_VERSION,
+  buildContextCaptureRecord,
+  defaultContextCapturePath,
+  normalizeProviderUsage,
+  recordContextCapture,
+} from './src/context-capture.mjs';
+export {
+  ARTIFACT_TOOL_NAME,
+  RESULT_DISCLOSURE_SCHEMA,
+  RESULT_DISCLOSURE_VERSION,
+  buildResultDisclosure,
+  serializeResultDisclosure,
+} from './src/result-disclosure.mjs';
+export {
+  ARTIFACT_RECOVERY_SCHEMA,
+  ARTIFACT_RECOVERY_VERSION,
+  MAX_RECOVERY_BYTES,
+  recoverArtifactContent,
+  recoverArtifactFromWorkspace,
+} from './src/artifact-recovery.mjs';
+export { runArtifactCli } from './src/artifact-cli.mjs';
+export {
+  DEFAULT_ARTIFACT_MAX_BYTES,
+  DEFAULT_ARTIFACT_TTL_MS,
+  cleanupArtifacts,
+} from './src/artifact-lifecycle.mjs';
+export { buildF1TelemetryEvent, publishF1Telemetry } from './src/f1-telemetry.mjs';
+export {
+  F4_EVENT_SCHEMA,
+  F4_EVENT_VERSION,
+  F4_HOSTS,
+  F4_LATENCY_BUCKETS,
+  F4_OPERATIONS,
+  F4_OUTCOMES,
+  F4_RESULT_BUCKETS,
+  buildF4Event,
+  buildF4TelemetryEvent,
+  defaultF4EventsPath,
+  DEFAULT_F4_TELEMETRY_ENDPOINT,
+  digestCapability,
+  latencyBucket,
+  publishF4Telemetry,
+  recordF4Event,
+  resultBucket,
+  serializeF4Event,
+} from './src/f4-telemetry.mjs';
+export {
+  GATE_EVIDENCE_SCHEMA,
+  GATE_SCHEMA,
+  GATE_THRESHOLDS,
+  GATE_VERSION,
+  evaluateGatewayGate,
+  serializeGatewayGate,
+} from './src/gateway-gate.mjs';
+export {
+  HISTORY_DISCLOSURE_SCHEMA,
+  HISTORY_DISCLOSURE_VERSION,
+  buildHistoryDisclosure,
+  serializeHistoryDisclosure,
+} from './src/history-disclosure.mjs';
 export { readStatusSnapshot, renderStatusLine, STATUSLINE_MAX_AGE_MS } from './src/statusline.mjs';
+export { GATEWAY_CATALOG_TOOL, LAZY_MCP_GATEWAY_SCHEMA, createLazyMcpGateway, validateJsonSchema } from './src/lazy-mcp-gateway.mjs';
+export { createConfiguredMcpServers, spawnMcpTransport, startLazyMcpGatewayStdio } from './src/lazy-mcp-gateway-stdio.mjs';
 export {
   activeSessionForPane,
   currentTmuxPanePid,

package/package.json

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

package/src/accounting-cli.mjs

@@ -21,7 +21,7 @@ export function formatAccountingReport(report) {
     `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}`,
+    `reported cost: ${report.cost.totalCostUsd === null ? report.cost.status : `$${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`);

package/src/artifact-cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { recoverArtifactFromWorkspace } from './artifact-recovery.mjs';
+
+function usage() {
+  return 'Usage: sando artifact get --ref HANDLE [--root DIR] [--start-byte N --end-byte N | --start-line N --end-line N] [--max-bytes N] [--json]\n';
+}
+
+function number(value, name) {
+  if (!/^\d+$/.test(value ?? '')) throw new Error(`${name} must be a non-negative integer`);
+  const result = Number(value);
+  if (!Number.isSafeInteger(result)) throw new Error(`${name} is too large`);
+  return result;
+}
+
+function parseArgs(argv) {
+  let args = [...argv];
+  if (args[0] === 'artifact') args = args.slice(1);
+  if (args[0] === 'get') args = args.slice(1);
+  const result = { root: process.cwd(), json: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--json') result.json = true;
+    else if (argument === '--help' || argument === '-h') result.help = true;
+    else if (['--root', '--ref', '--start-byte', '--end-byte', '--start-line', '--end-line', '--max-bytes'].includes(argument)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value`);
+      const key = argument.slice(2).replaceAll('-', '');
+      result[key] = ['startbyte', 'endbyte', 'startline', 'endline', 'maxbytes'].includes(key)
+        ? number(value, argument)
+        : value;
+      index += 1;
+    } else throw new Error('unknown artifact option');
+  }
+  if (!result.help && !result.ref) throw new Error('--ref is required');
+  if (!result.help && ((result.startbyte !== undefined) !== (result.endbyte !== undefined)
+    || (result.startline !== undefined) !== (result.endline !== undefined))) throw new Error('artifact ranges require start and end');
+  return result;
+}
+
+function terminal(report) {
+  return `Sando artifact ${report.handle}: ${report.bytes}B${report.truncated ? ' (bounded)' : ''}\n${report.content}\n`;
+}
+
+export function runArtifactCli({ argv = process.argv.slice(2), stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    const options = parseArgs(argv);
+    if (options.help) { stdout.write(usage()); return null; }
+    const report = recoverArtifactFromWorkspace({
+      cwd: path.resolve(options.root), ref: options.ref,
+      ...(options.startbyte !== undefined ? { startByte: options.startbyte, endByte: options.endbyte } : {}),
+      ...(options.startline !== undefined ? { startLine: options.startline, endLine: options.endline } : {}),
+      ...(options.maxbytes !== undefined ? { maxBytes: options.maxbytes } : {}),
+    });
+    stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : terminal(report));
+    return report;
+  } catch (error) {
+    stderr.write(`sando artifact get: ${error instanceof Error ? error.message : String(error)}\n${usage()}`);
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) runArtifactCli();

package/src/artifact-lifecycle.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_ARTIFACT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const DEFAULT_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
+
+function validNumber(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function safeArtifact(directory, name) {
+  if (!/^[a-f0-9]{64}\.txt$/.test(name)) return null;
+  const target = path.join(directory, name);
+  let link;
+  try { link = fs.lstatSync(target); } catch { return null; }
+  if (!link.isFile() || link.isSymbolicLink()) return null;
+  let resolved;
+  try { resolved = fs.realpathSync(target); } catch { return null; }
+  if (resolved !== target) return null;
+  let stat;
+  try { stat = fs.statSync(target); } catch { return null; }
+  return { target, name, bytes: stat.size, mtimeMs: stat.mtimeMs };
+}
+
+export function cleanupArtifacts(
+  directory,
+  {
+    now = Date.now(), ttlMs = DEFAULT_ARTIFACT_TTL_MS,
+    maxBytes = DEFAULT_ARTIFACT_MAX_BYTES, preserveName = null,
+  } = {},
+) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw new TypeError('artifact directory is invalid');
+  validNumber(now, 'now');
+  validNumber(ttlMs, 'ttlMs');
+  validNumber(maxBytes, 'maxBytes');
+  if (preserveName !== null && !/^[a-f0-9]{64}\.txt$/.test(preserveName)) {
+    throw new TypeError('preserveName is invalid');
+  }
+  const directoryStat = fs.lstatSync(directory, { throwIfNoEntry: false });
+  if (!directoryStat?.isDirectory() || directoryStat.isSymbolicLink()) throw new Error('artifact directory is unsafe');
+
+  const entries = fs.readdirSync(directory).map((name) => safeArtifact(directory, name)).filter(Boolean);
+  const expired = entries.filter((entry) => now - entry.mtimeMs >= ttlMs);
+  const keep = entries.filter((entry) => !expired.includes(entry));
+  let totalBytes = keep.reduce((total, entry) => total + entry.bytes, 0);
+  const removals = [...expired, ...keep.sort((left, right) => {
+    if (left.name === preserveName) return 1;
+    if (right.name === preserveName) return -1;
+    return left.mtimeMs - right.mtimeMs || left.name.localeCompare(right.name);
+  })];
+  let removed = 0;
+  let removedBytes = 0;
+  for (const entry of removals) {
+    if (expired.includes(entry) || totalBytes > maxBytes) {
+      try {
+        const current = safeArtifact(directory, entry.name);
+        if (!current || current.target !== entry.target) continue;
+        fs.rmSync(current.target);
+        removed += 1;
+        removedBytes += current.bytes;
+        if (!expired.includes(entry)) totalBytes -= current.bytes;
+      } catch { /* cleanup is best-effort and never follows unresolved targets */ }
+    }
+  }
+  return { removed, removedBytes, retainedBytes: Math.max(0, totalBytes) };
+}

package/src/artifact-recovery.mjs

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export const ARTIFACT_RECOVERY_SCHEMA = 'sando-artifact-recovery/v1';
+export const ARTIFACT_RECOVERY_VERSION = 1;
+export const MAX_RECOVERY_BYTES = 1_048_576;
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+function digest(text) {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function handleDigest(ref) {
+  const match = typeof ref === 'string' && ref.match(/^sando:(sha256:[a-f0-9]{16,64})$/);
+  if (!match) throw new TypeError('artifact handle is invalid');
+  return match[1];
+}
+
+export function validateArtifactHandle(ref) {
+  handleDigest(ref);
+  return ref;
+}
+
+function integer(value, name, { positive = false } = {}) {
+  if (!Number.isSafeInteger(value) || value < (positive ? 1 : 0)) throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function continuation(byte) { return (byte & 0xc0) === 0x80; }
+
+function safeBufferText(buffer, start, end) {
+  if (start > 0 && continuation(buffer[start])) throw new RangeError('byte range splits UTF-8');
+  if (end < buffer.length && continuation(buffer[end])) throw new RangeError('byte range splits UTF-8');
+  return buffer.subarray(start, end).toString('utf8');
+}
+
+function prefix(buffer, limit) {
+  let end = Math.min(buffer.length, limit);
+  while (end > 0 && end < buffer.length && continuation(buffer[end])) end -= 1;
+  return { text: buffer.subarray(0, end).toString('utf8'), truncated: end < buffer.length };
+}
+
+export function recoverArtifactContent({
+  ref, content, digest: expectedDigest, sourceBytes, startByte, endByte, startLine, endLine, maxBytes,
+} = {}) {
+  const handlePrefix = handleDigest(ref).slice('sha256:'.length);
+  const handle = ref;
+  if (typeof content !== 'string') throw new TypeError('artifact content is invalid');
+  const actualDigest = digest(content);
+  if (expectedDigest !== undefined && expectedDigest !== actualDigest) throw new Error('artifact digest integrity check failed');
+  const full = Buffer.from(content, 'utf8');
+  if (!actualDigest.slice('sha256:'.length).startsWith(handlePrefix)) throw new Error('artifact handle does not match content');
+  const limit = maxBytesValue(maxBytes);
+  const byteMode = startByte !== undefined || endByte !== undefined;
+  const lineMode = startLine !== undefined || endLine !== undefined;
+  if (byteMode && lineMode) throw new TypeError('artifact range is ambiguous');
+  let selected;
+  let range;
+  if (byteMode) {
+    const start = integer(startByte ?? 0, 'startByte');
+    const end = integer(endByte ?? full.length, 'endByte');
+    if (start > end || end > full.length) throw new RangeError('artifact byte range is invalid');
+    selected = safeBufferText(full, start, end);
+    range = { type: 'bytes', start, end };
+  } else if (lineMode) {
+    const start = integer(startLine ?? 1, 'startLine', { positive: true });
+    const end = integer(endLine ?? start, 'endLine', { positive: true });
+    const lines = content.split('\n');
+    if (start > end || start > lines.length || end > lines.length) throw new RangeError('artifact line range is invalid');
+    selected = lines.slice(start - 1, end).join('\n');
+    range = { type: 'lines', start, end };
+  } else {
+    selected = content;
+    range = { type: 'all' };
+  }
+  const selectedBuffer = Buffer.from(selected, 'utf8');
+  const bounded = prefix(selectedBuffer, limit);
+  const totalSourceBytes = integer(sourceBytes ?? full.length, 'sourceBytes');
+  if (totalSourceBytes !== full.length) throw new Error('artifact source byte metadata is inconsistent');
+  return {
+    schema: ARTIFACT_RECOVERY_SCHEMA,
+    version: ARTIFACT_RECOVERY_VERSION,
+    handle,
+    digest: actualDigest,
+    content: bounded.text,
+    bytes: Buffer.byteLength(bounded.text),
+    sourceBytes: totalSourceBytes,
+    range,
+    truncated: bounded.truncated,
+  };
+}
+
+function maxBytesValue(value) {
+  const result = value ?? 65_536;
+  integer(result, 'maxBytes', { positive: true });
+  if (result > MAX_RECOVERY_BYTES) throw new RangeError('maxBytes exceeds recovery limit');
+  return result;
+}
+
+function safeDirectory(target, name) {
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (!stat || !stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${name} is unavailable or unsafe`);
+}
+
+export function recoverArtifactFromWorkspace({ cwd, ref, ...range } = {}) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) throw new TypeError('artifact cwd is invalid');
+  const root = fs.realpathSync(cwd);
+  if (!fs.statSync(root).isDirectory()) throw new TypeError('artifact cwd is not a directory');
+  const stateRoot = path.join(root, '.sando');
+  const privateRoot = path.join(stateRoot, 'sando');
+  const directory = path.join(privateRoot, 'artifacts');
+  safeDirectory(stateRoot, 'artifact state');
+  safeDirectory(privateRoot, 'artifact private state');
+  safeDirectory(directory, 'artifact directory');
+  const digestPrefix = handleDigest(ref).slice('sha256:'.length);
+  const candidates = fs.readdirSync(directory)
+    .filter((entry) => /^[a-f0-9]{64}\.txt$/.test(entry) && entry.startsWith(digestPrefix));
+  if (candidates.length !== 1) throw new Error(candidates.length ? 'artifact handle is ambiguous' : 'artifact handle is unavailable');
+  const digestValue = `sha256:${candidates[0].slice(0, -'.txt'.length)}`;
+  const target = path.join(directory, candidates[0]);
+  const relative = path.relative(directory, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('artifact path escapes directory');
+  let descriptor;
+  try {
+    descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) throw new Error('artifact handle is unavailable');
+    if (stat.size > MAX_ARTIFACT_BYTES) throw new RangeError('artifact exceeds recovery limit');
+    const content = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(descriptor));
+    return recoverArtifactContent({ ref, content, digest: digestValue, ...range });
+  } catch (error) {
+    if (['ELOOP', 'ENOENT'].includes(error?.code)) throw new Error('artifact handle is unavailable', { cause: error });
+    throw error;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}

package/src/artifact-store.mjs

@@ -0,0 +1,44 @@
+import { recoverArtifactContent, validateArtifactHandle } from './artifact-recovery.mjs';
+
+const MAX_ARTIFACTS = 128;
+const MAX_STORED_BYTES = 64 * 1024 * 1024;
+const store = new Map();
+let storedBytes = 0;
+
+export function rememberArtifact(artifact) {
+  if (!artifact || typeof artifact.ref !== 'string' || typeof artifact.content !== 'string') throw new TypeError('artifact is invalid');
+  const bytes = Buffer.byteLength(artifact.content);
+  if (bytes > MAX_STORED_BYTES) throw new RangeError('artifact exceeds in-process recovery limit');
+  const previous = store.get(artifact.ref);
+  if (previous) storedBytes -= previous.bytes;
+  store.delete(artifact.ref);
+  while (store.size >= MAX_ARTIFACTS || storedBytes + bytes > MAX_STORED_BYTES) {
+    const oldest = store.keys().next().value;
+    if (oldest === undefined) break;
+    storedBytes -= store.get(oldest).bytes;
+    store.delete(oldest);
+  }
+  store.set(artifact.ref, {
+    content: artifact.content,
+    digest: artifact.sourceDigest,
+    sourceBytes: artifact.sourceBytes ?? artifact.bytes,
+    bytes,
+  });
+  storedBytes += bytes;
+}
+
+export function recoverStoredArtifact(options = {}) {
+  validateArtifactHandle(options.ref);
+  const entry = store.get(options.ref);
+  if (!entry) throw new Error('artifact handle is unavailable in this MCP session');
+  store.delete(options.ref);
+  store.set(options.ref, entry);
+  return recoverArtifactContent({ ...options, ...entry });
+}
+
+export function exposeMcpResult(result) {
+  if (!result?.artifact) return result;
+  rememberArtifact(result.artifact);
+  const { content: _content, ...artifact } = result.artifact;
+  return { ...result, artifact };
+}

package/src/cache-attribution.mjs

@@ -45,6 +45,10 @@ function counter(value) {
   return Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }
 
+function validCounter(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
 /** Stable digest of a JSON-serializable value. Order-sensitive by design: a reordered
  * tool array is a different byte prefix to the provider even if the set is equal. */
 export function shapeDigest(value) {
@@ -88,7 +92,9 @@ export function hasBreakpoint(body) {
  *
  * `current` / `previous` are `{ at, usage, tools, system, messages, body }`, where
  * `usage` is `{ cachedInputTokens, cacheWriteInputTokens, inputTokens }` as recorded
- * in the provider ledger. `previous` is null on the first turn of a session.
+ * in the provider ledger. `inputTokens` is the complete prompt, including cache
+ * reads and writes; `promptTokens` is accepted as its clearer alias. `previous` is
+ * null on the first turn of a session.
  */
 export function attributeTurn({
   current,
@@ -101,8 +107,10 @@ export function attributeTurn({
   const usage = object(current.usage) ? current.usage : {};
   const cacheReadTokens = counter(usage.cachedInputTokens);
   const cacheWriteTokens = counter(usage.cacheWriteInputTokens);
-  const freshInputTokens = counter(usage.inputTokens);
-  const totalPromptTokens = cacheReadTokens + cacheWriteTokens + freshInputTokens;
+  const promptTokens = validCounter(usage.promptTokens) ?? counter(usage.inputTokens);
+  const totalPromptTokens = promptTokens;
+  const effectiveInputTokens = Math.max(0, promptTokens - cacheReadTokens);
+  const freshInputTokens = Math.max(0, promptTokens - cacheReadTokens - cacheWriteTokens);
   const hit = cacheReadTokens > 0;
 
   const currentDigests = messageDigests(current.messages);
@@ -112,6 +120,8 @@ export function attributeTurn({
   const detail = {
     cacheReadTokens,
     cacheWriteTokens,
+    promptTokens,
+    effectiveInputTokens,
     freshInputTokens,
     totalPromptTokens,
     divergedAtMessage: divergedAt,

package/src/context-audit-cli.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  CONTEXT_CAPTURE_SCHEMA,
+  buildContextFootprintReport,
+} from './context-footprint.mjs';
+
+const MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+
+function usage() {
+  return 'Usage: sando context audit --host claude|codex [--input CAPTURE.json] [--json]\n';
+}
+
+function parseArgs(argv) {
+  let args = [...argv];
+  if (args[0] === 'context') args = args.slice(1);
+  if (args[0] === 'audit') args = args.slice(1);
+  const result = { host: undefined, input: undefined, json: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--help' || argument === '-h') result.help = true;
+    else if (argument === '--json') result.json = true;
+    else if (argument === '--host' || argument === '--input') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value`);
+      result[argument.slice(2)] = value;
+      index += 1;
+    } else throw new Error('unknown context audit option');
+  }
+  if (!result.help && !result.host) throw new Error('--host is required');
+  return result;
+}
+
+function readCapture(inputPath) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(inputPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_CAPTURE_BYTES) throw new Error('capture input is too large or not a file');
+    const source = fs.readFileSync(descriptor, 'utf8');
+    if (Buffer.byteLength(source, 'utf8') > MAX_CAPTURE_BYTES) throw new Error('capture input is too large');
+    try {
+      return JSON.parse(source);
+    } catch {
+      throw new Error('capture JSON is invalid');
+    }
+  } catch (error) {
+    if (error?.message === 'capture JSON is invalid' || error?.message === 'capture input is too large or not a file'
+      || error?.message === 'capture input is too large') throw error;
+    throw new Error('capture input cannot be read');
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+function unavailableCapture(host) {
+  return { schema: CONTEXT_CAPTURE_SCHEMA, host, body: { state: 'unavailable' } };
+}
+
+export function formatContextFootprintReport(report) {
+  const attribution = report.attribution.status === 'unavailable'
+    ? 'unavailable'
+    : `${report.attribution.status} (${report.attribution.bodyBytes}B, unknown ${report.attribution.unknownBytes}B)`;
+  const estimated = report.tokenAccounting.estimated.totalTokens === null
+    ? 'unavailable'
+    : String(report.tokenAccounting.estimated.totalTokens);
+  const provider = report.tokenAccounting.providerReported?.inputTokens === undefined
+    ? 'unavailable'
+    : String(report.tokenAccounting.providerReported.inputTokens);
+  return [
+    `Sando context audit: ${report.host}/${report.requestFormat ?? 'format unavailable'}`,
+    `body: ${report.observation.status}`,
+    `attribution: ${attribution}`,
+    `tool search: ${report.toolSearch.state}`,
+    `estimated input tokens: ${estimated}`,
+    `provider input tokens: ${provider}`,
+    `provenance: ${report.provenanceDigest}`,
+  ].join('\n') + '\n';
+}
+
+export function runContextAuditCli({ argv = process.argv.slice(2), stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    const options = parseArgs(argv);
+    if (options.help) {
+      stdout.write(usage());
+      return null;
+    }
+    const capture = options.input ? readCapture(options.input) : unavailableCapture(options.host);
+    if (capture?.host !== options.host) throw new Error('capture host does not match --host');
+    const report = buildContextFootprintReport(capture);
+    stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatContextFootprintReport(report));
+    return report;
+  } catch (error) {
+    stderr.write(`sando context audit: ${error instanceof Error ? error.message : String(error)}\n${usage()}`);
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) runContextAuditCli();