ai-lens 0.8.85 → 0.8.87

package/.commithash

@@ -1 +1 @@
-5905663
+ecde7fc

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.87 — 2026-06-11
+- fix: the client version reported to the server (`X-Client-Version`) now describes the code that actually ran. Previously a repo-path install (`init --use-repo-path`) reported the version of the old copied client in `~/.ai-lens/client/` forever, making up-to-date setups look ancient in server logs and diagnostics.
+
+## 0.8.86 — 2026-06-11
+- fix: `ai-lens import claude-code` now respects your configured projects filter (`AI_LENS_PROJECTS` / the `projects` setting) by default, the same way live capture does — previously, without an explicit `--projects` flag it imported your entire local history. Pass `--projects all` to deliberately import everything, or `--projects A,B` to use a different list. The import offer inside `ai-lens init` follows the same rule.
+
 ## 0.8.85 — 2026-06-09
 - feat: manage your own data from the CLI. `ai-lens list-sessions` lists your sessions, `ai-lens find-session <query>` finds one by id / project / source, and `ai-lens delete-sessions` removes your own sessions — by id (the short id shown by `list-sessions` works) or by `--from`/`--to` date range. Delete is a dry-run by default and only acts with `--yes`; it can only ever touch your own data, and a mistyped or ambiguous id is reported rather than silently ignored.
 - feat: `ai-lens import claude-code --from <date> --to <date>` imports a precise date window (events outside it are left out). Re-running an import over a window you've already imported is safe — it adds zero duplicates (every event has a stable id the server de-duplicates on), so you can re-seed a lost day without fear of doubling your history.

package/cli/import/claude-code.js

@@ -28,7 +28,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { writeToSpool, canonicalizeProjectPath, deterministicEventId } from '../../client/capture.js';
-import { PENDING_DIR, SENDING_DIR, DATA_DIR, ensureDataDir, getGitIdentity, getGitMetadata, getServerUrl, getAuthToken } from '../../client/config.js';
+import { PENDING_DIR, SENDING_DIR, DATA_DIR, ensureDataDir, getGitIdentity, getGitMetadata, getServerUrl, getAuthToken, getMonitoredProjects } from '../../client/config.js';
 import { mapTranscript } from './transcript-map.js';
 import { info, success, warn, error, heading, detail, blank } from '../logger.js';
 
@@ -125,6 +125,27 @@ function normalizeProjectArg(p) {
   return canonicalizeProjectPath(real) || real;
 }
 
+/**
+ * Resolve the effective project filter, mirroring live capture by default:
+ *   --projects A,B → explicit list (each entry ~-expanded + git-root canonicalized)
+ *   --projects all → no filter, even when one is configured (explicit override)
+ *   (no flag)      → the live-capture filter (AI_LENS_PROJECTS / config
+ *                    `projects`), so import never ships history that live
+ *                    capture would have dropped via project_filter.
+ * `monitored` is getMonitoredProjects() output: normalized absolute paths or
+ * null. Matching semantics are identical to live capture's pathContains
+ * (entry === path || path inside entry), so no extra canonicalization needed.
+ * Returns { filter: string[]|null, source: 'flag'|'config'|null }.
+ */
+export function resolveProjectFilter(projectsFlag, monitored) {
+  if (typeof projectsFlag === 'string' && projectsFlag.trim()) {
+    if (projectsFlag.trim().toLowerCase() === 'all') return { filter: null, source: null };
+    return { filter: projectsFlag.split(',').map(normalizeProjectArg).filter(Boolean), source: 'flag' };
+  }
+  if (Array.isArray(monitored) && monitored.length > 0) return { filter: monitored, source: 'config' };
+  return { filter: null, source: null };
+}
+
 /** Path-boundary match (so /repo does NOT match /repo2). */
 export function projectMatches(projectPath, filters) {
   if (!filters) return true;
@@ -299,9 +320,11 @@ export default async function importClaudeCode(flags) {
   const cutoff = (rangeMode && lower == null)
     ? new Date(0).toISOString()
     : resolveCutoff({ days, since, from });
-  const projectFilter = projects
-    ? projects.split(',').map(normalizeProjectArg).filter(Boolean)
-    : null;
+  const { filter: projectFilter, source: filterSource } = resolveProjectFilter(projects, getMonitoredProjects());
+  if (filterSource === 'config') {
+    info(`Project filter from config (AI_LENS_PROJECTS / ~/.ai-lens/config): ${projectFilter.join(', ')}`);
+    detail('Pass --projects all to import everything, or --projects A,B to override.');
+  }
   ensureDataDir();
   const ledger = loadLedger();
   // Human-readable window label for the progress lines.

package/cli/import.js

@@ -44,7 +44,7 @@ export default async function importCmd() {
 
   if (errors.length) {
     errors.forEach((e) => error(e));
-    info('Usage: ai-lens import claude-code [--days N | --since YYYY-MM-DD | --from YYYY-MM-DD --to YYYY-MM-DD] [--projects A,B] [--dry-run] [--no-redact]');
+    info('Usage: ai-lens import claude-code [--days N | --since YYYY-MM-DD | --from YYYY-MM-DD --to YYYY-MM-DD] [--projects A,B | --projects all] [--dry-run] [--no-redact]');
     process.exitCode = 1;
     return;
   }

package/cli/status.js

@@ -3,6 +3,9 @@ import { execSync, spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir, release as osRelease, arch as osArch } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import tls from 'node:tls';
+
+import { TLS_TRUST_CODES, tlsCodeOf, tlsVerdictSummary, issuerName } from '../client/tls-trust.js';
 
 import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, getCodexToolConfig, analyzeToolHooks, checkHooksDisabled, verifyCodexHookTrust, CAPTURE_PATH, TOOL_CONFIGS } from './hooks.js';
 import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, LAST_STATUS_REPORT_PATH, getGitIdentity, getMonitoredProjects } from '../client/config.js';
@@ -651,7 +654,13 @@ function checkSenderLog() {
           if (tsMs > lastErrorMs) {
             lastErrorMs = tsMs;
             lastError = entry.ts;
-            lastErrorCode = entry.cause?.code || entry.code || entry.error || null;
+            // Prefer a TLS-trust code wherever it hides in the (possibly nested) log shape —
+            // cause.innerCode / fallbackCode are populated by the sender's TLS path. Otherwise
+            // fall back to the first non-null code, as before.
+            const codeCandidates = [entry.cause?.code, entry.cause?.innerCode, entry.fallbackCode, entry.code, entry.error];
+            lastErrorCode = codeCandidates.find((c) => c && TLS_TRUST_CODES.has(c))
+              || codeCandidates.find((c) => c != null)
+              || null;
           }
           if (entry.msg === 'failed' && now - tsMs <= DAY_MS) recentFailed++;
         }
@@ -693,6 +702,7 @@ function checkSenderLog() {
   return {
     ok: !activeErrors,
     summary,
+    lastErrorCode,
     detail: `Log: ${LOG_PATH}\nTotal entries: ${lines.length}\nCounters: sent_ok=${sentOk}, failed=${failedCount} (${recentFailed} in 24h), rollbacks=${rollbackCount}\nLast send: ${lastSend || '(never)'}\nLast error: ${lastError || '(none)'}${lastErrorCode ? ` (${lastErrorCode})` : ''}\nState: ${state}\nLast 20 entries:\n${last20.join('\n')}`,
   };
 }
@@ -854,6 +864,7 @@ async function checkServer(serverUrl) {
   const PER_ATTEMPT_TIMEOUT = 5000;
   const codes = [];
   const attemptLog = [];
+  let lastErr;
   for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
     const start = Date.now();
     try {
@@ -874,8 +885,11 @@ async function checkServer(serverUrl) {
         detail: `URL: ${url}\nStatus: ${res.status}\nLatency: ${latency}ms\nResponse: ${body}`,
       };
     } catch (err) {
+      lastErr = err;
       const latency = Date.now() - start;
-      const code = err.code || err.cause?.code || err.message;
+      // Same cause-chain walker as errorCode below, so the printed code never disagrees
+      // with the code that triggers the TLS diagnostic.
+      const code = tlsCodeOf(err) || err.message;
       codes.push(code);
       attemptLog.push(`#${attempt}: ${code} (${latency}ms)`);
       if (attempt < ATTEMPTS) await new Promise(r => setTimeout(r, 1000));
@@ -883,11 +897,80 @@ async function checkServer(serverUrl) {
   }
   return {
     ok: false,
+    // errorCode uses the shared cause-chain walker so a TLS-trust code nested under
+    // err.cause.cause is still surfaced for the TLS diagnostic trigger.
+    errorCode: tlsCodeOf(lastErr),
     summary: `unreachable (${codes[codes.length - 1]}, ${ATTEMPTS} attempts)`,
     detail: `URL: ${url}\nUnreachable after ${ATTEMPTS} attempts:\n${attemptLog.join('\n')}`,
   };
 }
 
+// --- TLS diagnostic (Layer 2) -------------------------------------------------
+// Pure helpers are named-exported so test/cli/status.test.js can exercise them without
+// running the full status() flow or a live TLS endpoint.
+
+/** Parse serverUrl into a handshake target, or a skip reason for non-https / bad config. */
+export function tlsDiagTargetFromUrl(serverUrl) {
+  let u;
+  try { u = new URL(serverUrl); }
+  catch { return { skip: 'unparseable serverUrl' }; }
+  if (u.protocol !== 'https:') return { skip: `non-https (${u.protocol})` };
+  return { host: u.hostname, port: Number(u.port) || 443 };
+}
+
+/** Run the diagnostic only when a TLS chain-trust code surfaced (server probe or sender log). */
+export function shouldRunTlsDiag({ errorCode, lastErrorCode } = {}) {
+  return TLS_TRUST_CODES.has(errorCode) || TLS_TRUST_CODES.has(lastErrorCode);
+}
+
+/**
+ * Unauthenticated TLS handshake to read the cert actually served to this machine and name the
+ * interceptor. Never throws or hangs — every path resolves a graceful informational result.
+ */
+async function checkServerTls(serverUrl) {
+  const target = tlsDiagTargetFromUrl(serverUrl);
+  if (target.skip) {
+    return { ok: null, summary: `skipped — ${target.skip}`, detail: `TLS diagnostic skipped: ${target.skip}` };
+  }
+  const TIMEOUT = 5000;
+  const where = `${target.host}:${target.port}`;
+  return await new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => { if (!settled) { settled = true; resolve(result); } };
+    let socket;
+    try {
+      socket = tls.connect({ host: target.host, port: target.port, servername: target.host, rejectUnauthorized: false }, () => {
+        const cert = socket.getPeerCertificate();
+        try { socket.destroy(); } catch {}
+        if (!cert || Object.keys(cert).length === 0) {
+          done({ ok: null, summary: 'no peer certificate', detail: `Host: ${where}\nNo peer certificate returned` });
+          return;
+        }
+        const subject = cert.subject || {};
+        const verdict = tlsVerdictSummary(cert);
+        const detail = [
+          `Host: ${where}`,
+          `Subject CN: ${subject.CN || '(none)'}`,
+          `Issuer: ${issuerName(cert)}`,
+          `Valid: ${cert.valid_from || '?'} → ${cert.valid_to || '?'}`,
+          `Verdict: ${verdict}`,
+        ].join('\n');
+        done({ ok: null, summary: verdict, detail });
+      });
+      socket.setTimeout(TIMEOUT, () => {
+        try { socket.destroy(); } catch {}
+        done({ ok: null, summary: 'handshake timed out', detail: `Host: ${where}\nTLS handshake timed out after ${TIMEOUT}ms` });
+      });
+      socket.on('error', (err) => {
+        try { socket.destroy(); } catch {}
+        done({ ok: null, summary: `handshake error: ${err.code || err.message}`, detail: `Host: ${where}\nError: ${err.message}` });
+      });
+    } catch (err) {
+      done({ ok: null, summary: `handshake error: ${err.message}`, detail: `Host: ${where}\nError: ${err.message}` });
+    }
+  });
+}
+
 async function checkToken(serverUrl, authToken) {
   if (!serverUrl || !authToken) {
     const missing = !serverUrl ? 'server URL' : 'auth token';
@@ -1378,7 +1461,8 @@ export default async function status({ report = false } = {}) {
   printLine('Capture test', checkCaptureRun(toolsWithProject));
 
   // 9. Sender log
-  printLine('Sender log', checkSenderLog());
+  const senderLogResult = checkSenderLog();
+  printLine('Sender log', senderLogResult);
 
   // 10. Capture drops
   printLine('Capture drops', checkCaptureLog());
@@ -1392,6 +1476,13 @@ export default async function status({ report = false } = {}) {
   const serverResult = await checkServer(serverUrl);
   printLine('Server', serverResult);
 
+  // 12b. TLS diagnostic — only when a TLS chain-trust code surfaced (server probe or sender log).
+  // Interception is often intermittent, so the live handshake may currently pass — we still
+  // report the served issuer so the verdict is on record.
+  if (shouldRunTlsDiag({ errorCode: serverResult.errorCode, lastErrorCode: senderLogResult.lastErrorCode })) {
+    printLine('TLS diagnostic', await checkServerTls(serverUrl));
+  }
+
   // 13. Token validity
   const authToken = configResult.authToken || readLensConfig().authToken;
   const tokenResult = await checkToken(serverUrl, authToken);

package/client/config.js

@@ -1,5 +1,6 @@
 import { mkdirSync, appendFileSync, readFileSync, writeFileSync, renameSync, realpathSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import * as childProcess from 'node:child_process';
 
@@ -116,12 +117,41 @@ export function getAuthToken() {
   return process.env.AI_LENS_AUTH_TOKEN || loadConfig().authToken || null;
 }
 
+let _clientVersionCache = null;
+/** Test hook: reset the per-process getClientVersion cache. */
+export function _clearClientVersionCache() { _clientVersionCache = null; }
+
+/**
+ * Identify the RUNNING client code — not the installed copy. Resolution order:
+ *   1. version.json next to THIS module ({version, commit, packageRoot} written
+ *      by init at copy time, so it describes exactly these files) — the copy
+ *      install case (~/.ai-lens/client/);
+ *   2. the surrounding ai-lens package (repo checkout or npx cache): version
+ *      from ../package.json, commit from `git rev-parse` (live checkout) with
+ *      the published .commithash file as fallback (npx cache has no .git).
+ * It used to always read ~/.ai-lens/client/version.json, so a --use-repo-path
+ * install reported the stale copied version forever and X-Client-Version lied
+ * about what code actually ran (a 0.8.44 header over current-code events).
+ */
 export function getClientVersion() {
+  if (_clientVersionCache) return _clientVersionCache;
+  const here = dirname(fileURLToPath(import.meta.url));
   try {
-    return JSON.parse(readFileSync(join(CLIENT_INSTALL_DIR, 'version.json'), 'utf-8'));
-  } catch {
-    return { version: 'unknown', commit: 'unknown' };
-  }
+    _clientVersionCache = JSON.parse(readFileSync(join(here, 'version.json'), 'utf-8'));
+    return _clientVersionCache;
+  } catch { /* no sibling version.json — running from the package, not a copy */ }
+  try {
+    const packageRoot = resolve(here, '..');
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
+    if (pkg?.name === 'ai-lens' && pkg.version) {
+      let commit = null;
+      try { commit = _gitRunner(['-C', packageRoot, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8', timeout: 3000 }).trim() || null; } catch { /* not a checkout */ }
+      if (!commit) { try { commit = readFileSync(join(packageRoot, '.commithash'), 'utf-8').trim() || null; } catch { /* no .commithash */ } }
+      _clientVersionCache = { version: pkg.version, commit: commit || 'unknown', packageRoot };
+      return _clientVersionCache;
+    }
+  } catch { /* unreadable package.json */ }
+  return { version: 'unknown', commit: 'unknown' };
 }
 
 export function getGitIdentity(cwd) {

package/client/sender.js

@@ -18,6 +18,14 @@ import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import https from 'node:https';
+import {
+  isTlsTrustError,
+  tlsCodeOf,
+  tlsSelfHealEnabled,
+  systemCaAvailable,
+  loadTrustBundle,
+} from './tls-trust.js';
 import {
   ensureDataDir,
   PENDING_DIR,
@@ -619,10 +627,7 @@ export function isTransientFetchError(err) {
   return false;
 }
 
-async function postEventsOnce(serverUrl, events, identity, authToken) {
-  const body = JSON.stringify(events);
-  const url  = `${serverUrl}/api/events`;
-
+function buildHeaders(identity, authToken) {
   const { version: clientVersion, commit: clientCommit } = getClientVersion();
   const headers = {
     'Content-Type':     'application/json',
@@ -632,6 +637,13 @@ async function postEventsOnce(serverUrl, events, identity, authToken) {
   if (identity.email) headers['X-Developer-Git-Email'] = identity.email;
   if (identity.name)  headers['X-Developer-Name'] = encodeURIComponent(identity.name);
   if (authToken)      headers['X-Auth-Token'] = authToken;
+  return headers;
+}
+
+async function postEventsOnce(serverUrl, events, identity, authToken) {
+  const body = JSON.stringify(events);
+  const url  = `${serverUrl}/api/events`;
+  const headers = buildHeaders(identity, authToken);
 
   const res = await fetch(url, {
     method: 'POST',
@@ -648,6 +660,49 @@ async function postEventsOnce(serverUrl, events, identity, authToken) {
   throw new Error(`Server responded ${res.status}: ${data}`);
 }
 
+/**
+ * Fallback POST that trusts the OS certificate store (Node's bundled roots + system store +
+ * NODE_EXTRA_CA_CERTS). Used ONCE when the primary fetch() fails with a TLS chain-trust error
+ * (corporate proxy / antivirus interception). Built on node:https so we can pass a custom CA
+ * without adding undici as a dependency. A raw https.request has no AbortSignal equivalent, so
+ * the 30s budget is enforced explicitly via req.setTimeout.
+ */
+function postEventsOnceSystemCA(serverUrl, events, identity, authToken) {
+  const body = JSON.stringify(events);
+  const url  = new URL(`${serverUrl}/api/events`);
+  const headers = { ...buildHeaders(identity, authToken), 'Content-Length': Buffer.byteLength(body) };
+  const agent = new https.Agent({ ca: loadTrustBundle(), keepAlive: false });
+
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers,
+        agent,
+      },
+      (res) => {
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try { resolve(JSON.parse(data)); }
+            catch (e) { reject(new Error(`Invalid JSON response: ${e.message}`)); }
+          } else {
+            reject(new Error(`Server responded ${res.statusCode}: ${data}`));
+          }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.setTimeout(30_000, () => req.destroy(new Error('aborted due to timeout')));
+    req.end(body);
+  });
+}
+
 /**
  * POST events to the server with retries on transient transport errors.
  * Retries up to POST_MAX_ATTEMPTS - 1 times with POST_RETRY_BACKOFF_MS delays.
@@ -660,6 +715,7 @@ async function postEventsOnce(serverUrl, events, identity, authToken) {
 export async function postEvents(serverUrl, events, identity, authToken, opts = {}) {
   const { lockPath } = opts;
   let lastErr;
+  let triedSystemCa = false;
   for (let attempt = 0; attempt < POST_MAX_ATTEMPTS; attempt++) {
     if (attempt > 0) {
       await new Promise(r => setTimeout(r, POST_RETRY_BACKOFF_MS[attempt - 1]));
@@ -669,6 +725,29 @@ export async function postEvents(serverUrl, events, identity, authToken, opts =
       return await postEventsOnce(serverUrl, events, identity, authToken);
     } catch (err) {
       lastErr = err;
+      // TLS chain-trust failure (corporate proxy / antivirus interception): retry ONCE
+      // trusting the OS cert store. Only as a fallback after the strict fetch() failed, only
+      // for our fixed serverUrl, at most once per call.
+      if (!triedSystemCa && tlsSelfHealEnabled() && isTlsTrustError(err) && systemCaAvailable()) {
+        triedSystemCa = true;
+        const code = tlsCodeOf(err);
+        log({ msg: 'tls-self-heal-attempt', code });
+        try {
+          const result = await postEventsOnceSystemCA(serverUrl, events, identity, authToken);
+          log({ msg: 'recovered-via-system-ca', code, events: events.length });
+          return result;
+        } catch (e2) {
+          // The fallback handshake SUCCEEDED but the request itself failed (401, 5xx,
+          // timeout): e2 is the real story — surface it so e.g. the auth-failed hint
+          // fires instead of a misleading TLS verdict.
+          if (!isTlsTrustError(e2)) throw e2;
+          // The fallback handshake ALSO failed at the trust layer: throw the ORIGINAL
+          // error so isTlsTrustError stays true downstream (status diagnostic + log).
+          err.tlsSelfHeal = 'failed';
+          err.fallbackCode = tlsCodeOf(e2);
+          throw err; // NOT e2; do not fall through to transient-retry handling
+        }
+      }
       if (!isTransientFetchError(err)) throw err;
       const isLastAttempt = attempt === POST_MAX_ATTEMPTS - 1;
       if (isLastAttempt) break; // don't log a retry that will never happen
@@ -804,7 +883,21 @@ async function main() {
     const errorDetail = cause
       ? { message: cause.message, code: cause.code, ...(cause.cause ? { inner: cause.cause.message, innerCode: cause.cause.code } : {}) }
       : undefined;
-    log({ msg: 'failed', error: err.message, ...(errorDetail ? { cause: errorDetail } : {}), sent: sentEventIds.size, unsent: unsentIds.size, server: serverUrl });
+    // TLS chain-trust failures (corporate proxy / antivirus interception) carry a self-heal
+    // status + fix hint, so the fleet view (Axiom) and `ai-lens status` can name and resolve it.
+    const tlsFields = isTlsTrustError(err)
+      ? {
+          tlsTrust: true,
+          selfHeal: err.tlsSelfHeal                                   // 'failed' (fallback ran + threw)
+            ? err.tlsSelfHeal
+            : !tlsSelfHealEnabled() ? 'disabled'                     // AI_LENS_TLS_STRICT=1
+            : !systemCaAvailable() ? 'unavailable'                   // old Node (no getCACertificates)
+            : 'failed',
+          ...(err.fallbackCode ? { fallbackCode: err.fallbackCode } : {}),
+          hint: 'set NODE_OPTIONS=--use-system-ca or update ai-lens client',
+        }
+      : {};
+    log({ msg: 'failed', error: err.message, ...(errorDetail ? { cause: errorDetail } : {}), ...tlsFields, sent: sentEventIds.size, unsent: unsentIds.size, server: serverUrl });
     if (err.message.includes('401')) {
       log({ msg: 'auth-failed', error: 'Token invalid or revoked. Run: npx -y ai-lens init' });
     }

package/client/tls-trust.js

@@ -0,0 +1,106 @@
+/**
+ * AI Lens — TLS trust helpers (shared by client/sender.js and cli/status.js)
+ *
+ * Behind corporate TLS inspection (antivirus / proxy that re-signs HTTPS with its own CA,
+ * trusted by the OS store but NOT in Node's bundled CA list), `fetch()` fails with
+ * UNABLE_TO_VERIFY_LEAF_SIGNATURE and the sender's POST silently rolls back. These helpers
+ * let the sender self-heal (retry trusting the OS cert store) and let `status` name the
+ * interceptor instead of printing a bare error code.
+ */
+
+import tls from 'node:tls';
+
+// Error codes that mean "I couldn't build a trusted chain" — recoverable by trusting the OS
+// store. CERT_HAS_EXPIRED is deliberately EXCLUDED: a genuinely expired cert must not be
+// silently bypassed.
+export const TLS_TRUST_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'CERT_UNTRUSTED',
+]);
+
+/**
+ * Walk the error cause chain — Node's fetch() wraps the real code under `.cause`, and some
+ * undici/TLS wrappers nest one level deeper under `.cause.cause` (mirrors the `innerCode`
+ * depth the sender already logs). Returns the first TLS-trust code found, else the topmost
+ * non-null code (useful for logging non-TLS failures too).
+ */
+export function tlsCodeOf(err) {
+  if (!err) return undefined;
+  const codes = [err.code, err.cause?.code, err.cause?.cause?.code];
+  for (const c of codes) {
+    if (c && TLS_TRUST_CODES.has(c)) return c;
+  }
+  return codes.find((c) => c != null);
+}
+
+export function isTlsTrustError(err) {
+  return TLS_TRUST_CODES.has(tlsCodeOf(err));
+}
+
+/**
+ * Self-heal is ON by default; ONLY the exact string '1' disables it. '0'/empty/unset all keep
+ * it enabled (positive name on purpose — don't invert into `strictDisabled() === false`).
+ */
+export function tlsSelfHealEnabled() {
+  return process.env.AI_LENS_TLS_STRICT !== '1';
+}
+
+/** `tls.getCACertificates` was added in Node 22.15.0 / 23.10.0. Older Node → no self-heal. */
+export function systemCaAvailable() {
+  return typeof tls.getCACertificates === 'function';
+}
+
+/**
+ * Combine Node's bundled roots + the OS trust store + NODE_EXTRA_CA_CERTS into one deduped
+ * PEM array. We must include 'default' because `https.Agent({ ca })` REPLACES the bundle
+ * rather than appending to it. Returns undefined if the API is unavailable.
+ * Memoized: the trust store is effectively constant for the process lifetime, and the
+ * fallback path may run once per POST under sustained interception.
+ */
+let _trustBundleCache;
+export function loadTrustBundle() {
+  if (!systemCaAvailable()) return undefined;
+  if (_trustBundleCache) return _trustBundleCache;
+  const seen = new Set();
+  const bundle = [];
+  for (const type of ['default', 'system', 'extra']) {
+    let certs;
+    try { certs = tls.getCACertificates(type); } catch { certs = []; }
+    for (const pem of certs) {
+      if (!seen.has(pem)) { seen.add(pem); bundle.push(pem); }
+    }
+  }
+  _trustBundleCache = bundle;
+  return bundle;
+}
+
+/** Human label for a cert's issuer — single source of truth for verdicts AND detail lines. */
+export function issuerName(cert) {
+  const iss = (cert && cert.issuer) || {};
+  return iss.O || iss.CN || iss.OU || '(unknown issuer)';
+}
+
+/**
+ * Classify the cert actually served to the client. A Let's Encrypt issuer means we reached
+ * the real server (so a TLS error was a transient/incomplete-chain blip). Any other issuer
+ * is flagged as LIKELY interception — for THIS deployment the server cert is Let's Encrypt,
+ * but other orgs may legitimately front AI Lens with a different CA, so the verdict hedges
+ * rather than asserting.
+ */
+export function classifyTlsIssuer(cert) {
+  const who = issuerName(cert);
+  if (/let'?s encrypt/i.test(who)) return { kind: 'expected', who };
+  return { kind: 'interception', who };
+}
+
+/** One-line verdict string for the `status` diagnostic line. */
+export function tlsVerdictSummary(cert) {
+  const { kind, who } = classifyTlsIssuer(cert);
+  if (kind === 'expected') {
+    return `TLS chain served by «${who}» (expected) — a TLS error here is transient/incomplete-chain, not interception`;
+  }
+  return `TLS likely intercepted by «${who}» — fix: set NODE_OPTIONS=--use-system-ca (or update the ai-lens client). If your deployment legitimately uses «${who}», ignore this.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.85",
+  "version": "0.8.87",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {