claude-code-session-manager 0.84.0 → 0.86.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/__tests__/telemetrySettings.test.cjs

@@ -168,6 +168,38 @@ test('isMachineReportDue: true when lastMachineReportAt is more than 30 days bef
   expect(telemetrySettings.isMachineReportDue(cfg, { now, appVersion: '0.81.0' })).toBe(true);
 });
 
+test('save() merges a partial patch onto a fresh disk read — concurrent savers do not clobber each other', async () => {
+  const home = await mkHome();
+  const telemetrySettings = await freshModule(home);
+  const base = await telemetrySettings.load(); // mints + persists installId
+  expect(base.installId).not.toBe('');
+
+  // Two independent writers, each stamping a DIFFERENT field, racing each
+  // other — mirrors telemetryBoot's install-report stamp landing around the
+  // same time as telemetryClient's own daily-flush stamp. Neither holds the
+  // other's snapshot; each passes only the field it intends to change.
+  await Promise.all([
+    telemetrySettings.save({ lastMachineReportAt: '2026-01-01T00:00:00.000Z', lastMachineReportVersion: '2.0.0' }),
+    telemetrySettings.save({ lastDailyFlushAt: '2026-01-01T01:00:00.000Z' }),
+  ]);
+
+  const onDisk = await telemetrySettings.load();
+  expect(onDisk.lastMachineReportAt).toBe('2026-01-01T00:00:00.000Z');
+  expect(onDisk.lastMachineReportVersion).toBe('2.0.0');
+  expect(onDisk.lastDailyFlushAt).toBe('2026-01-01T01:00:00.000Z');
+  // Neither save touched installId/enabled/endpoint — they must survive too.
+  expect(onDisk.installId).toBe(base.installId);
+  expect(onDisk.enabled).toBe(base.enabled);
+  expect(onDisk.endpoint).toBe(base.endpoint);
+});
+
+test('save() rejects an unknown key without touching disk', async () => {
+  const home = await mkHome();
+  const telemetrySettings = await freshModule(home);
+  await telemetrySettings.load();
+  await expect(telemetrySettings.save({ notARealField: 'x' })).rejects.toThrow('Invalid telemetry config');
+});
+
 test('isMachineReportDue: false when same version and reported less than 30 days ago', async () => {
   const home = await mkHome();
   const telemetrySettings = await freshModule(home);

package/src/main/health.cjs

@@ -16,7 +16,9 @@ const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
-const { computeStallSummary, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD, classifyQueueStarvation } = require('./scheduler.cjs');
+const { computeStallSummary, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD, classifyQueueStarvation, STARVE_ESCALATION_MS } = require('./scheduler.cjs');
+const { findStarvedProjects } = require('./lib/schedulerBatch.cjs');
+const { AUDIT_LOG_PATH } = require('./lib/auditLog.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
@@ -458,6 +460,63 @@ function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs
   };
 }
 
+/**
+ * latestStarveEscalationReasons(auditLogPath) → { [cwd]: holdReason }
+ *
+ * health.cjs runs as its own cold process (`npm run health`), so it has no
+ * access to the live scheduler's in-memory `lastTick` — the durable
+ * audit-log.jsonl trail (auditLog.cjs) is the only place the hold reason a
+ * 'project_starve_escalated' event already recorded (scheduler.cjs's
+ * runStarveEscalationSweep) survives to be read from here. Reads the SAME
+ * recorded value rather than re-deriving it; the last record per cwd wins.
+ * Missing/unreadable log → {} (no reasons known yet), never a throw.
+ */
+function latestStarveEscalationReasons(auditLogPath) {
+  let lines;
+  try {
+    lines = fs.readFileSync(auditLogPath, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return {};
+  }
+  const byCwd = {};
+  for (const line of lines) {
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (rec?.kind === 'project_starve_escalated' && rec.cwd) byCwd[rec.cwd] = rec.holdReason ?? 'unknown';
+  }
+  return byCwd;
+}
+
+/**
+ * evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons)
+ *   → { ok, projects?, message? }
+ *
+ * Pure over its inputs. Reuses findStarvedProjects — the exact per-cwd
+ * STARVED verdict the live escalation (scheduler.cjs) acts on — so health
+ * reports the identical set of starved-past-threshold projects, never a
+ * re-derived one. `escalationReasons` supplies the hold reason per cwd (see
+ * latestStarveEscalationReasons); a cwd with no recorded reason yet reports
+ * 'unknown' rather than failing.
+ */
+function evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons = {}) {
+  const starved = findStarvedProjects(jobs, now, thresholdMs);
+  if (starved.length === 0) return { ok: true };
+  const projects = starved.map((sp) => ({
+    cwd: sp.cwd,
+    pendingCount: sp.pendingCount,
+    ageMs: sp.ageMs,
+    holdReason: escalationReasons[sp.cwd] ?? 'unknown',
+  }));
+  const message = `Project(s) starved past the ${Math.round(thresholdMs / 60_000)}m escalation threshold: ${
+    projects.map((p) => `${p.cwd} (${Math.round(p.ageMs / 60_000)}m, ${p.pendingCount} pending, hold=${p.holdReason})`).join('; ')
+  }`;
+  return { ok: false, projects, message };
+}
+
 function loadUsagePollerState(statePath) {
   let raw;
   try {
@@ -640,6 +699,18 @@ async function check() {
       status.issues.push(`Queue dispatch: ${status.components.queue_dispatch.message}`);
     }
 
+    // Per-project starve escalation (bounded consequence for project_starved
+    // — see runStarveEscalationSweep in scheduler.cjs). Distinct from
+    // queue_dispatch above: that's machine-wide dispatch liveness, this is
+    // "has any ONE project been starved past the LATER escalation threshold",
+    // the exact condition the 2026-09-12 19h Bilko starve went unreported by.
+    status.components.project_starve_escalation = evaluateStarveEscalationHealth(
+      queueState.jobs, now, STARVE_ESCALATION_MS, latestStarveEscalationReasons(AUDIT_LOG_PATH),
+    );
+    if (!status.components.project_starve_escalation.ok) {
+      status.issues.push(status.components.project_starve_escalation.message);
+    }
+
     // Worktree cap blocking every dispatchable pending job with nothing
     // running (see evaluateWorktreeCapBlocked's header) — a distinct
     // condition from generic tick/dispatch staleness above, since a leaked
@@ -877,7 +948,7 @@ async function check() {
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'queue_dispatch', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'queue_dispatch', 'project_starve_escalation', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -909,6 +980,8 @@ module.exports = {
   evaluateUsagePollerHealth,
   loadUsagePollerState,
   evaluateQueueDispatchHealth,
+  evaluateStarveEscalationHealth,
+  latestStarveEscalationReasons,
   DISPATCH_STALL_THRESHOLD_MS,
   TICK_STALL_THRESHOLD_MS,
   HEARTBEAT_STALE_MS,

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__/loadGate.test.cjs

@@ -125,7 +125,7 @@ test('an ungated tick never audits', () => {
   assert.equal(g.evaluate().shouldAudit, false);
 });
 
-test('escalates once the gated stretch exceeds the escalation window, and the stretch resets when load drops', () => {
+test('escalates once the gated stretch exceeds the escalation window, and the stretch only resets once load has stayed sub-threshold past the release window', () => {
   let l1 = 12.95;
   let t = 0;
   const g = createLoadGate({
@@ -134,6 +134,7 @@ test('escalates once the gated stretch exceeds the escalation window, and the st
     now: () => t,
     threshold: 0.85,
     escalateAfterMs: 45 * 60_000,
+    releaseWindowMs: 2 * 60_000,
   });
   assert.equal(g.evaluate().escalate, false);
   t += 44 * 60_000;
@@ -142,12 +143,43 @@ test('escalates once the gated stretch exceeds the escalation window, and the st
   const r = g.evaluate();
   assert.equal(r.escalate, true, 'at 45m: escalates');
   assert.equal(r.gatedSinceMs, 45 * 60_000);
+  // A single sub-threshold sample must NOT reset the stretch (the boundary-
+  // hovering bug this PRD fixes) — gatedSinceMs keeps growing.
   l1 = 1; t += 60_000;
-  assert.equal(g.evaluate().gatedSinceMs, 0, 'load dropped: stretch resets');
+  const oneMinBelow = g.evaluate();
+  assert.equal(oneMinBelow.gated, false, 'gate decision is immediate');
+  assert.equal(oneMinBelow.gatedSinceMs, 46 * 60_000, 'stretch not yet released');
+  // Load climbs back above threshold before the release window elapses: the
+  // stretch was never actually cleared, so it just keeps accumulating.
+  l1 = 12.95; t += 30_000;
+  assert.equal(g.evaluate().gatedSinceMs, 46 * 60_000 + 30_000, 'stretch survived the brief dip');
+  // Now hold sub-threshold continuously past the release window (the window
+  // is measured from the first sub-threshold sample of this sustained drop,
+  // so it takes a tick to mark that start, then another once the window has
+  // actually elapsed).
+  l1 = 1; t += 1;
+  g.evaluate();
+  t += 2 * 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'sustained sub-threshold load past the release window clears the stretch');
   l1 = 12.95; t += 60_000;
   assert.equal(g.evaluate().gatedSinceMs, 0, 'a fresh stretch starts from zero');
 });
 
+test('the gate decision itself is unaffected by hysteresis: a sub-threshold tick is never gated, even mid-stretch', () => {
+  let l1 = 12.95;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    releaseWindowMs: 5 * 60_000,
+  });
+  assert.equal(g.evaluate().gated, true);
+  l1 = 1; t += 60_000;
+  assert.equal(g.evaluate().gated, false, 'below threshold: gated:false immediately, hysteresis notwithstanding');
+});
+
 test('snapshot() reflects the last evaluation and is null before any', () => {
   const { g } = gateWith({});
   assert.equal(g.snapshot(), null);
@@ -157,3 +189,72 @@ test('snapshot() reflects the last evaluation and is null before any', () => {
   assert.equal(typeof s.at, 'string');
   assert.equal('shouldAudit' in s, false, 'per-tick flags are not part of the persisted snapshot');
 });
+
+test('snapshot() exposes gated, ratio, threshold, loadavg1, cores and gatedSinceMs (what buildScheduleStatePayload surfaces as loadGate)', () => {
+  const { g } = gateWith({});
+  g.evaluate();
+  const s = g.snapshot();
+  assert.equal(typeof s.gated, 'boolean');
+  assert.equal(typeof s.ratio, 'number');
+  assert.equal(typeof s.threshold, 'number');
+  assert.equal(typeof s.loadavg1, 'number');
+  assert.equal(typeof s.cores, 'number');
+  assert.equal(typeof s.gatedSinceMs, 'number');
+});
+
+// ─── hysteresis: the real observed boundary-hovering sequence ──────────────
+
+test('a boundary-hovering box (real observed sequence, alternating above/below threshold) grows gatedSinceMs monotonically across 50 simulated minutes and eventually escalates', () => {
+  // 14 cores, 0.85/core = 11.9 threshold; loadavg1 observed 2026-09-12
+  // oscillating 11.07 - 13.31, straddling the threshold every tick. Before
+  // this PRD, the immediate reset on ANY sub-threshold sample meant every
+  // one of these ticks reset gatedSince to null and escalate never fired.
+  const CORES = 14;
+  const THRESHOLD = 0.85;
+  const SEQUENCE = [11.07, 13.31, 11.51, 12.8];
+  let l1 = SEQUENCE[0];
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => CORES,
+    now: () => t,
+    threshold: THRESHOLD,
+    escalateAfterMs: 20 * 60_000, // shorter than the 45m default so 50 sim-minutes crosses it
+  });
+
+  const TICK_MS = 60_000;
+  const TOTAL_MS = 50 * 60_000;
+  let prevGatedSinceMs = -1;
+  let sawEscalate = false;
+  let i = 0;
+  for (let elapsed = 0; elapsed < TOTAL_MS; elapsed += TICK_MS) {
+    l1 = SEQUENCE[i % SEQUENCE.length];
+    i += 1;
+    const r = g.evaluate();
+    assert.ok(r.gatedSinceMs >= prevGatedSinceMs, `gatedSinceMs must not shrink (was ${prevGatedSinceMs}, now ${r.gatedSinceMs})`);
+    prevGatedSinceMs = r.gatedSinceMs;
+    if (r.escalate) sawEscalate = true;
+    t += TICK_MS;
+  }
+  assert.equal(sawEscalate, true, 'escalate must fire once the (never-reset) stretch exceeds escalateAfterMs');
+});
+
+test('the release window actually releases: sustained sub-threshold load past the window reports gated:false and gatedSinceMs:0 on the next tick', () => {
+  let l1 = 13.31;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    releaseWindowMs: 2 * 60_000,
+  });
+  assert.equal(g.evaluate().gated, true);
+  l1 = 5;
+  t += 1;
+  g.evaluate(); // marks the start of the sustained sub-threshold run
+  t += 2 * 60_000;
+  const r = g.evaluate();
+  assert.equal(r.gated, false);
+  assert.equal(r.gatedSinceMs, 0);
+});

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 () => {
@@ -115,6 +113,17 @@ test('with no version change, flush("version-change") does NOT run', async () =>
   expect(flushCalls).toEqual(['boot']);
 });
 
+test('a rejected reportInstall leaves lastMachineReportAt unset so the next boot retries', async () => {
+  const now = Date.now();
+  const { deps, state } = fakeDeps({ settings: { lastMachineReportVersion: '', lastMachineReportAt: null } });
+  deps.telemetryClient.reportInstall = async () => ({ accepted: false, reason: 'error' });
+
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+
+  expect(state().lastMachineReportAt).toBe(null);
+  expect(state().lastMachineReportVersion).toBe('');
+});
+
 test('fires app.launch via telemetryCounters with installChannel + appVersion', async () => {
   const now = Date.now();
   const { deps } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });

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];