claude-code-session-manager 0.85.0 → 0.86.0

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

@@ -150,6 +150,26 @@ test('ingress functions never throw on hostile inputs', async () => {
   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 () => {
@@ -269,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 () => {
@@ -532,11 +601,11 @@ test('wire field names match server/routes/telemetry.ts exactly', async () => {
   const errorCall = fetchFn.calls.find((c) => c.url.endsWith('/error'));
   const installCall = fetchFn.calls.find((c) => c.url.endsWith('/install'));
 
-  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());
+  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',
+    'app', 'app_version', 'arch', 'cpu_count', 'electron_version', 'env',
     'install_channel', 'install_id', 'locale', 'node_version',
     'os_release', 'platform', 'timezone', 'total_mem_mb',
   ].sort());
@@ -854,7 +923,7 @@ test('reportInstall() maps buildMachineProfile()\'s camelCase onto the exact sna
 
   expect(rec.channel).toBe('install');
   expect(Object.keys(rec.wire).sort()).toEqual([
-    'app', 'app_version', 'arch', 'cpu_count', 'electron_version',
+    'app', 'app_version', 'arch', 'cpu_count', 'electron_version', 'env',
     'install_channel', 'install_id', 'locale', 'node_version',
     'os_release', 'platform', 'timezone', 'total_mem_mb',
   ].sort());
@@ -962,6 +1031,7 @@ test('a stub server bound to 127.0.0.1 receives exactly one well-formed install
       install_channel: profile.installChannel,
       locale: profile.locale,
       timezone: String(profile.timezoneOffsetMinutes),
+      env: 'dev',
     });
     client.shutdown();
   } finally {

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

@@ -113,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/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/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);
   });
 }