sandoichi 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandoichi",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cuts what Claude Code and Codex charge you to re-read their own output.",
   "license": "MIT",
   "author": "yuzushi",
@@ -22,6 +22,7 @@
     "src"
   ],
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --test tests/*.test.mjs",
+    "postinstall": "node src/postinstall.mjs"
   }
 }

package/src/hook-cli.mjs

@@ -4,6 +4,40 @@ import path from 'node:path';
 
 import { createReceipt, normalizeEvent, normalizePolicy, optimizeToolOutput } from './core.mjs';
 import { defaultMetricsPath, recordMetrics } from './metrics.mjs';
+import {
+  closeFinishedDays, defaultTelemetryConfigPath, defaultTelemetryStatePaths, incrementCounter, readTelemetryConfig,
+} from './telemetry.mjs';
+
+const PLUGIN_VERSION = '0.1';
+
+function todayUtc() { return new Date().toISOString().slice(0, 10); }
+
+/** Only counts (never content, paths, or IDs) — see docs/plans/2026-08-25-sando-telemetry-design.md.
+ *  `enforce` covers both `apply` and `dry-run`: both walk the real rewrite path, only
+ *  `observe` collects without deciding anything. */
+function recordHookTelemetry({ host, env, policy, optimization }) {
+  const configPath = defaultTelemetryConfigPath(env);
+  let config;
+  try { config = readTelemetryConfig(configPath); } catch { return; }
+  if (!config.enabled) return;
+  try {
+    const statePaths = defaultTelemetryStatePaths(env);
+    incrementCounter({
+      statePaths,
+      day: todayUtc(),
+      event: 'hook_summary',
+      host,
+      mode: policy.mode === 'observe' ? 'observe' : 'enforce',
+      deltas: {
+        toolCalls: 1,
+        redactions: optimization.stats.redactions,
+        cappedOutputs: optimization.artifact ? 1 : 0,
+        bytesSaved: Math.max(0, optimization.stats.inputBytes - optimization.stats.inlineBytes),
+      },
+    });
+    closeFinishedDays({ statePaths, configPath, day: todayUtc(), pluginVersion: PLUGIN_VERSION });
+  } catch { /* telemetry is best-effort and must never affect hook output */ }
+}
 
 function hookPolicy(env, host) {
   const policy = env.SANDO_POLICY
@@ -69,6 +103,7 @@ export function runHookCli({ host, env = process.env } = {}) {
       try {
         recordMetrics({ storagePath: defaultMetricsPath(env), host, event, optimization, receipt });
       } catch {}
+      recordHookTelemetry({ host, env, policy, optimization });
       if (host === 'codex' && policy.mode === 'apply' && env.SANDO_CODEX_FALLBACK === 'feedback') {
         process.stdout.write(`${JSON.stringify(buildCodexFallback({ optimization, cwd: event.cwd }))}\n`);
         return;

package/src/postinstall.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// npm postinstall: one-time, local-only consent prompt. No network calls here —
+// upload happens later, only if enabled, from the hook/proxy paths. Must never
+// fail or hang an `npm install`: every path resolves, every error is swallowed.
+
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+
+import { CONSENT_VERSION, defaultTelemetryConfigPath, enableTelemetry, readTelemetryConfig } from './telemetry.mjs';
+
+const CONSENT_PROMPT = 'Enable anonymous telemetry? Full details at: TELEMETRY.md [y/N] ';
+
+export async function runPostinstall({
+  env = process.env, stdin = process.stdin, stdout = process.stdout,
+  readlineFactory = () => readline.createInterface({ input: stdin, output: stdout }),
+} = {}) {
+  try {
+    if (env.SANDO_SKIP_TELEMETRY_PROMPT) return;
+    if (!stdin.isTTY || !stdout.isTTY) return; // CI, --ignore-scripts consumers, piped installs, etc.
+
+    const configPath = defaultTelemetryConfigPath(env);
+    const current = readTelemetryConfig(configPath);
+    if (current.prompted_consent_version >= CONSENT_VERSION) return; // never re-ask on reinstall/upgrade
+
+    const rl = readlineFactory();
+    let answer;
+    try {
+      answer = await rl.question(CONSENT_PROMPT);
+    } finally {
+      rl.close();
+    }
+    const result = enableTelemetry({ configPath, interactive: true, answer });
+    stdout.write(result.enabled ? 'telemetry enabled.\n' : 'telemetry not enabled.\n');
+  } catch {
+    // A postinstall script must never fail `npm install`.
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  runPostinstall().finally(() => process.exit(0));
+}

package/src/provider-usage.mjs

@@ -148,7 +148,7 @@ function validateState(value) {
   return value;
 }
 
-function ensureDirectory(directory) {
+export function ensureDirectory(directory) {
   fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
   const stat = fs.lstatSync(directory);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('provider usage directory is unsafe');
@@ -156,7 +156,7 @@ function ensureDirectory(directory) {
 }
 
 function waitForLock() { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_WAIT_MS); }
-function withLock(lockPath, operation) {
+export function withLock(lockPath, operation) {
   let handle;
   for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
     try { handle = fs.openSync(lockPath, 'wx', 0o600); break; }
@@ -171,7 +171,7 @@ function withLock(lockPath, operation) {
   try { return operation(); } finally { fs.closeSync(handle); fs.rmSync(lockPath, { force: true }); }
 }
 
-function atomicWrite(filePath, value) {
+export function atomicWrite(filePath, value) {
   const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.tmp`);
   fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
   try { fs.renameSync(temporary, filePath); } catch (error) { fs.rmSync(temporary, { force: true }); throw error; }

package/src/proxy.mjs

@@ -1,7 +1,45 @@
 import http from 'node:http';
 
+import { estimateTokens } from './core.mjs';
 import { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './context-transform.mjs';
 import { recordProxyRequest } from './proxy-metrics.mjs';
+import {
+  closeFinishedDays, defaultTelemetryConfigPath, defaultTelemetryStatePaths, incrementCounter, readTelemetryConfig,
+} from './telemetry.mjs';
+
+const PLUGIN_VERSION = '0.1';
+
+function todayUtc() { return new Date().toISOString().slice(0, 10); }
+
+/** Only counts (never request/response content) — see docs/plans/2026-08-25-sando-telemetry-design.md.
+ *  `host` here is the provider request shape (`anthropic`/`openai`), which does not map cleanly to
+ *  Sando's `claude`/`codex` telemetry host enum; the proxy fronts both hosts equally, so it reports
+ *  under a fixed `claude` label — this is the one place the design doc's host/provider split is
+ *  approximate, flagged for the design doc rather than silently assumed. */
+function recordProxyTelemetry({ env, transformed, beforeText, afterText }) {
+  const configPath = defaultTelemetryConfigPath(env);
+  let config;
+  try { config = readTelemetryConfig(configPath); } catch { return; }
+  if (!config.enabled) return;
+  const cacheWarm = transformed.stats.cacheRewriteRatio !== null;
+  try {
+    const statePaths = defaultTelemetryStatePaths(env);
+    incrementCounter({
+      statePaths,
+      day: todayUtc(),
+      event: 'proxy_summary',
+      host: 'claude',
+      deltas: {
+        rewritesApplied: transformed.changed ? 1 : 0,
+        rewritesSkippedCache: transformed.stats.cacheProtectedSkips > 0 ? 1 : 0,
+        inputTokensSaved: Math.max(0, estimateTokens(beforeText) - estimateTokens(afterText)),
+        cacheHitYes: cacheWarm ? 1 : 0,
+        cacheHitNo: cacheWarm ? 0 : 1,
+      },
+    });
+    closeFinishedDays({ statePaths, configPath, day: todayUtc(), pluginVersion: PLUGIN_VERSION });
+  } catch { /* telemetry is best-effort and must never affect the proxied response */ }
+}
 
 const DEFAULT_MAX_BODY_BYTES = 16 * 1024 * 1024;
 const HOP_BY_HOP_HEADERS = new Set([
@@ -130,7 +168,7 @@ async function observeSemanticCandidates({ provider, candidates, semanticCompact
   }
 }
 
-export async function createProviderProxy({ upstream, host = '127.0.0.1', port = 0, policy = {}, maxBodyBytes = DEFAULT_MAX_BODY_BYTES, semanticCompactor, metricsPath } = {}) {
+export async function createProviderProxy({ upstream, host = '127.0.0.1', port = 0, policy = {}, maxBodyBytes = DEFAULT_MAX_BODY_BYTES, semanticCompactor, metricsPath, env = process.env } = {}) {
   const upstreamUrl = assertUpstream(upstream);
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw new TypeError('port is invalid');
   if (!Number.isInteger(maxBodyBytes) || maxBodyBytes < 1024) throw new TypeError('maxBodyBytes is invalid');
@@ -158,6 +196,10 @@ 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));
+            recordProxyTelemetry({
+              env, transformed,
+              beforeText: rawBody.toString('utf8'), afterText: body.toString('utf8'),
+            });
             lastStats = { provider, ...transformed.stats, changed: transformed.changed, reasons: transformed.reasons };
             recordProvider = provider;
             recordModel = typeof parsed?.model === 'string' ? parsed.model : null;

package/src/telemetry-cli.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+
+import {
+  defaultTelemetryConfigPath, defaultTelemetryStatePaths,
+  disableTelemetry, enableTelemetry, flushQueue, previewNextUpload, statusTelemetry,
+} from './telemetry.mjs';
+
+const USAGE = 'Usage: sando telemetry <status|enable|disable [--purge]|preview|flush>\n';
+const CONSENT_PROMPT = 'Enable anonymous telemetry? Full details at: TELEMETRY.md [y/N] ';
+
+async function defaultPrompt(message) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return await rl.question(message); } finally { rl.close(); }
+}
+
+export async function runTelemetryCli({
+  argv = process.argv.slice(2), env = process.env, stdout = process.stdout, stderr = process.stderr,
+  configPath = defaultTelemetryConfigPath(env), statePaths = defaultTelemetryStatePaths(env),
+  interactive = Boolean(process.stdin.isTTY), prompt = defaultPrompt,
+} = {}) {
+  const [command, ...rest] = argv;
+  try {
+    if (command === 'status') {
+      const config = statusTelemetry(configPath);
+      stdout.write(`telemetry: ${config.enabled ? 'enabled' : 'disabled'}\n`);
+      return config;
+    }
+    if (command === 'enable') {
+      if (!interactive) {
+        stderr.write('sando telemetry: enable requires an interactive session\n');
+        return enableTelemetry({ configPath, interactive: false });
+      }
+      const answer = await prompt(CONSENT_PROMPT);
+      const result = enableTelemetry({
+        configPath, interactive: true,
+        answer: /^(y|yes)$/i.test((answer ?? '').trim()) ? 'yes' : answer,
+      });
+      stdout.write(result.enabled ? 'telemetry enabled.\n' : 'telemetry not enabled.\n');
+      return result;
+    }
+    if (command === 'disable') {
+      const result = disableTelemetry({ configPath, statePaths, purge: rest.includes('--purge') });
+      stdout.write('telemetry disabled.\n');
+      return result;
+    }
+    if (command === 'preview') {
+      const config = statusTelemetry(configPath);
+      const preview = previewNextUpload({ statePaths, endpoint: config.endpoint });
+      stdout.write(`${JSON.stringify(preview, null, 2)}\n`);
+      return preview;
+    }
+    if (command === 'flush') {
+      const config = statusTelemetry(configPath);
+      if (!config.enabled) {
+        stdout.write('telemetry is disabled; nothing to flush.\n');
+        return { sent: 0 };
+      }
+      const result = await flushQueue({ statePaths, endpoint: config.endpoint });
+      stdout.write(`flushed ${result.sent} row(s).\n`);
+      return result;
+    }
+    stdout.write(USAGE);
+    return null;
+  } catch (error) {
+    stderr.write(`sando telemetry: ${error instanceof Error ? error.message : String(error)}\n`);
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  await runTelemetryCli();
+}

package/src/telemetry-flush-entry.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Detached flush entrypoint: invoked with --queue and --config, nothing else.
+// Never inherits provider credential env vars or contacts anything but the configured endpoint.
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { flushQueue, readTelemetryConfig } from './telemetry.mjs';
+
+function option(argv, name) {
+  const index = argv.indexOf(`--${name}`);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+export async function runTelemetryFlushEntry({ argv = process.argv.slice(2) } = {}) {
+  const queuePath = option(argv, 'queue');
+  const configPath = option(argv, 'config');
+  if (!queuePath || !configPath) throw new Error('telemetry-flush-entry requires --queue and --config');
+  const config = readTelemetryConfig(configPath);
+  if (!config.enabled) return { sent: 0 };
+  return flushQueue({ statePaths: { queue: queuePath }, endpoint: config.endpoint });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  await runTelemetryFlushEntry();
+}

package/src/telemetry.mjs

@@ -0,0 +1,357 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { atomicWrite, ensureDirectory, withLock } from './provider-usage.mjs';
+
+const SCHEMA_VERSION = 1;
+const MAX_STRING_LENGTH = 32;
+const MAX_EVENT_BYTES = 2048;
+
+const COUNT_BUCKETS = ['zero', 'one', '2_to_5', '6_to_20', 'gt_20'];
+const BYTE_BUCKETS = ['lt_4k', '4_to_16k', '16_to_64k', 'gte_64k'];
+const HOSTS = ['claude', 'codex'];
+const MODES = ['enforce', 'observe'];
+const YES_NO_UNKNOWN = ['yes', 'no', 'unknown'];
+
+const SHARED_FIELDS = {
+  schema_version: (value) => value === SCHEMA_VERSION,
+  event: (value) => value === 'hook_summary' || value === 'proxy_summary',
+  day_utc: (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value),
+  plugin_version: (value) => typeof value === 'string' && /^\d+\.\d+$/.test(value) && value.length <= MAX_STRING_LENGTH,
+  host: (value) => HOSTS.includes(value),
+};
+
+const HOOK_FIELDS = {
+  mode: (value) => MODES.includes(value),
+  tool_calls_bucket: (value) => COUNT_BUCKETS.includes(value),
+  redactions_bucket: (value) => COUNT_BUCKETS.includes(value),
+  capped_outputs_bucket: (value) => COUNT_BUCKETS.includes(value),
+  bytes_saved_bucket: (value) => BYTE_BUCKETS.includes(value),
+};
+
+const PROXY_FIELDS = {
+  rewrites_applied_bucket: (value) => COUNT_BUCKETS.includes(value),
+  rewrites_skipped_cache_bucket: (value) => COUNT_BUCKETS.includes(value),
+  input_tokens_saved_bucket: (value) => BYTE_BUCKETS.includes(value),
+  prompt_cache_hit: (value) => YES_NO_UNKNOWN.includes(value),
+};
+
+function fieldsForEvent(eventType) {
+  return eventType === 'hook_summary' ? HOOK_FIELDS : PROXY_FIELDS;
+}
+
+export function countBucket(count) {
+  if (!Number.isInteger(count) || count < 0) throw new Error('countBucket: invalid count');
+  if (count === 0) return 'zero';
+  if (count === 1) return 'one';
+  if (count <= 5) return '2_to_5';
+  if (count <= 20) return '6_to_20';
+  return 'gt_20';
+}
+
+export function byteBucket(bytes) {
+  if (!Number.isInteger(bytes) || bytes < 0) throw new Error('byteBucket: invalid byte count');
+  if (bytes < 4096) return 'lt_4k';
+  if (bytes < 16384) return '4_to_16k';
+  if (bytes < 65536) return '16_to_64k';
+  return 'gte_64k';
+}
+
+export function validateEvent(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('event must be an object');
+  if (!SHARED_FIELDS.event(payload.event)) throw new Error('event: unknown event type');
+  const allowed = { ...SHARED_FIELDS, ...fieldsForEvent(payload.event) };
+  for (const key of Object.keys(payload)) {
+    if (!Object.hasOwn(allowed, key)) throw new Error(`unknown field: ${key}`);
+  }
+  for (const [key, check] of Object.entries(allowed)) {
+    if (!Object.hasOwn(payload, key)) throw new Error(`missing field: ${key}`);
+    if (typeof payload[key] === 'string' && payload[key].length > MAX_STRING_LENGTH) throw new Error(`${key}: string too long`);
+    if (!check(payload[key])) throw new Error(`${key}: invalid value`);
+  }
+  return payload;
+}
+
+export function serializeEvent(payload) {
+  validateEvent(payload);
+  const serialized = JSON.stringify(payload);
+  if (Buffer.byteLength(serialized) > MAX_EVENT_BYTES) throw new Error('event exceeds serialized size limit');
+  return serialized;
+}
+
+export const TELEMETRY_CONFIG_VERSION = 1;
+export const CONSENT_VERSION = 1;
+// Canary phase: shared backend, fronted by a Cloudflare Tunnel so it's
+// reachable from any of the owner's machines (see
+// session-handoff/deploy/telemetry/). Rate-limited at nginx (30 req/min/IP).
+// Release/broader publication is still gated on the open items in
+// session-handoff/docs/telemetry-canary-report.md.
+export const TELEMETRY_ENDPOINT = 'https://telemetry.yuzushi.party/v1/logs';
+
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+
+function emptyTelemetryConfig() {
+  return { schema_version: TELEMETRY_CONFIG_VERSION, enabled: false, prompted_consent_version: 0 };
+}
+
+function validateTelemetryConfig(value) {
+  if (!record(value) || value.schema_version !== TELEMETRY_CONFIG_VERSION || typeof value.enabled !== 'boolean'
+    || !Number.isInteger(value.prompted_consent_version) || value.prompted_consent_version < 0) {
+    throw new Error('telemetry config is invalid');
+  }
+  if (value.enabled) {
+    if (!Number.isInteger(value.consent_version) || value.consent_version < 1
+      || typeof value.consented_at !== 'string' || Number.isNaN(Date.parse(value.consented_at))
+      || typeof value.endpoint !== 'string' || !value.endpoint) throw new Error('telemetry config is invalid');
+  }
+  return value;
+}
+
+export function defaultTelemetryConfigPath(env = process.env) {
+  const configHome = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  if (!path.isAbsolute(configHome)) throw new Error('config directory must be absolute');
+  return path.join(configHome, 'sando', 'telemetry.json');
+}
+
+export function defaultTelemetryStatePaths(env = process.env) {
+  const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+  if (!path.isAbsolute(stateHome)) throw new Error('state directory must be absolute');
+  const directory = path.join(stateHome, 'sando');
+  return { counters: path.join(directory, 'telemetry-counters.json'), queue: path.join(directory, 'telemetry-queue.jsonl') };
+}
+
+export function readTelemetryConfig(configPath = defaultTelemetryConfigPath()) {
+  if (!fs.existsSync(configPath)) return emptyTelemetryConfig();
+  return validateTelemetryConfig(JSON.parse(fs.readFileSync(configPath, 'utf8')));
+}
+
+function writeTelemetryConfig(configPath, config) {
+  validateTelemetryConfig(config);
+  ensureDirectory(path.dirname(configPath));
+  withLock(`${configPath}.lock`, () => atomicWrite(configPath, config));
+  return config;
+}
+
+export function statusTelemetry(configPath = defaultTelemetryConfigPath()) {
+  return readTelemetryConfig(configPath);
+}
+
+/** Only an explicit `yes` in an interactive session enables collection; anything else
+ *  (blank, `no`, EOF, or a non-interactive caller) writes the disabled prompt marker so
+ *  upgrades and reinstalls never re-prompt or silently opt a user in. */
+export function enableTelemetry({ configPath = defaultTelemetryConfigPath(), answer, interactive = true, now = () => new Date() } = {}) {
+  if (!interactive || typeof answer !== 'string' || answer.trim().toLowerCase() !== 'yes') {
+    return writeTelemetryConfig(configPath, { schema_version: TELEMETRY_CONFIG_VERSION, enabled: false, prompted_consent_version: CONSENT_VERSION });
+  }
+  return writeTelemetryConfig(configPath, {
+    schema_version: TELEMETRY_CONFIG_VERSION,
+    enabled: true,
+    prompted_consent_version: CONSENT_VERSION,
+    consent_version: CONSENT_VERSION,
+    consented_at: now().toISOString(),
+    endpoint: TELEMETRY_ENDPOINT,
+  });
+}
+
+const QUEUE_MAX_ROWS = 256;
+const QUEUE_MAX_BYTES = 256 * 1024;
+const DEFAULT_BATCH_MAX = 32;
+
+function emptyCounters() { return { schema_version: TELEMETRY_CONFIG_VERSION, counters: {} }; }
+function readCounters(countersPath) {
+  if (!fs.existsSync(countersPath)) return emptyCounters();
+  return JSON.parse(fs.readFileSync(countersPath, 'utf8'));
+}
+
+function readQueueRows(queuePath) {
+  if (!fs.existsSync(queuePath)) return [];
+  return fs.readFileSync(queuePath, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+function writeQueueRows(queuePath, rows) {
+  ensureDirectory(path.dirname(queuePath));
+  const temporary = path.join(path.dirname(queuePath), `.${path.basename(queuePath)}.${process.pid}.tmp`);
+  const content = rows.length ? `${rows.map((row) => JSON.stringify(row)).join('\n')}\n` : '';
+  fs.writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+  try { fs.renameSync(temporary, queuePath); } catch (error) { fs.rmSync(temporary, { force: true }); throw error; }
+  fs.chmodSync(queuePath, 0o600);
+}
+
+/** Enforces the bounded queue (256 rows / 256 KiB), dropping the oldest rows first —
+ *  a telemetry backlog must never grow without bound or block product behavior. */
+function appendQueueRows(queuePath, newRows) {
+  withLock(`${queuePath}.lock`, () => {
+    let rows = [...readQueueRows(queuePath), ...newRows];
+    if (rows.length > QUEUE_MAX_ROWS) rows = rows.slice(rows.length - QUEUE_MAX_ROWS);
+    while (rows.length > 0 && Buffer.byteLength(rows.map((row) => JSON.stringify(row)).join('\n')) > QUEUE_MAX_BYTES) rows.shift();
+    writeQueueRows(queuePath, rows);
+  });
+}
+
+function majorityCacheHit(entry) {
+  const yes = entry.cacheHitYes ?? 0;
+  const no = entry.cacheHitNo ?? 0;
+  const unknown = entry.cacheHitUnknown ?? 0;
+  if (yes > no && yes >= unknown) return 'yes';
+  if (no > yes && no >= unknown) return 'no';
+  return 'unknown';
+}
+
+function bucketEntry(entry, pluginVersion) {
+  if (entry.event === 'hook_summary') {
+    return {
+      schema_version: TELEMETRY_CONFIG_VERSION, event: 'hook_summary', day_utc: entry.day, plugin_version: pluginVersion,
+      host: entry.host, mode: entry.mode,
+      tool_calls_bucket: countBucket(entry.toolCalls ?? 0),
+      redactions_bucket: countBucket(entry.redactions ?? 0),
+      capped_outputs_bucket: countBucket(entry.cappedOutputs ?? 0),
+      bytes_saved_bucket: byteBucket(entry.bytesSaved ?? 0),
+    };
+  }
+  return {
+    schema_version: TELEMETRY_CONFIG_VERSION, event: 'proxy_summary', day_utc: entry.day, plugin_version: pluginVersion,
+    host: entry.host,
+    rewrites_applied_bucket: countBucket(entry.rewritesApplied ?? 0),
+    rewrites_skipped_cache_bucket: countBucket(entry.rewritesSkippedCache ?? 0),
+    input_tokens_saved_bucket: byteBucket(entry.inputTokensSaved ?? 0),
+    prompt_cache_hit: majorityCacheHit(entry),
+  };
+}
+
+/** Accumulates raw per-day counts in memory/on disk; values are only bucketed (and thus
+ *  only ever leave the machine) once `closeDay` closes a finished UTC day. */
+export function incrementCounter({ statePaths, day, event, host, mode, deltas = {} }) {
+  if (!['hook_summary', 'proxy_summary'].includes(event)) throw new Error('incrementCounter: invalid event');
+  const key = `${day}|${event}|${host}|${mode ?? ''}`;
+  ensureDirectory(path.dirname(statePaths.counters));
+  withLock(`${statePaths.counters}.lock`, () => {
+    const state = readCounters(statePaths.counters);
+    const existing = state.counters[key] ?? { day, event, host, mode: mode ?? null };
+    for (const [field, value] of Object.entries(deltas)) {
+      if (!Number.isInteger(value) || value < 0) throw new Error(`incrementCounter: invalid delta ${field}`);
+      existing[field] = (existing[field] ?? 0) + value;
+    }
+    state.counters[key] = existing;
+    atomicWrite(statePaths.counters, state);
+  });
+}
+
+/** Closes a finished UTC day: buckets its raw counters into daily_aggregate rows,
+ *  appends them to the upload queue, and clears them from the raw counter file so a
+ *  day is never counted twice. */
+export function closeDay({ statePaths, day, pluginVersion }) {
+  const closedRows = [];
+  withLock(`${statePaths.counters}.lock`, () => {
+    const state = readCounters(statePaths.counters);
+    const remaining = {};
+    for (const [key, entry] of Object.entries(state.counters)) {
+      if (entry.day !== day) { remaining[key] = entry; continue; }
+      closedRows.push(validateEvent(bucketEntry(entry, pluginVersion)));
+    }
+    state.counters = remaining;
+    ensureDirectory(path.dirname(statePaths.counters));
+    atomicWrite(statePaths.counters, state);
+  });
+  if (closedRows.length) appendQueueRows(statePaths.queue, closedRows);
+  return closedRows;
+}
+
+function launchDetachedFlush({ statePaths, configPath, spawnImpl }) {
+  try {
+    const entryPath = fileURLToPath(new URL('./telemetry-flush-entry.mjs', import.meta.url));
+    const child = spawnImpl(process.execPath, [entryPath, '--queue', statePaths.queue, '--config', configPath], {
+      detached: true, env: {}, stdio: 'ignore', windowsHide: true,
+    });
+    child.unref();
+  } catch { /* telemetry must never affect the caller */ }
+}
+
+/** Closes every raw counter day before `day` and starts one detached uploader.
+ * The child receives only local state paths and an empty environment. */
+export function closeFinishedDays({
+  statePaths, configPath = defaultTelemetryConfigPath(), day, pluginVersion,
+  spawnImpl = spawn,
+} = {}) {
+  const days = new Set();
+  if (fs.existsSync(statePaths.counters)) {
+    const state = readCounters(statePaths.counters);
+    for (const entry of Object.values(state.counters)) {
+      if (typeof entry.day === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(entry.day) && entry.day < day) days.add(entry.day);
+    }
+  }
+  const closedRows = [];
+  for (const closedDay of [...days].sort()) {
+    closedRows.push(...closeDay({ statePaths, day: closedDay, pluginVersion }));
+  }
+  if (closedRows.length) launchDetachedFlush({ statePaths, configPath, spawnImpl });
+  return closedRows;
+}
+
+export function loadBatch({ statePaths, max = DEFAULT_BATCH_MAX } = {}) {
+  return readQueueRows(statePaths.queue).slice(0, max);
+}
+
+export function ackBatch({ statePaths, count }) {
+  withLock(`${statePaths.queue}.lock`, () => {
+    const rows = readQueueRows(statePaths.queue);
+    writeQueueRows(statePaths.queue, rows.slice(count));
+  });
+}
+
+export function toOtlpLogs(rows) {
+  return {
+    resourceLogs: [{
+      resource: { attributes: [{ key: 'service.name', value: { stringValue: 'sando' } }] },
+      scopeLogs: [{
+        logRecords: rows.map((row) => ({
+          body: { stringValue: 'sando.daily_aggregate' },
+          attributes: Object.entries(row).map(([key, value]) => ({ key, value: { stringValue: String(value) } })),
+        })),
+      }],
+    }],
+  };
+}
+
+export function previewNextUpload({ statePaths, endpoint = TELEMETRY_ENDPOINT, max = DEFAULT_BATCH_MAX } = {}) {
+  const rows = loadBatch({ statePaths, max });
+  return { url: endpoint, headers: { 'content-type': 'application/json' }, body: toOtlpLogs(rows) };
+}
+
+/** Uploads at most one batch. Every failure mode (timeout, network error, non-2xx) is
+ *  swallowed and reported as `sent: 0` — telemetry must never throw into, or change the
+ *  outcome of, the hook or proxy call that triggered a day close. */
+export async function flushQueue({ statePaths, endpoint = TELEMETRY_ENDPOINT, max = DEFAULT_BATCH_MAX, timeoutMs = 3000 } = {}) {
+  const rows = loadBatch({ statePaths, max });
+  if (rows.length === 0) return { sent: 0 };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(endpoint, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(toOtlpLogs(rows)), signal: controller.signal,
+    });
+    if (!response.ok) return { sent: 0 };
+    ackBatch({ statePaths, count: rows.length });
+    return { sent: rows.length };
+  } catch {
+    return { sent: 0 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function disableTelemetry({ configPath = defaultTelemetryConfigPath(), purge = false, statePaths = defaultTelemetryStatePaths() } = {}) {
+  const previous = readTelemetryConfig(configPath);
+  const result = writeTelemetryConfig(configPath, {
+    schema_version: TELEMETRY_CONFIG_VERSION,
+    enabled: false,
+    prompted_consent_version: previous.prompted_consent_version || CONSENT_VERSION,
+  });
+  if (purge) {
+    for (const target of [statePaths.counters, statePaths.queue]) fs.rmSync(target, { force: true });
+  }
+  return result;
+}