claude-code-session-manager 0.84.0 → 0.86.0

package/src/main/__tests__/scheduler-quarantine-autoresolve.test.cjs

@@ -0,0 +1,165 @@
+/**
+ * scheduler-quarantine-autoresolve.test.cjs
+ *
+ * Covers the bounded automatic exit for a quarantined row that never
+ * received a `createdVia` provenance stamp (this PRD): the pure selector
+ * `selectQuarantineAutoResolveTargets`, the async applier
+ * `autoResolveQuarantine` (which re-reads the PRD file's frontmatter fresh
+ * from disk immediately before transitioning, so it can never race
+ * reconcile()'s own adopt path), and the kill switch
+ * `quarantineAutoResolveDisabled`.
+ *
+ * HOME is overridden to a tmp dir BEFORE requiring scheduler.cjs — same
+ * reason as scheduler-failed-autoreset.test.cjs (appendAuditEvent writes
+ * under $HOME/.claude/session-manager/audit-log.jsonl).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-quarantine-autoresolve.test.cjs
+ */
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'quarantine-autoresolve-test-'));
+process.env.HOME = tmpHome;
+
+const {
+  selectQuarantineAutoResolveTargets,
+  autoResolveQuarantine,
+  QUARANTINE_RESOLVE_CAP,
+  quarantineAutoResolveDisabled,
+} = require('../scheduler.cjs');
+
+const MIN_MS = 60_000;
+const THRESHOLD_MS = 60 * MIN_MS;
+
+function quarantinedJob(overrides = {}) {
+  return {
+    slug: 'quarantined-row',
+    cwd: '/home/user/project',
+    status: 'quarantined',
+    statusHistory: [{ to: 'quarantined', at: new Date(Date.now() - 90 * MIN_MS).toISOString() }],
+    ...overrides,
+  };
+}
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', 'test-epic-1', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  return { cwd, prdsDir };
+}
+
+// --- selectQuarantineAutoResolveTargets ---
+
+test('a fresh quarantined row (under threshold) is not selected', () => {
+  const job = quarantinedJob({
+    statusHistory: [{ to: 'quarantined', at: new Date(Date.now() - 2 * MIN_MS).toISOString() }],
+  });
+  assert.equal(selectQuarantineAutoResolveTargets([job], Date.now(), THRESHOLD_MS).length, 0);
+});
+
+test('a non-quarantined status is never selected', () => {
+  const job = quarantinedJob({ status: 'failed' });
+  assert.equal(selectQuarantineAutoResolveTargets([job], Date.now(), THRESHOLD_MS).length, 0);
+});
+
+test('a quarantined row with no statusHistory entry cannot have its age proven, and is skipped', () => {
+  const job = quarantinedJob({ statusHistory: [] });
+  assert.equal(selectQuarantineAutoResolveTargets([job], Date.now(), THRESHOLD_MS).length, 0);
+});
+
+test('a quarantined row past threshold, under the cap, is selected', () => {
+  const job = quarantinedJob({ quarantineResolveAttempts: 0 });
+  const found = selectQuarantineAutoResolveTargets([job], Date.now(), THRESHOLD_MS);
+  assert.equal(found.length, 1);
+  assert.equal(found[0].slug, 'quarantined-row');
+  assert.ok(found[0].ageMs >= 90 * MIN_MS - 1000);
+});
+
+test('a quarantined row that already spent its resolve cap is excluded', () => {
+  const job = quarantinedJob({ quarantineResolveAttempts: QUARANTINE_RESOLVE_CAP });
+  assert.equal(selectQuarantineAutoResolveTargets([job], Date.now(), THRESHOLD_MS).length, 0);
+});
+
+test('quarantineAutoResolveDisabled reflects SM_QUARANTINE_AUTORESOLVE_DISABLE', () => {
+  const saved = process.env.SM_QUARANTINE_AUTORESOLVE_DISABLE;
+  try {
+    delete process.env.SM_QUARANTINE_AUTORESOLVE_DISABLE;
+    assert.equal(quarantineAutoResolveDisabled(), false);
+    process.env.SM_QUARANTINE_AUTORESOLVE_DISABLE = '1';
+    assert.equal(quarantineAutoResolveDisabled(), true);
+  } finally {
+    if (saved === undefined) delete process.env.SM_QUARANTINE_AUTORESOLVE_DISABLE;
+    else process.env.SM_QUARANTINE_AUTORESOLVE_DISABLE = saved;
+  }
+});
+
+// --- autoResolveQuarantine: the applier ---
+
+test('a quarantined row whose PRD file still has no createdVia is auto-resolved to skipped', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-quarantine-autoresolve-noprovenance-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, 'quarantined-row.md'),
+      `---\ntitle: Unstamped PRD\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    const job = quarantinedJob({ cwd, quarantineResolveAttempts: 0 });
+    const outcome = await autoResolveQuarantine(job, 90 * MIN_MS);
+    assert.equal(outcome, 'skipped');
+    assert.equal(job.status, 'skipped');
+    assert.equal(job.quarantineResolveAttempts, 1);
+    assert.ok(typeof job.error === 'string' && /createdVia/.test(job.error));
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('a quarantined row whose PRD file HAS been stamped with createdVia is left alone — reconcile owns it now', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-quarantine-autoresolve-stamped-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, 'quarantined-row.md'),
+      `---\ntitle: Stamped PRD\ncwd: ${cwd}\nestimateMinutes: 15\ncreatedVia: scheduler-api\nissuedAt: 2026-08-07T00:00:00.000Z\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    const job = quarantinedJob({ cwd, quarantineResolveAttempts: 0 });
+    const outcome = await autoResolveQuarantine(job, 90 * MIN_MS);
+    assert.equal(outcome, null);
+    assert.equal(job.status, 'quarantined'); // untouched — the adopt path owns the next pass
+    assert.equal(job.quarantineResolveAttempts, 0);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('autoResolveQuarantine race-guards against a row that moved off quarantined', async () => {
+  const job = quarantinedJob({ status: 'pending', quarantineResolveAttempts: 0 });
+  assert.equal(await autoResolveQuarantine(job, 90 * MIN_MS), null);
+  assert.equal(job.status, 'pending'); // untouched
+});
+
+test('autoResolveQuarantine race-guards against a row whose resolve cap is already spent', async () => {
+  const job = quarantinedJob({ quarantineResolveAttempts: QUARANTINE_RESOLVE_CAP });
+  assert.equal(await autoResolveQuarantine(job, 90 * MIN_MS), null);
+  assert.equal(job.status, 'quarantined'); // untouched
+});
+
+test('a quarantined row whose PRD file is missing entirely is treated as still lacking provenance and auto-resolved', async () => {
+  const job = quarantinedJob({ cwd: '/nonexistent/project/path', quarantineResolveAttempts: 0 });
+  const outcome = await autoResolveQuarantine(job, 90 * MIN_MS);
+  assert.equal(outcome, 'skipped');
+  assert.equal(job.status, 'skipped');
+});

package/src/main/__tests__/scheduler-starve-escalation.test.cjs

@@ -0,0 +1,144 @@
+/**
+ * scheduler-starve-escalation.test.cjs — the `project_starved` audit event
+ * (scheduler.cjs ~line 8888) used to be emit-only: it fired every sweep
+ * forever with zero consequence. The 2026-09-12 audit log showed
+ * /home/bilko/Projects/Bilko emitting it ~115 times over a 19h starve with
+ * nothing acting on it. runStarveEscalationSweep is the bounded, automated
+ * consequence: a starve outliving STARVE_ESCALATION_MS gets a DISTINCT
+ * 'project_starve_escalated' audit event (once per starve stretch, latched
+ * per cwd) plus a toast-channel error via the existing 'schedule:stall'
+ * push (already wired to toast.error on the renderer side).
+ *
+ * Exercises selectStarveEscalations() (pure) directly, and
+ * runStarveEscalationSweep() (the side-effecting wrapper) against a real,
+ * scratch audit-log.jsonl and a fake attached window — matching
+ * queue-starvation-per-project.test.cjs's pattern of setting HOME before
+ * require() since every state path is baked from os.homedir() at load.
+ *
+ * Run: timeout 180 npx vitest run src/main/__tests__/scheduler-starve-escalation.test.cjs
+ */
+
+'use strict';
+
+import { test, beforeEach } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+process.env.HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'starve-escalation-test-'));
+
+const {
+  selectStarveEscalations,
+  runStarveEscalationSweep,
+  STARVE_ESCALATION_MS,
+  attachWindow,
+} = require('../scheduler.cjs');
+const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+
+const CWD_A = '/home/bilko/Projects/Bilko';
+const CWD_B = '/home/bilko/Projects/session-manager';
+
+function readAuditKind(kind) {
+  let lines;
+  try {
+    lines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+  return lines.map((l) => JSON.parse(l)).filter((r) => r.kind === kind);
+}
+
+function fakeWindow() {
+  const sent = [];
+  return {
+    sent,
+    isDestroyed: () => false,
+    webContents: {
+      isDestroyed: () => false,
+      isCrashed: () => false,
+      send: (channel, payload) => sent.push({ channel, payload }),
+    },
+  };
+}
+
+beforeEach(() => {
+  // Fresh scratch audit log per test so escalation counts never bleed across
+  // tests in this file.
+  fs.mkdirSync(path.dirname(AUDIT_LOG_PATH), { recursive: true });
+  fs.writeFileSync(AUDIT_LOG_PATH, '');
+  attachWindow(null);
+});
+
+test('selectStarveEscalations: escalates a row past threshold not already latched', () => {
+  const starved = [{ cwd: CWD_A, pendingCount: 3, oldestPendingSlug: 'x', ageMs: STARVE_ESCALATION_MS + 1 }];
+  const { toEscalate, toClear } = selectStarveEscalations(starved, new Set(), STARVE_ESCALATION_MS);
+  assert.equal(toEscalate.length, 1);
+  assert.equal(toEscalate[0].cwd, CWD_A);
+  assert.deepEqual(toClear, []);
+});
+
+test('selectStarveEscalations: never re-escalates a cwd already latched', () => {
+  const starved = [{ cwd: CWD_A, pendingCount: 3, oldestPendingSlug: 'x', ageMs: STARVE_ESCALATION_MS + 60_000 }];
+  const { toEscalate } = selectStarveEscalations(starved, new Set([CWD_A]), STARVE_ESCALATION_MS);
+  assert.deepEqual(toEscalate, []);
+});
+
+test('selectStarveEscalations: a latched cwd no longer starved is returned for latch-clear', () => {
+  const { toEscalate, toClear } = selectStarveEscalations([], new Set([CWD_A]), STARVE_ESCALATION_MS);
+  assert.deepEqual(toEscalate, []);
+  assert.deepEqual(toClear, [CWD_A]);
+});
+
+test('selectStarveEscalations: below-threshold starve is neither escalated nor cleared', () => {
+  const starved = [{ cwd: CWD_A, pendingCount: 1, oldestPendingSlug: 'x', ageMs: STARVE_ESCALATION_MS - 1 }];
+  const { toEscalate, toClear } = selectStarveEscalations(starved, new Set(), STARVE_ESCALATION_MS);
+  assert.deepEqual(toEscalate, []);
+  assert.deepEqual(toClear, []);
+});
+
+test('runStarveEscalationSweep: emits project_starve_escalated exactly once per starve stretch, plus a toast', () => {
+  const win = fakeWindow();
+  attachWindow(win);
+  const sp = { cwd: CWD_A, pendingCount: 4, oldestPendingSlug: 'oldest-a', ageMs: STARVE_ESCALATION_MS + 60_000 };
+
+  runStarveEscalationSweep([sp]);
+  assert.equal(readAuditKind('project_starve_escalated').length, 1);
+  assert.equal(win.sent.length, 1);
+  assert.equal(win.sent[0].channel, 'schedule:stall');
+  assert.match(win.sent[0].payload.message, /Bilko/);
+
+  const record = readAuditKind('project_starve_escalated')[0];
+  assert.equal(record.cwd, CWD_A);
+  assert.equal(record.pendingCount, 4);
+  assert.equal(record.oldestPendingSlug, 'oldest-a');
+  assert.equal(record.ageMs, sp.ageMs);
+  assert.ok(
+    ['slots-exhausted', 'memory-deferred', 'load-deferred', 'held', 'unknown'].includes(record.holdReason),
+    `unexpected holdReason: ${record.holdReason}`,
+  );
+
+  // Same still-starved stretch on the NEXT sweep must not escalate again.
+  runStarveEscalationSweep([sp]);
+  assert.equal(readAuditKind('project_starve_escalated').length, 1);
+  assert.equal(win.sent.length, 1);
+});
+
+test('runStarveEscalationSweep: the latch resets once the starve clears, so a later stretch escalates again', () => {
+  const win = fakeWindow();
+  attachWindow(win);
+  const sp = { cwd: CWD_B, pendingCount: 2, oldestPendingSlug: 'oldest-b', ageMs: STARVE_ESCALATION_MS + 1 };
+
+  runStarveEscalationSweep([sp]);
+  assert.equal(readAuditKind('project_starve_escalated').length, 1);
+
+  // Starve clears: this cwd is no longer reported by findStarvedProjects at all.
+  runStarveEscalationSweep([]);
+  assert.equal(readAuditKind('project_starve_escalated').length, 1); // no new escalation on a clear pass
+
+  // A NEW starve stretch on the same cwd must escalate again — the latch
+  // must not have been permanently burned by the first stretch.
+  runStarveEscalationSweep([sp]);
+  assert.equal(readAuditKind('project_starve_escalated').length, 2);
+  assert.equal(win.sent.length, 2);
+});

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

@@ -17,12 +17,14 @@ let originalHome;
 let originalSmTelemetry;
 let originalSmTelemetryEndpoint;
 let originalSmBeaconKey;
+let originalSmTelemetrySpool;
 
 beforeEach(() => {
   originalHome = process.env.HOME;
   originalSmTelemetry = process.env.SM_TELEMETRY;
   originalSmTelemetryEndpoint = process.env.SM_TELEMETRY_ENDPOINT;
   originalSmBeaconKey = process.env.SM_BEACON_KEY;
+  originalSmTelemetrySpool = process.env.SM_TELEMETRY_SPOOL;
 });
 
 afterEach(async () => {
@@ -30,6 +32,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();
   vi.unstubAllGlobals();
   while (tmpDirs.length) {
@@ -51,6 +54,13 @@ function fakeProfile(overrides = {}) {
     arch: 'x64',
     machineDigest: 'deadbeefcafe',
     installChannel: 'dev',
+    osRelease: '6.1.0',
+    cpuCount: 8,
+    totalMemMb: 16384,
+    nodeVersion: '20.11.0',
+    electronVersion: '33.0.0',
+    locale: 'en-US',
+    timezoneOffsetMinutes: 420,
     ...overrides,
   };
 }
@@ -65,6 +75,11 @@ function fakeProfile(overrides = {}) {
  */
 function freshClient(home, profileOverrides) {
   process.env.HOME = home;
+  // Explicit opt-in: this suite deliberately exercises telemetryClient's real
+  // queue/sent-file I/O, so it must override the test-environment no-op guard
+  // by pointing the spool at this test's own isolated tmp dir (never a real
+  // user's ~/.config/session-manager).
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
   for (const p of ['../lib/telemetryClient.cjs', '../config.cjs', '../lib/telemetrySettings.cjs', '../lib/machineProfile.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];
@@ -110,7 +125,7 @@ async function readQueueLines(client) {
 test('exports the full contract', async () => {
   const home = await mkHome();
   const client = freshClient(home);
-  for (const fn of ['track', 'logLine', 'reportError', 'flush', 'shutdown', 'status', 'recentRecords', 'isPending']) {
+  for (const fn of ['track', 'logLine', 'reportError', 'reportInstall', 'flush', 'shutdown', 'status', 'recentRecords', 'isPending']) {
     expect(typeof client[fn]).toBe('function');
   }
   client.shutdown();
@@ -130,10 +145,31 @@ test('ingress functions never throw on hostile inputs', async () => {
     await expect(client.track(bad, bad)).resolves.toBeDefined();
     await expect(client.logLine(bad)).resolves.toBeDefined();
     await expect(client.reportError(bad)).resolves.toBeDefined();
+    await expect(client.reportInstall(bad)).resolves.toBeDefined();
   }
   client.shutdown();
 });
 
+// ─── reportInstall failure visibility ──────────────────────────────────
+
+test('reportInstall logs a warn line naming the thrown error instead of swallowing it silently', async () => {
+  const home = await mkHome();
+  const client = freshClient(home);
+  client._setMachineProfileBuilder(() => { throw new Error('boom-profile'); });
+  const warnLines = [];
+  client._setLogger((payload) => warnLines.push(payload));
+
+  const result = await client.reportInstall(fakeProfile());
+
+  expect(result).toEqual({ accepted: false, reason: 'error' });
+  expect(warnLines).toHaveLength(1);
+  expect(warnLines[0].scope).toBe('telemetry');
+  expect(warnLines[0].level).toBe('warn');
+  expect(warnLines[0].message).toBe('reportInstall failed');
+  expect(warnLines[0].meta.error).toContain('boom-profile');
+  client.shutdown();
+});
+
 // ─── disabled at ingress ───────────────────────────────────────────────
 
 test('when telemetry is disabled, ingress drops at the point of entry', async () => {
@@ -146,6 +182,7 @@ test('when telemetry is disabled, ingress drops at the point of entry', async ()
   await client.track('evt', { a: 1 });
   await client.logLine({ level: 'info', msg: 'hi' });
   await client.reportError({ name: 'E', msg: 'boom', stack: 'at x' });
+  await client.reportInstall(fakeProfile());
 
   expect(client.status().pendingCount).toBe(0);
   expect(await readQueueLines(client)).toEqual([]);
@@ -252,6 +289,55 @@ test('attribution fields are exempt from redaction/clamping and arrive byte-iden
   client.shutdown();
 });
 
+// ─── env discriminator (wire-level, all four channels) ─────────────────
+
+test('every channel carries env:"dev" when SM_DEV drives installChannel, and it survives the queue round-trip through flush', async () => {
+  const home = await mkHome();
+  const client = freshClient(home, { installChannel: 'dev' });
+  const fetchFn = fetchStub(async () => okResponse());
+  client._setFetchImpl(fetchFn);
+
+  await client.track('evt', { a: 1 });
+  await client.logLine({ level: 'info', msg: 'hi' });
+  await client.reportError({ name: 'E', msg: 'boom', stack: 'at x' });
+  await client.reportInstall(fakeProfile({ installChannel: 'dev' }));
+
+  // Present the instant it's appended to telemetry-queue.jsonl, before any flush.
+  const queued = await readQueueLines(client);
+  expect(queued).toHaveLength(4);
+  for (const rec of queued) expect(rec.wire.env).toBe('dev');
+
+  // Still present in the exact body flush() POSTs.
+  await client.flush('manual');
+  expect(fetchFn.calls.length).toBeGreaterThan(0);
+  for (const call of fetchFn.calls) {
+    const bodies = Array.isArray(call.body.batch) ? call.body.batch : [call.body];
+    for (const wire of bodies) expect(wire.env).toBe('dev');
+  }
+  client.shutdown();
+});
+
+test('every channel carries env:"prod" for a non-dev installChannel', async () => {
+  const home = await mkHome();
+  const client = freshClient(home, { installChannel: 'npx' });
+
+  await client.track('evt', { a: 1 });
+  await client.logLine({ level: 'info', msg: 'hi' });
+  await client.reportError({ name: 'E', msg: 'boom', stack: 'at x' });
+  await client.reportInstall(fakeProfile({ installChannel: 'npx' }));
+
+  const queued = await readQueueLines(client);
+  expect(queued).toHaveLength(4);
+  for (const rec of queued) expect(rec.wire.env).toBe('prod');
+  client.shutdown();
+});
+
+test('env resolves to "test" under a real test-runner environment, independent of installChannel', () => {
+  const machineProfile = require('../lib/machineProfile.cjs');
+  expect(machineProfile.resolveEnv({ isTestRunner: true, installChannel: 'dev' })).toBe('test');
+  expect(machineProfile.resolveEnv({ isTestRunner: true, installChannel: 'npx' })).toBe('test');
+});
+
 // ─── queue is the accumulator, survives restart ────────────────────────
 
 test('a record survives a simulated process restart and is still pending', async () => {
@@ -504,6 +590,7 @@ test('wire field names match server/routes/telemetry.ts exactly', async () => {
   await client.track('evt-name', { a: 1 });
   await client.logLine({ level: 'warn', msg: 'm', fields: { b: 2 } });
   await client.reportError({ name: 'E', msg: 'm', stack: 'Error: m\n    at f (a.js:1:1)', context: { c: 3 } });
+  await client.reportInstall(fakeProfile());
 
   const fetchFn = fetchStub(async () => okResponse());
   client._setFetchImpl(fetchFn);
@@ -512,10 +599,16 @@ test('wire field names match server/routes/telemetry.ts exactly', async () => {
   const eventCall = fetchFn.calls.find((c) => c.url.endsWith('/event'));
   const logCall = fetchFn.calls.find((c) => c.url.endsWith('/log'));
   const errorCall = fetchFn.calls.find((c) => c.url.endsWith('/error'));
-
-  expect(Object.keys(eventCall.body.batch[0]).sort()).toEqual(['app', 'name', 'props', 'session_id', 'visitor_id'].sort());
-  expect(Object.keys(logCall.body.batch[0]).sort()).toEqual(['app', 'version', 'level', 'msg', 'visitor_id', 'session_id', 'fields', 'ts'].sort());
-  expect(Object.keys(errorCall.body.batch[0]).sort()).toEqual(['app', 'version', 'name', 'msg', 'stack', 'url', 'ua', 'visitor_id', 'session_id', 'context', 'ts'].sort());
+  const installCall = fetchFn.calls.find((c) => c.url.endsWith('/install'));
+
+  expect(Object.keys(eventCall.body.batch[0]).sort()).toEqual(['app', 'env', 'name', 'props', 'session_id', 'visitor_id'].sort());
+  expect(Object.keys(logCall.body.batch[0]).sort()).toEqual(['app', 'env', 'version', 'level', 'msg', 'visitor_id', 'session_id', 'fields', 'ts'].sort());
+  expect(Object.keys(errorCall.body.batch[0]).sort()).toEqual(['app', 'env', 'version', 'name', 'msg', 'stack', 'url', 'ua', 'visitor_id', 'session_id', 'context', 'ts'].sort());
+  expect(Object.keys(installCall.body).sort()).toEqual([
+    'app', 'app_version', 'arch', 'cpu_count', 'electron_version', 'env',
+    'install_channel', 'install_id', 'locale', 'node_version',
+    'os_release', 'platform', 'timezone', 'total_mem_mb',
+  ].sort());
   client.shutdown();
 });
 
@@ -778,6 +871,31 @@ test('status() reports a network error (fetch throw / status 0) with a plain-lan
   client.shutdown();
 });
 
+// ─── test-environment guard (poisoned-spool prevention) ─────────────────
+
+test('appendRecord() is a no-op under a test runner unless SM_TELEMETRY_SPOOL is explicitly set', async () => {
+  const home = await mkHome();
+  process.env.HOME = home;
+  delete process.env.SM_TELEMETRY_SPOOL;
+  for (const p of ['../lib/telemetryClient.cjs', '../config.cjs', '../lib/telemetrySettings.cjs', '../lib/machineProfile.cjs']) {
+    delete require.cache[require.resolve(p)];
+  }
+  const client = require('../lib/telemetryClient.cjs');
+  client._setMachineProfileBuilder(async () => fakeProfile());
+
+  expect(process.env.VITEST).toBeTruthy();
+  const trackResult = await client.track('evt', { a: 1 });
+  const logResult = await client.logLine({ level: 'info', msg: 'hi' });
+  const errorResult = await client.reportError({ name: 'E', msg: 'boom', stack: 'at x' });
+
+  expect(trackResult).toEqual({ accepted: false, reason: 'test-environment', recordId: expect.any(String) });
+  expect(logResult.accepted).toBe(false);
+  expect(errorResult.accepted).toBe(false);
+  expect(client.status().pendingCount).toBe(0);
+  await expect(fsp.access(client.queuePath())).rejects.toThrow();
+  client.shutdown();
+});
+
 // ─── clearQueue (opt-out side effect, PRD 1142) ──────────────────────────
 
 test('clearQueue() empties the in-memory queue and truncates the on-disk queue file', async () => {
@@ -794,6 +912,133 @@ test('clearQueue() empties the in-memory queue and truncates the on-disk queue f
   client.shutdown();
 });
 
+// ─── install channel (PRD: bilko.run app_installs) ──────────────────────
+
+test('reportInstall() maps buildMachineProfile()\'s camelCase onto the exact snake_case key set app_installs expects', async () => {
+  const home = await mkHome();
+  const client = freshClient(home);
+  const profile = fakeProfile();
+  await client.reportInstall(profile);
+  const [rec] = await readQueueLines(client);
+
+  expect(rec.channel).toBe('install');
+  expect(Object.keys(rec.wire).sort()).toEqual([
+    'app', 'app_version', 'arch', 'cpu_count', 'electron_version', 'env',
+    'install_channel', 'install_id', 'locale', 'node_version',
+    'os_release', 'platform', 'timezone', 'total_mem_mb',
+  ].sort());
+  expect(rec.wire.app).toBe('session-manager');
+  expect(rec.wire.app_version).toBe(profile.appVersion);
+  expect(rec.wire.platform).toBe(profile.platform);
+  expect(rec.wire.os_release).toBe(profile.osRelease);
+  expect(rec.wire.arch).toBe(profile.arch);
+  expect(rec.wire.cpu_count).toBe(profile.cpuCount);
+  expect(rec.wire.total_mem_mb).toBe(profile.totalMemMb);
+  expect(rec.wire.node_version).toBe(profile.nodeVersion);
+  expect(rec.wire.electron_version).toBe(profile.electronVersion);
+  expect(rec.wire.install_channel).toBe(profile.installChannel);
+  expect(rec.wire.locale).toBe(profile.locale);
+  expect(rec.wire.timezone).toBe(String(profile.timezoneOffsetMinutes));
+  expect(typeof rec.wire.install_id).toBe('string');
+  expect(rec.wire.install_id).toBeTruthy();
+  client.shutdown();
+});
+
+test('the install channel POSTs a flat body, never a {batch:[...]} envelope', async () => {
+  const home = await mkHome();
+  const client = freshClient(home);
+  await client.reportInstall(fakeProfile());
+  const fetchFn = fetchStub(async () => okResponse());
+  client._setFetchImpl(fetchFn);
+  const result = await client.flush('manual');
+
+  expect(result.sent.length).toBe(1);
+  expect(fetchFn).toHaveBeenCalledTimes(1);
+  expect(fetchFn.calls[0].url.endsWith('/api/telemetry/install')).toBe(true);
+  expect(fetchFn.calls[0].body.batch).toBeUndefined();
+  expect(fetchFn.calls[0].body.install_id).toBeTruthy();
+  client.shutdown();
+});
+
+test('a 400 on the install channel disables the client like any other malformed-contract 4xx', async () => {
+  const home = await mkHome();
+  const client = freshClient(home);
+  await client.reportInstall(fakeProfile());
+  client._setFetchImpl(fetchStub(async () => statusResponse(400)));
+  await client.flush('manual');
+  const st = client.status();
+  expect(st.disabledForProcess).toBe(true);
+  expect(st.pendingCount).toBe(1);
+  client.shutdown();
+});
+
+test('a 429 on the install channel backs off rather than disabling, same as event/log/error', async () => {
+  const home = await mkHome();
+  const client = freshClient(home);
+  await client.reportInstall(fakeProfile());
+  client._setFetchImpl(fetchStub(async () => statusResponse(429)));
+  await client.flush('manual');
+  const st = client.status();
+  expect(st.disabledForProcess).toBe(false);
+  expect(st.backoffUntil).toBeGreaterThan(Date.now() - 1);
+  expect(st.pendingCount).toBe(1);
+  client.shutdown();
+});
+
+test('a stub server bound to 127.0.0.1 receives exactly one well-formed install POST during a simulated boot', async () => {
+  const http = require('node:http');
+  const home = await mkHome();
+  let received = null;
+  let requestCount = 0;
+  const server = http.createServer((req, res) => {
+    if (req.url === '/api/telemetry/install') {
+      requestCount += 1;
+      let raw = '';
+      req.on('data', (chunk) => { raw += chunk; });
+      req.on('end', () => {
+        received = JSON.parse(raw);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+      });
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  process.env.SM_TELEMETRY_ENDPOINT = `http://127.0.0.1:${port}`;
+
+  try {
+    const client = freshClient(home);
+    // No _setFetchImpl — exercises the real global fetch path against the local stub.
+    const profile = fakeProfile();
+    await client.reportInstall(profile);
+    await client.flush('boot');
+
+    expect(requestCount).toBe(1);
+    expect(received).toEqual({
+      install_id: expect.any(String),
+      app: 'session-manager',
+      app_version: profile.appVersion,
+      platform: profile.platform,
+      os_release: profile.osRelease,
+      arch: profile.arch,
+      cpu_count: profile.cpuCount,
+      total_mem_mb: profile.totalMemMb,
+      node_version: profile.nodeVersion,
+      electron_version: profile.electronVersion,
+      install_channel: profile.installChannel,
+      locale: profile.locale,
+      timezone: String(profile.timezoneOffsetMinutes),
+      env: 'dev',
+    });
+    client.shutdown();
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}, 15000);
+
 test('clearQueue() never touches telemetry-sent.json', async () => {
   const home = await mkHome();
   const client = freshClient(home);