claude-code-session-manager 0.84.0 → 0.85.0

package/src/main/__tests__/telemetryContract.test.cjs

@@ -78,8 +78,9 @@ async function createStubServer() {
     events: [], // { event, tool, metadata, session_id, visitor_id, path, version }
     logs: [], // { app, version, level, msg, visitor_id, session_id, fields_json, created_at }
     errors: [], // { app, version, name, msg, stack, url, ua, visitor_id, session_id, context_json, created_at }
+    installsById: new Map(), // install_id -> materialised app_installs row (upsert, mirrors the deployed route)
     allRequests: [], // { path, headers, rawBody, parsedBody, channel }
-    overrides: { event: [], log: [], error: [] },
+    overrides: { event: [], log: [], error: [], install: [] },
   };
 
   function nextOverride(channel) {
@@ -95,6 +96,7 @@ async function createStubServer() {
     const channel = urlPath.endsWith('/event') ? 'event'
       : urlPath.endsWith('/log') ? 'log'
       : urlPath.endsWith('/error') ? 'error'
+      : urlPath.endsWith('/install') ? 'install'
       : null;
     state.allRequests.push({ path: urlPath, headers: req.headers, rawBody, parsedBody, channel });
 
@@ -111,6 +113,41 @@ async function createStubServer() {
       return;
     }
 
+    if (channel === 'install') {
+      // Flat body (never {batch:[...]}) — mirrors the real route's upsert
+      // keyed on install_id: first_seen_at preserved, everything else overwritten.
+      const b = parsedBody;
+      const installId = clamp(b.install_id, 80);
+      if (!installId) {
+        res.writeHead(400, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'install_id_required' }));
+        return;
+      }
+      const now = Math.floor(Date.now() / 1000);
+      const existing = state.installsById.get(installId);
+      state.installsById.set(installId, {
+        install_id: installId,
+        app: clamp(b.app, 60),
+        app_version: clamp(b.app_version, 20),
+        platform: clamp(b.platform, 20),
+        os_release: clamp(b.os_release, 80),
+        arch: clamp(b.arch, 20),
+        cpu_count: Number(b.cpu_count) || 0,
+        total_mem_mb: Number(b.total_mem_mb) || 0,
+        node_version: clamp(b.node_version, 20),
+        electron_version: clamp(b.electron_version, 20),
+        install_channel: clamp(b.install_channel, 20),
+        locale: clamp(b.locale, 20),
+        timezone: clamp(b.timezone, 20),
+        first_seen_at: existing ? existing.first_seen_at : now,
+        last_seen_at: now,
+        seen_count: existing ? existing.seen_count + 1 : 1,
+      });
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+
     const batchRaw = Array.isArray(parsedBody.batch) ? parsedBody.batch : [];
     const batch = batchRaw.slice(0, MAX_BATCH); // MAX_BATCH truncation, exactly as the deployed route does
 
@@ -228,6 +265,7 @@ let originalHome;
 let originalSmTelemetry;
 let originalSmTelemetryEndpoint;
 let originalSmBeaconKey;
+let originalSmTelemetrySpool;
 let stubServer;
 
 beforeAll(async () => {
@@ -247,6 +285,7 @@ beforeEach(() => {
   originalSmTelemetry = process.env.SM_TELEMETRY;
   originalSmTelemetryEndpoint = process.env.SM_TELEMETRY_ENDPOINT;
   originalSmBeaconKey = process.env.SM_BEACON_KEY;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
   process.env.SM_TELEMETRY_ENDPOINT = stubServer.url;
   delete process.env.SM_TELEMETRY;
 });
@@ -256,6 +295,7 @@ afterEach(async () => {
   if (originalSmTelemetry === undefined) delete process.env.SM_TELEMETRY; else process.env.SM_TELEMETRY = originalSmTelemetry;
   if (originalSmTelemetryEndpoint === undefined) delete process.env.SM_TELEMETRY_ENDPOINT; else process.env.SM_TELEMETRY_ENDPOINT = originalSmTelemetryEndpoint;
   if (originalSmBeaconKey === undefined) delete process.env.SM_BEACON_KEY; else process.env.SM_BEACON_KEY = originalSmBeaconKey;
+  if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   vi.useRealTimers();
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
@@ -306,6 +346,9 @@ const HOME_DEPENDENT_MODULES = ['../lib/telemetryClient.cjs', '../config.cjs', '
 /** A fresh telemetryClient bound to `home`, simulating a real relaunch: only on-disk state carries over. */
 function freshClient(home, profileOverrides) {
   process.env.HOME = home;
+  // Explicit opt-in: overrides the test-environment no-op guard so this
+  // suite's real telemetryClient calls actually persist into an isolated dir.
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
   for (const p of HOME_DEPENDENT_MODULES) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];
@@ -490,30 +533,30 @@ test('an emitted event, log, and error each map to non-NULL values for every col
 // AC: machine-profile record survives redaction + clamping intact
 // ═══════════════════════════════════════════════════════════════════════
 
-test('the machine-profile record arrives with every buildMachineProfile() field present after redaction/clamping, cpuModel verbatim', async () => {
+test('the install record arrives at app_installs with every mapped field present, snake_case, cpu_count/total_mem_mb numeric', async () => {
   const home = await mkHome();
   const client = freshClient(home);
   const profile = fakeProfile();
-  const before = stubServer.state.events.length;
 
-  await client.track('install.machine', profile);
+  await client.reportInstall(profile);
   await client.flush('manual');
 
-  const row = stubServer.state.events[before];
-  expect(row.event).toBe('install.machine');
-  const meta = JSON.parse(row.metadata);
-
-  const expectedFields = [
-    'appVersion', 'installChannel', 'machineDigest', 'platform', 'osRelease', 'arch',
-    'cpuModel', 'cpuCount', 'cpuSpeedMhz', 'totalMemMb', 'nodeVersion', 'electronVersion',
-    'chromeVersion', 'v8Version', 'claudeCliVersion', 'locale', 'timezoneOffsetMinutes', 'firstSeenAt',
-  ];
-  for (const f of expectedFields) {
-    expect(meta[f]).not.toBeUndefined();
-    expect(meta[f]).not.toBeNull();
-  }
-  // The over-eager-sanitiser casualty: a CPU model string containing spaces and '@'.
-  expect(meta.cpuModel).toBe('Intel(R) Xeon(R) CPU @ 2.20GHz');
+  const settings = require('../lib/telemetrySettings.cjs');
+  const persisted = await settings.load();
+  const row = stubServer.state.installsById.get(persisted.installId);
+  expect(row).toBeDefined();
+  expect(row.app).toBe('session-manager');
+  expect(row.app_version).toBe(profile.appVersion);
+  expect(row.platform).toBe(profile.platform);
+  expect(row.os_release).toBe(profile.osRelease);
+  expect(row.arch).toBe(profile.arch);
+  expect(row.cpu_count).toBe(profile.cpuCount);
+  expect(row.total_mem_mb).toBe(profile.totalMemMb);
+  expect(row.node_version).toBe(profile.nodeVersion);
+  expect(row.electron_version).toBe(profile.electronVersion);
+  expect(row.install_channel).toBe(profile.installChannel);
+  expect(row.locale).toBe(profile.locale);
+  expect(row.timezone).toBe(String(profile.timezoneOffsetMinutes));
 
   client.shutdown();
 });
@@ -522,23 +565,27 @@ test('the machine-profile record arrives with every buildMachineProfile() field
 // AC: machine profile sent once per version + once per 30-day heartbeat
 // ═══════════════════════════════════════════════════════════════════════
 
-test('install.machine fires once per app version and once per 30-day heartbeat, not once per launch', async () => {
+test('the install upsert fires once per app version and once per 30-day heartbeat, not once per launch', async () => {
   const home = await mkHome();
-  const before = stubServer.state.events.length;
+  let installId = null;
 
-  function countInstallMachine() {
-    return stubServer.state.events.slice(before).filter((r) => r.event === 'install.machine').length;
+  function seenCount() {
+    if (!installId) return 0;
+    const row = stubServer.state.installsById.get(installId);
+    return row ? row.seen_count : 0;
   }
 
   async function simulatedLaunch({ now, appVersion }) {
     const client = freshClient(home, { appVersion });
     const boot = freshBoot();
+    const telemetrySettings = require('../lib/telemetrySettings.cjs');
+    if (!installId) installId = (await telemetrySettings.load()).installId;
     await boot.bootSequence({
       now,
       appVersion,
       installChannel: 'dev',
       deps: {
-        telemetrySettings: require('../lib/telemetrySettings.cjs'),
+        telemetrySettings,
         telemetryClient: client,
         buildMachineProfile: async () => fakeProfile({ appVersion }),
         telemetryCounters: { trackAppLaunch: () => {} },
@@ -557,15 +604,15 @@ test('install.machine fires once per app version and once per 30-day heartbeat,
   await simulatedLaunch({ now: t0 + 2 * ONE_DAY, appVersion: '1.0.0' });
   await simulatedLaunch({ now: t0 + 3 * ONE_DAY, appVersion: '1.0.0' });
   await simulatedLaunch({ now: t0 + 4 * ONE_DAY, appVersion: '1.0.0' });
-  expect(countInstallMachine()).toBe(1);
+  expect(seenCount()).toBe(1);
 
   // Launch 6: version bump.
   await simulatedLaunch({ now: t0 + 5 * ONE_DAY, appVersion: '1.1.0' });
-  expect(countInstallMachine()).toBe(2);
+  expect(seenCount()).toBe(2);
 
   // Launch 7: 31 days after the version-bump report, same version -> heartbeat due.
   await simulatedLaunch({ now: t0 + 5 * ONE_DAY + 31 * ONE_DAY, appVersion: '1.1.0' });
-  expect(countInstallMachine()).toBe(3);
+  expect(seenCount()).toBe(3);
 });
 
 // ═══════════════════════════════════════════════════════════════════════

package/src/main/index.cjs

@@ -1070,8 +1070,8 @@ app.whenReady().then(async () => {
   });
 
   // Telemetry boot sequence: flush('boot') always, flush('version-change')
-  // when detected, and the once-per-machine install.machine profile when due
-  // (version bump or 30-day liveness heartbeat). See telemetryBoot.cjs.
+  // when detected, and the once-per-machine install upsert (app_installs) when
+  // due (version bump or 30-day liveness heartbeat). See telemetryBoot.cjs.
   require('./lib/telemetryBoot.cjs')
     .bootSequence({
       appVersion: app.getVersion(),

package/src/main/lib/__tests__/crashTelemetry.test.cjs

@@ -16,9 +16,11 @@ const { reportCrash } = require('../crashTelemetry.cjs');
 
 const tmpDirs = [];
 let originalHome;
+let originalSmTelemetrySpool;
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome;
+  if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
     await fsp.rm(d, { recursive: true, force: true });
@@ -27,9 +29,13 @@ afterEach(async () => {
 
 async function mkHome() {
   originalHome = process.env.HOME;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
   const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-crash-telemetry-home-'));
   tmpDirs.push(dir);
   process.env.HOME = dir;
+  // Explicit opt-in: overrides the test-environment no-op guard so this
+  // suite's real telemetryClient calls actually persist into an isolated dir.
+  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.config', 'session-manager');
   return dir;
 }
 

package/src/main/lib/__tests__/telemetryBacklog.test.cjs

@@ -18,13 +18,16 @@ const { resolveProjectContext } = require('../projectRootResolve.cjs');
 
 const tmpDirs = [];
 let originalHome;
+let originalSmTelemetrySpool;
 
 beforeEach(() => {
   originalHome = process.env.HOME;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
 });
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome;
+  if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   vi.unstubAllGlobals();
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
@@ -51,6 +54,9 @@ function fakeProfile(overrides = {}) {
 /** Reloads the HOME-dependent modules (config.cjs computes allowedRoots from os.homedir() at require time). */
 function freshTelemetry(home) {
   process.env.HOME = home;
+  // Explicit opt-in: overrides the test-environment no-op guard so this
+  // suite's real telemetryClient calls actually persist into an isolated dir.
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
   for (const p of ['../telemetryClient.cjs', '../../config.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];

package/src/main/lib/__tests__/telemetryBoot.test.cjs

@@ -27,7 +27,7 @@ function fakeDeps({ settings } = {}) {
       },
       telemetryClient: {
         flush: async (reason) => { flushCalls.push(reason); return { sent: [], failed: [], reason }; },
-        track: async (name, props) => ({ accepted: true, name, props }),
+        reportInstall: async (profile) => ({ accepted: true, profile }),
       },
       buildMachineProfile: async () => ({ appVersion: '1.0.0', platform: 'linux', arch: 'x64', machineDigest: 'abc123' }),
       telemetryCounters: { trackAppLaunch: () => {} },
@@ -42,11 +42,11 @@ test('a second boot at the same version within 30 days sends nothing', async ()
     settings: { lastMachineReportAt: priorReportAt, lastMachineReportVersion: '1.0.0' },
   });
   const seen = [];
-  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+  deps.telemetryClient.reportInstall = async (profile) => { seen.push(profile); return { accepted: true }; };
 
   await bootSequence({ now, appVersion: '1.0.0', deps });
 
-  expect(seen.filter((e) => e.name === 'install.machine')).toHaveLength(0);
+  expect(seen).toHaveLength(0);
   expect(state().lastMachineReportAt).toBe(priorReportAt);
 });
 
@@ -56,12 +56,11 @@ test('a version bump sends the machine profile exactly once', async () => {
     settings: { lastMachineReportAt: new Date(now - DAY_MS).toISOString(), lastMachineReportVersion: '1.0.0' },
   });
   const seen = [];
-  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+  deps.telemetryClient.reportInstall = async (profile) => { seen.push(profile); return { accepted: true }; };
 
   await bootSequence({ now, appVersion: '2.0.0', deps });
 
-  const installEvents = seen.filter((e) => e.name === 'install.machine');
-  expect(installEvents.length).toBe(1);
+  expect(seen.length).toBe(1);
   expect(state().lastMachineReportVersion).toBe('2.0.0');
 });
 
@@ -71,27 +70,26 @@ test('31 days on an unchanged version sends the machine profile exactly once (li
     settings: { lastMachineReportAt: new Date(now - 31 * DAY_MS).toISOString(), lastMachineReportVersion: '1.0.0' },
   });
   const seen = [];
-  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+  deps.telemetryClient.reportInstall = async (profile) => { seen.push(profile); return { accepted: true }; };
 
   await bootSequence({ now, appVersion: '1.0.0', deps });
 
-  const installEvents = seen.filter((e) => e.name === 'install.machine');
-  expect(installEvents.length).toBe(1);
+  expect(seen.length).toBe(1);
   expect(state().lastMachineReportAt).toBe(new Date(now).toISOString());
 });
 
-test('the install.machine event appVersion prop equals the appVersion stamped on a sibling error record', async () => {
+test('the install report appVersion equals the appVersion stamped on a sibling error record', async () => {
   const now = Date.now();
   const { deps } = fakeDeps({ settings: { lastMachineReportVersion: '', lastMachineReportAt: null } });
   const seen = [];
-  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+  deps.telemetryClient.reportInstall = async (profile) => { seen.push(profile); return { accepted: true }; };
   // Sibling error record stamped by the SAME process's telemetryClient with the same appVersion.
   const siblingErrorStampAppVersion = '1.0.0';
 
   await bootSequence({ now, appVersion: '1.0.0', deps });
 
-  const [install] = seen.filter((e) => e.name === 'install.machine');
-  expect(install.props.appVersion).toBe(siblingErrorStampAppVersion);
+  const [install] = seen;
+  expect(install.appVersion).toBe(siblingErrorStampAppVersion);
 });
 
 test('on app ready, flush("boot") always runs', async () => {

package/src/main/lib/__tests__/telemetryConsent.test.cjs

@@ -13,13 +13,16 @@ const path = require('node:path');
 
 const tmpDirs = [];
 let originalHome;
+let originalSmTelemetrySpool;
 
 beforeEach(() => {
   originalHome = process.env.HOME;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
 });
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome; else delete process.env.HOME;
+  if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   vi.unstubAllGlobals();
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
@@ -35,6 +38,9 @@ async function mkHome() {
 
 function freshModules(home) {
   process.env.HOME = home;
+  // Explicit opt-in: overrides the test-environment no-op guard so this
+  // suite's real telemetryClient calls actually persist into an isolated dir.
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
   for (const p of ['../telemetryConsent.cjs', '../telemetryClient.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs', '../../config.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];

package/src/main/lib/__tests__/telemetryCountersMetadataColumn.test.cjs

@@ -18,9 +18,11 @@ const counters = require('../telemetryCounters.cjs');
 
 const tmpDirs = [];
 let originalHome;
+let originalSmTelemetrySpool;
 
 afterEach(async () => {
   if (originalHome !== undefined) process.env.HOME = originalHome;
+  if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
     await fsp.rm(d, { recursive: true, force: true });
@@ -29,9 +31,13 @@ afterEach(async () => {
 
 async function mkHome() {
   originalHome = process.env.HOME;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
   const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-telemetry-counters-home-'));
   tmpDirs.push(dir);
   process.env.HOME = dir;
+  // Explicit opt-in: overrides the test-environment no-op guard so this
+  // suite's real telemetryClient calls actually persist into an isolated dir.
+  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.config', 'session-manager');
   return dir;
 }
 

package/src/main/lib/queueStore.cjs

@@ -220,6 +220,11 @@ function shapeMachine(data) {
     config: data.config || {},
     scheduledFor: data.scheduledFor ?? null,
     lastRunAt: data.lastRunAt ?? null,
+    // Distinct from lastRunAt (stamped only when tickQueue actually launches a
+    // job): this is stamped every time tickQueue gets far enough to evaluate
+    // the queue at all, whether or not that evaluation ends in a launch. See
+    // classifyQueueStarvation's header for why the two must never merge.
+    lastDispatchAttemptAt: data.lastDispatchAttemptAt ?? null,
     paused: data.paused ?? null,
     // Launch circuit breaker (lib/launchFailure.cjs): per-persona blocks and
     // the degraded-mode env a persona is currently launching with. Machine
@@ -440,7 +445,7 @@ function shapeJobs(raw, file) {
  * consulted so writeSplit can persist "this project now has zero jobs".
  */
 function readMergedSync(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
   const sourceCwds = [];
   const machine = loadMachineStateSync();
   if (machine.shaped) {
@@ -473,7 +478,7 @@ function readMergedSync(opts) {
 
 /** Async twin of readMergedSync for IPC hot paths. */
 async function readMerged(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
   const sourceCwds = [];
   const machine = await loadMachineState();
   if (machine.shaped) {
@@ -525,6 +530,7 @@ async function writeSplit(state, defaultCwd) {
     config: state.config,
     scheduledFor: state.scheduledFor ?? null,
     lastRunAt: state.lastRunAt ?? null,
+    lastDispatchAttemptAt: state.lastDispatchAttemptAt ?? null,
     paused: state.paused ?? null,
     launchBlocks: state.launchBlocks ?? {},
     launchMitigations: state.launchMitigations ?? {},

package/src/main/lib/telemetryBoot.cjs

@@ -36,10 +36,15 @@ function resolveDeps(deps = {}) {
  *  2. flush('version-change') — only when this install's persisted
  *     lastMachineReportVersion differs from the running appVersion (the same
  *     signal that also gates the machine-profile heartbeat below).
- *  3. install.machine — sent once as track('install.machine', profile) when
- *     telemetrySettings.isMachineReportDue() is true (a version bump, OR the
- *     30-day liveness heartbeat), then lastMachineReportAt/Version are
+ *  3. install upsert — sent once via telemetryClient.reportInstall(profile)
+ *     when telemetrySettings.isMachineReportDue() is true (a version bump, OR
+ *     the 30-day liveness heartbeat), then lastMachineReportAt/Version are
  *     persisted so a same-version reboot within the window sends nothing.
+ *     This lands in bilko.run's app_installs table (the sole source for
+ *     every install-shaped number on the site). It replaces the former
+ *     track('install.machine', profile) call, which duplicated the same
+ *     facts into funnel_events for no reader — app_installs is now the only
+ *     destination for a machine profile.
  *  4. app.launch — one counter event per boot, via telemetryCounters so the
  *     shape lives in exactly one place across every counter this PRD adds.
  */
@@ -57,7 +62,7 @@ async function bootSequence({ now = Date.now(), appVersion, installChannel, deps
 
   if (telemetrySettings.isMachineReportDue(settings, { now, appVersion })) {
     const profile = await buildMachineProfile();
-    await telemetryClient.track('install.machine', profile);
+    await telemetryClient.reportInstall(profile);
     await telemetrySettings.save({
       ...settings,
       lastMachineReportAt: new Date(now).toISOString(),

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
@@ -88,12 +93,37 @@ const S = {
   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() {
@@ -368,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 };
@@ -475,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) {
@@ -496,6 +570,26 @@ 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}`;
 }
@@ -537,15 +631,34 @@ 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));
@@ -640,6 +753,7 @@ module.exports = {
   track,
   logLine,
   reportError,
+  reportInstall,
   flush,
   shutdown,
   status,