claude-code-session-manager 0.79.0 → 0.81.0

package/src/main/__tests__/scheduler-reap-dead-running-jobs.test.cjs

@@ -223,7 +223,11 @@ test('reapDeadRunningJobs salvages a delta-scoped in-place patch (PRD 1098) when
 
   const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
   const row = jobs.find((j) => j.slug === 'vanished-inplace');
-  assert.equal(row.status, 'completed');
+  // PRD 1133: a successful-looking reap that left everything uncommitted
+  // (no branch, HEAD never moved) must never read as 'completed' — this is
+  // exactly the dangerous shape the reaper now proves against.
+  assert.equal(row.status, 'needs_review');
+  assert.equal(row.verifierVerdict, 'reaped_without_integration');
   assert.ok(row.salvagePatch, 'a salvage patch must be recorded on the row');
   assert.ok(fs.existsSync(row.salvagePatch));
   const patch = fs.readFileSync(row.salvagePatch, 'utf8');
@@ -332,8 +336,207 @@ test('reapDeadRunningJobs skips in-place salvage (no whole-tree dump) when the r
 
   const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
   const row = jobs.find((j) => j.slug === 'vanished-no-baseline');
-  assert.equal(row.status, 'completed');
+  // PRD 1133: no commit landed (HEAD never moved) — must not read as 'completed'
+  // just because the log's own result event looked clean.
+  assert.equal(row.status, 'needs_review');
+  assert.equal(row.verifierVerdict, 'reaped_without_integration');
   assert.equal(row.salvagePatch, undefined, 'must skip salvage entirely rather than ever dumping the whole tree');
   assert.equal(row.leftoverPaths, undefined, 'no baseline means no safe attribution — must not guess');
   assert.equal(row.leftoverCount, undefined);
 });
+
+// ---------- PRD 1133: reaper must prove integration before 'completed' ----------
+
+test('reapDeadRunningJobs: a worktree job shaped like PRD 1118 (branch un-integrated, landedCommit absent) comes out needs_review, naming the branch, and never merges it', async () => {
+  const projectCwd = path.join(tmpHome, 'i-project-1118-shape');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const headBefore = git(['rev-parse', 'HEAD'], projectCwd).trim();
+  const slug = '1118-pause-until-the-binding-rate-limit-window';
+  const branch = `sm-job/${slug}`;
+  // Simulate the job's own worktree branch: one real commit, never merged
+  // back into the main tree (exactly the live 1118 shape — "one real commit,
+  // +301", stranded on sm-job/1118-... with landedCommit undefined).
+  git(['checkout', '-b', branch], projectCwd);
+  fs.writeFileSync(path.join(projectCwd, 'rateLimitWindow.cjs'), 'module.exports = {};\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'add rateLimitWindow.cjs'], projectCwd);
+  // Back to the original tip (detached is fine — reap only reads guardCwd's
+  // current HEAD, it never needs a named branch checked out).
+  git(['checkout', headBefore], projectCwd);
+
+  const runId = `run-${slug}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 }, // guaranteed-dead pid
+      guardHeadBefore: headBefore,
+      startedAt: new Date(Date.now() - 60_000).toISOString(),
+    },
+  ]);
+  writeRunLog(runId, slug, ['{"type":"result","subtype":"success","result":"done","is_error":false}']);
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  assert.equal(row.status, 'needs_review', 'a successful-looking result event must not be enough on its own');
+  assert.equal(row.verifierVerdict, 'reaped_without_integration');
+  assert.match(row.error, new RegExp(branch.replace('/', '\\/')), 'the parked reason must name the branch that still holds the work');
+  assert.equal(row.landedCommit, undefined, 'nothing was actually merged, so landedCommit must stay unset');
+
+  // The branch itself must survive untouched — this reap must never attempt
+  // (let alone perform) the merge.
+  const branchStillExists = git(['rev-parse', '--verify', branch], projectCwd).trim();
+  assert.ok(branchStillExists, 'the un-integrated branch must be preserved, not merged or deleted, by a mere reap');
+  assert.equal(git(['rev-parse', 'HEAD'], projectCwd).trim(), headBefore, 'guardCwd HEAD must not have moved — no merge was performed');
+});
+
+test('reapDeadRunningJobs: a worktree job whose branch is already fully integrated into HEAD comes out completed, with landedCommit stamped', async () => {
+  const projectCwd = path.join(tmpHome, 'j-project-real-success');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const headBefore = git(['rev-parse', 'HEAD'], projectCwd).trim();
+  const slug = 'real-successful-worktree-run';
+  const branch = `sm-job/${slug}`;
+  git(['checkout', '-b', branch], projectCwd);
+  fs.writeFileSync(path.join(projectCwd, 'feature.txt'), 'shipped\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'ship feature'], projectCwd);
+  git(['checkout', headBefore], projectCwd); // back to the pre-branch tip (detached)
+  // Simulate a normal completion pass having already integrated the branch
+  // (integrateJobBranch's own fast-forward path) BEFORE the process vanished
+  // between that merge and the queue write landing.
+  git(['merge', '--ff-only', branch], projectCwd);
+  const headAfterMerge = git(['rev-parse', 'HEAD'], projectCwd).trim();
+
+  const runId = `run-${slug}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      guardHeadBefore: headBefore,
+      startedAt: new Date(Date.now() - 60_000).toISOString(),
+    },
+  ]);
+  writeRunLog(runId, slug, ['{"type":"result","subtype":"success","result":"done","is_error":false}']);
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  assert.equal(row.status, 'completed', 'the branch is already an ancestor of HEAD — the work genuinely landed');
+  assert.equal(row.verifierVerdict, undefined);
+  assert.equal(row.landedCommit, headAfterMerge, 'HEAD advanced during the run window — landedCommit must be stamped');
+});
+
+test('reapDeadRunningJobs: a worktree job whose branch never diverged from its base (legitimate no-op) still completes, not punished', async () => {
+  const projectCwd = path.join(tmpHome, 'k-project-noop-worktree');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const headBefore = git(['rev-parse', 'HEAD'], projectCwd).trim();
+  const slug = 'noop-worktree-job';
+  const branch = `sm-job/${slug}`;
+  // Branch created but nothing ever committed on it — a genuine no-op run.
+  git(['branch', branch], projectCwd);
+
+  const runId = `run-${slug}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      guardHeadBefore: headBefore,
+      startedAt: new Date(Date.now() - 60_000).toISOString(),
+    },
+  ]);
+  writeRunLog(runId, slug, ['{"type":"result","subtype":"success","result":"done","is_error":false}']);
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  assert.equal(row.status, 'completed', 'a branch with no new commits is a legitimate no-op, not a finish-protocol violation');
+  assert.equal(row.verifierVerdict, undefined);
+  assert.equal(row.landedCommit, undefined, 'HEAD never moved — nothing to stamp');
+});
+
+test('reapDeadRunningJobs: an in-place run in a git repo whose HEAD genuinely advanced during the run window completes, with landedCommit stamped', async () => {
+  const projectCwd = path.join(tmpHome, 'l-project-inplace-success');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const headBefore = git(['rev-parse', 'HEAD'], projectCwd).trim();
+  const startedAt = new Date(Date.now() - 60_000).toISOString();
+  fs.writeFileSync(path.join(projectCwd, 'shipped.txt'), 'done\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'in-place job commit'], projectCwd);
+  const headAfter = git(['rev-parse', 'HEAD'], projectCwd).trim();
+
+  const slug = 'inplace-job-real-commit';
+  const runId = `run-${slug}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      guardHeadBefore: headBefore,
+      startedAt,
+    },
+  ]);
+  writeRunLog(runId, slug, ['{"type":"result","subtype":"success","result":"done","is_error":false}']);
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  assert.equal(row.status, 'completed');
+  assert.equal(row.verifierVerdict, undefined);
+  assert.equal(row.landedCommit, headAfter);
+});
+
+test('reapDeadRunningJobs: a non-git cwd skips the integration check entirely, preserving today\'s behaviour', async () => {
+  const projectCwd = path.join(tmpHome, 'm-project-non-git');
+  fs.mkdirSync(projectCwd, { recursive: true });
+  registerActiveProject(projectCwd);
+
+  const slug = 'non-git-cwd-job';
+  const runId = `run-${slug}`;
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 },
+      // No git repo at all — the integration/HEAD-advance check must be
+      // skipped, never treated as a failure to prove landing.
+    },
+  ]);
+  writeRunLog(runId, slug, ['{"type":"result","subtype":"success","result":"done","is_error":false}']);
+
+  bustCwdCache();
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  assert.equal(row.status, 'completed', 'a non-git cwd must keep today\'s behaviour — the check is meaningless there');
+  assert.equal(row.verifierVerdict, undefined);
+});

package/src/main/__tests__/scheduler-reconcile-quarantine.test.cjs

@@ -146,6 +146,57 @@ test('reconcile() exempts a fix-plan PRD (NN-fix-*) from quarantine even with no
   }
 });
 
+test('reconcile() does NOT stamp investigationDepth for a createdVia-stamped PRD whose slug merely starts with "fix-" (PRD 1126/1131 regression)', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-fake-fixplan-');
+  try {
+    // Mirrors PRD 1126: authored via scheduler_create_prd (createdVia stamped),
+    // slug happens to kebab-case into "fix-..." — must NOT be treated as a
+    // genuine scheduler-authored fix plan just because the name matches.
+    fs.writeFileSync(
+      path.join(prdsDir, '9005-fix-plan-death-reopens-parent.md'),
+      `---\ntitle: Fix plan death reopens parent\ncwd: ${cwd}\nestimateMinutes: 15\ncreatedVia: scheduler-api\nissuedAt: 2026-08-07T00:00:00.000Z\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9005-fix-plan-death-reopens-parent');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+    expect(row.isFixPlan).toBe(false);
+    expect(row.investigationDepth).toBeUndefined();
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() stamps isFixPlan + investigationDepth for a genuine spawnInvestigation-authored fix plan (explicit isFixPlan:true, no createdVia)', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-genuine-fixplan-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9006-fix-something.md'),
+      `---\ntitle: Fix something\ncwd: ${cwd}\nestimateMinutes: 15\nisFixPlan: true\n---\n\n# Goal\nHeal it.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9006-fix-something');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+    expect(row.isFixPlan).toBe(true);
+    expect(row.investigationDepth).toBe(2);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
 test('reconcile() adopts a quarantined row to pending once its PRD file is stamped', async () => {
   const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-adopt-');
   try {

package/src/main/__tests__/scheduler-resume-recovery.test.cjs

@@ -0,0 +1,254 @@
+/**
+ * scheduler-resume-recovery.test.cjs — PRD 1111: resume-first recovery for a
+ * job parked in needs_review with verdict 'uncommitted_changes'. Before this
+ * feature, every such job went straight to spawnInvestigation (a cold-read
+ * fix-plan PRD authored by a FRESH session with no memory of the run it's
+ * diagnosing). This suite covers selectResumeRecoveryTarget's eligibility
+ * table, the --resume vs --session-id argv split (buildClaudeSpawnArgs), the
+ * preamble builder, the one-attempt bound, the SM_RESUME_RECOVERY_DISABLE
+ * kill-switch, and the two skip-gates (spawnInvestigation, selectAutoFixTargets).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-resume-recovery.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const {
+  selectResumeRecoveryTarget,
+  buildResumeRecoveryPreamble,
+  buildClaudeSpawnArgs,
+  selectAutoFixTargets,
+  spawnInvestigation,
+} = require('../scheduler.cjs');
+
+const savedDisable = process.env.SM_RESUME_RECOVERY_DISABLE;
+afterEach(() => {
+  if (savedDisable === undefined) delete process.env.SM_RESUME_RECOVERY_DISABLE;
+  else process.env.SM_RESUME_RECOVERY_DISABLE = savedDisable;
+});
+
+function baseJob(overrides = {}) {
+  return {
+    slug: '900-example',
+    status: 'needs_review',
+    verifierVerdict: 'uncommitted_changes',
+    sessionId: 'sess-abc-123',
+    uncommittedPaths: ['src/foo.js', 'src/bar.js'],
+    ...overrides,
+  };
+}
+
+// ---------- selectResumeRecoveryTarget eligibility table ----------
+
+test('selectResumeRecoveryTarget: eligible shape returns a resume decision', () => {
+  const target = selectResumeRecoveryTarget(baseJob());
+  expect(target).toEqual({
+    slug: '900-example',
+    sessionId: 'sess-abc-123',
+    dirtyPaths: ['src/foo.js', 'src/bar.js'],
+    salvagePatch: null,
+  });
+});
+
+test('selectResumeRecoveryTarget: carries salvagePatch through when present on the row', () => {
+  const target = selectResumeRecoveryTarget(baseJob({ salvagePatch: '/tmp/runs/x/900-example.uncommitted.patch' }));
+  expect(target.salvagePatch).toBe('/tmp/runs/x/900-example.uncommitted.patch');
+});
+
+const notNeedsReviewStatuses = ['pending', 'running', 'investigating', 'completed', 'failed', 'skipped'];
+for (const status of notNeedsReviewStatuses) {
+  test(`selectResumeRecoveryTarget: status=${status} → null`, () => {
+    expect(selectResumeRecoveryTarget(baseJob({ status }))).toBeNull();
+  });
+}
+
+const nonRecoverableVerdicts = [
+  'silent_no_op',
+  'pass_no_commit_already_shipped',
+  'pass_no_commit_prior_run_verified',
+  'transcript_errors',
+  'deps_unmet',
+  'halt',
+  'verify_unavailable',
+  'worktree_integration_failed',
+  'shared_tree_reverted',
+  undefined,
+];
+for (const verdict of nonRecoverableVerdicts) {
+  test(`selectResumeRecoveryTarget: verdict=${JSON.stringify(verdict)} → null`, () => {
+    expect(selectResumeRecoveryTarget(baseJob({ verifierVerdict: verdict }))).toBeNull();
+  });
+}
+
+test('selectResumeRecoveryTarget: missing sessionId → null', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ sessionId: undefined }))).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: empty-string sessionId → null', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ sessionId: '' }))).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: non-string sessionId → null', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ sessionId: 12345 }))).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: resumeRecoveryAttempted === true → null (bounded to one attempt)', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ resumeRecoveryAttempted: true }))).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: resumeRecoveryAttempted absent/false → still eligible', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ resumeRecoveryAttempted: false }))).not.toBeNull();
+  expect(selectResumeRecoveryTarget(baseJob())).not.toBeNull();
+});
+
+test('selectResumeRecoveryTarget: no recorded dirty paths → null', () => {
+  expect(selectResumeRecoveryTarget(baseJob({ uncommittedPaths: [] }))).toBeNull();
+  expect(selectResumeRecoveryTarget(baseJob({ uncommittedPaths: undefined }))).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: null/undefined job → null', () => {
+  expect(selectResumeRecoveryTarget(null)).toBeNull();
+  expect(selectResumeRecoveryTarget(undefined)).toBeNull();
+});
+
+test('selectResumeRecoveryTarget: SM_RESUME_RECOVERY_DISABLE=1 → null even for an otherwise-eligible job', () => {
+  process.env.SM_RESUME_RECOVERY_DISABLE = '1';
+  expect(selectResumeRecoveryTarget(baseJob())).toBeNull();
+});
+
+// ---------- --resume vs --session-id argv (buildClaudeSpawnArgs) ----------
+
+test('buildClaudeSpawnArgs: resume=true passes --resume <sessionId>, never --session-id', () => {
+  const args = buildClaudeSpawnArgs({ prompt: 'preamble text', model: 'sonnet', sessionId: 'sess-abc-123', resume: true });
+  expect(args).toContain('--resume');
+  expect(args[args.indexOf('--resume') + 1]).toBe('sess-abc-123');
+  expect(args).not.toContain('--session-id');
+});
+
+test('buildClaudeSpawnArgs: resume=false passes --session-id <sessionId>, never --resume', () => {
+  const args = buildClaudeSpawnArgs({ prompt: 'prd body', model: 'sonnet', sessionId: 'sess-fresh-456', resume: false });
+  expect(args).toContain('--session-id');
+  expect(args[args.indexOf('--session-id') + 1]).toBe('sess-fresh-456');
+  expect(args).not.toContain('--resume');
+});
+
+test('buildClaudeSpawnArgs: --model is always explicitly pinned, both modes', () => {
+  for (const resume of [true, false]) {
+    const args = buildClaudeSpawnArgs({ prompt: 'x', model: 'sonnet', sessionId: 'sid', resume });
+    const modelIdx = args.indexOf('--model');
+    expect(modelIdx).toBeGreaterThanOrEqual(0);
+    expect(args[modelIdx + 1]).toBe('sonnet');
+  }
+});
+
+// ---------- preamble content (buildResumeRecoveryPreamble) ----------
+
+test('buildResumeRecoveryPreamble: contains every recorded dirty path', () => {
+  const dirtyPaths = ['src/main/scheduler.cjs', 'session-manager-operations/scheduler/prds/900-example.md'];
+  const preamble = buildResumeRecoveryPreamble({ dirtyPaths, salvagePatch: null });
+  for (const p of dirtyPaths) {
+    expect(preamble).toContain(p);
+  }
+});
+
+test('buildResumeRecoveryPreamble: does NOT re-embed a PRD body passed in as an unrelated string', () => {
+  const prdBody = '# Goal\nSome long PRD body that must never appear in a resume preamble.\n## Acceptance criteria\n- [ ] thing';
+  const preamble = buildResumeRecoveryPreamble({ dirtyPaths: ['a.js'], salvagePatch: null });
+  expect(preamble).not.toContain(prdBody);
+  expect(preamble).not.toContain('Acceptance criteria');
+});
+
+test('buildResumeRecoveryPreamble: instructs verifying paths on disk, foreground gate, and commit', () => {
+  const preamble = buildResumeRecoveryPreamble({ dirtyPaths: ['a.js'], salvagePatch: null });
+  expect(preamble).toMatch(/verify/i);
+  expect(preamble).toMatch(/FOREGROUND/);
+  expect(preamble).toMatch(/commit/i);
+});
+
+test('buildResumeRecoveryPreamble: mentions the salvage patch path when present', () => {
+  const preamble = buildResumeRecoveryPreamble({ dirtyPaths: ['a.js'], salvagePatch: '/tmp/runs/x/900-example.uncommitted.patch' });
+  expect(preamble).toContain('/tmp/runs/x/900-example.uncommitted.patch');
+});
+
+// ---------- selectAutoFixTargets skips resume-eligible jobs ----------
+
+test('selectAutoFixTargets: excludes a job selectResumeRecoveryTarget accepts', () => {
+  const job = baseJob({ runId: 'run-1' });
+  const targets = selectAutoFixTargets([job], {
+    fixSlugExists: () => false,
+    resolveJobRunId: () => job.runId,
+  });
+  expect(targets).toEqual([]);
+});
+
+test('selectAutoFixTargets: still selects a needs_review job that is NOT resume-eligible (different verdict)', () => {
+  const job = baseJob({ runId: 'run-1', verifierVerdict: 'transcript_errors' });
+  const targets = selectAutoFixTargets([job], {
+    fixSlugExists: () => false,
+    resolveJobRunId: () => job.runId,
+  });
+  expect(targets.map((t) => t.slug)).toEqual([job.slug]);
+});
+
+test('selectAutoFixTargets: a resume-recovery-exhausted job (resumeRecoveryAttempted=true) falls through to normal auto-fix eligibility', () => {
+  const job = baseJob({ runId: 'run-1', resumeRecoveryAttempted: true });
+  const targets = selectAutoFixTargets([job], {
+    fixSlugExists: () => false,
+    resolveJobRunId: () => job.runId,
+  });
+  expect(targets.map((t) => t.slug)).toEqual([job.slug]);
+});
+
+// ---------- resume-then-fail: never a dead end ----------
+
+test('resume-then-fail: a job whose one resume attempt is spent falls through to the normal fix-plan path, not a dead end', () => {
+  // spawnResumeRecovery reuses spawnJob wholesale, so a resume run that
+  // itself re-parks in needs_review runs through the SAME finalize mutate as
+  // any other run — the only difference is resumeRecoveryAttempted is now
+  // true on the row (stamped atomically with the 'running' transition
+  // before the resume child ever spawned).
+  const jobAfterFailedResume = baseJob({ runId: 'run-2', resumeRecoveryAttempted: true });
+  // A second resume is refused...
+  expect(selectResumeRecoveryTarget(jobAfterFailedResume)).toBeNull();
+  // ...but the job is NOT stranded: it is offered for a fix-plan exactly
+  // like any other needs_review job, via the same gate spawnInvestigation's
+  // periodic caller (reverifyNeedsReview) consults.
+  const targets = selectAutoFixTargets([jobAfterFailedResume], {
+    fixSlugExists: () => false,
+    resolveJobRunId: () => jobAfterFailedResume.runId,
+  });
+  expect(targets.map((t) => t.slug)).toEqual([jobAfterFailedResume.slug]);
+});
+
+// ---------- spawnInvestigation's own resume-first guard ----------
+
+test('spawnInvestigation: a resume-eligible job is skipped before any fix-plan work (returns deferred:false immediately)', async () => {
+  const job = baseJob();
+  // A resume-eligible job trips the guard before spawnInvestigation ever
+  // touches the filesystem for runDir/investigationDepth lookups, so a
+  // nonexistent runDir is safe to pass here — proves the guard runs first.
+  const result = await spawnInvestigation(job, '/nonexistent/run/dir/for/this/test');
+  expect(result).toEqual({ deferred: false });
+});
+
+test('spawnInvestigation: resume-recovery-exhausted job (resumeRecoveryAttempted=true) is NOT skipped by the resume guard', async () => {
+  // slug matches the fix-plan pattern + investigationDepth beyond the cap so
+  // the NEXT gate (isFixPlanBeyondDepthCap) trips deterministically and
+  // returns before any fs/spawn work — proving the resume guard was passed
+  // through, not that this particular job happens to be safe to fully run.
+  const job = baseJob({ slug: '01-fix-example', resumeRecoveryAttempted: true, investigationDepth: 99 });
+  const result = await spawnInvestigation(job, '/nonexistent/run/dir/for/this/test');
+  expect(result).toEqual({ deferred: false });
+});
+
+test('SM_RESUME_RECOVERY_DISABLE=1: spawnInvestigation is NOT skipped by the resume guard for an otherwise-eligible job', async () => {
+  process.env.SM_RESUME_RECOVERY_DISABLE = '1';
+  const job = baseJob({ slug: '01-fix-example', investigationDepth: 99 });
+  // With the kill-switch on, selectResumeRecoveryTarget returns null, so the
+  // resume guard never fires; the job falls through to the NEXT gate
+  // (isFixPlanBeyondDepthCap, tripped here via investigationDepth: 99) —
+  // proving today's pre-feature behaviour is restored exactly.
+  const result = await spawnInvestigation(job, '/nonexistent/run/dir/for/this/test');
+  expect(result).toEqual({ deferred: false });
+});

package/src/main/__tests__/schedulerBatchRootBlocker.test.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+// PRD 1123 — a single row parked in `needs_review` (or `failed`/`skipped`)
+// several dependsOn hops down used to read as generic starvation: the picker
+// only ever named a held job's IMMEDIATE dep, which is very often just
+// another `pending` row, not the actual cause. These tests pin the root-
+// blocker walk: the reason must name the transitive ancestor that is itself
+// not blocked by anything, plus the count of jobs held behind it and its
+// status — and must terminate (not hang) on a dependsOn cycle.
+//
+// Run: timeout 120 npx vitest run src/main/__tests__/schedulerBatchRootBlocker.test.cjs
+
+const assert = require('node:assert/strict');
+const { pickForProject, DEFAULT_PROJECT_CWD } = require('../lib/schedulerBatch.cjs');
+
+const CWD = DEFAULT_PROJECT_CWD;
+
+function job(slug, status, extra = {}) {
+  return { slug, status, cwd: CWD, dependsOn: [], ...extra };
+}
+
+test('a 3-deep chain rooted at a needs_review row names the ROOT, not the middle link', () => {
+  const jobs = [
+    job('100-root', 'needs_review'),
+    job('101-middle', 'pending', { dependsOn: ['100-root'] }),
+    job('102-leaf', 'pending', { dependsOn: ['101-middle'] }),
+  ];
+  const { batch, reason, holds } = pickForProject(jobs, new Set(), 3);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  // Names the root, not the immediate (middle) dep as the cause.
+  assert.match(reason, /root blocker 100-root/);
+  assert.match(reason, /needs_review/);
+  assert.match(reason, /is a QUESTION awaiting a human/);
+  // Both downstream jobs are counted as held behind the root.
+  assert.match(reason, /holding 2 job\(s\)/);
+  assert.match(reason, /101-middle/);
+  assert.match(reason, /102-leaf/);
+
+  const leafHold = holds.find((h) => h.slug === '102-leaf');
+  assert.equal(leafHold.dep, '101-middle'); // immediate dep still recorded
+  assert.equal(leafHold.rootSlug, '100-root'); // but the row also knows the root
+  assert.equal(leafHold.rootStatus, 'needs_review');
+});
+
+test('the same 3-deep chain rooted at a FAILED row names the root, not the middle link', () => {
+  const jobs = [
+    job('200-root', 'failed'),
+    job('201-middle', 'pending', { dependsOn: ['200-root'] }),
+    job('202-leaf', 'pending', { dependsOn: ['201-middle'] }),
+  ];
+  const { batch, reason, holds } = pickForProject(jobs, new Set(), 3);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /root blocker 200-root/);
+  assert.match(reason, /\(failed\)/);
+  assert.match(reason, /holding 1 job\(s\)/); // only 202-leaf: 201-middle is caught by the shallow failed-dep bucket
+  assert.match(reason, /Reset or archive 200-root/);
+
+  const leafHold = holds.find((h) => h.slug === '202-leaf');
+  assert.equal(leafHold.rootSlug, '200-root');
+  assert.equal(leafHold.rootStatus, 'failed');
+  const middleHold = holds.find((h) => h.slug === '201-middle');
+  assert.equal(middleHold.rootSlug, '200-root');
+  assert.equal(middleHold.rootStatus, 'failed');
+});
+
+test('a 2-node dependsOn cycle is reported as its own reason, not a hang', () => {
+  const jobs = [
+    job('300-a', 'pending', { dependsOn: ['301-b'] }),
+    job('301-b', 'pending', { dependsOn: ['300-a'] }),
+  ];
+  const start = Date.now();
+  const { batch, reason } = pickForProject(jobs, new Set(), 3);
+  assert.ok(Date.now() - start < 5000, 'must terminate quickly, not hang');
+  assert.deepEqual(batch, []);
+  assert.match(reason, /CYCLE/);
+  assert.match(reason, /300-a/);
+  assert.match(reason, /301-b/);
+  // Reported exactly once, not once per member.
+  assert.equal((reason.match(/CYCLE/g) || []).length, 1);
+});
+
+test('no false stall reported when the gate is not the reason the batch is empty (slots exhausted)', () => {
+  const jobs = [job('400-a', 'pending'), job('401-b', 'pending')];
+  const { batch, reason } = pickForProject(jobs, new Set(), 0);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /no slots free/);
+  assert.doesNotMatch(reason, /root blocker/);
+});
+
+test('no false stall reported when the gate is not the reason the batch is empty (project cap)', () => {
+  const prevCap = process.env.SM_PROJECT_JOB_CAP;
+  process.env.SM_PROJECT_JOB_CAP = '1';
+  try {
+    const jobs = [
+      job('402-running', 'running'),
+      job('403-pending', 'pending'),
+    ];
+    const { batch, reason } = pickForProject(jobs, new Set(['402-running']), 3);
+    assert.deepEqual(batch, []);
+    assert.match(reason, /project-cap/);
+    assert.doesNotMatch(reason, /root blocker/);
+  } finally {
+    if (prevCap === undefined) delete process.env.SM_PROJECT_JOB_CAP;
+    else process.env.SM_PROJECT_JOB_CAP = prevCap;
+  }
+});
+
+test('a running/pending-rooted chain reports no stall reason (expected to clear on its own)', () => {
+  const jobs = [
+    job('500-root', 'running'),
+    job('501-dependent', 'pending', { dependsOn: ['500-root'] }),
+  ];
+  const { batch, reason } = pickForProject(jobs, new Set(['500-root']), 3);
+  assert.deepEqual(batch, []);
+  assert.equal(reason, null);
+});