claude-code-session-manager 0.83.0 → 0.85.0

package/src/main/lib/telemetryClient.cjs

@@ -1,6 +1,11 @@
 /**
  * telemetryClient — the single egress module that ships telemetry to
- * bilko.run's beacon endpoints (POST /api/telemetry/event, /log, /error).
+ * bilko.run's beacon endpoints (POST /api/telemetry/event, /log, /error,
+ * /install). The `install` channel is a durable upsert keyed on install_id
+ * (app_installs), not an append like the other three — its wire body is a
+ * single flat snake_case object, never `{batch:[...]}` — so it is routed
+ * through the same queue/dedup/backoff machinery but sent one record at a
+ * time via sendSingle() rather than sendBatch().
  *
  * Records accumulate durably in ~/.config/session-manager/telemetry-queue.jsonl
  * the instant they're accepted, and are only ever sent by flush(reason) — on
@@ -83,14 +88,42 @@ const S = {
   errSeen: new Map(),
   dailyTimer: null,
   flushChain: Promise.resolve(),
+  lastError: null,
+  lastFlushAt: null,
+  lastFlushReason: null,
 };
 
+/**
+ * SM_TELEMETRY_SPOOL, when set, overrides the spool directory in place of
+ * `~/.config/session-manager` — the explicit opt-in a test that genuinely
+ * needs to exercise real queue/sent-file I/O uses to prove it isn't about to
+ * write into a real user's spool (see isTestEnvironment() below).
+ */
+function spoolDir() {
+  return process.env.SM_TELEMETRY_SPOOL || path.join(os.homedir(), '.config', 'session-manager');
+}
+
 function queuePath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'telemetry-queue.jsonl');
+  return path.join(spoolDir(), 'telemetry-queue.jsonl');
 }
 
 function sentPath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'telemetry-sent.json');
+  return path.join(spoolDir(), 'telemetry-sent.json');
+}
+
+/**
+ * True when running under a test runner (VITEST, NODE_ENV=test) with no
+ * explicit SM_TELEMETRY_SPOOL override. Gates appendRecord() below so a test
+ * that merely exercises epicMint/scheduler/etc. code paths — without itself
+ * setting up an isolated spool — can never accumulate fake records into a
+ * real user's telemetry-queue.jsonl. A test that deliberately wants to
+ * exercise real persistence (telemetryClient's own suite) sets
+ * SM_TELEMETRY_SPOOL to an isolated directory, which counts as an explicit
+ * opt-in and disables this guard.
+ */
+function isTestEnvironment() {
+  if (process.env.SM_TELEMETRY_SPOOL) return false;
+  return !!process.env.VITEST || process.env.NODE_ENV === 'test';
 }
 
 function getBeaconToken() {
@@ -365,6 +398,9 @@ function pushRecent(rec) {
 }
 
 async function appendRecord(channel, wire, recordId) {
+  if (isTestEnvironment()) {
+    return { accepted: false, reason: 'test-environment', recordId };
+  }
   if (S.queueIds.has(recordId) || S.sentIds.has(recordId)) {
     S.dedupedAppends += 1;
     return { accepted: false, reason: 'duplicate', recordId };
@@ -472,6 +508,47 @@ async function reportError(opts) {
   }
 }
 
+function buildInstallWire(profile, installId) {
+  const p = safeObj(profile);
+  return {
+    install_id: safeStr(installId, 80),
+    app: 'session-manager',
+    app_version: safeStr(p.appVersion, 20),
+    platform: safeStr(p.platform, 20),
+    os_release: safeStr(p.osRelease, 80),
+    arch: safeStr(p.arch, 20),
+    cpu_count: typeof p.cpuCount === 'number' ? p.cpuCount : 0,
+    total_mem_mb: typeof p.totalMemMb === 'number' ? p.totalMemMb : 0,
+    node_version: safeStr(p.nodeVersion, 20),
+    electron_version: safeStr(p.electronVersion, 20),
+    install_channel: safeStr(p.installChannel, 20),
+    locale: safeStr(p.locale, 20),
+    // machineProfile deliberately never carries an IANA timezone name — only
+    // the numeric UTC offset (see machineProfile.cjs) — so that is what maps
+    // onto the server's `timezone` column.
+    timezone: safeStr(p.timezoneOffsetMinutes, 20),
+  };
+}
+
+/**
+ * Reports the once-per-cadence install/liveness record. Unlike track/logLine/
+ * reportError this isn't arbitrary user content, so it skips redactDeep() —
+ * every field already comes from machineProfile's own anonymity contract —
+ * and it never merges an attribution block onto the body, since the server's
+ * app_installs upsert doesn't read a recordId.
+ */
+async function reportInstall(profile) {
+  try {
+    await ensureInit();
+    if (!telemetrySettings.isEnabled(S.settings)) return { accepted: false, reason: 'disabled' };
+    const recordId = crypto.randomUUID();
+    const wire = buildInstallWire(profile, S.settings.installId);
+    return await appendRecord('install', wire, recordId);
+  } catch {
+    return { accepted: false, reason: 'error' };
+  }
+}
+
 // ─── egress ────────────────────────────────────────────────────────────
 
 async function sendBatch(channel, wireBatch) {
@@ -493,16 +570,42 @@ async function sendBatch(channel, wireBatch) {
   }
 }
 
+/** Like sendBatch(), but posts `wire` as a flat body — the install route takes one upsert, never a `{batch:[...]}` envelope. */
+async function sendSingle(channel, wire) {
+  const fetchFn = S.fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (typeof fetchFn !== 'function') return { ok: false, status: 0 };
+  const base = telemetrySettings.resolveEndpoint(S.settings);
+  const url = `${base}/api/telemetry/${channel}`;
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-SM-Beacon': `session-manager/${S.profile.appVersion}`,
+    'X-SM-Beacon-Key': getBeaconToken(),
+  };
+  try {
+    const res = await fetchFn(url, { method: 'POST', headers, body: JSON.stringify(wire) });
+    if (res && res.ok) return { ok: true };
+    return { ok: false, status: res ? res.status : 0 };
+  } catch {
+    return { ok: false, status: 0 };
+  }
+}
+
+function describeFailureStatus(status) {
+  return status === 0 ? 'network error' : `HTTP ${status}`;
+}
+
 function applyFailureBackoff(status) {
   if (status === 429 || status === 0 || status >= 500) {
     S.consecutiveFailures += 1;
     const ms = Math.min(BACKOFF_BASE_MS * (2 ** (S.consecutiveFailures - 1)), BACKOFF_MAX_MS);
     S.backoffUntil = Date.now() + ms;
+    S.lastError = { status, message: describeFailureStatus(status), at: Date.now() };
     return;
   }
   if (status >= 400 && status < 500) {
     // Malformed-contract circuit breaker (includes 401) — not retried.
     S.disabledForProcess = true;
+    S.lastError = { status, message: describeFailureStatus(status), at: Date.now() };
   }
 }
 
@@ -528,21 +631,41 @@ async function flushImpl(reason) {
     if (S.disabledForProcess) return result;
     if (Date.now() < S.backoffUntil) return result;
 
-    const byChannel = { event: [], log: [], error: [] };
+    const byChannel = { event: [], log: [], error: [], install: [] };
     for (const r of S.queue) {
       if (byChannel[r.channel]) byChannel[r.channel].push(r);
     }
 
     let sawFailure = false;
-    for (const channel of ['event', 'log', 'error']) {
+    for (const channel of ['event', 'log', 'error', 'install']) {
       if (sawFailure) break;
       const records = byChannel[channel];
+      if (channel === 'install') {
+        for (const r of records) {
+          const res = await sendSingle('install', r.wire);
+          if (res.ok) {
+            S.consecutiveFailures = 0;
+            S.backoffUntil = 0;
+            S.lastError = null;
+            removeFromQueue(r.recordId);
+            addToSent(r.recordId);
+            result.sent.push(r.recordId);
+          } else {
+            result.failed.push(r.recordId);
+            applyFailureBackoff(res.status);
+            sawFailure = true;
+            break;
+          }
+        }
+        continue;
+      }
       for (let i = 0; i < records.length; i += MAX_BATCH) {
         const batch = records.slice(i, i + MAX_BATCH);
         const res = await sendBatch(channel, batch.map((r) => r.wire));
         if (res.ok) {
           S.consecutiveFailures = 0;
           S.backoffUntil = 0;
+          S.lastError = null;
           for (const r of batch) {
             removeFromQueue(r.recordId);
             addToSent(r.recordId);
@@ -564,6 +687,8 @@ async function flushImpl(reason) {
       S.settings = await telemetrySettings.save({ ...S.settings, lastDailyFlushAt: new Date().toISOString() });
     }
   } catch { /* fail-inert */ }
+  S.lastFlushAt = Date.now();
+  S.lastFlushReason = safeReason;
   return result;
 }
 
@@ -584,6 +709,9 @@ function status() {
     consecutiveFailures: S.consecutiveFailures,
     backoffUntil: S.backoffUntil,
     profileBuildCount: S.profileBuildCount,
+    lastError: S.lastError,
+    lastFlushAt: S.lastFlushAt,
+    lastFlushReason: S.lastFlushReason,
   };
 }
 
@@ -591,6 +719,21 @@ function recentRecords() {
   return S.recent.slice();
 }
 
+/**
+ * Opt-out side effect: drops every not-yet-sent record from disk + memory so
+ * a re-enable later never resends a payload that was only ever queued while
+ * the user was opted out. Does NOT touch telemetry-sent.json or the backlog
+ * watermarks — those describe history that already left the machine, and
+ * clearing them would make a re-enable resend it. Never throws.
+ */
+async function clearQueue() {
+  S.queue = [];
+  S.queueIds = new Set();
+  try {
+    await config.writeTextAtomic(queuePath(), '', { mode: 0o600 });
+  } catch { /* best-effort */ }
+}
+
 async function isPending(recordId) {
   await ensureInit();
   return S.queueIds.has(recordId);
@@ -610,11 +753,13 @@ module.exports = {
   track,
   logLine,
   reportError,
+  reportInstall,
   flush,
   shutdown,
   status,
   recentRecords,
   isPending,
+  clearQueue,
   queuePath,
   sentPath,
   _setFetchImpl,

package/src/main/lib/telemetryConsent.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * telemetryConsent — the write-path the `telemetry:set-config` IPC handler
+ * delegates to, pulled out of src/main/index.cjs so it can be unit-tested
+ * without an Electron runtime (index.cjs requires('electron') at module
+ * load, which vitest can't satisfy).
+ *
+ * The one side effect beyond a plain settings save: turning telemetry OFF
+ * clears the pending queue file, so a later re-enable never resends a
+ * payload that only ever accumulated while the user was opted out. It does
+ * NOT touch telemetry-sent.json or the backlog watermarks — those describe
+ * history already delivered, and clearing them would make a re-enable
+ * resend it. See session-manager-operations/architecture/telemetry.md.
+ */
+
+function resolveDeps(deps = {}) {
+  return {
+    telemetrySettings: deps.telemetrySettings || require('./telemetrySettings.cjs'),
+    telemetryClient: deps.telemetryClient || require('./telemetryClient.cjs'),
+  };
+}
+
+async function applyConsentUpdate(cfg, depsOverride) {
+  const deps = resolveDeps(depsOverride);
+  const before = await deps.telemetrySettings.load();
+  const saved = await deps.telemetrySettings.save(cfg);
+  if (before.enabled && !saved.enabled) {
+    await deps.telemetryClient.clearQueue();
+  }
+  return saved;
+}
+
+module.exports = { applyConsentUpdate };

package/src/main/lib/telemetryCounters.cjs

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * telemetryCounters.cjs — the ONE place every usage counter event is emitted
+ * from, so 'session.open'/'epic.create'/'scheduler.job.finish'/'app.launch'
+ * each have exactly one call site's worth of shape logic even though they're
+ * fired from four different subsystems (pty.cjs, epicMint.cjs,
+ * scheduleJobTransitions.cjs, telemetryBoot.cjs).
+ *
+ * Structural props only — no free text, no cwd, no path — so a counter event
+ * can never carry a prompt/transcript/project-name leak by accident. Lazily
+ * requires telemetryClient.cjs (mirrors opsErrorLog.cjs's lazy require of
+ * opsOwnership.cjs) so this module stays Electron-free and importable from a
+ * plain-Node test.
+ */
+
+function track(name, props, deps) {
+  try {
+    const telemetryClient = (deps && deps.telemetryClient) || require('./telemetryClient.cjs');
+    telemetryClient.track(name, props);
+  } catch { /* counters must never break the caller */ }
+}
+
+function trackAppLaunch({ installChannel, appVersion } = {}, deps) {
+  track('app.launch', { installChannel: installChannel || null, appVersion: appVersion || null }, deps);
+}
+
+function trackSessionOpen(deps) {
+  track('session.open', {}, deps);
+}
+
+function trackEpicCreate(deps) {
+  track('epic.create', {}, deps);
+}
+
+function trackSchedulerJobFinish({ status } = {}, deps) {
+  track('scheduler.job.finish', { status: status || null }, deps);
+}
+
+module.exports = {
+  trackAppLaunch,
+  trackSessionOpen,
+  trackEpicCreate,
+  trackSchedulerJobFinish,
+};

package/src/main/pty.cjs

@@ -22,6 +22,7 @@ const { checkInsideHome } = require('./lib/insideHome.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const opsErrorLog = require('./lib/opsErrorLog.cjs');
 const { resolveEpicSpawnCwd } = require('./lib/epicSpawnCwd.cjs');
+const telemetryCounters = require('./lib/telemetryCounters.cjs');
 
 // Absolute path to the installed package root (src/main/ -> ../../), shown in
 // the remediation message so the user can cd there and rebuild.
@@ -200,6 +201,7 @@ class PtyManager {
       return { pid: null, cwd, reattached: false, error: String(err?.message || 'spawn-failed') };
     }
     console.log('[pty] spawned pid=', proc.pid, 'for tabId=', tabId);
+    telemetryCounters.trackSessionOpen();
 
     const spawnedAt = Date.now();
     let gotData = false;