claude-code-session-manager 0.94.0 → 0.96.0

package/src/main/lib/epicWorktreeProjectConfig.cjs

@@ -2,21 +2,30 @@
 
 /**
  * epicWorktreeProjectConfig.cjs — per-project UI toggle for Epic worktree
- * isolation (PRD 1035, final link of the epic-worktree-isolation chain).
+ * isolation (PRD 1035, final link of the epic-worktree-isolation chain;
+ * moved off the machine-wide global map onto the per-project ops root by
+ * PRD 1390).
  *
  * `SM_EPIC_WORKTREE_DISABLE` (gitWorktree.cjs) is an env var, checked once at
  * process start — there was previously no way to turn the feature off for
  * one project from the app itself. This module is that per-project knob:
- * a single JSON file mapping project cwd -> disabled, read by
+ * `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json`
+ * holding `{ disabled: boolean }` for that one project, read by
  * gitWorktree.cjs's `isWorktreeDisabled('epic', cwd)` on every worktree
  * creation attempt, and read/written by Settings.tsx's per-project toggle
  * over the two IPC handlers registered below.
  *
- * Lives under `~/.claude/session-manager/` — machine-runtime bookkeeping,
- * the same tier as scheduler-machine.json (see queueStore.cjs's header
- * comment) — NOT under any project's `session-manager-operations/`, so the
- * single-writer OWNERS law (opsOwnership.cjs) doesn't apply here; this file
- * only ever has one writer (this module) by construction.
+ * By shape the old single global file (`{ "<project-cwd>": true|false }` under
+ * `~/.claude/session-manager/`) was per-project config keyed by project path —
+ * the wrong tier. It now lives in the `prompt-sessions` ops namespace, already
+ * owned by writer 'epics' (opsOwnership.cjs), the same as every other Epic
+ * record. Migration is lossless and one-shot: on first read for a cwd whose
+ * new per-project file doesn't exist yet, the legacy global map is checked for
+ * that cwd's key; if present (the map only ever stores `true` — `false` is
+ * represented by key absence), the new file is seeded with it. The legacy file
+ * itself is left in place — untouched, never deleted — so any OTHER project's
+ * still-unmigrated key keeps resolving correctly until that project is itself
+ * touched.
  *
  * Plain Node (no Electron deps in the read/write helpers) so gitWorktree.cjs
  * — itself Electron-free — can require this lazily without pulling Electron
@@ -26,19 +35,22 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { assertOpsWrite, opsPath } = require('./opsOwnership.cjs');
 
-const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'epic-worktree-project-config.json');
+// The old machine-wide map. Read-only from here on (migration source only) —
+// never written again, and deliberately never deleted so unmigrated projects
+// keep working. Resolved per-call (not a frozen const) so tests can point
+// this at a throwaway tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH
+// instead of touching the real machine-level file.
+const DEFAULT_LEGACY_CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'epic-worktree-project-config.json');
 
-// Resolved per-call (not a frozen const) so tests can point this at a
-// throwaway tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH instead of
-// mutating the real machine-level file at DEFAULT_CONFIG_PATH.
-function configPath() {
-  return process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH || DEFAULT_CONFIG_PATH;
+function legacyConfigPath() {
+  return process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH || DEFAULT_LEGACY_CONFIG_PATH;
 }
 
-function readConfig() {
+function readLegacyConfig() {
   try {
-    const raw = fs.readFileSync(configPath(), 'utf8');
+    const raw = fs.readFileSync(legacyConfigPath(), 'utf8');
     const parsed = JSON.parse(raw);
     return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
   } catch {
@@ -46,31 +58,62 @@ function readConfig() {
   }
 }
 
-function writeConfig(config) {
-  const file = configPath();
+/** `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json` */
+function perProjectConfigPath(cwd) {
+  return opsPath(cwd, 'prompt-sessions', 'epic-worktree-config.json');
+}
+
+function readPerProjectConfigFile(cwd) {
+  try {
+    const raw = fs.readFileSync(perProjectConfigPath(cwd), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePerProjectConfig(cwd, config, writer = 'epics') {
+  const file = perProjectConfigPath(cwd);
+  assertOpsWrite(file, writer);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(config, null, 2));
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
   fs.renameSync(tmp, file);
 }
 
+/**
+ * One-shot migration: when the per-project file doesn't exist yet, seed it
+ * from the legacy global map's entry for this cwd (present only when it was
+ * explicitly disabled — the legacy map deletes the key on re-enable). Never
+ * touches the legacy file itself.
+ */
+function readOrMigratePerProjectConfig(cwd) {
+  const existing = readPerProjectConfigFile(cwd);
+  if (existing) return existing;
+  const legacyValue = readLegacyConfig()[cwd];
+  if (legacyValue !== true) return { disabled: false };
+  const seeded = { disabled: true };
+  writePerProjectConfig(cwd, seeded);
+  return seeded;
+}
+
 /** True when the project at `cwd` has explicitly turned Epic worktree isolation off. */
 function isEpicWorktreeDisabledForProject(cwd) {
   if (!cwd || typeof cwd !== 'string') return false;
-  return readConfig()[cwd] === true;
+  try {
+    return readOrMigratePerProjectConfig(cwd).disabled === true;
+  } catch {
+    return false;
+  }
 }
 
-/** Persists (or clears, when `disabled` is false) the per-project toggle. */
-function setEpicWorktreeDisabledForProject(cwd, disabled) {
+/** Persists the per-project toggle. */
+function setEpicWorktreeDisabledForProject(cwd, disabled, writer = 'epics') {
   if (!cwd || typeof cwd !== 'string') throw new Error('setEpicWorktreeDisabledForProject: cwd is required');
-  const config = readConfig();
-  if (disabled) {
-    config[cwd] = true;
-  } else {
-    delete config[cwd];
-  }
-  writeConfig(config);
-  return disabled;
+  const value = !!disabled;
+  writePerProjectConfig(cwd, { disabled: value }, writer);
+  return value;
 }
 
 function registerEpicWorktreeProjectConfigHandlers() {
@@ -94,8 +137,9 @@ function registerEpicWorktreeProjectConfigHandlers() {
 }
 
 module.exports = {
-  DEFAULT_CONFIG_PATH,
-  configPath,
+  DEFAULT_LEGACY_CONFIG_PATH,
+  legacyConfigPath,
+  perProjectConfigPath,
   isEpicWorktreeDisabledForProject,
   setEpicWorktreeDisabledForProject,
   registerEpicWorktreeProjectConfigHandlers,

package/src/main/lib/loadGate.cjs

@@ -57,12 +57,36 @@ function isLoadGated(loadavg1, cores, threshold) {
   return loadavg1 / cores > threshold;
 }
 
-/** Best-effort top-N CPU consumers (Linux only). Returns [] anywhere else or on error. */
-function topCpuConsumers(n = 3) {
-  if (process.platform !== 'linux') return [];
+/**
+ * Best-effort top-N CPU consumers, for the audit line the scheduler warn-logs
+ * when the load gate has held jobs past its escalation window. Diagnostic only
+ * — nothing downstream branches on the result, so it fails to [] rather than
+ * throwing. Supported on Linux AND macOS (the two platforms this app targets);
+ * [] anywhere else or on any error.
+ *
+ * The `ps` invocation is platform-specific and NOT interchangeable:
+ *  - Linux (GNU/procps): `ps -eo pid,pcpu,comm --sort=-pcpu`. `--sort` is a
+ *    GNU long option.
+ *  - macOS (BSD ps): has NO `--sort` (`ps: illegal option -- -`, which threw
+ *    and left the gate audit logging `top CPU: n/a` on every Mac). BSD sorts
+ *    with `-r` (by CPU usage) and takes `-A` for all processes, `-c` for the
+ *    executable comm without its path. `ps -Aco pid,pcpu,comm -r` is the
+ *    column-and-sort equivalent.
+ * Both print a `PID %CPU COMM` header we skip, so downstream parsing is shared.
+ * `execImpl` is injected only by the unit test; production uses execFileSync.
+ */
+function topCpuConsumers(n = 3, { execImpl = execFileSync, platform = process.platform } = {}) {
+  let args;
+  if (platform === 'linux') {
+    args = ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'];
+  } else if (platform === 'darwin') {
+    args = ['-Aco', 'pid,pcpu,comm', '-r'];
+  } else {
+    return [];
+  }
   try {
-    const out = execFileSync('ps', ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'], { encoding: 'utf8', timeout: 2000 });
-    return out.split('\n').slice(1, 1 + n).map((l) => l.trim()).filter(Boolean);
+    const out = execImpl('ps', args, { encoding: 'utf8', timeout: 2000 });
+    return String(out).split('\n').slice(1, 1 + n).map((l) => l.trim()).filter(Boolean);
   } catch {
     return [];
   }

package/src/main/lib/loopDelay.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Event-loop delay probe for the main-process memory heartbeat. Wraps a
+ * perf_hooks IntervalHistogram (injectable for tests): enable() at init,
+ * snapshot() once per heartbeat returns the interval just ended in ms and
+ * reset()s, disable() rides the heartbeat teardown. No timer of its own.
+ */
+
+const { monitorEventLoopDelay } = require('node:perf_hooks');
+
+const LOOP_DELAY_RESOLUTION_MS = 20;
+// A single beat whose worst loop delay exceeds this is a visible main-thread stall.
+const LOOP_STALL_WARN_MS = 250;
+
+const NS_PER_MS = 1e6;
+const toMs = (ns) => Math.round(ns / NS_PER_MS * 10) / 10;
+
+function createLoopDelayMonitor(createHistogram = monitorEventLoopDelay) {
+  const h = createHistogram({ resolution: LOOP_DELAY_RESOLUTION_MS });
+  return {
+    enable() { h.enable(); },
+    disable() { h.disable(); },
+    /** Percentiles for the interval since the last snapshot; resets the histogram. */
+    snapshot() {
+      const out = {
+        loopDelayP50Ms: toMs(h.percentile(50)),
+        loopDelayP99Ms: toMs(h.percentile(99)),
+        loopDelayMaxMs: toMs(h.max),
+      };
+      h.reset();
+      return out;
+    },
+  };
+}
+
+/** Log level + message for a heartbeat given its loop-delay snapshot. */
+function stallVerdict(snap) {
+  return snap.loopDelayMaxMs > LOOP_STALL_WARN_MS
+    ? { level: 'warn', message: 'main loop stall' }
+    : null;
+}
+
+module.exports = { createLoopDelayMonitor, stallVerdict, LOOP_STALL_WARN_MS, LOOP_DELAY_RESOLUTION_MS };

package/src/main/lib/opsOwnership.cjs

@@ -60,6 +60,15 @@ const OWNERS = Object.freeze({
   // bilko-host-publisher Epic authors beyond dist/ is agent-Write-tool
   // output, same unenforceable-by-construction class as project-pages/output.
   'bilko-host': 'bilko-host',
+  // Memory Clusters owns its own regenerable per-project cache (PRD 1389) —
+  // memoryAggregate.cjs's clustering result, rebuilt on any explicit
+  // refresh:true. See memory-clusters/README.md.
+  'memory-clusters': 'memory-clusters',
+  // Per-project UI state (PRD 1398) — small renderer prefs that used to live
+  // in cwd-scoped or (worse) global localStorage keys. Written directly by
+  // the renderer through the generic config:write-json IPC with writer:
+  // 'ui-prefs'; no dedicated main-process module. See ui-prefs/README.md.
+  'ui-prefs': 'ui-prefs',
 });
 
 /**
@@ -170,6 +179,20 @@ function assertOpsWrite(absPath, writer) {
   // worktree-cwd hazard (PRD 1082; incidents 2026-08-30, 2026-09-01).
   const { inOps } = parseOpsPath(absPath);
   if (inOps) {
+    // classifyCwd fails closed on a non-absolute absPath (returns
+    // innermostOpsRoot: null) — path.dirname(null) throws a raw, untagged
+    // TypeError, which would crash this "last line of defense" instead of
+    // producing the graceful, catchable refusal every other branch here
+    // gives. A caller that skips the absolute-path helpers (opsPath/
+    // resolveProjectRoot) and hands assertOpsWrite a relative fragment
+    // containing an OPS_ROOT_DIR segment must still fail closed, not crash.
+    if (typeof absPath !== 'string' || !path.isAbsolute(absPath)) {
+      const err = new Error(
+        `refusing to write ${OPS_ROOT_DIR}/ state: absPath must be absolute, got "${absPath}"`,
+      );
+      err.unknownCwd = true;
+      throw err;
+    }
     // innermostOpsRoot (lastIndexOf) is the fact THIS gate keys on; activeSessions
     // truncates at the outermost instead — cwdClassify returns both, unified in
     // neither direction.

package/src/main/lib/planValidator.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * planValidator.cjs — pure predicate telling a work-item's dispatch whether a
+ * plan-level `validator` job (PRD 1405/1407) will re-review its diff once the
+ * plan finishes, so the per-job finish protocol and per-PRD validation prompt
+ * (PRD 986) can both yield to it instead of duplicating the same review. No
+ * filesystem or scheduler knowledge — the caller supplies the queue rows.
+ */
+
+/**
+ * hasDownstreamValidator(job, jobs) → boolean
+ *
+ * True iff `jobs` contains a row with `agentType === 'validator'`, status
+ * `pending` or `running`, whose `dependsOn` names `job.slug`. A validator job
+ * itself never has a downstream validator (it IS the plan's validation pass).
+ */
+function hasDownstreamValidator(job, jobs) {
+  if (!job || !Array.isArray(jobs)) return false;
+  if (job.agentType === 'validator') return false;
+  return jobs.some((row) => row
+    && row.agentType === 'validator'
+    && (row.status === 'pending' || row.status === 'running')
+    && Array.isArray(row.dependsOn)
+    && row.dependsOn.includes(job.slug));
+}
+
+module.exports = { hasDownstreamValidator };

package/src/main/lib/prdCreate.cjs

@@ -31,6 +31,7 @@ const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentT
 const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
 const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
+const { sizingWarnings } = require('./prdSizing.cjs');
 
 // A caller-supplied slug that already starts with its own `NN-` (e.g.
 // "254-perf-x") used to silently become the double-prefixed row
@@ -133,10 +134,10 @@ function buildPrdBody(input) {
   const oosLines = oosSource.map((line) => `- ${line}`).join('\n');
 
   const standardsPointer = [
-    `Before writing any code, read \`${STANDARDS_PATH}\` — it has the Performance, Debugging,`,
-    'API-reuse, TDD, and Execution-discipline rules that apply to this PRD. Every rule in it is',
-    'mandatory, especially Execution discipline (bounded commands, verify before done, the',
-    'finish-protocol sentinel).',
+    'Your system prompt carries the ordered run contract.',
+    `\`${STANDARDS_PATH}\` holds the reasoning behind each contract line (Performance, Debugging,`,
+    'API reuse, TDD, Execution discipline) — read the section a line points at when it is unclear;',
+    'do not re-read the whole file every run.',
   ].join('\n');
 
   const bodyLines = [
@@ -496,6 +497,8 @@ async function createPrd(input, remote) {
     epicId: writeResult.epicId ?? null,
     enqueued: false,
     note: 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
+    // Advisory only (PRD 1403) — never blocks the write. See prdSizing.cjs.
+    warnings: sizingWarnings(input),
   };
 }
 
@@ -541,6 +544,7 @@ function registerAdminRoute(adminHttp, remote) {
       epicId: result.epicId ?? null,
       enqueued: false,
       note: result.note,
+      warnings: result.warnings,
     });
   });
 }

package/src/main/lib/prdSizing.cjs

@@ -0,0 +1,83 @@
+/**
+ * prdSizing.cjs — pure PRD-size warning rules (PRD 1403).
+ *
+ * The measured actual/estimate ratio across scheduler runs sits at 0.24 (p50) with 60% of
+ * jobs finishing in <=10 min, yet nothing at the authoring gate flags an oversized PRD before
+ * it lands. `sizingWarnings` is the single rule set; prdCreate.cjs's createPrd() surfaces its
+ * output in the create-prd response, and scheduler-mcp-server.cjs's scheduler_create_prd
+ * handler prints it as a "Sizing warnings:" block. Warnings never block a write.
+ */
+'use strict';
+
+const SIZING_LIMITS = {
+  estimateMinutes: 15,
+  acLines: 8,
+  acLineChars: 400,
+  bodyChars: 7000,
+};
+
+// Open-ended search-and-fix shape, e.g. "grep the codebase and update every call site." Matches
+// across sentence boundaries within one AC line ([\s\S]*, not [^.]*) — a natural two-sentence
+// phrasing like "Search the codebase for X. Update every call site." is exactly the shape this
+// rule exists to catch, and a period must not be enough to dodge it.
+const OPEN_ENDED_RE = /\b(grep|search|scan|audit|find)\b[\s\S]*\b(and|then)\b[\s\S]*\b(update|fix|adjust|migrate|change)\b/i;
+const TIMEOUT_CMD_RE = /\btimeout\s+\d+/gi;
+
+/**
+ * Pure — no I/O. Returns one human-readable warning per triggered rule, `[]` when nothing
+ * is triggered. `input` mirrors createPrd()'s own input shape; missing/non-array fields are
+ * treated as empty/absent rather than thrown on, since this is advisory only.
+ */
+function sizingWarnings(input) {
+  const { estimateMinutes, goal, implementationNotes } = input || {};
+  const acceptanceCriteria = Array.isArray(input?.acceptanceCriteria) ? input.acceptanceCriteria : [];
+  const acLines = acceptanceCriteria.filter((line) => typeof line === 'string');
+
+  const warnings = [];
+
+  if (typeof estimateMinutes === 'number' && estimateMinutes > SIZING_LIMITS.estimateMinutes) {
+    warnings.push(
+      `estimateMinutes (${estimateMinutes}) exceeds the ${SIZING_LIMITS.estimateMinutes}-minute sizing limit — split this PRD into smaller work items.`,
+    );
+  }
+
+  if (acceptanceCriteria.length > SIZING_LIMITS.acLines) {
+    warnings.push(
+      `acceptanceCriteria has ${acceptanceCriteria.length} lines, exceeding the ${SIZING_LIMITS.acLines}-line sizing limit — split into smaller, single-purpose PRDs.`,
+    );
+  }
+
+  if (acLines.some((line) => line.length > SIZING_LIMITS.acLineChars)) {
+    warnings.push(
+      `One or more acceptance criteria lines exceed ${SIZING_LIMITS.acLineChars} characters — break the line up into smaller, single-purpose criteria.`,
+    );
+  }
+
+  if (acLines.some((line) => OPEN_ENDED_RE.test(line))) {
+    warnings.push(
+      'One or more acceptance criteria lines describe an open-ended search-and-fix task (e.g. "grep ... and update ...") — scope it to a concrete, bounded change instead.',
+    );
+  }
+
+  if (acLines.some((line) => {
+    const matches = line.match(TIMEOUT_CMD_RE);
+    return matches && matches.length >= 2;
+  })) {
+    warnings.push(
+      'One or more acceptance criteria lines run two or more `timeout <n>` commands — split into separate criteria, one command each.',
+    );
+  }
+
+  const bodyChars = String(goal || '').length
+    + String(implementationNotes || '').length
+    + acLines.join('\n').length;
+  if (bodyChars > SIZING_LIMITS.bodyChars) {
+    warnings.push(
+      `Combined goal + implementation notes + acceptance criteria is ${bodyChars} characters, exceeding the ${SIZING_LIMITS.bodyChars}-character sizing limit — split into smaller PRDs.`,
+    );
+  }
+
+  return warnings;
+}
+
+module.exports = { SIZING_LIMITS, sizingWarnings };

package/src/main/lib/runLogRetention.cjs

@@ -43,13 +43,8 @@
  */
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
-
-const DEFAULT_RUNS_DIR = path.join(
-  os.homedir(),
-  '.claude', 'session-manager', 'scheduled-plans', 'runs'
-);
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 // Any status that is not yet a terminal outcome. Mirrors the status literals
 // used throughout scheduler.cjs (see e.g. its DOD_SLUG_RE-adjacent status
@@ -436,14 +431,13 @@ function applyRetention(runsDir, settings, opts) {
  * startup timer, alongside finalizeClosedDays) — never on its own timer.
  */
 function runBootSweep(opts) {
-  const runsDir = (opts && opts.runsDir) || DEFAULT_RUNS_DIR;
+  const runsDir = (opts && opts.runsDir) || schedulerPaths.runsDir();
   const queueStore = require('./queueStore.cjs');
   const state = queueStore.readMergedSync();
   return applyRetention(runsDir, state.config || {}, { jobs: state.jobs || [] });
 }
 
 module.exports = {
-  DEFAULT_RUNS_DIR,
   LIVE_STATUSES,
   isLiveJob,
   liveKeysFromJobs,

package/src/main/lib/telemetryBacklog.cjs

@@ -21,7 +21,7 @@
  * a conservative, delivery-confirmed offset) at once — see the two-phase
  * design below.
  *
- * TWO-PHASE WATERMARK. Per file, ~/.config/session-manager/telemetry-
+ * TWO-PHASE WATERMARK. Per file, ~/.claude/session-manager/telemetry-
  * watermarks.json tracks:
  *   - bytesEnqueued:  how far we've read + handed lines to telemetryClient.
  *                     Advances the instant a line has been processed
@@ -85,8 +85,14 @@ function lastRunSummary() {
   return lastSummary ? { ...lastSummary } : null;
 }
 
+let migrated = false;
 function watermarksPath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'telemetry-watermarks.json');
+  const p = path.join(os.homedir(), '.claude', 'session-manager', 'telemetry-watermarks.json');
+  if (!migrated) {
+    migrated = true;
+    config.migrateLegacyHomeFile(path.join(os.homedir(), '.config', 'session-manager', 'telemetry-watermarks.json'), p);
+  }
+  return p;
 }
 
 function resolveDeps(deps = {}) {
@@ -154,7 +160,7 @@ function entryFor(wm, key) {
 
 /**
  * Known projects come from the same source of truth the renderer restores
- * tabs from (sessionsStore.cjs's ~/.config/session-manager/tabs.json — TAB =
+ * tabs from (sessionsStore.cjs's ~/.claude/session-manager/tabs.json — TAB =
  * cwd = Main Project), deduped by normalized cwd, with ephemeral (worktree /
  * tmpdir) cwds excluded before normalization even runs, since a worktree cwd
  * would otherwise resolve back to its real project and be scanned twice

package/src/main/lib/telemetryClient.cjs

@@ -7,7 +7,7 @@
  * 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
+ * Records accumulate durably in ~/.claude/session-manager/telemetry-queue.jsonl
  * the instant they're accepted, and are only ever sent by flush(reason) — on
  * a deliberate cadence (boot / daily / version-change / quit / manual), never
  * on a short interval. Every record is idempotent by recordId and stamped at
@@ -111,12 +111,21 @@ function logWarn(message, meta) {
 
 /**
  * SM_TELEMETRY_SPOOL, when set, overrides the spool directory in place of
- * `~/.config/session-manager` — the explicit opt-in a test that genuinely
+ * `~/.claude/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).
  */
+let spoolMigrated = false;
 function spoolDir() {
-  return process.env.SM_TELEMETRY_SPOOL || path.join(os.homedir(), '.config', 'session-manager');
+  if (process.env.SM_TELEMETRY_SPOOL) return process.env.SM_TELEMETRY_SPOOL;
+  const dir = path.join(os.homedir(), '.claude', 'session-manager');
+  if (!spoolMigrated) {
+    spoolMigrated = true;
+    const oldDir = path.join(os.homedir(), '.config', 'session-manager');
+    config.migrateLegacyHomeFile(path.join(oldDir, 'telemetry-queue.jsonl'), path.join(dir, 'telemetry-queue.jsonl'));
+    config.migrateLegacyHomeFile(path.join(oldDir, 'telemetry-sent.json'), path.join(dir, 'telemetry-sent.json'));
+  }
+  return dir;
 }
 
 function queuePath() {

package/src/main/lib/telemetrySettings.cjs

@@ -1,7 +1,7 @@
 /**
  * telemetrySettings — persists product-telemetry consent/config + install identity.
  *
- * Storage: ~/.config/session-manager/telemetry.json
+ * Storage: ~/.claude/session-manager/telemetry.json
  * Shape: {
  *   enabled: boolean,                // ON by default — hard kill switch is SM_TELEMETRY=0
  *   installId: string,               // crypto.randomUUID(), minted once, the only identity
@@ -45,8 +45,14 @@ const DEFAULTS = Object.freeze({
 
 const KNOWN_KEYS = new Set(Object.keys(DEFAULTS));
 
+let migrated = false;
 function storePath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'telemetry.json');
+  const p = path.join(os.homedir(), '.claude', 'session-manager', 'telemetry.json');
+  if (!migrated) {
+    migrated = true;
+    config.migrateLegacyHomeFile(path.join(os.homedir(), '.config', 'session-manager', 'telemetry.json'), p);
+  }
+  return p;
 }
 
 function isValid(cfg) {

package/src/main/lib/usageCircuit.cjs

@@ -50,19 +50,44 @@ function isResetFresh(iso, now) {
   return resetMs > nowMs;
 }
 
+/** Flat sibling window that mirrors a `limits[]` entry's `kind`, for resets_at backfill. */
+const FLAT_WINDOW_BY_KIND = { session: 'five_hour', weekly_all: 'seven_day' };
+
+/** An entry's utilization: real `percent`, else the flat-shape `utilization`. */
+function entryPercent(l) {
+  return Number.isFinite(l.percent) ? l.percent : l.utilization;
+}
+
 /**
- * Which window is actually binding dispatch. Prefers `payload.limits[]`'s
- * `is_active` entry (the richer per-window shape); falls back to the flat
- * `five_hour` field when `limits[]` is absent, matching usage.cjs's shape.
+ * Which window is actually binding dispatch. The real /api/oauth/usage
+ * `limits[]` entries carry `kind` / `group` / `percent` / `severity` /
+ * `resets_at` / `scope` / `is_active` (percent is 0-100, may exceed 100).
+ * Only UNSCOPED entries (`scope == null`) are candidates — a scoped entry
+ * (e.g. `weekly_scoped` for one model) does not bind dispatch generally. Among
+ * them the HIGHEST finite percent wins ("binding" = closest to blocking us);
+ * `is_active` only breaks ties, because the API sets it on group precedence
+ * and trusting it alone would pick weekly_all 64 over session 95. With no
+ * usable unscoped entry, falls back to the flat `five_hour`. Pure, no I/O.
  */
 function bindingWindow(payload) {
-  if (payload && Array.isArray(payload.limits) && payload.limits.length) {
-    const active = payload.limits.find((l) => l && l.is_active);
-    if (active) {
+  if (payload && Array.isArray(payload.limits)) {
+    let best = null;
+    let bestPct = -Infinity;
+    for (const l of payload.limits) {
+      if (!l || l.scope != null) continue;
+      const pct = entryPercent(l);
+      if (!Number.isFinite(pct)) continue;
+      if (pct > bestPct || (pct === bestPct && l.is_active === true && !(best && best.is_active === true))) {
+        best = l;
+        bestPct = pct;
+      }
+    }
+    if (best) {
+      const flat = payload[FLAT_WINDOW_BY_KIND[best.kind]];
       return {
-        name: active.type || active.name || 'unknown',
-        utilization: active.utilization,
-        resets_at: active.resets_at ?? null,
+        name: best.kind || best.type || best.name || 'unknown',
+        utilization: bestPct,
+        resets_at: best.resets_at ?? (flat ? flat.resets_at ?? null : null),
       };
     }
   }
@@ -88,15 +113,18 @@ function degradedConcurrencyCap(configuredCap) {
 
 /**
  * Conservative budget to run on while the meter is down. utilization is
- * carried forward from the last known-good BINDING window — never 0, which
- * would read as "plenty of headroom" instead of "we don't know." A fresh
+ * carried forward from the last known-good BINDING window (a genuine 0% stays
+ * 0); with no payload ever received it is 100, never a blind 0 that would read
+ * as "plenty of headroom" instead of "we don't know." A fresh
  * executor-observed 429 (its own window not yet passed) pins utilization to
  * 100 regardless of the stale cached value. concurrencyCap never exceeds 2
  * (or SM_USAGE_DEGRADED_CAP, if set).
  */
 function degradedBudget(lastGoodPayload, executorEvidence = {}) {
+  // "Never a blind 0" means NO payload ever received -> 100. A payload whose
+  // binding window genuinely reads 0% carries forward as 0.
   const window = bindingWindow(lastGoodPayload);
-  let utilization = Number.isFinite(window.utilization) && window.utilization > 0
+  let utilization = lastGoodPayload && Number.isFinite(window.utilization)
     ? window.utilization
     : 100;