claude-code-session-manager 0.84.0 → 0.86.0

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

@@ -32,6 +32,15 @@ const { loadGateThreshold, JOB_OVERRUN_FLOOR_MS } = require('./schedulerConfig.c
 // every tick would bury the signal in its own noise.
 const AUDIT_INTERVAL_MS = 10 * 60_000;
 
+// Default hysteresis release window for the gated stretch (PRD: boundary-
+// hovering load). A box sitting right at the threshold oscillates above/below
+// it tick to tick; clearing `gatedSince` on the first sub-threshold sample
+// reset the stretch counter every time, so `escalate` (and the warn-log with
+// topCpuConsumers()) never fired even after 80+ minutes of effectively
+// continuous gating. The stretch now only clears once load has stayed below
+// threshold continuously for this long.
+const RELEASE_WINDOW_MS = 2 * 60_000;
+
 /**
  * isLoadGated(loadavg1, cores, threshold) → boolean
  *
@@ -82,9 +91,11 @@ function createLoadGate({
   threshold = loadGateThreshold,
   auditIntervalMs = AUDIT_INTERVAL_MS,
   escalateAfterMs = JOB_OVERRUN_FLOOR_MS,
+  releaseWindowMs = RELEASE_WINDOW_MS,
 } = {}) {
   let lastAuditAt = null; // null = never audited; the first gated tick always audits
   let gatedSince = null;
+  let belowSince = null; // start of the current continuous sub-threshold run, while a stretch is open
   let last = null;
 
   function evaluate({ bypass = false } = {}) {
@@ -95,10 +106,21 @@ function createLoadGate({
     const ratio = c > 0 && Number.isFinite(l1) ? l1 / c : 0;
     const wouldGate = isLoadGated(l1, c, th);
 
+    // Hysteresis: the STRETCH (gatedSince) only clears after load has stayed
+    // below threshold continuously for releaseWindowMs. This never affects
+    // `gated` itself below — a sub-threshold tick still returns gated:false
+    // immediately; only the bookkeeping/escalation lags behind.
     if (wouldGate) {
       if (gatedSince === null) gatedSince = t;
+      belowSince = null;
+    } else if (gatedSince !== null) {
+      if (belowSince === null) belowSince = t;
+      if (t - belowSince >= releaseWindowMs) {
+        gatedSince = null;
+        belowSince = null;
+      }
     } else {
-      gatedSince = null;
+      belowSince = null;
     }
     const gated = wouldGate && !bypass;
     const bypassed = wouldGate && bypass;

package/src/main/lib/machineProfile.cjs

@@ -51,6 +51,20 @@ function resolveInstallChannel({ appPath = null, devFlag = !!process.env.SM_DEV
   return 'unknown';
 }
 
+/**
+ * Resolves the wire-level `env` discriminator ('prod' | 'dev' | 'test') from
+ * the real signals the caller already has — never inferred downstream from
+ * an appVersion string, which is how 1,526 pre-release/test `epic.create`
+ * records ended up misread as production usage (see telemetry.md). `test`
+ * takes priority: a vitest run that happens to report a `dev` installChannel
+ * (SM_DEV set in the test env) is still test traffic, not dev usage.
+ */
+function resolveEnv({ isTestRunner = false, installChannel } = {}) {
+  if (isTestRunner) return 'test';
+  if (installChannel === 'dev') return 'dev';
+  return 'prod';
+}
+
 /** sha256 of the concatenated stable spec fields, truncated to 12 hex chars. */
 function computeMachineDigest(specs) {
   const material = [
@@ -141,4 +155,5 @@ module.exports = {
   buildMachineProfile,
   computeMachineDigest,
   resolveInstallChannel,
+  resolveEnv,
 };

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/schedulerBatch.cjs

@@ -102,9 +102,20 @@ function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
     }
     return satisfiedBareSlugs.has(bareSlug(slug));
   };
+  // A dep row is blocking unless it's 'completed', OR it's a 'skipped' row
+  // stamped `needsReviewAutoResolvedSkip` — the bounded needs_review
+  // auto-resolve terminal decision (scheduler.cjs's
+  // applyNeedsReviewAutoResolve). That skip is deliberately NOT the
+  // "PRD source vanished, a human must author a fresh PRD" skip the
+  // heldBySkippedDep messaging above describes — it already got every
+  // bounded chance to resolve itself, so treating it as a permanent
+  // dependsOn block would defeat the whole point of that auto-resolve pass
+  // (a chain that never drains without an operator).
+  const isSatisfiedRow = (dep) => dep.status === 'completed'
+    || (dep.status === 'skipped' && dep.needsReviewAutoResolvedSkip === true);
   return (job.dependsOn ?? []).find((slug) => {
     const rows = rowsForDep(slug);
-    if (rows.length > 0) return rows.some((dep) => dep.status !== 'completed');
+    if (rows.length > 0) return rows.some((dep) => !isSatisfiedRow(dep));
     return !isKnownSatisfied(slug);
   });
 }

package/src/main/lib/schedulerConfig.cjs

@@ -81,6 +81,19 @@ module.exports = {
   // 1086). Escalation only — warn + audit, never dispatch.
   STARVATION_ESCALATE_MS: 45 * 60_000,
 
+  // A project still meeting findStarvedProjects' STARVED verdict past THIS
+  // (later) threshold gets a bounded, automated consequence beyond the
+  // repeating project_starved WARN above: a one-shot 'project_starve_escalated'
+  // audit event + a user-facing toast naming the project and the last tick's
+  // hold reason (scheduler.cjs's `lastTick`). Escalation only — never
+  // auto-resets, auto-cancels, or bypasses a gate; the queue's own state is
+  // untouched. The 2026-09-12 audit log showed /home/bilko/Projects/Bilko
+  // emit project_starved for 19h straight (ageMs 60.5M → 68.9M) with zero
+  // consequence and no toast — this is the fix. Latched per-cwd so the SAME
+  // starve stretch escalates exactly once; the latch resets the moment that
+  // cwd stops appearing in findStarvedProjects.
+  STARVE_ESCALATION_MS: 60 * 60_000,
+
   // A RUNNING job that has overrun its own PRD's `estimateMinutes` by this
   // factor is escalated. Distinct from MAX_JOB_DURATION_MS (4h), which is a
   // deadman kill: a 20-minute PRD still running at 3h is 9x over estimate but

package/src/main/lib/telemetryBoot.cjs

@@ -36,10 +36,17 @@ 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
- *     persisted so a same-version reboot within the window sends nothing.
+ *  3. install upsert — sent once via telemetryClient.reportInstall(profile)
+ *     when telemetrySettings.isMachineReportDue() is true (a version bump, OR
+ *     the 30-day liveness heartbeat). lastMachineReportAt/Version are only
+ *     persisted when reportInstall() reports success — a failed/dropped
+ *     upsert stays due so the next boot retries, rather than being marked
+ *     done regardless of outcome.
+ *     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,12 +64,13 @@ 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 telemetrySettings.save({
-      ...settings,
-      lastMachineReportAt: new Date(now).toISOString(),
-      lastMachineReportVersion: appVersion,
-    });
+    const reportResult = await telemetryClient.reportInstall(profile);
+    if (reportResult && reportResult.accepted) {
+      await telemetrySettings.save({
+        lastMachineReportAt: new Date(now).toISOString(),
+        lastMachineReportVersion: appVersion,
+      });
+    }
   }
 
   telemetryCounters.trackAppLaunch({ installChannel, appVersion });

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
@@ -86,20 +91,73 @@ const S = {
   lastError: null,
   lastFlushAt: null,
   lastFlushReason: null,
+  logger: null,
 };
 
+/**
+ * Best-effort warn logger for failures this module would otherwise swallow
+ * (e.g. reportInstall()'s bare catch). Lazily requires logs.cjs — which
+ * requires('electron') at module scope — so this stays a no-op under plain
+ * vitest with no Electron runtime, exactly like machineProfile.cjs's
+ * resolveElectronApp(). Injectable via _setLogger so tests can observe it
+ * without an Electron runtime.
+ */
+function logWarn(message, meta) {
+  try {
+    const fn = S.logger || require('../logs.cjs').writeLine;
+    fn({ scope: 'telemetry', level: 'warn', message, meta });
+  } catch { /* logs unavailable outside an Electron runtime */ }
+}
+
+/**
+ * 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() {
   return process.env.SM_BEACON_KEY || FALLBACK_BEACON_KEY;
 }
 
+/**
+ * The wire-level `env` discriminator for the currently-running process,
+ * resolved from real signals (never from an appVersion string — see
+ * machineProfile.cjs's resolveEnv header comment for why that matters).
+ */
+function currentEnv() {
+  return machineProfile.resolveEnv({
+    isTestRunner: isTestEnvironment(),
+    installChannel: S.profile && S.profile.installChannel,
+  });
+}
+
 // ─── safe coercion helpers (never throw, regardless of input shape) ───────
 
 function safeObj(v) {
@@ -368,6 +426,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 };
@@ -403,6 +464,7 @@ async function track(name, props) {
       props: meta,
       session_id: S.sessionId,
       visitor_id: S.settings.installId,
+      env: currentEnv(),
     };
     return await appendRecord('event', wire, recordId);
   } catch {
@@ -432,6 +494,7 @@ async function logLine(opts) {
       session_id: S.sessionId,
       fields: meta,
       ts: Date.now(),
+      env: currentEnv(),
     };
     return await appendRecord('log', wire, recordId);
   } catch {
@@ -468,6 +531,7 @@ async function reportError(opts) {
       session_id: S.sessionId,
       context: meta,
       ts: Date.now(),
+      env: currentEnv(),
     };
     return await appendRecord('error', wire, recordId);
   } catch {
@@ -475,6 +539,53 @@ 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),
+    // Resolved from this passed-in profile's own installChannel (never
+    // S.profile — reportInstall() is always given a freshly-built profile,
+    // not the module-singleton one) plus the current process's test-runner
+    // signal, same three-value contract as the other three channels.
+    env: machineProfile.resolveEnv({ isTestRunner: isTestEnvironment(), installChannel: p.installChannel }),
+  };
+}
+
+/**
+ * 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 (e) {
+    logWarn('reportInstall failed', { error: e && e.message ? e.message : String(e) });
+    return { accepted: false, reason: 'error' };
+  }
+}
+
 // ─── egress ────────────────────────────────────────────────────────────
 
 async function sendBatch(channel, wireBatch) {
@@ -496,6 +607,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 +668,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));
@@ -571,7 +721,7 @@ async function flushImpl(reason) {
     await persistSent();
 
     if (safeReason === 'daily' && result.failed.length === 0) {
-      S.settings = await telemetrySettings.save({ ...S.settings, lastDailyFlushAt: new Date().toISOString() });
+      S.settings = await telemetrySettings.save({ lastDailyFlushAt: new Date().toISOString() });
     }
   } catch { /* fail-inert */ }
   S.lastFlushAt = Date.now();
@@ -636,10 +786,15 @@ function _setMachineProfileBuilder(fn) {
   S.profileBuilder = typeof fn === 'function' ? fn : machineProfile.buildMachineProfile;
 }
 
+function _setLogger(fn) {
+  S.logger = typeof fn === 'function' ? fn : null;
+}
+
 module.exports = {
   track,
   logLine,
   reportError,
+  reportInstall,
   flush,
   shutdown,
   status,
@@ -650,4 +805,5 @@ module.exports = {
   sentPath,
   _setFetchImpl,
   _setMachineProfileBuilder,
+  _setLogger,
 };

package/src/main/lib/telemetrySettings.cjs

@@ -78,11 +78,28 @@ function normalize(cfg) {
   };
 }
 
+/**
+ * Persists `patch` merged onto a FRESHLY-READ copy of the on-disk config —
+ * never onto a caller-held snapshot. Two independent modules (telemetryBoot's
+ * install-report stamp, telemetryClient's own daily-flush stamp) each keep
+ * their own in-memory copy of settings loaded at different times; if save()
+ * blindly wrote a caller's full snapshot, whichever call landed last would
+ * silently revert every field the OTHER caller had just written (a lost
+ * update — the root cause behind lastMachineReportAt never sticking). Calls
+ * are still serialized through the existing writeQueue chain, so the fresh
+ * read for call N+1 always observes call N's write.
+ */
 let writeQueue = Promise.resolve();
-async function save(cfg) {
-  if (!isValid(cfg)) throw new Error('Invalid telemetry config');
-  const next = normalize(cfg);
+async function save(patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('Invalid telemetry config');
+  for (const k of Object.keys(patch)) {
+    if (!KNOWN_KEYS.has(k)) throw new Error('Invalid telemetry config');
+  }
   const run = async () => {
+    const current = await readRaw();
+    const merged = { ...current, ...patch };
+    if (!isValid(merged)) throw new Error('Invalid telemetry config');
+    const next = normalize(merged);
     await config.writeTextAtomic(storePath(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
     return next;
   };

package/src/main/pty.cjs

@@ -109,6 +109,15 @@ class PtyManager {
     // renderer will re-register its data/exit listeners on the same IPC
     // channels. The data stream is live; pre-reattach output is lost, which
     // is acceptable for a dev reload.
+    //
+    // Telemetry: this branch deliberately does NOT call
+    // telemetryCounters.trackSessionOpen() (see below, after the real spawn).
+    // Tab = claudeSessionId is a 1:1 mapping (CLAUDE.md domain model) — a
+    // reattach is the SAME session process still running, not a new one, so
+    // counting it here would double-count every renderer reload and every
+    // switch back to an already-open Epic's Terminal pane within the same
+    // Electron process. `session.open` counts fresh PTY spawns only; see
+    // telemetry.md for the full rationale and its trade-off.
     const existing = this.sessions.get(tabId);
     if (existing) {
       console.log('[pty] reattach to existing session tabId=', tabId, 'pid=', existing.proc.pid);