claude-code-session-manager 0.122.0 → 0.123.0

package/src/main/lib/prd/prdGateFiles.cjs

@@ -244,6 +244,36 @@ function renderFilesSection(files) {
   ];
 }
 
+/**
+ * Inverse of renderFilesSection: read the bullet entries under the `# Files`
+ * heading (up to the next top-level heading) back out of a PRD body. Returns
+ * [] when there is no such section. Strips only the renderer's `- ` prefix
+ * (plus tolerated wrapping backticks); prose lines are ignored.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+function parseFilesSection(body) {
+  if (typeof body !== 'string') return [];
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^#\s+Files\s*$/.test(l));
+  if (start === -1) return [];
+  const out = [];
+  let inFence = false;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    if (!inFence && /^#\s/.test(line)) break;
+    const m = line.match(/^[-*]\s+(.+?)\s*$/);
+    if (!m) continue;
+    let entry = m[1];
+    const tick = entry.match(/^`([^`]+)`$/);
+    if (tick) entry = tick[1];
+    if (entry && !out.includes(entry)) out.push(entry);
+  }
+  return out;
+}
+
 /**
  * Render the `# Gate` body section as an array of lines. `commandsOrNone`
  * must already be validated (validateGate's `commands` output) — either
@@ -280,5 +310,6 @@ module.exports = {
   validateGate,
   validateFiles,
   renderFilesSection,
+  parseFilesSection,
   renderGateSection,
 };

package/src/main/lib/scheduler/definitionOfDone.cjs

@@ -427,7 +427,8 @@ function extractAcCommand(prdBody) {
  * Runs the resolved gate with `runGateSequence`, the same runner the
  * scheduler's shadow gate uses: `&&` semantics, each run gets its own
  * isolated TMPDIR and `CI=1`, and at most one gate runs machine-wide at a
- * time. This never spawns `claude` and never writes to queue.json — it only
+ * time (the flag-free variant is runIsolatedSequence, which never reports
+ * 'busy'). This never spawns `claude` and never writes to queue.json — it only
  * re-runs the already-authored gate command.
  *
  * Result `status` meanings:
@@ -756,6 +757,7 @@ function writeReport(key, { acResults = [], riskFlags = [], runsDir } = {}) {
 // records the outcome next to the verdict. Not a claude -p run, so it takes no
 // slot from sessionSlots; instead a single module-level flag keeps at most one
 // shadow gate in flight machine-wide (the scheduler is one process).
+// runIsolatedSequence is the flag-free variant: same run, no single-flight.
 let gateInFlight = false;
 const OUTPUT_TAIL_CHARS = 1000;
 // Bounded full-output ring kept for baseline comparison (failing test ids).
@@ -829,9 +831,28 @@ function runOneGateCommand(cmd, { cwd, env }) {
  */
 async function runGateSequence(sequence, { cwd }) {
   if (gateInFlight) return { status: 'busy', results: [] };
+  gateInFlight = true;
+  try {
+    return await runIsolatedSequence(sequence, { cwd });
+  } finally {
+    gateInFlight = false;
+  }
+}
+
+/**
+ * Flag-free variant of runGateSequence: same `&&` semantics, own mkdtemp
+ * TMPDIR (removed afterwards) and CI=1, but it never reads or writes
+ * `gateInFlight`, so it never returns 'busy' and never makes a concurrent
+ * runGateSequence return 'busy'. Meant for per-worktree work (e.g. worktree
+ * setup) whose callers bound their own parallelism.
+ *
+ * @param {Array<{argv:string[], timeoutMs:number, env?:object}>} sequence
+ * @param {{ cwd: string }} opts
+ * @returns {Promise<{ status: 'green'|'red'|'unavailable', results: object[] }>}
+ */
+async function runIsolatedSequence(sequence, { cwd }) {
   if (!Array.isArray(sequence) || !sequence.length) return { status: 'unavailable', results: [] };
   try { fs.statSync(cwd); } catch { return { status: 'unavailable', results: [] }; }
-  gateInFlight = true;
   let tmp = null;
   try {
     tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-gate-shadow-'));
@@ -847,7 +868,6 @@ async function runGateSequence(sequence, { cwd }) {
   } catch {
     return { status: 'unavailable', results: [] };
   } finally {
-    gateInFlight = false;
     if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } }
   }
 }
@@ -899,6 +919,7 @@ module.exports = {
   isNoneGate,
   resolveGate,
   runGateSequence,
+  runIsolatedSequence,
   extractSection,
   reverifyAc,
   reverifyBatch,

package/src/main/lib/scheduler/queueStore.cjs

@@ -218,10 +218,11 @@ function stateCwds(opts) {
 
 function bustCwdCache() {
   cwdCache = { at: 0, cwds: Object.freeze([]) };
-  // Without this chain, activeSessions' own scan cache hands stateCwds a
-  // stale list even after this bust — turning a caller's "I just wrote a
-  // brand-new project's first state file, make it visible now" into a
-  // no-op until activeSessions' independent TTL expires.
+  // Shallow bust: activeSessions keeps its per-dir cache and the next scan
+  // only picks up new project dirs. That is enough for new-project
+  // visibility — a brand-new project's transcript dir changes
+  // ~/.claude/projects' mtime, which the incremental path already sees.
+  // Callers needing a never-stale scan pass { deep: true } themselves.
   bustProjectCwdCache();
 }
 

package/src/main/lib/scheduler/scheduleJobSchema.cjs

@@ -88,6 +88,7 @@ const ScheduleJobSchema = z
     runtime: ScheduleJobRuntimeSchema.optional(),
     verifierVerdict: z.string().optional(),
     dependsOn: z.array(z.string()).optional(),
+    files: z.array(z.string()).optional(),
     originSessionId: z.string().nullable().optional(),
     sourceTabId: z.string().nullable().optional(),
     sourcePromptId: z.string().nullable().optional(),

package/src/main/lib/scheduler/schedulerBatch.cjs

@@ -141,8 +141,32 @@ function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
   });
 }
 
+/** Normalise a `files` entry for overlap comparison (`./a//b` -> `a/b`, trailing `/` kept). */
+function normFilePath(f) {
+  const raw = String(f ?? '').trim().replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/{2,}/g, '/');
+  return raw;
+}
+
+/** Equal paths, or a folder entry (ending in `/`) that prefixes the other path. */
+function pathsOverlap(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  if (a.endsWith('/') && b.startsWith(a)) return true;
+  if (b.endsWith('/') && a.startsWith(b)) return true;
+  return false;
+}
+
+/** True when two jobs' `files` arrays overlap. Empty/missing files never overlap. */
+function filesOverlap(aFiles, bFiles) {
+  if (!Array.isArray(aFiles) || !Array.isArray(bFiles)) return false;
+  const a = aFiles.map(normFilePath).filter(Boolean);
+  const b = bFiles.map(normFilePath).filter(Boolean);
+  return a.some((x) => b.some((y) => pathsOverlap(x, y)));
+}
+
 /**
- * Per-project batch picker. `dependsOn` is the ONLY ordering primitive.
+ * Per-project batch picker. `dependsOn` is the only ORDERING primitive;
+ * files-overlap (see below) is a mutual-exclusion hold, never an order.
  *
  * Rules:
  *   1. Eligible = pending, not already running, and no blocking dependency.
@@ -386,10 +410,24 @@ function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = n
   // parallelGroup is a PRIORITY HINT, not a barrier: when there are more
   // eligible jobs than slots, the lower (earlier-authored) PRD numbers go
   // first. Everything else about the number is display-only.
-  const batch = pending
-    .slice()
-    .sort((a, b) => (a.parallelGroup ?? 99) - (b.parallelGroup ?? 99))
-    .slice(0, effectiveSlots);
+  // files-overlap: mutual exclusion only. An eligible job is skipped while a
+  // running job (or one picked earlier in this call) shares a path with it.
+  const inFlight = projectJobs.filter((j) => j.status === 'running' || runningSlugsInProject.has(j.slug));
+  const batch = [];
+  for (const j of pending.slice().sort((a, b) => (a.parallelGroup ?? 99) - (b.parallelGroup ?? 99))) {
+    if (batch.length >= effectiveSlots) break;
+    const other = [...inFlight, ...batch].find((o) => o.slug !== j.slug && filesOverlap(j.files, o.files));
+    if (other) {
+      holds.push({ slug: j.slug, dep: null, depStatus: null, reason: `files-overlap:${other.slug}` });
+      continue;
+    }
+    batch.push(j);
+  }
+  if (batch.length === 0) {
+    const reason = `[scheduler] files-overlap [${projectCwd}]: holding ${pending.length} eligible job(s) behind running jobs sharing files`;
+    console.log(reason);
+    return { batch: [], reason, holds };
+  }
   console.log(
     `[scheduler] concurrency [${projectCwd}]: firing ${batch.length} of ${pending.length} ` +
     `eligible job(s) [${batch.map((j) => j.slug).join(', ')}]`,

package/src/main/lib/scheduler/schedulerPaths.cjs

@@ -119,6 +119,7 @@ function watchdogRelaunchLogPath() {
   );
 }
 function historyRollupStampPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'history-rollup.stamp'), 'historyRollupStampPath'); }
+function historyRollupCursorPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'history-rollup.cursor.json'), 'historyRollupCursorPath'); }
 function historyRollupLockPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'history-rollup.lock'), 'historyRollupLockPath'); }
 function historyRollupPath() { return path.join(schedulerHome(), 'history-rollup.jsonl'); }
 function auditLogPath() { return path.join(schedulerHome(), 'audit-log.jsonl'); }
@@ -206,6 +207,7 @@ module.exports = {
   watchdogRelaunchStatePath,
   watchdogRelaunchLogPath,
   historyRollupStampPath,
+  historyRollupCursorPath,
   historyRollupLockPath,
   historyRollupPath,
   auditLogPath,

package/src/main/lib/scheduler/watchdogHelpers.cjs

@@ -158,6 +158,8 @@ function evaluateDispatchLiveness(entry, now = Date.now(), { deadMs = DEFAULT_DI
 
 const DEFAULT_RELAUNCH_DEBOUNCE_MS = 90_000;
 const DEFAULT_MAX_RELAUNCH_ATTEMPTS = 3;
+// After the fast attempts are spent, keep retrying forever on this bounded backoff.
+const DEFAULT_CAPPED_RETRY_MS = 30 * 60_000;
 
 /**
  * checkAppLiveness(opts?) → { alive: boolean, reason: string }
@@ -188,12 +190,26 @@ function readRelaunchState(statePath = schedulerPaths.watchdogRelaunchStatePath(
     return {
       lastAttemptTs: typeof raw.lastAttemptTs === 'number' ? raw.lastAttemptTs : null,
       attemptCount: typeof raw.attemptCount === 'number' ? raw.attemptCount : 0,
+      lastBackoffLogTs: typeof raw.lastBackoffLogTs === 'number' ? raw.lastBackoffLogTs : null,
     };
   } catch {
-    return { lastAttemptTs: null, attemptCount: 0 };
+    return { lastAttemptTs: null, attemptCount: 0, lastBackoffLogTs: null };
   }
 }
 
+/**
+ * resetRelaunchState — zero the attempt counter. Called by the watchdog on every
+ * fresh, non-degraded heartbeat. Writes only when the state is not already zeroed.
+ */
+function resetRelaunchState({ statePath = schedulerPaths.watchdogRelaunchStatePath() } = {}) {
+  const state = readRelaunchState(statePath);
+  if (state.attemptCount === 0 && state.lastAttemptTs === null && state.lastBackoffLogTs === null) {
+    return { reset: false };
+  }
+  writeRelaunchState(statePath, { lastAttemptTs: null, attemptCount: 0 });
+  return { reset: true };
+}
+
 /** Atomic write via atomicFs.cjs (mirrors config.cjs writeJsonSync). */
 function writeRelaunchState(statePath, state) {
   atomicFs.writeJsonAtomicSync(statePath, state);
@@ -231,15 +247,73 @@ function relaunchSpec(opts) {
   return { command: 'npx', args: ['claude-code-session-manager@latest'], packaged: false };
 }
 
-function defaultSpawnRelaunch({ logPath = schedulerPaths.watchdogRelaunchLogPath(), packaged, execPath, spawnFn } = {}) {
-  const spawn = spawnFn || require('node:child_process').spawn;
+/** Resolve an executable on a PATH string (no shell). Returns null when absent. */
+function findOnPath(name, envPath) {
+  if (typeof envPath !== 'string') return null;
+  for (const dir of envPath.split(':')) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch { /* keep scanning */ }
+  }
+  return null;
+}
+
+/**
+ * relaunchInvocation — pure. Under systemd (INVOCATION_ID set) the relaunch must
+ * live in its own transient user unit, or the oneshot watchdog unit's cgroup
+ * teardown kills it. KillMode=process so a successor spawned by the old app's
+ * npx survives that npx exiting.
+ */
+function relaunchInvocation({ spec, env, logPath, now, systemdRunPath }) {
+  if (typeof env?.INVOCATION_ID === 'string' && env.INVOCATION_ID !== '' && typeof systemdRunPath === 'string') {
+    return {
+      mode: 'systemd-run',
+      command: systemdRunPath,
+      args: [
+        '--user', '--collect', '--quiet',
+        `--unit=session-manager-relaunch-${now}`,
+        '-p', 'KillMode=process',
+        '-p', `StandardOutput=append:${logPath}`,
+        '-p', `StandardError=append:${logPath}`,
+        `--setenv=PATH=${env.PATH}`,
+        '--',
+        spec.command, ...spec.args,
+      ],
+    };
+  }
+  return { mode: 'detached', command: spec.command, args: spec.args };
+}
+
+function defaultSpawnRelaunch({
+  logPath = schedulerPaths.watchdogRelaunchLogPath(), packaged, execPath, spawnFn, spawnSyncFn,
+  env: envIn = process.env, now = Date.now(),
+} = {}) {
+  const cp = require('node:child_process');
+  const spawn = spawnFn || cp.spawn;
+  const spawnSync = spawnSyncFn || cp.spawnSync;
   const spec = relaunchSpec({ packaged, execPath });
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const env = { ...envIn };
+  // The watchdog may itself run as node via the app binary; the relaunched app must not.
+  if (spec.packaged) delete env.ELECTRON_RUN_AS_NODE;
+  const inv = relaunchInvocation({
+    spec, env, logPath, now,
+    systemdRunPath: env.INVOCATION_ID ? findOnPath('systemd-run', env.PATH) : null,
+  });
+  let result = { mode: 'detached' };
+  if (inv.mode === 'systemd-run') {
+    const r = spawnSync(inv.command, inv.args, { timeout: 15000, stdio: 'ignore', env });
+    if (r && !r.error && r.status === 0) {
+      return { mode: 'systemd-run', ok: true, unit: `session-manager-relaunch-${now}` };
+    }
+    logRelaunchLine(logPath, `systemd-run failed (${r?.error?.message || `status ${r?.status}`}) — falling back to detached spawn`);
+    result = { mode: 'detached-fallback' };
+  }
   const fd = fs.openSync(logPath, 'a');
   try {
-    const env = { ...process.env };
-    // The watchdog may itself run as node via the app binary; the relaunched app must not.
-    if (spec.packaged) delete env.ELECTRON_RUN_AS_NODE;
     const child = spawn(spec.command, spec.args, {
       detached: true,
       stdio: ['ignore', fd, fd],
@@ -252,6 +326,7 @@ function defaultSpawnRelaunch({ logPath = schedulerPaths.watchdogRelaunchLogPath
   } finally {
     fs.closeSync(fd);
   }
+  return result;
 }
 
 /**
@@ -259,14 +334,14 @@ function defaultSpawnRelaunch({ logPath = schedulerPaths.watchdogRelaunchLogPath
  *
  * Debounced, capped auto-relaunch:
  *   - alive (heartbeat fresh or pid alive)             → no-op, reset attempt state.
- *   - dead + attemptCount already at maxAttempts         → skip, log diagnostic (give up).
+ *   - dead + attemptCount at maxAttempts, last attempt < cappedRetryMs ago
+ *                                                         → skip ('backoff'), one log line per window.
+ *   - dead + attemptCount at maxAttempts, window elapsed  → spawn again (retries forever).
  *   - dead + last attempt < debounceMs ago                → skip (still booting).
  *   - dead + debounce elapsed + under cap               → spawn, bump attemptCount, log.
  *
- * attemptCount only resets to 0 once a fresh heartbeat is observed (i.e. a
- * relaunch actually succeeded), so 3 relaunch attempts that each fail to
- * produce a fresh heartbeat permanently cap further attempts until a human
- * intervenes or the app comes up some other way.
+ * attemptCount resets to 0 when the alive branch here sees a live app, and the
+ * watchdog script also calls resetRelaunchState() on every fresh heartbeat.
  */
 function maybeRelaunchApp({
   heartbeatPath = schedulerPaths.heartbeatPath(),
@@ -275,6 +350,7 @@ function maybeRelaunchApp({
   logPath = schedulerPaths.watchdogRelaunchLogPath(),
   debounceMs = DEFAULT_RELAUNCH_DEBOUNCE_MS,
   maxAttempts = DEFAULT_MAX_RELAUNCH_ATTEMPTS,
+  cappedRetryMs = DEFAULT_CAPPED_RETRY_MS,
   now = Date.now(),
   spawnFn = defaultSpawnRelaunch,
   restartingMarkerPath = schedulerPaths.restartingMarkerPath(),
@@ -283,7 +359,7 @@ function maybeRelaunchApp({
   const state = readRelaunchState(statePath);
 
   if (liveness.alive) {
-    if (state.attemptCount !== 0 || state.lastAttemptTs !== null) {
+    if (state.attemptCount !== 0 || state.lastAttemptTs !== null || state.lastBackoffLogTs !== null) {
       writeRelaunchState(statePath, { lastAttemptTs: null, attemptCount: 0 });
     }
     return { relaunched: false, reason: 'alive', attemptCount: 0 };
@@ -298,23 +374,35 @@ function maybeRelaunchApp({
   }
 
   if (state.attemptCount >= maxAttempts) {
-    logRelaunchLine(
-      logPath,
-      `giving up: ${state.attemptCount} relaunch attempt(s) already made and heartbeat is still stale — manual intervention required`,
-    );
-    return { relaunched: false, reason: 'capped', attemptCount: state.attemptCount };
-  }
-
-  if (state.lastAttemptTs !== null && (now - state.lastAttemptTs) < debounceMs) {
+    const sinceLast = state.lastAttemptTs === null ? Infinity : now - state.lastAttemptTs;
+    if (sinceLast < cappedRetryMs) {
+      const nextRetryInMs = cappedRetryMs - sinceLast;
+      const logged = state.lastBackoffLogTs;
+      if (logged === null || logged < state.lastAttemptTs || now - logged >= cappedRetryMs) {
+        logRelaunchLine(
+          logPath,
+          `backoff: ${state.attemptCount} relaunch attempt(s) made and heartbeat is still stale — next retry in ${Math.ceil(nextRetryInMs / 60_000)} min`,
+        );
+        writeRelaunchState(statePath, {
+          lastAttemptTs: state.lastAttemptTs, attemptCount: state.attemptCount, lastBackoffLogTs: now,
+        });
+      }
+      return { relaunched: false, reason: 'backoff', attemptCount: state.attemptCount, nextRetryInMs };
+    }
+    // Window elapsed: fall through to spawn (skips debounce, which is shorter).
+  } else if (state.lastAttemptTs !== null && (now - state.lastAttemptTs) < debounceMs) {
     return { relaunched: false, reason: 'debounce', attemptCount: state.attemptCount };
   }
 
   const attemptCount = state.attemptCount + 1;
-  spawnFn({ logPath });
+  const spawned = spawnFn({ logPath, now });
+  const how = spawned && spawned.mode === 'systemd-run'
+    ? `via systemd-run unit ${spawned.unit || `session-manager-relaunch-${now}`}${spawned.ok === false ? ' (failed)' : ''}`
+    : spawned && spawned.mode === 'detached-fallback' ? 'detached (systemd-run fallback)' : 'detached';
   writeRelaunchState(statePath, { lastAttemptTs: now, attemptCount });
   logRelaunchLine(
     logPath,
-    `relaunch attempt ${attemptCount}/${maxAttempts}: spawning "npx claude-code-session-manager@latest" (heartbeat stale, last-known pid dead)`,
+    `relaunch attempt ${attemptCount}${attemptCount > maxAttempts ? ' (backoff retry)' : `/${maxAttempts}`}: spawning ${how} (heartbeat stale, last-known pid dead)`,
   );
   return { relaunched: true, reason: 'launched', attemptCount };
 }
@@ -463,8 +551,11 @@ module.exports = {
   releaseLock,
   checkAppLiveness,
   readRelaunchState,
+  resetRelaunchState,
   writeRelaunchState,
   defaultSpawnRelaunch,
+  relaunchInvocation,
+  findOnPath,
   relaunchSpec,
   maybeRelaunchApp,
   DEFAULT_MAX_AGE_MS,
@@ -474,6 +565,7 @@ module.exports = {
   DEFAULT_FINALIZE_BUDGET_MS,
   DEFAULT_RELAUNCH_DEBOUNCE_MS,
   DEFAULT_MAX_RELAUNCH_ATTEMPTS,
+  DEFAULT_CAPPED_RETRY_MS,
 };
 
 // Lazy default-path getters (SM_SCHEDULER_HOME resolved at read, never at require).

package/src/main/lib/telemetry/mainHeapSnapshot.cjs

@@ -0,0 +1,69 @@
+/**
+ * mainHeapSnapshot.cjs — bounded, automatic V8 heap snapshot of the MAIN process.
+ * Captures at most once per process when heapUsed crosses a threshold, keeps at
+ * most 2 `main-heap-*.heapsnapshot` files, and refuses when disk is tight.
+ * Synchronous (v8.writeHeapSnapshot) — acceptable once per boot for diagnosis.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_THRESHOLD_MB = 1800;
+const KEEP = 2;
+const PREFIX = 'main-heap-';
+const SUFFIX = '.heapsnapshot';
+
+const defaultState = { captured: false };
+
+function resolveThreshold(thresholdMb) {
+  if (Number.isFinite(thresholdMb) && thresholdMb > 0) return thresholdMb;
+  const env = Number(process.env.SM_MAIN_HEAP_SNAPSHOT_MB);
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_THRESHOLD_MB;
+}
+
+function pruneOld(dir, keep) {
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.startsWith(PREFIX) && n.endsWith(SUFFIX)); } catch { return; }
+  // ISO timestamps sort lexically; oldest first.
+  names.sort();
+  for (const n of names.slice(0, Math.max(0, names.length - keep))) {
+    try { fs.unlinkSync(path.join(dir, n)); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * @param {{ heapUsedMb:number, thresholdMb?:number, dir?:string, now?:Date,
+ *   writeFn?:(p:string)=>any, statfsFn?:Function, state?:{captured:boolean} }} opts
+ * @returns {{ captured:boolean, filePath?:string, reason?:string }}
+ */
+function maybeCaptureMainHeap(opts = {}) {
+  const state = opts.state || defaultState;
+  if (process.env.SM_MAIN_HEAP_SNAPSHOT === '0') return { captured: false, reason: 'disabled' };
+  if (state.captured) return { captured: false, reason: 'already-captured' };
+  const heapUsedMb = Number(opts.heapUsedMb);
+  if (!Number.isFinite(heapUsedMb) || heapUsedMb < resolveThreshold(opts.thresholdMb)) {
+    return { captured: false, reason: 'below-threshold' };
+  }
+  const dir = opts.dir || require('../scheduler/schedulerPaths.cjs').heapSnapshotDir();
+  const writeFn = opts.writeFn || ((p) => require('node:v8').writeHeapSnapshot(p));
+  const statfsFn = opts.statfsFn || fs.statfsSync;
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const st = statfsFn(dir);
+    const freeMb = (Number(st.bavail) * Number(st.bsize)) / 1048576;
+    if (!(freeMb >= 3 * heapUsedMb)) return { captured: false, reason: 'low-disk' };
+    // Leave room for the new file: keep KEEP-1 old ones, so KEEP remain after the write.
+    pruneOld(dir, KEEP - 1);
+    state.captured = true;
+    const filePath = path.join(dir, `${PREFIX}${now.toISOString().replace(/[:.]/g, '-')}${SUFFIX}`);
+    writeFn(filePath);
+    return { captured: true, filePath };
+  } catch (err) {
+    return { captured: false, reason: `error: ${err && err.message}` };
+  }
+}
+
+module.exports = { maybeCaptureMainHeap, DEFAULT_THRESHOLD_MB };

package/src/main/lib/telemetry/telemetryBoot.cjs

@@ -24,9 +24,31 @@ function resolveDeps(deps = {}) {
     telemetryClient: deps.telemetryClient || require('./telemetryClient.cjs'),
     buildMachineProfile: deps.buildMachineProfile || require('../machineProfile.cjs').buildMachineProfile,
     telemetryCounters: deps.telemetryCounters || require('./telemetryCounters.cjs'),
+    getSeedStatus: deps.getSeedStatus || (() => require('../../seedStatus.cjs').getSeedStatus()),
   };
 }
 
+/**
+ * Maps getSeedStatus() to enum-only strings (never the fix text or a path).
+ * Any failure or malformed shape yields null — never a throw.
+ */
+function buildSeeds(getSeedStatus) {
+  try {
+    const s = getSeedStatus();
+    const pick = (id) => {
+      const v = s && s[id] && s[id].status;
+      return typeof v === 'string' ? v : null;
+    };
+    return {
+      devPlugin: pick('dev-plugin'),
+      schedulerMcp: pick('scheduler-mcp'),
+      agentPersonas: pick('agent-personas'),
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * bootSequence({ now, appVersion, installChannel, deps }) — call once per
  * process from app.whenReady.
@@ -52,7 +74,7 @@ function resolveDeps(deps = {}) {
  */
 async function bootSequence({ now = Date.now(), appVersion, installChannel, deps: depsOverride } = {}) {
   const deps = resolveDeps(depsOverride);
-  const { telemetrySettings, telemetryClient, buildMachineProfile, telemetryCounters } = deps;
+  const { telemetrySettings, telemetryClient, buildMachineProfile, telemetryCounters, getSeedStatus } = deps;
 
   const settings = await telemetrySettings.load();
   const versionChanged = settings.lastMachineReportVersion !== appVersion;
@@ -63,7 +85,7 @@ async function bootSequence({ now = Date.now(), appVersion, installChannel, deps
   }
 
   if (telemetrySettings.isMachineReportDue(settings, { now, appVersion })) {
-    const profile = await buildMachineProfile();
+    const profile = { ...(await buildMachineProfile()), seeds: buildSeeds(getSeedStatus) };
     const reportResult = await telemetryClient.reportInstall(profile);
     if (reportResult && reportResult.accepted) {
       await telemetrySettings.save({
@@ -76,4 +98,4 @@ async function bootSequence({ now = Date.now(), appVersion, installChannel, deps
   telemetryCounters.trackAppLaunch({ installChannel, appVersion });
 }
 
-module.exports = { bootSequence };
+module.exports = { bootSequence, buildSeeds };

package/src/main/lib/telemetry/telemetryClient.cjs

@@ -580,9 +580,21 @@ function buildInstallWire(profile, installId) {
     // 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 }),
+    // First-boot seeder outcomes (enum strings only) or null — see telemetryBoot.buildSeeds.
+    seeds: sanitizeSeeds(p.seeds),
   };
 }
 
+const SEED_ENUM = new Set(['done', 'pending', 'failed', 'exhausted']);
+function sanitizeSeeds(seeds) {
+  if (!seeds || typeof seeds !== 'object') return null;
+  const out = {};
+  for (const k of ['devPlugin', 'schedulerMcp', 'agentPersonas']) {
+    out[k] = SEED_ENUM.has(seeds[k]) ? seeds[k] : null;
+  }
+  return out;
+}
+
 /**
  * Reports the once-per-cadence install/liveness record. Unlike track/logLine/
  * reportError this isn't arbitrary user content, so it skips redactDeep() —

package/src/main/lib/telemetry/telemetryCounters.cjs

@@ -29,8 +29,30 @@ function trackSessionOpen(deps) {
   track('session.open', {}, deps);
 }
 
-function trackEpicCreate(deps) {
-  track('epic.create', {}, deps);
+// Enum mappers — user-authored values never leave the machine; only the closed
+// shipped sets do. Sets are required lazily so this module stays light.
+function mapTag(tag) {
+  if (typeof tag !== 'string' || !tag) return null;
+  try {
+    const { EpicTagSchema } = require('../promptSessionSchema.cjs');
+    return EpicTagSchema.options.includes(tag) ? tag : 'other';
+  } catch { return 'other'; }
+}
+
+function mapAgentType(agentType) {
+  if (typeof agentType !== 'string' || !agentType) return null;
+  try {
+    const { PERSONAS } = require('../../seedAgentPersonas.cjs');
+    return PERSONAS.includes(agentType) ? agentType : 'custom';
+  } catch { return 'custom'; }
+}
+
+function trackEpicCreate({ tag, agentType } = {}, deps) {
+  track('epic.create', { tag: mapTag(tag), agentType: mapAgentType(agentType) }, deps);
+}
+
+function trackPrdCreate({ agentType } = {}, deps) {
+  track('prd.create', { agentType: mapAgentType(agentType) }, deps);
 }
 
 function trackSchedulerJobFinish({ status } = {}, deps) {
@@ -41,5 +63,6 @@ module.exports = {
   trackAppLaunch,
   trackSessionOpen,
   trackEpicCreate,
+  trackPrdCreate,
   trackSchedulerJobFinish,
 };