claude-code-session-manager 0.119.0 → 0.120.0

package/src/main/crashDiagnostics.cjs

@@ -26,7 +26,7 @@
 const { app, powerSaveBlocker, powerMonitor, crashReporter } = require('electron');
 const fs = require('node:fs');
 const path = require('node:path');
-const { reportCrash } = require('./lib/telemetry/crashTelemetry.cjs');
+const { reportCrash, classifyUncleanShutdown, reportChildProcessGone } = require('./lib/telemetry/crashTelemetry.cjs');
 const { createLoopDelayMonitor, stallVerdict } = require('./lib/util/loopDelay.cjs');
 
 let logs = null;
@@ -37,6 +37,7 @@ let loopMonitor = null;
 let sentinelPath = null;
 let startedAtIso = null;
 let lastSample = null;
+let lastLoop = null;
 
 // Warn threshold for total working set across all Electron processes. The OOM
 // journal showed a single renderer hitting ~900 MB anon-rss before the kernel
@@ -140,6 +141,7 @@ function persistSentinel(clean) {
     startedAt: startedAtIso,
     closedAt: clean ? new Date().toISOString() : undefined,
     lastSample,
+    loop: lastLoop ? { loopDelayMaxMs: lastLoop.loopDelayMaxMs, loopDelayP99Ms: lastLoop.loopDelayP99Ms } : null,
   };
   try {
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
@@ -152,11 +154,12 @@ function persistSentinel(clean) {
 
 function heartbeat() {
   lastSample = sampleMemory();
+  const loop = loopMonitor ? loopMonitor.snapshot() : null;
+  lastLoop = loop;
   // Persist every tick so the final pre-crash sample survives a SIGKILL.
   persistSentinel(false);
   const top = [...lastSample.procs].sort((a, b) => b.mb - a.mb).slice(0, 4);
   const level = lastSample.totalMb >= MEM_WARN_MB ? 'warn' : 'debug';
-  const loop = loopMonitor ? loopMonitor.snapshot() : null;
   logs?.writeLine({
     scope: 'crash-diag',
     level,
@@ -183,10 +186,14 @@ function checkPreviousRun() {
   if (!prev || prev.open !== true) return;
   const s = prev.lastSample;
   const lastTop = s && Array.isArray(s.procs) ? [...s.procs].sort((a, b) => b.mb - a.mb).slice(0, 4).map((p) => `${p.type}:${p.mb}MB`) : undefined;
+  const lastLoopDelayMaxMs = prev.loop?.loopDelayMaxMs;
+  const sampleMs = s?.ts ? Date.parse(s.ts) : NaN;
+  const silentGapSec = Number.isFinite(sampleMs) ? Math.round((Date.now() - sampleMs) / 1000) : undefined;
+  const likelyCause = classifyUncleanShutdown({ lastLoopDelayMaxMs, lastTotalMb: s?.totalMb, silentGapSec });
   logs?.writeLine({
     scope: 'crash-diag',
     level: 'error',
-    message: 'previous session ended UNCLEANLY (likely OOM-kill / native crash — no graceful quit)',
+    message: `previous session ended UNCLEANLY (likelyCause=${likelyCause}; no graceful quit)`,
     meta: {
       prevPid: prev.pid,
       startedAt: prev.startedAt,
@@ -195,7 +202,10 @@ function checkPreviousRun() {
       lastMainRssMb: s?.main?.rssMb,
       lastTop,
       powerBlockerHeldAtDeath: s?.powerBlockerHeld,
-      hint: 'Check `journalctl -k | grep -i oom` around lastSampleTs to confirm the kernel OOM-killer.',
+      lastLoopDelayMaxMs,
+      silentGapSec,
+      likelyCause,
+      hint: 'Check `journalctl -k | grep -i oom` around lastSampleTs to confirm the kernel OOM-killer, and the "main-loop stall" heartbeats before lastSampleTs to confirm a wedged main thread.',
     },
   });
   // The unclean-shutdown postmortem is the report most likely to be the ONLY
@@ -209,6 +219,9 @@ function checkPreviousRun() {
       lastMainRssMb: s?.main?.rssMb,
       lastTop,
       powerBlockerHeldAtDeath: s?.powerBlockerHeld,
+      lastLoopDelayMaxMs,
+      silentGapSec,
+      likelyCause,
     },
   });
 }
@@ -244,15 +257,7 @@ function registerCrashHooks() {
         lastTotalMb: lastSample?.totalMb,
       },
     });
-    reportCrash({
-      reason: details?.reason || 'unknown',
-      meta: {
-        type: details?.type,
-        name: details?.name || details?.serviceName,
-        exitCode: details?.exitCode,
-        lastTotalMb: lastSample?.totalMb,
-      },
-    });
+    reportChildProcessGone({ details, lastTotalMb: lastSample?.totalMb });
   });
 
   // powerMonitor ties the suspend story to the crash timeline. If we ever log

package/src/main/health.cjs

@@ -10,7 +10,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { execFileSync } = require('node:child_process');
 const { POLL_INTERVAL_MS, loadGateThreshold } = require('./lib/scheduler/schedulerConfig.cjs');
-const { opsPath } = require('./lib/opsOwnership.cjs');
+const { opsPath, OPS_ROOT_DIR } = require('./lib/opsOwnership.cjs');
 const { effectivePaused } = require('./lib/scheduler/upgradeDrain.cjs');
 const { checkPersonaImports } = require('./lib/persona-macro/personaImportHealth.cjs');
 const { checkDelegationReadiness } = require('./lib/epic/delegationReadiness.cjs');
@@ -24,6 +24,7 @@ const { classifyQueueStarvation, launchBlockedSlugs, STARVE_ESCALATION_MS } = re
 const { REVERIFY_INTERVAL_MS } = require('./scheduler/reviewLadder.cjs');
 const { findStarvedProjects, findUnresolvableDepRoots, DEFAULT_PROJECT_CWD, DEP_HISTORY_FAIL_OPEN } = require('./lib/scheduler/schedulerBatch.cjs');
 const { auditLogPath, readTail } = require('./lib/telemetry/auditLog.cjs');
+const { checkMainDependencyHealth } = require('./lib/git/depHealth.cjs');
 const { resolveBuildIdentity } = require('./lib/buildIdentity.cjs');
 const { computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/scheduler/runLogRetention.cjs');
 const { allProjectCwds } = require('./lib/activeSessions.cjs');
@@ -399,6 +400,41 @@ function evaluateEpicIndexHealth(cwds) {
   return { component: { ok: !anyOrphanRows, byProject }, issues };
 }
 
+// Read-only scan for stray `session-manager-operations` dirs nested under a
+// project root (symptom of a writer joining an agent cwd without
+// projectRootOf/opsPath). The top-level one is legitimate; node_modules, .git
+// and .claude/worktrees are skipped. Bounded depth, sync readdir, never writes.
+const OPS_DIR_NAME = OPS_ROOT_DIR;
+function findNestedOpsRoots(projectRoot, { maxDepth = 3 } = {}) {
+  const found = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue; // symlinks are not followed
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      const full = path.join(dir, e.name);
+      if (e.name === '.claude') {
+        // only .claude/worktrees is skipped; other .claude children still scan
+        if (depth + 1 < maxDepth) {
+          try {
+            for (const c of fs.readdirSync(full, { withFileTypes: true })) {
+              if (c.isDirectory() && c.name !== 'worktrees') walk(path.join(full, c.name), depth + 2);
+            }
+          } catch { /* unreadable */ }
+        }
+        continue;
+      }
+      if (e.name === OPS_DIR_NAME) {
+        if (depth > 0) { found.push(full); continue; } // stray; don't descend
+      }
+      if (depth + 1 < maxDepth) walk(full, depth + 1);
+    }
+  };
+  walk(projectRoot, 0);
+  return found;
+}
+
 // Pure evaluator over ~/.claude/session-manager/scheduler-state.json's parsed
 // content (the sidecar scheduler.cjs's pollLoop maintains for the billing
 // usage-meter / rate-limit-window poller — see rateLimitPollerStreak tests).
@@ -619,14 +655,56 @@ function latestStarveEscalationReasons(auditLogPath) {
  * repo HEAD differs from the installed build. Both are reported, neither is
  * critical (never flips status.ok).
  */
-function evaluateBuildFreshness({ running = null, installedOnDisk = null, repoHead = null } = {}) {
+const WORKTREE_SAFETY_PATHS = [
+  'src/main/lib/git/worktreeDeps.cjs',
+  'src/main/lib/git/depHealth.cjs',
+  'src/main/lib/git/gitWorktree.cjs',
+  'src/main/lib/git/jobWorktree.cjs',
+];
+
+function evaluateBuildFreshness({ running = null, installedOnDisk = null, repoHead = null, safetyCommitsMissing = [] } = {}) {
   const differs = (a, b) => !!a && !!b && !(a.startsWith(b) || b.startsWith(a));
   const restartNeeded = differs(running, installedOnDisk);
   const publishNeeded = differs(repoHead, installedOnDisk);
   const notes = [];
   if (restartNeeded) notes.push(`restart needed: running ${running}, installed ${installedOnDisk}`);
   if (publishNeeded) notes.push(`publish needed: repo HEAD ${repoHead}, installed ${installedOnDisk}`);
-  return { ok: true, running, installedOnDisk, repoHead, restartNeeded, publishNeeded, ...(notes.length ? { note: notes.join('; ') } : {}) };
+  let safetyIssue;
+  if (safetyCommitsMissing.length) {
+    const listed = safetyCommitsMissing.slice(0, 3).map((c) => `${c.sha} ${c.subject}`).join('; ');
+    const more = safetyCommitsMissing.length > 3 ? `; +${safetyCommitsMissing.length - 3} more` : '';
+    safetyIssue = `running build ${running} predates ${safetyCommitsMissing.length} worktree-safety commit(s): ${listed}${more} — publish a new release and restart Session Manager`;
+  }
+  return {
+    ok: true, running, installedOnDisk, repoHead, restartNeeded, publishNeeded,
+    safetyCommitsMissing, ...(safetyIssue ? { safetyIssue } : {}),
+    ...(notes.length ? { note: notes.join('; ') } : {}),
+  };
+}
+
+/**
+ * evaluateMainDepLinks(results) → { component, issues }
+ *
+ * Pure over `Array<{ cwd, health }>` (health = checkMainDependencyHealth's
+ * return). One issue per project whose node_modules links point into a job
+ * worktree or dangle. Non-critical: component.ok is always true.
+ */
+function evaluateMainDepLinks(results = []) {
+  const list = Array.isArray(results) ? results : [];
+  const broken = [];
+  const issues = [];
+  for (const { cwd, health } of list) {
+    if (!health || health.ok !== false) continue;
+    if (health.reason !== 'links-into-worktree' && health.reason !== 'dangling-links') continue;
+    const missing = Array.isArray(health.missing) ? health.missing : [];
+    broken.push({ cwd, reason: health.reason, missing });
+    const shown = missing.slice(0, 5).join(', ');
+    const more = missing.length > 5 ? `, +${missing.length - 5} more` : '';
+    issues.push(
+      `${cwd}: node_modules ${health.reason}${shown ? ` (${shown}${more})` : ''} — fix: cd ${cwd} && CI=1 pnpm install --offline --frozen-lockfile`,
+    );
+  }
+  return { component: { ok: true, checked: list.length, broken }, issues };
 }
 
 /**
@@ -1234,6 +1312,18 @@ async function check(opts = {}) {
     status.components.epic_transcripts = { ok: true, error: e.message };
   }
 
+  // 6.665. Nested ops roots (NON-fatal WARN): stray session-manager-operations
+  // dirs under this project. Read-only; never deletes.
+  try {
+    const nested = findNestedOpsRoots(PROJECT_ROOT, { maxDepth: 3 });
+    status.components.nested_ops_roots = { ok: true, count: nested.length, paths: nested };
+    if (nested.length > 0) {
+      status.issues.push(`Warning: ${nested.length} nested session-manager-operations dir(s): ${nested.join(', ')}`);
+    }
+  } catch (e) {
+    status.components.nested_ops_roots = { ok: true, error: e.message };
+  }
+
   // 6.7. Build freshness (informational): running heartbeat vs installed
   // build-info vs repo HEAD.
   try {
@@ -1243,15 +1333,47 @@ async function check(opts = {}) {
         timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
       }).trim() || null;
     } catch { /* not a git checkout */ }
+    const running = readFreshHeartbeat(schedulerPaths.heartbeatPath())?.build?.codeSha ?? null;
+    let safetyCommitsMissing = [];
+    if (typeof running === 'string' && running && typeof repoHead === 'string' && repoHead) {
+      try {
+        safetyCommitsMissing = execFileSync(
+          'git',
+          ['-C', PROJECT_ROOT, 'log', '--format=%h%x09%s', `${running}..HEAD`, '--', ...WORKTREE_SAFETY_PATHS],
+          { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+        ).split('\n').filter(Boolean).map((line) => {
+          const i = line.indexOf('\t');
+          return { sha: line.slice(0, i), subject: line.slice(i + 1) };
+        });
+      } catch { safetyCommitsMissing = []; }
+    }
     status.components.build = evaluateBuildFreshness({
-      running: readFreshHeartbeat(schedulerPaths.heartbeatPath())?.build?.codeSha ?? null,
+      running,
       installedOnDisk: resolveBuildIdentity().codeSha ?? null,
       repoHead,
+      safetyCommitsMissing,
     });
+    if (status.components.build.safetyIssue) status.issues.push(status.components.build.safetyIssue);
   } catch (e) {
     status.components.build = { ok: true, error: e.message };
   }
 
+  // 6.75. Main-checkout dependency links: node_modules entries pointing into a
+  // job worktree or dangling, for every cwd the queue knows. Non-critical.
+  if (queueState) {
+    try {
+      const cwds = [...new Set(Object.values(queueState.jobs || {})
+        .map((j) => j && j.cwd).filter((c) => typeof c === 'string' && c))].slice(0, 50);
+      const results = cwds.filter((cwd) => fs.existsSync(cwd))
+        .map((cwd) => ({ cwd, health: checkMainDependencyHealth(cwd) }));
+      const { component, issues } = evaluateMainDepLinks(results);
+      status.components.main_dep_links = component;
+      status.issues.push(...issues);
+    } catch (e) {
+      status.components.main_dep_links = { ok: true, error: e.message };
+    }
+  }
+
   // 6.8. Credential health (informational-but-loud): is the Claude OAuth token
   // usable? An expired/absent token silently voids every headless `claude -p`
   // job — the queue "runs" but nothing authenticates. refreshIfNeeded() reads
@@ -1297,6 +1419,7 @@ module.exports = {
   evaluateCredentialHealth,
   computeEpicIndexDrift,
   evaluateEpicIndexHealth,
+  findNestedOpsRoots,
   computeProjectProblemCounts,
   evaluateWorktreeCapBlocked,
   evaluatePerProjectStall,
@@ -1309,6 +1432,8 @@ module.exports = {
   evaluateBlockingParkHealth,
   evaluateStarveEscalationHealth,
   evaluateBuildFreshness,
+  evaluateMainDepLinks,
+  WORKTREE_SAFETY_PATHS,
   latestStarveEscalationReasons,
   DISPATCH_STALL_THRESHOLD_MS,
   DISPATCH_WARN_THRESHOLD_MS,

package/src/main/index.cjs

@@ -1007,6 +1007,7 @@ pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
 activeIndexMerge.registerActiveIndexMergeHandlers();
 promptSessionsCreateEpic.registerPromptSessionsCreateEpicHandlers();
+require('./lib/epic/archivedTranscript.cjs').registerIpc(ipcMain);
 customerFeedbackIpc.registerCustomerFeedbackHandlers();
 epicWorktreeMint.registerEpicWorktreeMintHandlers();
 epicWorktreeMerge.registerEpicWorktreeMergeHandlers();
@@ -1044,6 +1045,11 @@ try {
 } catch (e) {
   logs.writeLine({ scope: 'main', level: 'error', message: 'updater IPC registration failed', meta: { error: e?.message } });
 }
+try {
+  require('./lib/opsRetentionSettings.cjs').registerIpc(ipcMain);
+} catch (e) {
+  logs.writeLine({ scope: 'main', level: 'error', message: 'ops retention IPC registration failed', meta: { error: e?.message } });
+}
 chatRunner.registerChatHandlers();
 
 // Direct in-process PRD authoring for a queued PromptTicket classified
@@ -1110,9 +1116,11 @@ const SMFILE_MIME = {
 // E2E tests also skip so playwright.electron.launch can run multiple specs
 // back-to-back without the prior app's lock causing the next launch to quit.
 const isDev = process.env.SM_DEV === '1' || process.env.SM_E2E === '1';
+let lostInstanceLock = false;
 if (!isDev) {
   const gotLock = app.requestSingleInstanceLock();
   if (!gotLock) {
+    lostInstanceLock = true;
     terminateLosingInstance(app);
   } else {
     app.on('second-instance', () => {
@@ -1125,6 +1133,31 @@ if (!isDev) {
   }
 }
 
+function runRunLogRetentionPass() {
+  if (lostInstanceLock) return;
+  try {
+    const schedulerPaths = require('./lib/scheduler/schedulerPaths.cjs');
+    const staleTmpSweep = require('./lib/scheduler/staleTmpSweep.cjs');
+    const result = runLogRetention.runBootSweep();
+    const plansRoot = schedulerPaths.scheduledPlansRoot();
+    const tmp = staleTmpSweep.sweepStaleTmp(plansRoot);
+    const archive = staleTmpSweep.pruneRunsArchive(path.join(plansRoot, 'runs-archive'));
+    logs.writeLine({
+      scope: 'run-log-retention',
+      level: 'info',
+      message: result.deleted ? 'sweep applied' : 'sweep dry-run',
+      meta: {
+        deleted: result.deleted,
+        removedFiles: (result.removedFiles || 0) + tmp.removedFiles + archive.removedFiles,
+        freedBytes: (result.freedBytes || 0) + tmp.freedBytes + archive.freedBytes,
+        errorCount: (result.errors ? result.errors.length : 0) + tmp.errors.length + archive.errors.length,
+      },
+    });
+  } catch (e) {
+    logs.writeLine({ scope: 'run-log-retention', level: 'error', message: 'sweep failed', meta: { error: e?.message } });
+  }
+}
+
 // Global webContents hardening — applies to DevTools, future webContents, etc.
 // Must be registered before app.whenReady so it captures the first window too.
 app.on('web-contents-created', (_e, wc) => {
@@ -1454,25 +1487,31 @@ app.whenReady().then(async () => {
       logs.writeLine({ scope: 'history-rollup', level: 'error', message: 'finalizeClosedDays failed', meta: { error: e?.message } });
     });
     runIntradayRefresh();
-    // Run-log retention sweep: same deferred-30s, once-per-boot shape as the
-    // history rollup above. Read-only unless config.schedulerRunLogRetention
+    // Run-log retention sweep: runs once 30s after boot, then every 24h (a
+    // long-lived app would otherwise never trim). Skipped when this process
+    // lost the single-instance lock (lostInstanceLock, set beside
+    // terminateLosingInstance above). Read-only unless config.schedulerRunLogRetention
     // opts in (see runLogRetention.cjs's safety model) — non-fatal on error.
-    try {
-      const result = runLogRetention.runBootSweep();
-      logs.writeLine({
-        scope: 'run-log-retention',
-        level: 'info',
-        message: result.deleted ? 'boot sweep applied' : 'boot sweep dry-run',
-        meta: {
-          deleted: result.deleted,
-          removedFiles: result.removedFiles,
-          freedBytes: result.freedBytes,
-          errorCount: result.errors ? result.errors.length : 0,
-        },
-      });
-    } catch (e) {
-      logs.writeLine({ scope: 'run-log-retention', level: 'error', message: 'boot sweep failed', meta: { error: e?.message } });
-    }
+    runRunLogRetentionPass();
+    const retentionTimer = setInterval(runRunLogRetentionPass, 24 * 60 * 60 * 1000);
+    if (retentionTimer.unref) retentionTimer.unref();
+    // Archived-transcript migration: move embedded `transcript` strings into gzip
+    // sidecars, <=50 files per project per boot, yielding between files. Uses the
+    // cached allProjectCwds() list (never a fresh ~/.claude/projects scan).
+    (async () => {
+      try {
+        const { migrateProject } = require('./lib/epic/archivedTranscriptMigration.cjs');
+        for (const projectCwd of allProjectCwds()) {
+          const r = await migrateProject(projectCwd, { limit: 50, yieldFn: () => new Promise((res) => setImmediate(res)) });
+          if (r.migrated || r.errors.length) {
+            logs.writeLine({ scope: 'main', level: r.errors.length ? 'warn' : 'info', message: 'archived transcript migration', meta: { projectCwd, migrated: r.migrated, freedBytes: r.freedBytes, errors: r.errors.length } });
+          }
+          await new Promise((res) => setImmediate(res));
+        }
+      } catch (e) {
+        logs.writeLine({ scope: 'main', level: 'error', message: 'archived transcript migration failed', meta: { error: e?.message } });
+      }
+    })();
   }, 30_000);
   // Keep TODAY's rollup line current so the History dashboard never needs to
   // fall back to a live transcript scan. Shares the same O_EXCL lock file as

package/src/main/ipcSchemas.cjs

@@ -415,9 +415,9 @@ const schedulerCreatePrd = z.object({
   // User-selected work-type tag (PRD 774; independence from the parent
   // Epic's own tag confirmed PRD 1041) — deterministic, never LLM-classified.
   // Epic tag and PRD tag draw on the same WorkType vocabulary
-  // (lib/prd/workTypeLibrary.cjs) but are independent values; 'discussion' is
+  // (lib/prd/workTypeLibrary.cjs) but are independent values; 'discussion' and 'portfolio' are
   // excluded here for the same reason adminPrdFrontmatterPatch excludes it
-  // below — a discussion-tagged Epic never reaches PRD authoring.
+  // below — a discussion- or portfolio-tagged Epic never reaches PRD authoring.
   tag: PrdWorkTypeSchema.optional(),
   // WHO executes this PRD (persona name, `~/.claude/agents/<name>.md`) —
   // independent of `tag` above. Optional: prdCreate.cjs's buildPrdBody fills
@@ -516,7 +516,7 @@ const adminPrdFrontmatterPatch = z.object({
   parallelGroup: z.number().int().min(0).max(999999).optional(),
   sourcePromptId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   sourceTabId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
-  // 'discussion' deliberately excluded: matches prdFrontmatter.cjs's
+  // 'discussion' and 'portfolio' deliberately excluded: matches prdFrontmatter.cjs's
   // parsePrdFile, which never parses that value for a PRD's tag key (a
   // discussion-tagged Epic never reaches PRD authoring) — see
   // workTypeLibrary.cjs's PrdWorkTypeSchema.

package/src/main/lib/activeSessions.cjs

@@ -51,6 +51,13 @@ function isSstHarnessCwd(cwd) {
 // Transcript reads only need the last line with a `cwd` field — a few dozen
 // lines is always enough. 64 KB keeps peak RSS proportionate.
 const TAIL_BYTES = 64 * 1024;
+// A single transcript line (base64 render, big tool result) can exceed TAIL_BYTES
+// and leave the tail with no complete `cwd` row. Only on that miss the tail
+// grows (x16 per step) up to MAX_TAIL_BYTES, then up to MAX_FALLBACK_FILES
+// newest transcripts are tried before the project is given up on.
+const MAX_TAIL_BYTES = 16 * 1024 * 1024;
+const MAX_FALLBACK_FILES = 5;
+const TAIL_GROWTH = 16;
 
 // Safety cap on distinct cwds to bound result set size. O(1) extra space.
 const MAX_CWDS = 50;
@@ -139,6 +146,20 @@ function readTailLines(filePath, maxBytes) {
   return buf.toString('utf8').split('\n').filter((l) => l.trim());
 }
 
+function fileSizeSync(fp) {
+  try { return fs.statSync(fp).size; } catch { return 0; }
+}
+
+/** lastCwdInLines(lines) → the `cwd` of the last parseable row that has one, or null. */
+function lastCwdInLines(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let row;
+    try { row = JSON.parse(lines[i]); } catch { continue; }
+    if (row && row.cwd) return row.cwd;
+  }
+  return null;
+}
+
 /**
  * scanOneProjectDirSync(projDir) → {rawCwd, newestMtimeMs} | null
  * Newest *.jsonl's mtime plus its last parseable `cwd`, for one project dir.
@@ -149,28 +170,25 @@ function scanOneProjectDirSync(projDir) {
     entries = fs.readdirSync(projDir).filter((f) => f.endsWith('.jsonl'));
   } catch { return null; }
 
-  let newestPath = null;
-  let newestMtimeMs = 0;
+  const files = [];
   for (const tf of entries) {
     const fp = path.join(projDir, tf);
-    try {
-      const st = fs.statSync(fp);
-      if (st.mtimeMs > newestMtimeMs) {
-        newestMtimeMs = st.mtimeMs;
-        newestPath = fp;
-      }
-    } catch { continue; }
+    try { files.push({ fp, mtimeMs: fs.statSync(fp).mtimeMs }); } catch { continue; }
   }
-  if (!newestPath) return null;
+  if (!files.length) return null;
+  files.sort((x, y) => y.mtimeMs - x.mtimeMs);
+  const newestMtimeMs = files[0].mtimeMs;
 
-  const tlines = readTailLines(newestPath, TAIL_BYTES);
-  let rawCwd = null;
-  for (let i = tlines.length - 1; i >= 0; i--) {
-    let row;
-    try { row = JSON.parse(tlines[i]); } catch { continue; }
-    if (row.cwd) { rawCwd = row.cwd; break; }
+  for (const { fp } of files.slice(0, MAX_FALLBACK_FILES)) {
+    let size = TAIL_BYTES;
+    for (;;) {
+      const rawCwd = lastCwdInLines(readTailLines(fp, size));
+      if (rawCwd) return { rawCwd, newestMtimeMs };
+      if (size >= MAX_TAIL_BYTES || size >= fileSizeSync(fp)) break;
+      size = Math.min(size * TAIL_GROWTH, MAX_TAIL_BYTES);
+    }
   }
-  return rawCwd ? { rawCwd, newestMtimeMs } : null;
+  return null;
 }
 
 /**
@@ -262,28 +280,27 @@ async function scanOneProjectDirAsync(projDir) {
     entries = (await fsp.readdir(projDir)).filter((f) => f.endsWith('.jsonl'));
   } catch { return null; }
 
-  let newestPath = null;
-  let newestMtimeMs = 0;
+  const files = [];
   for (const tf of entries) {
     const fp = path.join(projDir, tf);
-    try {
-      const st = await fsp.stat(fp);
-      if (st.mtimeMs > newestMtimeMs) {
-        newestMtimeMs = st.mtimeMs;
-        newestPath = fp;
-      }
-    } catch { continue; }
+    try { files.push({ fp, mtimeMs: (await fsp.stat(fp)).mtimeMs }); } catch { continue; }
   }
-  if (!newestPath) return null;
+  if (!files.length) return null;
+  files.sort((x, y) => y.mtimeMs - x.mtimeMs);
+  const newestMtimeMs = files[0].mtimeMs;
 
-  const tlines = await readTailLinesAsync(newestPath, TAIL_BYTES);
-  let rawCwd = null;
-  for (let i = tlines.length - 1; i >= 0; i--) {
-    let row;
-    try { row = JSON.parse(tlines[i]); } catch { continue; }
-    if (row.cwd) { rawCwd = row.cwd; break; }
+  for (const { fp } of files.slice(0, MAX_FALLBACK_FILES)) {
+    let size = TAIL_BYTES;
+    for (;;) {
+      const rawCwd = lastCwdInLines(await readTailLinesAsync(fp, size));
+      if (rawCwd) return { rawCwd, newestMtimeMs };
+      let fileSize = 0;
+      try { fileSize = (await fsp.stat(fp)).size; } catch { /* gone: stop growing */ }
+      if (size >= MAX_TAIL_BYTES || size >= fileSize) break;
+      size = Math.min(size * TAIL_GROWTH, MAX_TAIL_BYTES);
+    }
   }
-  return rawCwd ? { rawCwd, newestMtimeMs } : null;
+  return null;
 }
 
 /**

package/src/main/lib/claude/agentModelResolve.cjs

@@ -212,10 +212,10 @@ function buildPersonaBodyText(rawBody, personaPath) {
  * same runaway-file protection.
  *
  * @param {{ cwd: string, agentType: string|null, fallbackModel?: string, deps?: object }} opts
- * @returns {Promise<{ model: string, systemPrompt: string|null, personaPath: string|null }>}
+ * @returns {Promise<{ model: string, systemPrompt: string|null, personaPath: string|null, tools: string[]|null }>}
  */
 async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLBACK_MODEL, deps = {} } = {}) {
-  const miss = { model: fallbackModel, systemPrompt: null, personaPath: null };
+  const miss = { model: fallbackModel, systemPrompt: null, personaPath: null, tools: null };
   if (!agentType) return miss;
   try {
     const getBody = deps.getPersonaBody || require('../../agentLibrary.cjs').getPersonaBody;
@@ -230,7 +230,9 @@ async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLB
     const { fm, body } = persona.fm ? persona : splitFrontmatter(persona.text);
     const model = fm.model && fm.model !== 'inherit' ? fm.model : fallbackModel;
     const systemPrompt = buildPersonaBodyText(body, persona.path);
-    return { model, systemPrompt, personaPath: persona.path };
+    const parseTools = deps.parseTools || require('../../agentLibrary.cjs').parseTools;
+    const list = parseTools(typeof fm.tools === 'string' ? fm.tools : '');
+    return { model, systemPrompt, personaPath: persona.path, tools: list.length ? list : null };
   } catch {
     return miss;
   }

package/src/main/lib/claude/personaToolScope.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * personaToolScope.cjs — turns a persona's `tools:` list into the claude CLI
+ * args that actually ENFORCE it on a headless `claude -p` run.
+ *
+ * Verified on CLI 2.1.302: under `--dangerously-skip-permissions`,
+ * `--allowedTools` restricts nothing and `--tools` only filters built-ins (MCP
+ * tools stay). `--agents '<json>' --agent <name>` with a `tools` array enforces
+ * exact per-tool scoping, MCP tools included, while the Claude Code harness
+ * prompt, CLAUDE.md, `--append-system-prompt` and `--disallowedTools` keep
+ * working.
+ *
+ * Pure: no fs, and no require of scheduler.cjs (cycle) — the caller passes its
+ * HEADLESS_DISALLOWED_TOOLS list in.
+ */
+
+// Always granted to a scoped run: the finish protocol runs /code-review and
+// /security-review (Skill + Agent); MCP tools are deferred, so ToolSearch is
+// needed to reach them; TodoWrite is the run's own planning aid.
+const HEADLESS_TOOL_FLOOR = Object.freeze(['Agent', 'Skill', 'ToolSearch', 'TodoWrite']);
+
+const HEADLESS_SCOPE_AGENT_NAME = 'sm-headless-scoped';
+
+/**
+ * @param {readonly string[]|null|undefined} tools persona `tools:` list
+ * @param {{ disallowed?: readonly string[] }} [opts]
+ * @returns {{ tools: string[] }|null} null = persona declares no restriction
+ */
+function buildPersonaToolScope(tools, { disallowed = [] } = {}) {
+  if (!Array.isArray(tools) || tools.length === 0) return null;
+  const names = tools
+    .filter((t) => typeof t === 'string')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (names.length === 0 || names.includes('*')) return null;
+  const blocked = new Set(disallowed);
+  const out = [];
+  for (const name of [...names, ...HEADLESS_TOOL_FLOOR]) {
+    if (blocked.has(name) || out.includes(name)) continue;
+    out.push(name);
+  }
+  return { tools: out };
+}
+
+/**
+ * @param {{ tools: string[] }|null} scope result of buildPersonaToolScope
+ * @returns {string[]} argv fragment ([] when unscoped)
+ */
+function personaToolScopeArgs(scope) {
+  if (!scope) return [];
+  const def = {
+    description: 'Headless run with a scheduler-enforced tool scope.',
+    prompt: 'Tool scope is enforced by the scheduler.',
+    tools: scope.tools,
+  };
+  return [
+    '--agents', JSON.stringify({ [HEADLESS_SCOPE_AGENT_NAME]: def }),
+    '--agent', HEADLESS_SCOPE_AGENT_NAME,
+  ];
+}
+
+module.exports = {
+  HEADLESS_TOOL_FLOOR,
+  HEADLESS_SCOPE_AGENT_NAME,
+  buildPersonaToolScope,
+  personaToolScopeArgs,
+};