claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/lib/queueStore.cjs

@@ -31,14 +31,13 @@
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
-const os = require('node:os');
 const crypto = require('node:crypto');
 const { allProjectCwds, activeProjectCwds, bustProjectCwdCache } = require('./activeSessions.cjs');
+const { classifyCwd } = require('./cwdClassify.cjs');
 const { assertOpsWrite, resolveOpsRoot, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 const { ScheduleJobSchema } = require('./scheduleJobSchema.cjs');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
-const MACHINE_STATE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-machine.json');
-const LEGACY_QUEUE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'queue.json');
 const OPS_DIRNAME = OPS_ROOT_DIR;
 const STATE_SUBPATH = ['scheduler', 'state'];
 
@@ -118,7 +117,12 @@ function projectHistoryPath(cwd) {
  */
 function queuePathOrSkip(cwd, context) {
   try {
-    return projectQueuePath(cwd);
+    const file = projectQueuePath(cwd);
+    // Unprovable project identity: the row stays dispatchable and is never
+    // dropped or emptied — the write itself is refused by assertOpsWrite.
+    const { kind, reason } = classifyCwd(cwd);
+    if (kind === 'unknown') console.warn(`[queueStore] ${context}: project identity unprovable for "${cwd}" (${reason}) — reads allowed, writes refused`);
+    return file;
   } catch (e) {
     if (e?.ephemeral) {
       console.warn(`[queueStore] ${context}: refusing ephemeral cwd "${cwd}" — ${e.message}`);
@@ -190,8 +194,10 @@ async function writeJsonAtomic(file, value) {
 // list briefly. Correctness fallback: a brand-new project appears at worst
 // CACHE_MS late, and its first write goes through writeSplit which busts the
 // cache.
-const CACHE_MS = 30_000;
-let cwdCache = { at: 0, cwds: [] };
+// Above the 60 s dispatch-loop interval so one pass never re-scans cold; the
+// cached array is frozen (shared, never mutated).
+const CACHE_MS = 120_000;
+let cwdCache = { at: 0, cwds: Object.freeze([]) };
 
 function stateCwds(opts) {
   const now = Date.now();
@@ -205,12 +211,13 @@ function stateCwds(opts) {
   }
   // ...and active projects are included even before their first write.
   for (const cwd of activeProjectCwds(undefined, opts)) add(cwd);
+  Object.freeze(cwds);
   if (!opts) cwdCache = { at: now, cwds };
   return cwds;
 }
 
 function bustCwdCache() {
-  cwdCache = { at: 0, cwds: [] };
+  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
@@ -231,6 +238,10 @@ function shapeMachine(data) {
     // classifyQueueStarvation's header for why the two must never merge.
     lastDispatchAttemptAt: data.lastDispatchAttemptAt ?? null,
     paused: data.paused ?? null,
+    // Upgrade-drain state (lib/upgradeDrain.cjs): deliberately NOT part of
+    // `paused`, so a rate-limit pause can neither overwrite it nor have the
+    // manual-clear cooldown swallow it.
+    drain: data.drain && typeof data.drain === 'object' ? data.drain : null,
     // Launch circuit breaker (lib/launchFailure.cjs): per-persona blocks and
     // the degraded-mode env a persona is currently launching with. Machine
     // state, not per-project: the broken thing is the installed CLI.
@@ -291,7 +302,6 @@ function findLongestValidJsonPrefix(raw) {
 // project's own ops root is the natural home for a machine-level log entry,
 // mirroring scheduler.cjs's own `job.cwd || DEFAULT_PROJECT_CWD` fallback for
 // cwd-less machine errors (schedulerBatch.cjs's DEFAULT_PROJECT_CWD).
-const MACHINE_STATE_LOG_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
 
 // The truncated tail in the real 2026-09-11 tear contained an orphaned
 // `resumeAt` fragment with no way to reconstruct the `paused` object it
@@ -306,7 +316,7 @@ const PAUSED_HINT_RE = /"paused"|resumeAt/;
 function logMachineStateRecovery({ level, message, meta }) {
   try {
     const { appendError } = require('./opsErrorLog.cjs');
-    appendError({ cwd: MACHINE_STATE_LOG_CWD, scope: 'scheduler', level, message, meta });
+    appendError({ cwd: schedulerPaths.machineStateLogCwd(), scope: 'scheduler', level, message, meta });
   } catch { /* durable logging must never block recovery */ }
   console.error(`[queueStore] ${message}`);
 }
@@ -331,7 +341,7 @@ function buildMachineStateRecovery(raw, parseError) {
           ? '; the discarded tail looks like it contained paused/resumeAt data that could not '
             + 'be reconstructed — verify pause status manually'
           : ''),
-      meta: { path: MACHINE_STATE_PATH, prefixLength: prefix.prefixLength, totalLength: raw.length, pausedHint },
+      meta: { path: schedulerPaths.machineStatePath(), prefixLength: prefix.prefixLength, totalLength: raw.length, pausedHint },
     };
   }
   // No valid JSON prefix at all: fall back to defaults (shapeMachine({}) —
@@ -344,7 +354,7 @@ function buildMachineStateRecovery(raw, parseError) {
     message:
       `scheduler-machine.json unrecoverable (${parseError?.message}) — falling back to defaults `
       + 'so dispatch does not silently halt',
-    meta: { path: MACHINE_STATE_PATH, totalLength: raw.length },
+    meta: { path: schedulerPaths.machineStatePath(), totalLength: raw.length },
   };
 }
 
@@ -352,7 +362,7 @@ function recoverTornMachineStateSync(raw, parseError) {
   const recovery = buildMachineStateRecovery(raw, parseError);
   logMachineStateRecovery(recovery);
   try {
-    writeJsonAtomicSync(MACHINE_STATE_PATH, recovery.value);
+    writeJsonAtomicSync(schedulerPaths.machineStatePath(), recovery.value);
   } catch (e) {
     console.error(`[queueStore] failed to persist recovered machine state: ${e?.message}`);
   }
@@ -363,7 +373,7 @@ async function recoverTornMachineState(raw, parseError) {
   const recovery = buildMachineStateRecovery(raw, parseError);
   logMachineStateRecovery(recovery);
   try {
-    await writeJsonAtomic(MACHINE_STATE_PATH, recovery.value);
+    await writeJsonAtomic(schedulerPaths.machineStatePath(), recovery.value);
   } catch (e) {
     console.error(`[queueStore] failed to persist recovered machine state: ${e?.message}`);
   }
@@ -378,10 +388,10 @@ async function recoverTornMachineState(raw, parseError) {
 function loadMachineStateSync() {
   let raw;
   try {
-    raw = fs.readFileSync(MACHINE_STATE_PATH, 'utf8');
+    raw = fs.readFileSync(schedulerPaths.machineStatePath(), 'utf8');
   } catch (e) {
     if (e?.code === 'ENOENT') return {};
-    return { unreadable: `machine state unreadable: ${e?.message}`, unreadablePath: MACHINE_STATE_PATH };
+    return { unreadable: `machine state unreadable: ${e?.message}`, unreadablePath: schedulerPaths.machineStatePath() };
   }
   try {
     return { shaped: shapeMachine(JSON.parse(raw)) };
@@ -394,10 +404,10 @@ function loadMachineStateSync() {
 async function loadMachineState() {
   let raw;
   try {
-    raw = await fsp.readFile(MACHINE_STATE_PATH, 'utf8');
+    raw = await fsp.readFile(schedulerPaths.machineStatePath(), 'utf8');
   } catch (e) {
     if (e?.code === 'ENOENT') return {};
-    return { unreadable: `machine state unreadable: ${e?.message}`, unreadablePath: MACHINE_STATE_PATH };
+    return { unreadable: `machine state unreadable: ${e?.message}`, unreadablePath: schedulerPaths.machineStatePath() };
   }
   try {
     return { shaped: shapeMachine(JSON.parse(raw)) };
@@ -442,15 +452,17 @@ function shapeJobs(raw, file) {
 
 /**
  * readMergedSync(opts?) → { config, jobs, scheduledFor, lastRunAt, paused,
- * unreadable?, unreadablePath?, sourceCwds }.
+ * unreadable?, unreadablePath?, unreadableCwds, sourceCwds }.
  *
- * `unreadable` mirrors the old single-file semantics: ANY source file that
- * exists but fails to parse halts scheduling (never treat a project's queue
- * as empty because it read corrupt). `sourceCwds` records every project file
- * consulted so writeSplit can persist "this project now has zero jobs".
+ * `unreadable` is reserved for the machine-runtime file alone (a machine-wide
+ * halt). A project shard that exists but fails to read/parse is quarantined
+ * per cwd in `unreadableCwds: [{cwd, file, error}]` — other projects keep
+ * dispatching, and the torn shard is never treated as empty, recovered, or
+ * written. `sourceCwds` records every healthy project file consulted so
+ * writeSplit can persist "this project now has zero jobs".
  */
 function readMergedSync(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
   const sourceCwds = [];
   const machine = loadMachineStateSync();
   if (machine.shaped) {
@@ -473,8 +485,9 @@ function readMergedSync(opts) {
       sourceCwds.push(cwd);
     } catch (e) {
       if (e?.code === 'ENOENT') { sourceCwds.push(cwd); continue; }
-      out.unreadable = out.unreadable || `project queue unreadable (${file}): ${e?.message}`;
-      out.unreadablePath = out.unreadablePath || file;
+      // Quarantine this ONE shard; never recover or rewrite it (a job shard is a
+      // ledger — a prefix could time-travel a running row back to pending).
+      out.unreadableCwds.push({ cwd, file, error: e?.message ?? String(e) });
     }
   }
   defineSources(out, sourceCwds);
@@ -483,7 +496,7 @@ function readMergedSync(opts) {
 
 /** Async twin of readMergedSync for IPC hot paths. */
 async function readMerged(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
   const sourceCwds = [];
   const machine = await loadMachineState();
   if (machine.shaped) {
@@ -506,8 +519,9 @@ async function readMerged(opts) {
       sourceCwds.push(cwd);
     } catch (e) {
       if (e?.code === 'ENOENT') { sourceCwds.push(cwd); continue; }
-      out.unreadable = out.unreadable || `project queue unreadable (${file}): ${e?.message}`;
-      out.unreadablePath = out.unreadablePath || file;
+      // Quarantine this ONE shard; never recover or rewrite it (a job shard is a
+      // ledger — a prefix could time-travel a running row back to pending).
+      out.unreadableCwds.push({ cwd, file, error: e?.message ?? String(e) });
     }
   }
   defineSources(out, sourceCwds);
@@ -531,21 +545,25 @@ function defineSources(state, sourceCwds) {
  * deletions stick.
  */
 async function writeSplit(state, defaultCwd) {
-  await writeJsonAtomic(MACHINE_STATE_PATH, {
+  await writeJsonAtomic(schedulerPaths.machineStatePath(), {
     config: state.config,
     scheduledFor: state.scheduledFor ?? null,
     lastRunAt: state.lastRunAt ?? null,
     lastDispatchAttemptAt: state.lastDispatchAttemptAt ?? null,
     paused: state.paused ?? null,
+    drain: state.drain ?? null,
     launchBlocks: state.launchBlocks ?? {},
     launchMitigations: state.launchMitigations ?? {},
   });
 
+  // A quarantined shard is left byte-identical: never re-created or clobbered,
+  // even if merged rows carry that cwd.
+  const quarantined = new Set((state.unreadableCwds ?? []).map((u) => u.cwd));
   const byCwd = new Map();
-  for (const cwd of state.sourceCwds ?? []) byCwd.set(cwd, []);
+  for (const cwd of state.sourceCwds ?? []) if (!quarantined.has(cwd)) byCwd.set(cwd, []);
   for (const job of state.jobs ?? []) {
     const cwd = job.cwd || defaultCwd;
-    if (!cwd) continue; // nowhere to put it; job is dropped from persistence rather than crashing
+    if (!cwd || quarantined.has(cwd)) continue; // nowhere to put it; job is dropped from persistence rather than crashing
     if (!byCwd.has(cwd)) byCwd.set(cwd, []);
     byCwd.get(cwd).push(job);
   }
@@ -576,7 +594,7 @@ async function writeSplit(state, defaultCwd) {
 async function migrateLegacyGlobalQueue(defaultCwd) {
   let raw;
   try {
-    raw = await fsp.readFile(LEGACY_QUEUE_PATH, 'utf8');
+    raw = await fsp.readFile(schedulerPaths.legacyQueuePath(), 'utf8');
   } catch {
     return { migrated: false };
   }
@@ -588,8 +606,8 @@ async function migrateLegacyGlobalQueue(defaultCwd) {
     return { migrated: false, error: e?.message };
   }
 
-  if (!fs.existsSync(MACHINE_STATE_PATH)) {
-    await writeJsonAtomic(MACHINE_STATE_PATH, {
+  if (!fs.existsSync(schedulerPaths.machineStatePath())) {
+    await writeJsonAtomic(schedulerPaths.machineStatePath(), {
       config: legacy.config || {},
       scheduledFor: legacy.scheduledFor ?? null,
       lastRunAt: legacy.lastRunAt ?? null,
@@ -622,14 +640,12 @@ async function migrateLegacyGlobalQueue(defaultCwd) {
     }
   }
 
-  await fsp.rename(LEGACY_QUEUE_PATH, `${LEGACY_QUEUE_PATH}.retired-${Date.now()}`);
+  await fsp.rename(schedulerPaths.legacyQueuePath(), `${schedulerPaths.legacyQueuePath()}.retired-${Date.now()}`);
   bustCwdCache();
   return { migrated: true, moved, projects: byCwd.size };
 }
 
 module.exports = {
-  MACHINE_STATE_PATH,
-  LEGACY_QUEUE_PATH,
   STATE_SUBPATH,
   projectStateDir,
   projectQueuePath,
@@ -645,3 +661,7 @@ module.exports = {
   writeJsonAtomicSync,
   findLongestValidJsonPrefix,
 };
+
+// Lazy path getters (SM_SCHEDULER_HOME resolved at read, never at require).
+Object.defineProperty(module.exports, 'MACHINE_STATE_PATH', { get: schedulerPaths.machineStatePath, enumerable: true });
+Object.defineProperty(module.exports, 'LEGACY_QUEUE_PATH', { get: schedulerPaths.legacyQueuePath, enumerable: true });

package/src/main/lib/quietMachineLease.cjs

@@ -12,17 +12,22 @@
  */
 'use strict';
 
+const { appendAuditEvent } = require('./auditLog.cjs');
+const { isProvablyDead, DEFAULT_GRACE_MS } = require('./reservationExpiry.cjs');
+
 // slug of the job currently holding the lease, or null.
 let heldBySlug = null;
+let heldClaimedAt = 0;
 
 function isHeld() {
   return heldBySlug !== null;
 }
 
 /** acquire(slug) → true if the lease was free and is now held by `slug`. */
-function acquire(slug) {
+function acquire(slug, { claimedAt = Date.now() } = {}) {
   if (heldBySlug !== null) return false;
   heldBySlug = String(slug);
+  heldClaimedAt = claimedAt;
   return true;
 }
 
@@ -36,6 +41,17 @@ function release(slug) {
   return true;
 }
 
+/** expireDead — free a lease whose holder has no running row and is past the grace window
+ * (the lease never carries a pid; the row-liveness + grace proof is the whole test). */
+function expireDead({ liveSlugs, now = Date.now(), graceMs = DEFAULT_GRACE_MS } = {}) {
+  if (heldBySlug === null) return false;
+  const live = liveSlugs instanceof Set ? liveSlugs : new Set(liveSlugs || []);
+  if (!isProvablyDead({ claimedAt: heldClaimedAt, pid: null }, { live: live.has(heldBySlug), now, graceMs })) return false;
+  appendAuditEvent('quiet_lease_expired', { slug: heldBySlug });
+  heldBySlug = null;
+  return true;
+}
+
 function holder() {
   return heldBySlug;
 }
@@ -43,6 +59,7 @@ function holder() {
 /** Test hook: force the lease back to free. */
 function __resetForTests() {
   heldBySlug = null;
+  heldClaimedAt = 0;
 }
 
-module.exports = { isHeld, acquire, release, holder, __resetForTests };
+module.exports = { isHeld, acquire, release, expireDead, holder, __resetForTests };

package/src/main/lib/reservationExpiry.cjs

@@ -0,0 +1,30 @@
+/**
+ * reservationExpiry.cjs — the single fail-CLOSED "is this reservation's owner
+ * provably dead?" predicate shared by sessionSlots, quietMachineLease, the
+ * investigation set and gitWorktree's accounting. A reservation is released
+ * only on proof: no live row for its slug AND (a stamped pid that is dead, or
+ * no pid ever stamped and claimedAt older than graceMs). Anything ambiguous
+ * (live row, live pid, inside the grace window, claimed after the pass began)
+ * is kept. Never signals a process.
+ */
+'use strict';
+
+const DEFAULT_GRACE_MS = 10 * 60 * 1000;
+
+function defaultPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === 'EPERM'; }
+}
+
+/**
+ * @param {{ claimedAt: number, pid: number|null }} res
+ * @param {{ live: boolean, pidAlive?: (pid:number)=>boolean, now: number, graceMs?: number }} ctx
+ */
+function isProvablyDead(res, { live, pidAlive = defaultPidAlive, now, graceMs = DEFAULT_GRACE_MS }) {
+  if (live) return false;
+  // Made after the pass began (i.e. this tick) — never expire it.
+  if (!Number.isFinite(res.claimedAt) || res.claimedAt > now) return false;
+  if (Number.isInteger(res.pid) && res.pid > 0) return !pidAlive(res.pid);
+  return now - res.claimedAt > graceMs;
+}
+
+module.exports = { isProvablyDead, defaultPidAlive, DEFAULT_GRACE_MS };

package/src/main/lib/runClaudeP.cjs

@@ -15,7 +15,8 @@
  */
 
 const { spawn } = require('node:child_process');
-const { resolveClaudeBin } = require('./claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
+const { withProcRole } = require('./cleanEnv.cjs');
 
 const MAX_OUT_BYTES = 8 * 1024 * 1024;
 
@@ -31,7 +32,8 @@ function runClaudeP(prompt, { model = 'sonnet', timeoutMs = 180_000, systemPromp
       '--output-format', 'text',
     ];
     if (systemPrompt) args.push('--append-system-prompt', systemPrompt);
-    const child = spawn(bin, args, { env: { ...process.env, SM_KG_INTERNAL: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    const target = claudeSpawnTarget('aux', 'runclaudep', bin);
+    const child = spawn(target.command, args, { env: withProcRole({ ...process.env, SM_KG_INTERNAL: '1' }, 'aux'), stdio: ['ignore', 'pipe', 'pipe'], ...(target.argv0 ? { argv0: target.argv0 } : {}) });
     let out = '';
     let err = '';
     let killedForSize = false;

package/src/main/lib/runLogRetention.cjs

@@ -12,7 +12,8 @@
  *
  * Directory shape: one subdirectory per tick (`RUNS_DIR/<iso-ts>/`, minted by
  * scheduler.cjs's pickRunDir), which commonly holds MANY different PRD
- * slugs' artifacts side by side — `<slug>.log`, `<slug>.meta.json`, and an
+ * slugs' artifacts side by side — `<slug>.log`, `<slug>.meta.json`, the
+ * `<slug>.supervisor.json` dispatch record (jobSupervisorRecord.cjs), and an
  * optional `root-cause-<slug>.md` (rcaReport.cjs) per slug. Retention is
  * therefore computed per (runId, slug) ENTRY, not per directory: a directory
  * is only "fully removable" once every entry it holds is independently
@@ -131,7 +132,7 @@ function scanRunEntries(runsDir) {
     for (const metaFile of metaFiles) {
       const slug = metaFile.slice(0, -META_SUFFIX.length);
       const relatedNames = files.filter(
-        (f) => f === metaFile || f === `${slug}.log` || f === `root-cause-${slug}.md`
+        (f) => f === metaFile || f === `${slug}.log` || f === `${slug}.supervisor.json` || f === `root-cause-${slug}.md`
       );
 
       let sizeBytes = 0;

package/src/main/lib/scheduleJobSchema.cjs

@@ -1,6 +1,6 @@
 /**
  * Canonical runtime schema for a ScheduleJob record, mirroring the TS
- * `ScheduleJob` interface at src/preload/api.d.ts:375-422 field-for-field.
+ * `ScheduleJob` interface (`ScheduleJob` in src/preload/api.d.ts) field-for-field.
  *
  * Modelled directly on promptSessionSchema.cjs's "zod schema asserted at the
  * main-process boundary" pattern: the Epic entity has had this guarantee
@@ -52,7 +52,7 @@ const ScheduleJobStatusHistoryEntrySchema = z
   .passthrough();
 
 // Only `slug` and `status` are required. Every other ScheduleJob field
-// (src/preload/api.d.ts:375-422) is declared here for documentation and type
+// (`ScheduleJob` in src/preload/api.d.ts) is declared here for documentation and type
 // checking when present, but kept optional: a job row moves through several
 // legitimate partial shapes across its life (freshly minted with nulls,
 // mid-run with runtime fields, terminal with exitCode/error) and plenty of

package/src/main/lib/scheduleJobTransitions.cjs

@@ -207,7 +207,23 @@ function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } =
   // Fire-and-forget, exactly like every other best-effort side-channel write
   // in this codebase (rcaReport.cjs, auditLog.cjs's own posture) — a ledger
   // write failure must never fail or delay the transition it's recording.
-  if (toStatus === 'needs_review' && from !== 'needs_review') {
+  // 'investigating' is a PAUSE, not a resolution, when it's reached FROM
+  // needs_review: spawnInvestigation always restores the job to exactly the
+  // status it left (a snapshot taken before the pause), so
+  // needs_review -> investigating -> needs_review is one continuous episode,
+  // not two. Without this check, the pause mints a spurious 'auto-fix'
+  // resolution mid-episode, then the resume mints a spurious fresh entry
+  // that overwrites the original episode's runId/enteredAt/reason in the
+  // ledger's by-key maps (keyed on slug+runId) — corrupting byLadderRung and
+  // understating dwell time. Detected via the stamped episode fields
+  // themselves rather than the transition's source string, since the same
+  // 'investigating' status is also reached fresh from 'failed' (a job that
+  // was never parked needs_review at all, and has no episode to pause).
+  const isNeedsReviewPause = from === 'needs_review' && toStatus === 'investigating';
+  const pausedEpisodeOpen = job.needsReviewEntryRunId !== undefined;
+  const isNeedsReviewResume = from === 'investigating' && pausedEpisodeOpen;
+
+  if (toStatus === 'needs_review' && from !== 'needs_review' && !isNeedsReviewResume) {
     // ENTRY: stamp the episode's runId/enteredAt on the job itself so the
     // RESOLUTION line (below) can reference the SAME runId even if the job's
     // own `runId` is reassigned in between (e.g. a resume-recovery
@@ -217,9 +233,17 @@ function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } =
     queueHistory.appendHistory([buildNeedsReviewEntryLine(job, entry)]).catch((e) => {
       console.error('[scheduleJobTransitions] failed to append needs_review entry', e?.message ?? String(e));
     });
-  } else if (from === 'needs_review' && toStatus !== 'needs_review') {
+  } else if (
+    (from === 'needs_review' && toStatus !== 'needs_review' && !isNeedsReviewPause)
+    || (isNeedsReviewResume && toStatus !== 'needs_review')
+  ) {
     // RESOLUTION: read the episode stamped at entry, then clear it — the
     // episode is over regardless of what this resolution line looks like.
+    // The `isNeedsReviewResume` arm covers an episode that paused for
+    // investigation and is now resolving to something other than
+    // needs_review (e.g. the investigation actually fixed it) — the episode
+    // stamps were deliberately left untouched across the pause, so this
+    // still references the ORIGINAL entry time, not the pause's.
     const episode = { runId: job.needsReviewEntryRunId ?? null, enteredAt: job.needsReviewEnteredAt ?? null };
     delete job.needsReviewEntryRunId;
     delete job.needsReviewEnteredAt;
@@ -227,6 +251,9 @@ function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } =
       console.error('[scheduleJobTransitions] failed to append needs_review resolution', e?.message ?? String(e));
     });
   }
+  // else: isNeedsReviewPause (needs_review -> investigating), or
+  // isNeedsReviewResume && toStatus === 'needs_review' (investigating ->
+  // needs_review, still the same open episode) — intentionally a no-op.
 
   return true;
 }

package/src/main/lib/schedulerBatch.cjs

@@ -75,7 +75,7 @@ function dedupeCycles(cycles) {
   return out;
 }
 
-function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
+function makeDepResolver(projectJobs, satisfiedSlugs = new Set()) {
   const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
   const rowsByBareSlug = new Map();
   for (const j of projectJobs) {
@@ -102,6 +102,31 @@ function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
     }
     return satisfiedBareSlugs.has(bareSlug(slug));
   };
+  return { rowsForDep, isKnownSatisfied };
+}
+
+/**
+ * findUnresolvableDepRoots(projectJobs, satisfiedSlugs) → string[]
+ *
+ * Pure. The dep slugs that name NO live row and NO completion/archive record
+ * — the roots findBlockingDep holds as 'unresolved'. Unlike a failed/pending
+ * dep row, nothing in the queue will ever change one of these; only a human
+ * (or a restored record) can. Sorted, de-duplicated. O(jobs + deps).
+ */
+function findUnresolvableDepRoots(projectJobs, satisfiedSlugs = new Set()) {
+  const { rowsForDep, isKnownSatisfied } = makeDepResolver(projectJobs, satisfiedSlugs);
+  const roots = new Set();
+  for (const j of projectJobs) {
+    if (j.status !== 'pending') continue;
+    for (const dep of j.dependsOn ?? []) {
+      if (rowsForDep(dep).length === 0 && !isKnownSatisfied(dep)) roots.add(dep);
+    }
+  }
+  return [...roots].sort();
+}
+
+function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
+  const { rowsForDep, isKnownSatisfied } = makeDepResolver(projectJobs, satisfiedSlugs);
   // A dep row is blocking unless it's 'completed', OR it's a 'skipped' row
   // stamped `needsReviewAutoResolvedSkip` — the bounded needs_review
   // auto-resolve terminal decision (scheduler.cjs's
@@ -658,6 +683,6 @@ function findStarvedProjects(jobs, now, thresholdMs) {
 }
 
 module.exports = {
-  pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, DEFAULT_PROJECT_CWD,
+  pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, findUnresolvableDepRoots, DEFAULT_PROJECT_CWD,
   DEP_HISTORY_FAIL_OPEN,
 };