claude-code-session-manager 0.119.1 → 0.121.0

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,
+};

package/src/main/lib/epic/archivedTranscript.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * archivedTranscript.cjs — gzip sidecar store for the raw Claude JSONL that
+ * archived Epic JSONs used to embed as a `transcript` string. The sidecar
+ * lives at `prompt-sessions/transcripts-archive/<epicId>.jsonl.gz` (inside the
+ * `prompt-sessions` namespace, so the `epics` owner already covers it) and the
+ * caller keeps only the small pointer returned by writeSidecar.
+ *
+ * Electron-free at load (like epicStatusMirror.cjs); registerIpc takes ipcMain.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const zlib = require('node:zlib');
+const { assertOpsWrite, opsPath } = require('../opsOwnership.cjs');
+const atomicFs = require('../util/atomicFs.cjs');
+
+const SUBDIR = 'transcripts-archive';
+
+function assertSafeEpicId(epicId) {
+  if (typeof epicId !== 'string' || !epicId || epicId.includes('..') || /[\\/\0]/.test(epicId)) {
+    throw new Error(`archivedTranscript: invalid epicId "${epicId}"`);
+  }
+}
+
+function sidecarPath(cwd, epicId) {
+  assertSafeEpicId(epicId);
+  return opsPath(cwd, 'prompt-sessions', SUBDIR, `${epicId}.jsonl.gz`);
+}
+
+const sha256Of = (text) => crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+
+/**
+ * writeSidecar(cwd, epicId, text) -> {path, bytes, gzBytes, sha256}.
+ * Idempotent: if the existing sidecar already decompresses to the same text,
+ * nothing is rewritten.
+ */
+function writeSidecar(cwd, epicId, text, { writer = 'epics' } = {}) {
+  if (typeof text !== 'string') throw new Error('archivedTranscript: text must be a string');
+  const file = sidecarPath(cwd, epicId);
+  assertOpsWrite(file, writer);
+  const sha256 = sha256Of(text);
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const existing = readSidecar(cwd, epicId);
+  if (existing !== null && sha256Of(existing) === sha256) {
+    return { path: file, bytes, gzBytes: fs.statSync(file).size, sha256 };
+  }
+  const gz = zlib.gzipSync(Buffer.from(text, 'utf8'));
+  atomicFs.writeTextAtomicSync(file, gz);
+  return { path: file, bytes, gzBytes: gz.length, sha256 };
+}
+
+/** readSidecar(cwd, epicId) -> string | null (null when absent or unreadable). */
+function readSidecar(cwd, epicId) {
+  const file = sidecarPath(cwd, epicId);
+  try {
+    return zlib.gunzipSync(fs.readFileSync(file)).toString('utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * archiveTranscript({cwd, epicId, claudeSessionId}, {resolvePath}) -> pointer | null.
+ * Reads the raw Claude JSONL main-side and writes the sidecar; null when the
+ * JSONL is missing or empty (caller falls back to durableTurns).
+ */
+function archiveTranscript(args, { resolvePath } = {}) {
+  const { cwd, epicId, claudeSessionId } = args || {};
+  if (typeof cwd !== 'string' || !require('node:path').isAbsolute(cwd)) {
+    throw new Error('archivedTranscript: cwd must be an absolute path');
+  }
+  assertSafeEpicId(epicId);
+  if (typeof claudeSessionId !== 'string' || !claudeSessionId) return null;
+  const resolve = resolvePath || ((c, s) => require('../../transcripts.cjs').transcriptPath(c, s));
+  let text;
+  try {
+    text = fs.readFileSync(resolve(cwd, claudeSessionId), 'utf8');
+  } catch {
+    return null;
+  }
+  if (!text) return null;
+  return writeSidecar(cwd, epicId, text);
+}
+
+function registerIpc(ipcMain, deps) {
+  ipcMain.handle('promptSessions:archiveTranscript', async (_e, payload) => archiveTranscript(payload, deps));
+}
+
+module.exports = { writeSidecar, readSidecar, sidecarPath, archiveTranscript, registerIpc };

package/src/main/lib/epic/archivedTranscriptMigration.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * archivedTranscriptMigration.cjs — one-shot, idempotent, crash-safe move of the
+ * embedded `transcript` string in archived Epic JSONs into the gzip sidecar
+ * (archivedTranscript.cjs). Per file: write sidecar -> re-read + compare sha ->
+ * only then atomically rewrite the JSON with `transcriptRef` and no `transcript`.
+ * A crash or failure before the rewrite leaves the original JSON byte-identical.
+ *
+ * Never touches `active-index.json` or files whose status is 'active'.
+ * Writes as the `epics` owner (the sidecar lives inside `prompt-sessions`).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { assertOpsWrite, opsPath } = require('../opsOwnership.cjs');
+const atomicFs = require('../util/atomicFs.cjs');
+const archivedTranscript = require('./archivedTranscript.cjs');
+
+const SKIP_FILES = new Set(['active-index.json']);
+
+/**
+ * migrateProject(projectRoot, {dryRun, limit, yieldFn, deps})
+ *   -> Promise<{scanned, migrated, skipped, freedBytes, errors}>
+ * `limit` caps files migrated (or failed) per call; dryRun counts what would
+ * migrate without writing. `deps` lets tests inject the sidecar functions.
+ */
+async function migrateProject(projectRoot, { dryRun = false, limit = Infinity, yieldFn = null, deps = {} } = {}) {
+  const writeSidecar = deps.writeSidecar || archivedTranscript.writeSidecar;
+  const readSidecar = deps.readSidecar || archivedTranscript.readSidecar;
+  const result = { scanned: 0, migrated: 0, skipped: 0, freedBytes: 0, errors: [] };
+  const dir = opsPath(projectRoot, 'prompt-sessions');
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return result;
+  }
+  let attempted = 0;
+  for (const name of names) {
+    if (!name.endsWith('.json') || SKIP_FILES.has(name)) continue;
+    if (attempted >= limit) break;
+    result.scanned += 1;
+    const file = path.join(dir, name);
+    try {
+      const raw = fs.readFileSync(file, 'utf8');
+      // Cheap pre-check so files without a transcript are never JSON-parsed.
+      if (!raw.includes('"transcript"')) { result.skipped += 1; continue; }
+      const doc = JSON.parse(raw);
+      if (!doc || typeof doc !== 'object' || typeof doc.transcript !== 'string' || doc.status === 'active') {
+        result.skipped += 1;
+        continue;
+      }
+      attempted += 1;
+      const epicId = name.slice(0, -'.json'.length);
+      if (dryRun) {
+        result.migrated += 1;
+        result.freedBytes += Buffer.byteLength(doc.transcript, 'utf8');
+        continue;
+      }
+      assertOpsWrite(file, 'epics');
+      const ref = writeSidecar(projectRoot, epicId, doc.transcript);
+      const back = readSidecar(projectRoot, epicId);
+      if (typeof back !== 'string' || archivedTranscriptSha(back) !== ref.sha256) {
+        throw new Error('sidecar sha mismatch');
+      }
+      const { transcript: _drop, ...rest } = doc;
+      const next = { ...rest, transcriptRef: { path: ref.path, bytes: ref.bytes, gzBytes: ref.gzBytes, sha256: ref.sha256 } };
+      atomicFs.writeJsonAtomicSync(file, next);
+      result.migrated += 1;
+      result.freedBytes += Math.max(0, Buffer.byteLength(raw, 'utf8') - fs.statSync(file).size);
+    } catch (e) {
+      result.errors.push({ file: name, error: e && e.message ? e.message : String(e) });
+    }
+    if (yieldFn) await yieldFn();
+  }
+  return result;
+}
+
+function archivedTranscriptSha(text) {
+  return require('node:crypto').createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+module.exports = { migrateProject };

package/src/main/lib/epic/delegationReadiness.cjs

@@ -671,6 +671,7 @@ function logAutoInstallEvent({ cwd, guard, action, error }) {
       scope: 'delegationReadiness',
       level: action === 'error' ? 'error' : 'info',
       message: `auto-install ${guard}: ${action}`,
+      code: `guard-install-${action}:${guard}`,
       meta: { guard, action, ...(error ? { error } : {}) },
     });
   } catch { /* logging must never break the caller */ }
@@ -796,6 +797,7 @@ async function ensureGuardsInstalled(cwd, { homeDir = os.homedir() } = {}) {
 module.exports = {
   checkDelegationReadiness,
   ensureGuardsInstalled,
+  logAutoInstallEvent,
   clearGuardsInstalledCache,
   installPrdWriteGuard,
   installDestructiveGitGuard,

package/src/main/lib/epic/epicSettle.cjs

@@ -21,6 +21,17 @@ const ts = (at) => {
 const isValidatorCheckin = (e, bare) =>
   e.agentType === 'validator' || (e.agentType == null && bare.startsWith('validate-'));
 
+// Mirrors the scheduler's cancel rule locally (lib/epic stays free of scheduler deps).
+const isCancelledRow = (r) => {
+  if (!r || (r.status !== 'failed' && r.status !== 'needs_review')) return false;
+  if (typeof r.cancelledAt === 'string' && r.cancelledAt) return true;
+  const hist = Array.isArray(r.statusHistory) ? r.statusHistory : [];
+  for (let i = hist.length - 1; i >= 0; i--) {
+    if (hist[i] && hist[i].to === r.status) return hist[i].source === 'remote:cancelJob';
+  }
+  return false;
+};
+
 /**
  * @param {{ epicId: string, cwd?: string|null, events?: any[], jobs?: any[], now?: number, horizonMs?: number }} args
  */
@@ -34,8 +45,13 @@ function evaluateEpicSettle({ epicId, cwd, events, jobs, now, horizonMs } = {})
     (r) => r && (r.epicId === epicId || r.sourcePromptId === epicId) && (r.cwd == null || cwd == null || r.cwd === cwd),
   );
   const settled = !epicRows.some((r) => r.status === 'pending' || r.status === 'running');
+  const cancelled = epicRows
+    .filter(isCancelledRow)
+    .map((r) => String(r.slug))
+    .sort();
+  const cancelledSet = new Set(cancelled.flatMap((s) => [s, bareSlug(s)]));
   const parked = epicRows
-    .filter((r) => r.status === 'needs_review')
+    .filter((r) => r.status === 'needs_review' && !isCancelledRow(r))
     .map((r) => String(r.slug))
     .sort();
 
@@ -83,7 +99,7 @@ function evaluateEpicSettle({ epicId, cwd, events, jobs, now, horizonMs } = {})
   const failed = [];
   for (const [bare, { event, t }] of checkins) {
     if (event.outcome === 'failed') {
-      failed.push(event.prdSlug);
+      if (!cancelledSet.has(event.prdSlug) && !cancelledSet.has(bare)) failed.push(event.prdSlug);
       continue;
     }
     const v = verdicts.get(bare);
@@ -94,12 +110,12 @@ function evaluateEpicSettle({ epicId, cwd, events, jobs, now, horizonMs } = {})
   failed.sort();
 
   const digestKey = createHash('sha1')
-    .update(JSON.stringify({ verified, refuted, failed, parked, uncovered: uncovered.map((u) => u.slug) }))
+    .update(JSON.stringify({ verified, refuted, failed, parked, cancelled, uncovered: uncovered.map((u) => u.slug) }))
     .digest('hex')
     .slice(0, 16);
-  const hasContent = [uncovered, verified, refuted, failed, parked].some((l) => l.length > 0);
+  const hasContent = [uncovered, verified, refuted, failed, parked, cancelled].some((l) => l.length > 0);
 
-  return { settled, uncovered, verified, refuted, failed, parked, digestKey, hasContent };
+  return { settled, uncovered, verified, refuted, failed, parked, cancelled, digestKey, hasContent };
 }
 
 module.exports = { evaluateEpicSettle, DEFAULT_SETTLE_HORIZON_MS };

package/src/main/lib/epic/epicValidationHook.cjs

@@ -52,6 +52,7 @@ function buildSettledDigest(settle, { epicId, notValidatedReason } = {}) {
   const refuted = s.refuted || [];
   const failed = s.failed || [];
   const parked = s.parked || [];
+  const cancelled = s.cancelled || [];
   const notValidated = (s.uncovered || []).map((u) => (typeof u === 'string' ? u : u.slug));
   const lines = [
     `PLAN SETTLED — no PRD of this session is pending or running. This is ONE digest, not a per-PRD request.`,
@@ -70,6 +71,12 @@ function buildSettledDigest(settle, { epicId, notValidatedReason } = {}) {
   if (parked.length) {
     lines.push('', `Parked (needs_review) (${parked.length}):`, ...parked.map((p) => `- ${p}`));
   }
+  if (cancelled.length) {
+    lines.push(
+      '', `Cancelled (${cancelled.length}) — stopped by scheduler_cancel_job; only scheduler_reset_job revives them:`,
+      ...cancelled.map((c) => `- ${c}`),
+    );
+  }
   if (notValidated.length) {
     lines.push(
       '', `Not validated (${notValidated.length}) — ${notValidatedReason || 'no validator checked them'}:`,

package/src/main/lib/git/depHealth.cjs

@@ -0,0 +1,161 @@
+/**
+ * depHealth.cjs — detect and repair a broken pnpm node_modules in the main checkout.
+ *
+ * Incident: a `pnpm install` run through a symlinked worktree node_modules purged
+ * the main checkout's modules dir, so every later gate went red with
+ * `Cannot find module .../node_modules/typescript/bin/tsc`. Recovery is
+ * `pnpm install --offline` in the main checkout; it needs CI=1 plus
+ * `--config.confirmModulesPurge=false`, otherwise pnpm prompts and aborts with
+ * ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.
+ *
+ * Second incident (Bilko, 2026-10-18): the same install rewrote 37 workspace links
+ * in the main checkout's node_modules to point into a job worktree; once the
+ * worktree was deleted they all dangled. Workspace packages are not in the root
+ * package.json deps, so the deps check missed it. findWorktreeEscapingLinks flags
+ * top-level links that resolve into a worktree root or dangle.
+ *
+ * Neither function throws. The check runs on the scheduler main loop, so it is
+ * O(deps) stats plus one bounded top-level readdir (no deep walks).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+const MAX_DEPS = 200;
+const MAX_MISSING = 20;
+const TAIL_CHARS = 2000;
+const MAX_SCANNED = 2000;
+
+function defaultWorktreeRoots() {
+  try {
+    const sp = require('../scheduler/schedulerPaths.cjs');
+    return [sp.worktreeRoot('job'), sp.worktreeRoot('epic')].filter((r) => typeof r === 'string' && r);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan node_modules/* and node_modules/@scope/* (lstat only, no deeper) for symlinks
+ * that resolve into a worktree root or whose target is gone.
+ * @param {string} mainCwd
+ * @param {{ worktreeRoots?: string[] }} [opts]
+ * @returns {{ intoWorktree: string[], dangling: string[] }}
+ */
+function findWorktreeEscapingLinks(mainCwd, opts = {}) {
+  const intoWorktree = [];
+  const dangling = [];
+  try {
+    const rawRoots = Array.isArray(opts.worktreeRoots) ? opts.worktreeRoots : defaultWorktreeRoots();
+    const roots = [];
+    for (const r of rawRoots) {
+      if (!r) continue;
+      roots.push(path.resolve(r));
+      try { roots.push(fs.realpathSync(r)); } catch { /* root absent */ }
+    }
+    const modules = path.join(mainCwd, 'node_modules');
+    let scanned = 0;
+    const check = (rel) => {
+      const full = path.join(modules, rel);
+      let target;
+      try {
+        target = fs.realpathSync(full);
+      } catch (e) {
+        if (dangling.length < MAX_MISSING) dangling.push(rel);
+        return;
+      }
+      if (roots.some((r) => target.startsWith(r + path.sep)) && intoWorktree.length < MAX_MISSING) {
+        intoWorktree.push(rel);
+      }
+    };
+    const entries = fs.readdirSync(modules, { withFileTypes: true });
+    outer: for (const ent of entries) {
+      if (ent.name.startsWith('.')) continue;
+      if (++scanned > MAX_SCANNED) break;
+      if (ent.name.startsWith('@')) {
+        let subs = [];
+        try { subs = fs.readdirSync(path.join(modules, ent.name), { withFileTypes: true }); } catch { continue; }
+        for (const sub of subs) {
+          if (sub.name.startsWith('.')) continue;
+          if (++scanned > MAX_SCANNED) break outer;
+          if (sub.isSymbolicLink()) check(`${ent.name}/${sub.name}`);
+        }
+      } else if (ent.isSymbolicLink()) {
+        check(ent.name);
+      }
+    }
+  } catch {
+    return { intoWorktree: [], dangling: [] };
+  }
+  return { intoWorktree, dangling };
+}
+
+/**
+ * @param {string} mainCwd
+ * @param {{ worktreeRoots?: string[] }} [opts]
+ * @returns {{ ok: boolean, skipped?: string, reason?: string, missing?: string[] }}
+ */
+function checkMainDependencyHealth(mainCwd, opts = {}) {
+  try {
+    if (!fs.existsSync(path.join(mainCwd, 'pnpm-lock.yaml'))) return { ok: true, skipped: 'not-pnpm' };
+    const modules = path.join(mainCwd, 'node_modules');
+    let isDir = false;
+    try { isDir = fs.statSync(modules).isDirectory(); } catch { /* missing */ }
+    if (!isDir) return { ok: false, reason: 'node_modules-missing' };
+    if (!fs.existsSync(path.join(modules, '.modules.yaml'))) return { ok: false, reason: 'modules-yaml-missing' };
+
+    const links = findWorktreeEscapingLinks(mainCwd, { worktreeRoots: opts && opts.worktreeRoots });
+    if (links.intoWorktree.length) return { ok: false, reason: 'links-into-worktree', missing: links.intoWorktree };
+    if (links.dangling.length) return { ok: false, reason: 'dangling-links', missing: links.dangling };
+
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(path.join(mainCwd, 'package.json'), 'utf8'));
+    } catch {
+      return { ok: true, skipped: 'no-package-json' };
+    }
+    if (!pkg || typeof pkg !== 'object') return { ok: true, skipped: 'no-package-json' };
+    const names = [
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+    ].slice(0, MAX_DEPS);
+    const missing = [];
+    for (const name of names) {
+      try {
+        fs.statSync(path.join(modules, name, 'package.json'));
+      } catch {
+        if (missing.length < MAX_MISSING) missing.push(name);
+      }
+    }
+    return missing.length ? { ok: false, reason: 'unresolved-deps', missing } : { ok: true };
+  } catch {
+    return { ok: true, skipped: 'no-package-json' };
+  }
+}
+
+/**
+ * @param {string} mainCwd
+ * @returns {Promise<{ ok: boolean, code: number|null, tail: string }>}
+ */
+function repairMainDependencies(mainCwd) {
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        process.env.SM_PNPM_BIN || 'pnpm',
+        ['install', '--offline', '--frozen-lockfile', '--config.confirmModulesPurge=false'],
+        { cwd: mainCwd, env: { ...process.env, CI: '1' }, timeout: 300_000, maxBuffer: 16 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          const tail = `${stdout || ''}${stderr || ''}`.slice(-TAIL_CHARS) || (err ? String(err.message) : '');
+          if (!err) return resolve({ ok: true, code: 0, tail });
+          resolve({ ok: false, code: typeof err.code === 'number' ? err.code : null, tail: tail || String(err.message) });
+        },
+      );
+    } catch (e) {
+      resolve({ ok: false, code: null, tail: String((e && e.message) || e) });
+    }
+  });
+}
+
+module.exports = { checkMainDependencyHealth, findWorktreeEscapingLinks, repairMainDependencies };