sandoichi 0.4.2 → 0.5.0

package/src/slice.mjs

@@ -0,0 +1,419 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadProjectRedactionProfile } from './redaction-config.mjs';
+import { PLUGIN_VERSION } from './version.mjs';
+
+const READ_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const WRITE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const REPLACE_ANNOTATIONS = { ...WRITE_ANNOTATIONS, destructiveHint: true };
+const INTEGER = { type: 'integer', minimum: 1 };
+const MAX_FETCH_LINES = 400;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 120_000;
+const HANDLE_PATTERN = '^sym#[a-f0-9]{16}@[a-f0-9]{16}$';
+const HANDLE_RE = new RegExp(HANDLE_PATTERN);
+
+const definitions = [
+  {
+    name: 'sando_slice_for', upstream: 'for', write: false,
+    description: 'Discover task-relevant symbols from the configured workspace. Returns native content and index freshness metadata unchanged.',
+    required: ['task'], properties: { task: { type: 'string', minLength: 1 }, budget_tokens: INTEGER }, annotations: READ_ANNOTATIONS,
+  },
+  {
+    name: 'sando_slice_find_symbol', upstream: 'find_symbol', write: false,
+    description: 'Find one symbol and its direct callers and callees. Preserves handles, ambiguity, floors, and index freshness metadata.',
+    required: ['symbol'], properties: { symbol: { type: 'string', minLength: 1 }, limit: INTEGER, offset: { type: 'integer', minimum: 0 } }, annotations: READ_ANNOTATIONS,
+  },
+  {
+    name: 'sando_slice_find_referencing_symbols', upstream: 'find_referencing_symbols', write: false,
+    description: 'Find direct referencing symbols. Preserves handles, ambiguity, floors, and index freshness metadata.',
+    required: ['symbol'], properties: { symbol: { type: 'string', minLength: 1 }, limit: INTEGER, offset: { type: 'integer', minimum: 0 } }, annotations: READ_ANNOTATIONS,
+  },
+  {
+    name: 'sando_slice_fetch_body', upstream: 'fetch_body', write: false,
+    description: `Fetch source for a symbol handle, bounded to at most ${MAX_FETCH_LINES} body-relative lines. Stale and ambiguous handles are refused.`,
+    required: ['handle'], properties: { handle: { type: 'string', pattern: HANDLE_PATTERN }, start_line: INTEGER, end_line: INTEGER }, annotations: READ_ANNOTATIONS,
+  },
+  {
+    name: 'sando_slice_replace_symbol_body', upstream: 'replace_symbol_body', write: true,
+    description: 'Replace exactly the definition span returned by sando_slice_fetch_body. Modifiers outside that span are preserved; do not repeat them in new_body. Requires a fresh handle and SANDO_SLICE_WRITE=1.',
+    required: ['handle', 'new_body'], properties: { handle: { type: 'string', pattern: HANDLE_PATTERN }, new_body: { type: 'string', minLength: 1 }, post_check: { type: 'boolean' } }, annotations: REPLACE_ANNOTATIONS,
+  },
+  {
+    name: 'sando_slice_insert_after_symbol', upstream: 'insert_after_symbol', write: true,
+    description: 'Insert text after the definition identified by a fresh handle. Requires SANDO_SLICE_WRITE=1; the native engine owns stale-handle refusal, newline handling, and atomic writes.',
+    required: ['handle', 'text'], properties: { handle: { type: 'string', pattern: HANDLE_PATTERN }, text: { type: 'string', minLength: 1 }, post_check: { type: 'boolean' } }, annotations: WRITE_ANNOTATIONS,
+  },
+];
+
+const byName = new Map(definitions.map((definition) => [definition.name, definition]));
+
+export class SliceRpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.name = 'SliceRpcError';
+    this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
+function configurationError(message) { return new SliceRpcError(-32603, message); }
+
+function configuration(env) {
+  const binarySetting = env?.SANDO_SLICE_BINARY;
+  if (typeof binarySetting !== 'string' || !path.isAbsolute(binarySetting) || binarySetting.includes('\0')) {
+    throw configurationError('SANDO_SLICE_BINARY must be an absolute executable file');
+  }
+  let executable;
+  try {
+    executable = fs.realpathSync(binarySetting);
+    const stat = fs.statSync(executable);
+    if (!stat.isFile()) throw new Error('not a file');
+    fs.accessSync(executable, fs.constants.X_OK);
+  } catch {
+    throw configurationError('SANDO_SLICE_BINARY must be an absolute executable file');
+  }
+
+  const rootSetting = env?.SANDO_SLICE_ROOT;
+  if (typeof rootSetting !== 'string' || !path.isAbsolute(rootSetting) || rootSetting.includes('\0')) {
+    throw configurationError('SANDO_SLICE_ROOT must be an absolute canonical directory');
+  }
+  let root;
+  try {
+    root = fs.realpathSync(rootSetting);
+    const stat = fs.lstatSync(rootSetting);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || root !== path.resolve(rootSetting)) throw new Error('not canonical');
+  } catch {
+    throw configurationError('SANDO_SLICE_ROOT must be an absolute canonical directory');
+  }
+  return { executable, root };
+}
+
+function publicTool({ name, description, required, properties, annotations }) {
+  return { name, description, inputSchema: { type: 'object', additionalProperties: false, required, properties }, annotations };
+}
+
+export function SLICE_TOOLS(env = process.env) {
+  try { configuration(env); } catch { return []; }
+  return definitions.filter((definition) => !definition.write || env?.SANDO_SLICE_WRITE === '1').map(publicTool);
+}
+
+export function spawnSliceProcess({ executable, root }) {
+  return spawn(executable, [root, '--mcp'], { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+}
+
+class SliceSession {
+  constructor(child) {
+    if (!child?.stdin || !child?.stdout || !child?.stderr) throw configurationError('Slice backend did not provide stdio pipes');
+    this.child = child;
+    this.pending = new Map();
+    this.nextId = 1;
+    this.closed = false;
+    this.stdout = Buffer.alloc(0);
+    child.stdout.on('data', (chunk) => this.consume(Buffer.from(chunk)));
+    child.stderr.resume();
+    child.stdin.on('error', (error) => this.close(configurationError(`Slice backend stdin failed: ${error.message}`)));
+    child.on('error', (error) => this.close(configurationError(`Slice backend unavailable: ${error.message}`)));
+    child.on('exit', (code, signal) => this.fail(configurationError(
+      `Slice backend exited before replying (code=${code ?? 'null'}, signal=${signal ?? 'none'})`,
+    )));
+  }
+
+  async initialize(context) {
+    const result = await this.request('initialize', {
+      protocolVersion: '2025-11-25',
+      capabilities: {},
+      clientInfo: { name: 'sando', version: PLUGIN_VERSION },
+    }, context);
+    if (!result || typeof result !== 'object' || typeof result.protocolVersion !== 'string'
+      || !result.capabilities || typeof result.capabilities !== 'object'
+      || !result.serverInfo || typeof result.serverInfo.name !== 'string') {
+      const error = configurationError('Slice backend returned an invalid initialize result');
+      this.close(error);
+      throw error;
+    }
+    this.notify('notifications/initialized', {});
+  }
+
+  request(method, params, { signal, deadline } = {}) {
+    if (this.closed) return Promise.reject(configurationError('Slice backend is closed'));
+    if (signal?.aborted) return Promise.reject(new SliceRpcError(-32800, 'Slice request cancelled'));
+    const remaining = (deadline ?? Date.now() + REQUEST_TIMEOUT_MS) - Date.now();
+    if (remaining <= 0) return Promise.reject(configurationError('Slice request timed out before execution'));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        const error = new SliceRpcError(-32800, 'Slice request cancelled');
+        this.close(error);
+      };
+      if (signal) signal.addEventListener('abort', abort, { once: true });
+      const timer = setTimeout(() => this.close(configurationError('Slice request timed out')), remaining);
+      this.pending.set(id, {
+        resolve,
+        reject,
+        cleanup: () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); },
+      });
+      this.write({ jsonrpc: '2.0', id, method, params }, id);
+    });
+  }
+
+  consume(chunk) {
+    this.stdout = Buffer.concat([this.stdout, chunk]);
+    while (true) {
+      const newline = this.stdout.indexOf(0x0a);
+      if (newline < 0) {
+        if (this.stdout.length > MAX_RESPONSE_BYTES) this.close(configurationError(`Slice response exceeded ${MAX_RESPONSE_BYTES} bytes`));
+        return;
+      }
+      if (newline > MAX_RESPONSE_BYTES) {
+        this.close(configurationError(`Slice response exceeded ${MAX_RESPONSE_BYTES} bytes`));
+        return;
+      }
+      const line = this.stdout.subarray(0, newline).toString('utf8');
+      this.stdout = this.stdout.subarray(newline + 1);
+      this.receive(line);
+      if (this.closed) return;
+    }
+  }
+
+  notify(method, params) { this.write({ jsonrpc: '2.0', method, params }); }
+
+  write(message, id) {
+    this.child.stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+      if (!error || id === undefined) return;
+      const pending = this.pending.get(id);
+      if (!pending) return;
+      this.close(configurationError(`Slice request write failed: ${error.message}`));
+    });
+  }
+
+  receive(line) {
+    let message;
+    try { message = JSON.parse(line); }
+    catch { this.close(configurationError('Slice backend returned invalid JSON')); return; }
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      this.close(configurationError('Slice backend returned an invalid JSON-RPC envelope'));
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+    this.pending.delete(message.id);
+    pending.cleanup();
+    if (message.error) pending.reject(new SliceRpcError(message.error.code, message.error.message, message.error.data));
+    else pending.resolve(message.result);
+  }
+
+  fail(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const pending of this.pending.values()) {
+      pending.cleanup();
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  close(error = configurationError('Slice backend closed')) {
+    if (this.closed) return;
+    this.fail(error);
+    this.child.kill();
+  }
+}
+
+function argumentsFor(definition, args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(args))) {
+    throw new SliceRpcError(-32602, 'Slice arguments must be an object');
+  }
+  const allowed = new Set(Object.keys(definition.properties));
+  for (const key of Reflect.ownKeys(args)) {
+    if (typeof key !== 'string') throw new SliceRpcError(-32602, 'unknown Slice argument');
+    if (!allowed.has(key)) throw new SliceRpcError(-32602, `unknown argument: ${key}`);
+  }
+  for (const key of definition.required) {
+    if (!Object.hasOwn(args, key)) throw new SliceRpcError(-32602, `missing required argument: ${key}`);
+  }
+  for (const [key, value] of Object.entries(args)) {
+    const schema = definition.properties[key];
+    const validType = schema.type === 'string' ? typeof value === 'string'
+      : schema.type === 'integer' ? Number.isSafeInteger(value)
+        : schema.type === 'boolean' ? typeof value === 'boolean'
+          : false;
+    if (!validType
+      || (schema.minLength !== undefined && value.length < schema.minLength)
+      || (schema.minimum !== undefined && value < schema.minimum)
+      || (schema.pattern !== undefined && !(new RegExp(schema.pattern)).test(value))) {
+      throw new SliceRpcError(-32602, `invalid argument: ${key}`);
+    }
+  }
+  const forwarded = { ...args };
+  if (definition.upstream === 'fetch_body') {
+    const start = forwarded.start_line ?? 1;
+    const end = forwarded.end_line ?? (start + MAX_FETCH_LINES - 1);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start || end - start + 1 > MAX_FETCH_LINES) {
+      throw new SliceRpcError(-32602, `fetch_body range must span 1..${MAX_FETCH_LINES} positive body-relative lines`);
+    }
+    forwarded.start_line = start;
+    forwarded.end_line = end;
+  }
+  if (definition.write) {
+    if (typeof forwarded.handle !== 'string' || !HANDLE_RE.test(forwarded.handle)) {
+      throw new SliceRpcError(-32602, 'Slice writes require a fresh handle from sando_slice_find_symbol');
+    }
+    forwarded.symbol = forwarded.handle;
+    delete forwarded.handle;
+  }
+  return forwarded;
+}
+
+export function isSliceTool(name) { return byName.has(name); }
+
+function resolveRedactionProfile(root) {
+  try {
+    return loadProjectRedactionProfile(root).profile;
+  } catch (error) {
+    throw configurationError(`Slice redaction config is invalid: ${error.message}`);
+  }
+}
+
+function redactError(error, profile) {
+  const message = profile.redact(error instanceof Error ? error.message : String(error)).text;
+  let data;
+  if (error?.data !== undefined) data = profile.redactStructured(error.data).value;
+  return new SliceRpcError(Number.isInteger(error?.code) ? error.code : -32603, message, data);
+}
+
+function redactContentText(text, profile) {
+  try {
+    const redacted = profile.redactStructured(JSON.parse(text));
+    return { value: JSON.stringify(redacted.value), count: redacted.count };
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const redacted = profile.redact(text);
+    return { value: redacted.text, count: redacted.count };
+  }
+}
+
+function redactResult(result, profile) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(result))) {
+    throw configurationError('Slice backend returned an invalid tool result');
+  }
+  const outer = profile.redactStructured(Object.fromEntries(
+    Object.entries(result).filter(([key]) => key !== 'content'),
+  ));
+  let count = outer.count;
+  let content;
+  if (Object.hasOwn(result, 'content')) {
+    if (!Array.isArray(result.content)) throw configurationError('Slice backend returned invalid tool content');
+    content = result.content.map((item) => {
+      if (!item || typeof item !== 'object' || Array.isArray(item)
+          || ![Object.prototype, null].includes(Object.getPrototypeOf(item))) {
+        throw configurationError('Slice backend returned invalid tool content');
+      }
+      const metadata = profile.redactStructured(Object.fromEntries(
+        Object.entries(item).filter(([key]) => key !== 'text'),
+      ));
+      count += metadata.count;
+      if (!Object.hasOwn(item, 'text')) return metadata.value;
+      if (typeof item.text !== 'string') throw configurationError('Slice backend returned invalid tool content');
+      const text = redactContentText(item.text, profile);
+      count += text.count;
+      return { ...metadata.value, text: text.value };
+    });
+  }
+  const value = { ...outer.value, ...(content === undefined ? {} : { content }) };
+  if (count === 0) return { value, count };
+  return {
+    count,
+    value: {
+      ...value,
+      _sando_redaction: {
+        count,
+        source_round_trip: false,
+        message: 'Redacted source is not round-trippable and cannot be used for symbol replacement.',
+      },
+    },
+  };
+}
+
+export function createSliceBridge({
+  env = process.env,
+  spawnBackend = spawnSliceProcess,
+  contextKey = () => '',
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+} = {}) {
+  if (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1) {
+    throw configurationError('Slice requestTimeoutMs must be a positive integer');
+  }
+  let session;
+  let sessionKey;
+  let queue = Promise.resolve();
+  let closed = false;
+  const redactedHandles = new Set();
+
+  async function invoke(name, args, context) {
+    if (closed) throw configurationError('Slice bridge is closed');
+    if (context.signal?.aborted) throw new SliceRpcError(-32800, 'Slice request cancelled');
+    if (Date.now() >= context.deadline) throw configurationError('Slice request timed out before execution');
+    const definition = byName.get(name);
+    if (!definition) throw new SliceRpcError(-32602, 'Unknown Slice tool');
+    const forwarded = argumentsFor(definition, args);
+    if (definition.write && env?.SANDO_SLICE_WRITE !== '1') {
+      throw new SliceRpcError(-32602, 'Slice writes are disabled; set SANDO_SLICE_WRITE=1 to enable them');
+    }
+    const config = configuration(env);
+    const profile = resolveRedactionProfile(config.root);
+    if (definition.upstream === 'replace_symbol_body' && redactedHandles.has(args.handle)) {
+      throw new SliceRpcError(-32602, 'Slice fetched redacted source is not round-trippable; fetch an unredacted handle before writing');
+    }
+    const key = `${config.executable}\0${config.root}\0${contextKey(context)}`;
+    try {
+      if (!session || session.closed || key !== sessionKey) {
+        session?.close();
+        session = new SliceSession(spawnBackend(config, context));
+        sessionKey = key;
+        await session.initialize(context);
+      }
+      const result = await session.request('tools/call', { name: definition.upstream, arguments: forwarded }, context);
+      const redacted = redactResult(result, profile);
+      if (definition.upstream === 'fetch_body' && redacted.count > 0) redactedHandles.add(args.handle);
+      return redacted.value;
+    } catch (error) {
+      throw redactError(error, profile);
+    }
+  }
+
+  return {
+    call(name, args = {}, context = {}) {
+      if (closed) return Promise.reject(configurationError('Slice bridge is closed'));
+      if (context.signal?.aborted) return Promise.reject(new SliceRpcError(-32800, 'Slice request cancelled'));
+      const deadline = Date.now() + requestTimeoutMs;
+      const admitted = { ...context, deadline };
+      let timer;
+      let abort;
+      const waiting = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(configurationError('Slice request timed out')), requestTimeoutMs);
+        if (context.signal) {
+          abort = () => reject(new SliceRpcError(-32800, 'Slice request cancelled'));
+          context.signal.addEventListener('abort', abort, { once: true });
+        }
+      });
+      const result = queue.then(() => invoke(name, args, admitted));
+      queue = result.catch(() => {});
+      return Promise.race([result, waiting]).finally(() => {
+        clearTimeout(timer);
+        context.signal?.removeEventListener('abort', abort);
+      });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      session?.close();
+      session = undefined;
+      sessionKey = undefined;
+    },
+  };
+}

package/src/statusline.mjs

@@ -33,19 +33,14 @@ function readMetricsSnapshot(metricsPath, { host, sessionId, model } = {}) {
     const records = scopedRecords(state.records, { host, sessionId });
     if (!records.length) return undefined;
     const report = buildMetricsReport({ ...state, records }, { sessionId });
-    const hasProvider = records.some((item) => item.providerReportedSavingsTokens !== null);
-    const hasEstimate = records.some((item) => item.providerReportedSavingsTokens === null);
-    const providerSavings = report.cumulative.providerReportedSavingsTokens;
-    const source = hasProvider && !hasEstimate && providerSavings !== null
-      ? 'provider-reported' : 'estimate';
+    const source = 'estimate';
     const estimatedInputTokens = records.reduce((total, item) => total + item.estimatedInputTokens, 0);
     const latest = [...records].sort((left, right) => left.at.localeCompare(right.at)).at(-1);
     return {
       updatedAt: latestAt(records), source,
       model: model ?? latest?.model,
       estimatedInputTokens,
-      savedTokens: source === 'provider-reported'
-        ? providerSavings : report.cumulative.estimatedTransformSavingsTokens,
+      savedTokens: report.cumulative.estimatedTransformSavingsTokens,
     };
   } catch {
     return undefined;
@@ -85,7 +80,8 @@ function compactTokens(value) {
 export function renderStatusLine({ metrics } = {}) {
   if (!Number.isSafeInteger(metrics?.savedTokens) || metrics.savedTokens < 0
     || !Number.isSafeInteger(metrics?.estimatedInputTokens) || metrics.estimatedInputTokens <= 0) return '🥪 —';
-  const percentage = Math.round(metrics.savedTokens / metrics.estimatedInputTokens * 100);
   const estimate = metrics.source === 'estimate' ? '~' : '';
-  return `🥪 saved ${estimate}${compactTokens(metrics.savedTokens)} ctx tok (${percentage}%)`;
+  const percentage = metrics.source === 'estimate'
+    ? ` (${Math.round(metrics.savedTokens / metrics.estimatedInputTokens * 100)}%)` : '';
+  return `🥪 saved ${estimate}${compactTokens(metrics.savedTokens)} ctx tok${percentage}`;
 }

package/src/telemetry.mjs

@@ -29,6 +29,20 @@ const F1_STATUSES = ['complete', 'partial', 'unavailable'];
 const F1_RATIO_BUCKETS = ['zero', 'lt_1pct', '1_to_10pct', 'gt_10pct', 'unavailable'];
 const F1_SIZE_BUCKETS = [...BYTE_BUCKETS, 'unavailable'];
 const F1_INPUT_BUCKETS = [...COUNT_BUCKETS, 'unavailable'];
+// Reduction without coverage reads as better than it is: a day that bounds heavily on the 3% of
+// commands it recognises looks identical to one that bounds everything. These are the reasons the
+// shell classifier already emits, so they are a closed set and carry nothing free-form.
+// Counts alone cannot answer "how much did it reach": 1,276 routed and 43,945 bypassed both land
+// in `gt_100`, and so would the reverse. The ratio is the field that carries the answer.
+export const COVERAGE_RATIO_BUCKETS = ['zero', 'lt_1pct', '1_to_10pct', '10_to_50pct', '50_to_90pct', 'gt_90pct'];
+
+export const COVERAGE_REASONS = [
+  'ambiguous-shell', 'compound-feeds-pipeline', 'compound-has-redirect', 'compound-segment-ambiguous',
+  'grep-shape', 'head-shape', 'invalid-input', 'read-shape', 'routing-disabled', 'sed-shape',
+  'tail-unbounded-from-end', 'unsafe-cwd', 'unsafe-grep-pattern', 'unsafe-grep-target',
+  'unsafe-read-target', 'unsupported-shell', 'unsupported-tool', 'other',
+];
+
 export const FAILURE_STAGES = [
   'policy', 'input', 'redaction', 'optimization', 'artifact', 'output', 'upstream', 'response',
 ];
@@ -37,7 +51,7 @@ const SHARED_FIELDS = {
   schema_version: (value) => value === SCHEMA_VERSION,
   event: (value) => [
     'hook_summary', 'proxy_summary', 'active_day', 'hook_failure_summary', 'proxy_failure_summary',
-    'f1_footprint', 'f4_gateway',
+    'f1_footprint', 'f4_gateway', 'coverage_summary',
   ].includes(value),
   day_utc: (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value),
   plugin_version: (value) => typeof value === 'string' && /^\d+\.\d+(?:\.\d+)?$/.test(value) && value.length <= MAX_STRING_LENGTH,
@@ -69,6 +83,14 @@ const PROXY_FAILURE_FIELDS = {
   provider: (value) => PROVIDERS.includes(value),
   failure_stage: (value) => FAILURE_STAGES.includes(value),
 };
+const COVERAGE_FIELDS = {
+  host: (value) => HOSTS.includes(value),
+  routed_bucket: (value) => COUNT_BUCKETS.includes(value),
+  bypassed_bucket: (value) => COUNT_BUCKETS.includes(value),
+  coverage_ratio_bucket: (value) => COVERAGE_RATIO_BUCKETS.includes(value),
+  top_bypass_reason: (value) => COVERAGE_REASONS.includes(value),
+};
+
 const F4_FIELDS = {
   f4_host: (value) => F4_HOSTS.includes(value),
   f4_operation: (value) => F4_OPERATIONS.includes(value),
@@ -91,6 +113,7 @@ function fieldsForEvent(eventType) {
   if (eventType === 'active_day') return ACTIVE_DAY_FIELDS;
   if (eventType === 'hook_failure_summary') return HOOK_FAILURE_FIELDS;
   if (eventType === 'f4_gateway') return F4_FIELDS;
+  if (eventType === 'coverage_summary') return COVERAGE_FIELDS;
   return PROXY_FAILURE_FIELDS;
 }
 
@@ -259,11 +282,11 @@ const LEASE_MS = 5 * 60 * 1000;
 const RETRY_DELAYS_MS = [60_000, 300_000, 1_800_000, 7_200_000, 21_600_000];
 const CHILD_ENV_KEYS = ['HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE'];
 
-function emptyCounters() { return { schema_version: TELEMETRY_CONFIG_VERSION, counters: {}, active_days: {} }; }
+function emptyCounters() { return { schema_version: TELEMETRY_CONFIG_VERSION, counters: {}, active_days: {}, coverage_days: {} }; }
 function readCounters(countersPath) {
   if (!fs.existsSync(countersPath)) return emptyCounters();
   const state = JSON.parse(fs.readFileSync(countersPath, 'utf8'));
-  return { ...state, counters: state.counters ?? {}, active_days: state.active_days ?? {} };
+  return { ...state, counters: state.counters ?? {}, active_days: state.active_days ?? {}, coverage_days: state.coverage_days ?? {} };
 }
 
 function readQueueRows(queuePath) {
@@ -320,9 +343,10 @@ function publicRow(row) {
 }
 
 function bucketEntry(entry, pluginVersion) {
+  const recordedVersion = entry.pluginVersion ?? pluginVersion;
   if (entry.event === 'hook_summary') {
     return {
-      schema_version: SCHEMA_VERSION, event: 'hook_summary', day_utc: entry.day, plugin_version: PLUGIN_VERSION,
+      schema_version: SCHEMA_VERSION, event: 'hook_summary', day_utc: entry.day, plugin_version: recordedVersion,
       host: entry.host, mode: entry.mode,
       tool_calls_bucket: countBucket(entry.toolCalls ?? 0),
       capped_outputs_bucket: countBucket(entry.cappedOutputs ?? 0),
@@ -331,41 +355,70 @@ function bucketEntry(entry, pluginVersion) {
     };
   }
   if (entry.event === 'proxy_summary') return {
-    schema_version: SCHEMA_VERSION, event: 'proxy_summary', day_utc: entry.day, plugin_version: PLUGIN_VERSION,
+    schema_version: SCHEMA_VERSION, event: 'proxy_summary', day_utc: entry.day, plugin_version: recordedVersion,
     provider: entry.provider ?? 'unknown', mode: entry.mode ?? 'enforce',
     rewrites_applied_bucket: countBucket(entry.rewritesApplied ?? 0),
     rewrites_skipped_cache_bucket: countBucket(entry.rewritesSkippedCache ?? 0),
     input_tokens_saved_bucket: byteBucket(entry.inputTokensSaved ?? 0),
   };
+  if (entry.event === 'coverage_summary') {
+    const reasons = Object.entries(entry)
+      .filter(([field, count]) => field.startsWith(REASON_PREFIX) && Number.isInteger(count) && count > 0)
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const leading = reasons[0]?.[0].slice(REASON_PREFIX.length);
+    const routed = entry.routed ?? 0;
+    const bypassed = entry.bypassed ?? 0;
+    return {
+      schema_version: SCHEMA_VERSION, event: 'coverage_summary', day_utc: entry.day, plugin_version: recordedVersion,
+      host: entry.host,
+      routed_bucket: countBucket(routed),
+      bypassed_bucket: countBucket(bypassed),
+      coverage_ratio_bucket: coverageRatioBucket(routed, routed + bypassed),
+      // A reason this build does not know travels as `other`, never as free text.
+      top_bypass_reason: COVERAGE_REASONS.includes(leading) ? leading : 'other',
+    };
+  }
   if (entry.event === 'hook_failure_summary') return {
-    schema_version: SCHEMA_VERSION, event: 'hook_failure_summary', day_utc: entry.day, plugin_version: PLUGIN_VERSION,
+    schema_version: SCHEMA_VERSION, event: 'hook_failure_summary', day_utc: entry.day, plugin_version: recordedVersion,
     host: entry.host, failure_stage: entry.failureStage,
   };
   return {
-    schema_version: SCHEMA_VERSION, event: 'proxy_failure_summary', day_utc: entry.day, plugin_version: PLUGIN_VERSION,
+    schema_version: SCHEMA_VERSION, event: 'proxy_failure_summary', day_utc: entry.day, plugin_version: recordedVersion,
     provider: entry.provider, failure_stage: entry.failureStage,
   };
 }
 
 /** 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, provider, mode, failureStage, deltas = {} }) {
-  if (!['hook_summary', 'proxy_summary', 'hook_failure_summary', 'proxy_failure_summary'].includes(event)) {
+export function incrementCounter({ statePaths, day, pluginVersion = PLUGIN_VERSION, event, host, provider, mode, failureStage, deltas = {} }) {
+  if (!['hook_summary', 'proxy_summary', 'hook_failure_summary', 'proxy_failure_summary', 'coverage_summary'].includes(event)) {
     throw new Error('incrementCounter: invalid event');
   }
   const isProxy = event.startsWith('proxy_');
   const dimension = isProxy ? provider : host;
-  const key = event.includes('failure')
-    ? [day, event, dimension, failureStage ?? ''].join('|')
-    : [day, event, dimension, mode ?? ''].join('|');
+  if (!SHARED_FIELDS.plugin_version(pluginVersion)) throw new Error('incrementCounter: invalid plugin version');
+  const suffix = event.includes('failure') ? failureStage ?? '' : mode ?? '';
+  const key = [day, pluginVersion, event, dimension, suffix].join('|');
+  const legacyKey = [day, event, dimension, suffix].join('|');
   ensureDirectory(path.dirname(statePaths.counters));
   withLock(`${statePaths.counters}.lock`, () => {
     const state = readCounters(statePaths.counters);
-    const existing = state.counters[key] ?? {
-      day, event, ...(isProxy ? { provider: dimension } : { host: dimension }),
+    const legacy = state.counters[legacyKey];
+    let existing = state.counters[key];
+    if (legacy && !legacy.pluginVersion) {
+      if (existing) {
+        for (const [field, value] of Object.entries(legacy)) {
+          if (Number.isInteger(value) && value >= 0) existing[field] = (existing[field] ?? 0) + value;
+        }
+      } else existing = legacy;
+      delete state.counters[legacyKey];
+    }
+    existing ??= {
+      day, pluginVersion, event, ...(isProxy ? { provider: dimension } : { host: dimension }),
       ...(event.endsWith('_summary') && !event.includes('failure') ? { mode: mode ?? null } : {}),
       ...(event.includes('failure') ? { failureStage } : {}),
     };
+    existing.pluginVersion = pluginVersion;
     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;
@@ -375,23 +428,52 @@ export function incrementCounter({ statePaths, day, event, host, provider, mode,
   });
 }
 
-export function recordFailure({ statePaths, day, event, host, provider, failureStage }) {
+export function recordFailure({ statePaths, day, pluginVersion = PLUGIN_VERSION, event, host, provider, failureStage }) {
   incrementCounter({
-    statePaths, day, event, host, provider, failureStage, deltas: { count: 1 },
+    statePaths, day, pluginVersion, event, host, provider, failureStage, deltas: { count: 1 },
   });
 }
 
 /** Queues a single non-aggregate activity marker for this UTC day and host. */
-export function recordActiveDay({ statePaths, day, pluginVersion, host }) {
+export const REASON_PREFIX = 'reason:';
+
+export function coverageRatioBucket(routed, total) {
+  if (!Number.isInteger(routed) || !Number.isInteger(total) || routed < 0 || total < routed) {
+    throw new Error('coverageRatioBucket: invalid counts');
+  }
+  if (total === 0 || routed === 0) return 'zero';
+  const ratio = routed / total;
+  if (ratio < 0.01) return 'lt_1pct';
+  if (ratio < 0.1) return '1_to_10pct';
+  if (ratio < 0.5) return '10_to_50pct';
+  if (ratio < 0.9) return '50_to_90pct';
+  return 'gt_90pct';
+}
+
+/** One call per classified shell command. Counters close into a single row per day, next to the
+ * reduction they qualify: a large saving on a small share of commands should not read the same as
+ * a large saving on all of them. */
+export function recordCoverage({ statePaths, day, pluginVersion = PLUGIN_VERSION, host, routed, reason }) {
+  const deltas = routed ? { routed: 1 } : { bypassed: 1 };
+  if (!routed) {
+    const label = COVERAGE_REASONS.includes(reason) ? reason : 'other';
+    deltas[`${REASON_PREFIX}${label}`] = 1;
+  }
+  incrementCounter({ statePaths, day, pluginVersion, event: 'coverage_summary', host, deltas });
+}
+
+export function recordActiveDay({ statePaths, day, pluginVersion = PLUGIN_VERSION, host }) {
   const marker = {
-    schema_version: SCHEMA_VERSION, event: 'active_day', day_utc: day, plugin_version: PLUGIN_VERSION, host,
+    schema_version: SCHEMA_VERSION, event: 'active_day', day_utc: day, plugin_version: pluginVersion, host,
   };
   const validatedMarker = validateEvent(marker);
-  const activeDayKey = `${day}|${host}`;
+  const activeDayKey = `${day}|${pluginVersion}|${host}`;
+  const legacyActiveDayKey = `${day}|${host}`;
   ensureDirectory(path.dirname(statePaths.counters));
   withLock(`${statePaths.counters}.lock`, () => {
     const state = readCounters(statePaths.counters);
     const activeDays = state.active_days;
+    if (Object.hasOwn(activeDays, legacyActiveDayKey)) delete activeDays[legacyActiveDayKey];
     const cutoff = Date.parse(`${day}T00:00:00Z`) - (ACTIVE_DAY_RETENTION_DAYS - 1) * 86_400_000;
     for (const [key, recordedDay] of Object.entries(activeDays)) {
       if (Date.parse(`${recordedDay}T00:00:00Z`) < cutoff) delete activeDays[key];