claude-code-session-manager 0.79.0 → 0.81.0

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

@@ -0,0 +1,199 @@
+/**
+ * scheduler-leftover-quarantine.test.cjs — PRD 1128: once resume-first
+ * recovery (PRD 1111) is spent and a job STILL parks needs_review with
+ * 'uncommitted_changes', its recorded leftover paths must be quarantined off
+ * the shared tree (onto a dedicated `sm-salvage/<slug>` ref) rather than left
+ * dirty forever, poisoning every later worktree merge for that project (the
+ * 216-jupiter-sand-kazekage incident, 2026-09-06).
+ *
+ * selectLeftoverQuarantineTarget is the pure eligibility rule (no I/O);
+ * quarantineLeftovers is the git plumbing, exercised against a real
+ * throwaway repo under os.tmpdir() (same pattern as gitWorktree.test.cjs).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-leftover-quarantine.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const scheduler = require('../scheduler.cjs');
+const { selectLeftoverQuarantineTarget, quarantineLeftovers } = scheduler;
+
+let tmpRoot;
+let repoCwd;
+let originalDisable;
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'original a\n', 'utf8');
+  fs.writeFileSync(path.join(dir, 'c.txt'), 'original c\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-leftover-quarantine-'));
+  repoCwd = path.join(tmpRoot, 'repo');
+  initRepo(repoCwd);
+  originalDisable = process.env.SM_LEFTOVER_QUARANTINE_DISABLE;
+  delete process.env.SM_LEFTOVER_QUARANTINE_DISABLE;
+});
+
+afterEach(() => {
+  if (originalDisable === undefined) delete process.env.SM_LEFTOVER_QUARANTINE_DISABLE;
+  else process.env.SM_LEFTOVER_QUARANTINE_DISABLE = originalDisable;
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+// ──────────────────────────────────────────── selectLeftoverQuarantineTarget (pure)
+
+function eligibleJob(overrides = {}) {
+  return {
+    slug: 'my-slug',
+    cwd: repoCwd,
+    status: 'needs_review',
+    verifierVerdict: 'uncommitted_changes',
+    resumeRecoveryAttempted: true,
+    uncommittedPaths: ['a.txt', 'b.txt'],
+    ...overrides,
+  };
+}
+
+test('selectLeftoverQuarantineTarget: eligible job with no foreign WIP returns all uncommitted paths', () => {
+  const target = selectLeftoverQuarantineTarget(eligibleJob());
+  expect(target).toEqual({ slug: 'my-slug', cwd: repoCwd, paths: ['a.txt', 'b.txt'] });
+});
+
+test('selectLeftoverQuarantineTarget: a path present in preRunDirtyPaths (foreign WIP) is excluded', () => {
+  const target = selectLeftoverQuarantineTarget(eligibleJob({ preRunDirtyPaths: ['a.txt'] }));
+  expect(target).toEqual({ slug: 'my-slug', cwd: repoCwd, paths: ['b.txt'] });
+});
+
+test('selectLeftoverQuarantineTarget: every uncommitted path being foreign WIP returns null', () => {
+  const target = selectLeftoverQuarantineTarget(eligibleJob({ preRunDirtyPaths: ['a.txt', 'b.txt'] }));
+  expect(target).toBeNull();
+});
+
+test('selectLeftoverQuarantineTarget: not eligible unless resume recovery was already attempted', () => {
+  expect(selectLeftoverQuarantineTarget(eligibleJob({ resumeRecoveryAttempted: false }))).toBeNull();
+  expect(selectLeftoverQuarantineTarget(eligibleJob({ resumeRecoveryAttempted: undefined }))).toBeNull();
+});
+
+test('selectLeftoverQuarantineTarget: wrong status or verdict is ineligible', () => {
+  expect(selectLeftoverQuarantineTarget(eligibleJob({ status: 'completed' }))).toBeNull();
+  expect(selectLeftoverQuarantineTarget(eligibleJob({ verifierVerdict: 'transcript_errors' }))).toBeNull();
+});
+
+test('selectLeftoverQuarantineTarget: a second call is a no-op once leftoverQuarantineAttempted is true', () => {
+  const job = eligibleJob();
+  expect(selectLeftoverQuarantineTarget(job)).not.toBeNull();
+  job.leftoverQuarantineAttempted = true;
+  expect(selectLeftoverQuarantineTarget(job)).toBeNull();
+});
+
+test('selectLeftoverQuarantineTarget: kill-switch SM_LEFTOVER_QUARANTINE_DISABLE=1 always returns null', () => {
+  process.env.SM_LEFTOVER_QUARANTINE_DISABLE = '1';
+  expect(selectLeftoverQuarantineTarget(eligibleJob())).toBeNull();
+});
+
+// ──────────────────────────────────────────── quarantineLeftovers (real git plumbing)
+
+test('quarantineLeftovers: commits leftovers onto sm-salvage/<slug> and restores the tree to baseline', async () => {
+  const baseline = git(['rev-parse', 'HEAD'], repoCwd).trim();
+  fs.writeFileSync(path.join(repoCwd, 'a.txt'), 'modified a\n', 'utf8');
+  fs.writeFileSync(path.join(repoCwd, 'b.txt'), 'new file b\n', 'utf8');
+
+  const result = await quarantineLeftovers({ cwd: repoCwd, slug: 'my-slug', paths: ['a.txt', 'b.txt'], headBefore: baseline });
+
+  expect(result.ok).toBe(true);
+  expect(result.ref).toBe('sm-salvage/my-slug');
+  expect(result.commit).toBeTruthy();
+  expect(result.quarantinedPaths.sort()).toEqual(['a.txt', 'b.txt']);
+
+  // The checked-out branch never moved.
+  expect(git(['rev-parse', 'HEAD'], repoCwd).trim()).toBe(baseline);
+  // The salvage ref's parent is the baseline commit.
+  expect(git(['rev-parse', `${result.ref}^`], repoCwd).trim()).toBe(baseline);
+  // The salvage commit carries the leftover content.
+  expect(git(['show', `${result.ref}:a.txt`], repoCwd)).toBe('modified a\n');
+  expect(git(['show', `${result.ref}:b.txt`], repoCwd)).toBe('new file b\n');
+
+  // The working tree is restored to the pre-run baseline.
+  expect(fs.readFileSync(path.join(repoCwd, 'a.txt'), 'utf8')).toBe('original a\n');
+  expect(fs.existsSync(path.join(repoCwd, 'b.txt'))).toBe(false);
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+});
+
+test('quarantineLeftovers: a path dirty at dispatch time (foreign WIP, filtered out by the caller) is left exactly as-is', async () => {
+  const baseline = git(['rev-parse', 'HEAD'], repoCwd).trim();
+  fs.writeFileSync(path.join(repoCwd, 'a.txt'), 'modified a\n', 'utf8');
+  fs.writeFileSync(path.join(repoCwd, 'c.txt'), 'someone elses edit\n', 'utf8');
+
+  // Simulate the caller having already excluded 'c.txt' via preRunDirtyPaths
+  // by never passing it in `paths`.
+  const result = await quarantineLeftovers({ cwd: repoCwd, slug: 'my-slug', paths: ['a.txt'], headBefore: baseline });
+
+  expect(result.ok).toBe(true);
+  expect(result.quarantinedPaths).toEqual(['a.txt']);
+  // The foreign path is completely untouched.
+  expect(fs.readFileSync(path.join(repoCwd, 'c.txt'), 'utf8')).toBe('someone elses edit\n');
+  expect(git(['status', '--porcelain', '--', 'c.txt'], repoCwd).trim()).not.toBe('');
+});
+
+test('quarantineLeftovers: a path no longer dirty on disk is skipped, not force-restored', async () => {
+  const baseline = git(['rev-parse', 'HEAD'], repoCwd).trim();
+  fs.writeFileSync(path.join(repoCwd, 'a.txt'), 'modified a\n', 'utf8');
+  fs.writeFileSync(path.join(repoCwd, 'b.txt'), 'new file b\n', 'utf8');
+  // a.txt gets committed by something else between parking and quarantine —
+  // it is no longer dirty relative to the live tree.
+  git(['add', 'a.txt'], repoCwd);
+  git(['commit', '-q', '-m', 'a.txt landed separately'], repoCwd);
+
+  const result = await quarantineLeftovers({ cwd: repoCwd, slug: 'my-slug', paths: ['a.txt', 'b.txt'], headBefore: baseline });
+
+  expect(result.ok).toBe(true);
+  expect(result.quarantinedPaths).toEqual(['b.txt']);
+  expect(result.skippedPaths).toEqual(['a.txt']);
+  // a.txt was never touched — still whatever the later commit left it as.
+  expect(fs.readFileSync(path.join(repoCwd, 'a.txt'), 'utf8')).toBe('modified a\n');
+  expect(fs.existsSync(path.join(repoCwd, 'b.txt'))).toBe(false);
+});
+
+test('quarantineLeftovers: a git command failure abandons the whole attempt with the tree untouched', async () => {
+  fs.writeFileSync(path.join(repoCwd, 'a.txt'), 'modified a\n', 'utf8');
+
+  const result = await quarantineLeftovers({
+    cwd: repoCwd,
+    slug: 'my-slug',
+    paths: ['a.txt'],
+    headBefore: '0000000000000000000000000000000000000000', // never resolvable
+  });
+
+  expect(result.ok).toBe(false);
+  expect(result.reason).toBeTruthy();
+  // Nothing was quarantined or restored.
+  expect(fs.readFileSync(path.join(repoCwd, 'a.txt'), 'utf8')).toBe('modified a\n');
+  expect(git(['status', '--porcelain'], repoCwd).trim()).not.toBe('');
+  expect(() => git(['rev-parse', '--verify', 'refs/heads/sm-salvage/my-slug'], repoCwd)).toThrow();
+});
+
+test('quarantineLeftovers: a non-git cwd is abandoned cleanly with a reason', async () => {
+  const notARepo = path.join(tmpRoot, 'not-a-repo');
+  fs.mkdirSync(notARepo, { recursive: true });
+  fs.writeFileSync(path.join(notARepo, 'a.txt'), 'x\n', 'utf8');
+
+  const result = await quarantineLeftovers({ cwd: notARepo, slug: 'my-slug', paths: ['a.txt'] });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toBeTruthy();
+});

package/src/main/__tests__/scheduler-looks-done.test.cjs

@@ -33,7 +33,7 @@ const { execFileSync } = require('node:child_process');
 const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'looks-done-test-'));
 process.env.HOME = tmpHome;
 
-const { reverifyNeedsReview, computeLooksDone } = require('../scheduler.cjs');
+const { reverifyNeedsReview, computeLooksDone, findSatisfyingCommitOnMain } = require('../scheduler.cjs');
 const { resolvePrdWriteDir } = require('../lib/prdLocations.cjs');
 const { bustCwdCache } = require('../lib/queueStore.cjs');
 
@@ -51,6 +51,18 @@ function initRepo(dir) {
   git(['commit', '-q', '-m', 'initial'], dir);
 }
 
+// -b main pins the branch name regardless of the host's init.defaultBranch
+// config — findSatisfyingCommitOnMain's tests need a deterministic 'main' ref.
+function initRepoOnMain(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q', '-b', 'main'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
 function commitFile(dir, relPath, content, message) {
   const abs = path.join(dir, relPath);
   fs.mkdirSync(path.dirname(abs), { recursive: true });
@@ -228,6 +240,134 @@ test('computeLooksDone: no declared paths on the PRD → null, never fabricates
   assert.equal(looksDone, null);
 });
 
+test('needs_review row with autoFixAttempted:true is never also stamped looksDone (PRD 1136 — mutually exclusive)', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-already-fix-planned');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd, 'proj-already-fix-planned-slug');
+  writePrd(projectCwd, '30-example', [
+    '# Implementation notes',
+    'Edit `src/thing.js`.',
+  ].join('\n'));
+
+  // startedAt/finishedAt are fixed well in the past so the real-time commit
+  // below lands outside committedInWindow's [startedAt, finishedAt+60s]
+  // window — otherwise the pre-existing heal pass would auto-complete the
+  // row before ever reaching the stillOpen/looksDone branch this test
+  // targets (committedInWindow, unlike computeLooksDone's landedSinceRun,
+  // has no upper bound skip).
+  const startedAt = '2020-01-01T00:00:00.000Z';
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: '30-example',
+      status: 'needs_review',
+      cwd: projectCwd,
+      runId: 'run-30',
+      startedAt,
+      finishedAt: '2020-01-01T00:05:00.000Z',
+      verifierVerdict: 'transcript_errors',
+      error: 'transcript_errors: stale verdict',
+      // A fix-plan child was already minted for this row at finalize time —
+      // the exact ordering that always precedes a later reverifyNeedsReview
+      // pass, since autoFixAttempted is stamped synchronously in the same
+      // mutate() as the needs_review transition itself.
+      autoFixAttempted: true,
+    },
+  ]);
+  writeRunLog('run-30', '30-example', [
+    '[scheduler] starting 30-example',
+    JSON.stringify({ type: 'result', subtype: 'error_during_execution', is_error: true, result: 'still broken' }),
+  ]);
+
+  commitFile(projectCwd, 'src/thing.js', 'hello', 'later commit touching the declared path');
+
+  await reverifyNeedsReview();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  assert.equal(jobs.length, 1);
+  assert.equal(jobs[0].status, 'needs_review');
+  assert.equal(jobs[0].looksDone, undefined, 'a row already fix-planned must never also be stamped looksDone');
+  assert.equal(jobs[0].error, 'transcript_errors: stale verdict', 'the looksDone annotation must not overwrite the original error');
+});
+
+// findSatisfyingCommitOnMain — PRD 1136's already-satisfied-on-main evidence
+// query. Requires EVERY declared path to have landed on main since
+// queuedAt, not just one — a code-review finding (2026-09-07) confirmed
+// that a PRD citing both its real target file and a second file purely as
+// context (e.g. a `path/to/file.js:123` reference) would otherwise
+// auto-complete unattended off any unrelated commit touching only that
+// second, incidental file.
+
+test('findSatisfyingCommitOnMain: single declared path, satisfying commit lands on main → returns the sha', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-satisfied-single-path');
+  initRepoOnMain(projectCwd);
+  registerActiveProject(projectCwd, 'proj-satisfied-single-path-slug');
+  writePrd(projectCwd, '40-single-path', [
+    '# Implementation notes',
+    'Edit `src/real-work.js`.',
+  ].join('\n'));
+
+  const queuedAt = new Date().toISOString();
+  await wait(1100);
+  commitFile(projectCwd, 'src/real-work.js', 'hello', 'fix real-work');
+
+  const job = { slug: '40-single-path', cwd: projectCwd, queuedAt };
+  const commits = await findSatisfyingCommitOnMain(job);
+  assert.equal(commits.length, 1);
+});
+
+test('findSatisfyingCommitOnMain: two declared paths but only ONE lands → [] (not satisfied — no false completion off an incidental context citation)', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-satisfied-partial-path');
+  initRepoOnMain(projectCwd);
+  registerActiveProject(projectCwd, 'proj-satisfied-partial-path-slug');
+  writePrd(projectCwd, '41-partial-path', [
+    '# Implementation notes',
+    'Edit `src/real-work.js`. See `src/main/hotfile.js:123` for context.',
+  ].join('\n'));
+
+  const queuedAt = new Date().toISOString();
+  await wait(1100);
+  // Only the incidentally-cited context file gets a later, UNRELATED commit
+  // — the actual target path (src/real-work.js) never lands.
+  commitFile(projectCwd, 'src/main/hotfile.js', 'unrelated change', 'unrelated commit');
+
+  const job = { slug: '41-partial-path', cwd: projectCwd, queuedAt };
+  const commits = await findSatisfyingCommitOnMain(job);
+  assert.deepEqual(commits, [], 'partial path coverage must never be treated as satisfied');
+});
+
+test('findSatisfyingCommitOnMain: two declared paths, BOTH land → returns satisfying commits', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-satisfied-both-paths');
+  initRepoOnMain(projectCwd);
+  registerActiveProject(projectCwd, 'proj-satisfied-both-paths-slug');
+  writePrd(projectCwd, '42-both-paths', [
+    '# Implementation notes',
+    'Edit `src/real-work.js` and `src/main/hotfile.js`.',
+  ].join('\n'));
+
+  const queuedAt = new Date().toISOString();
+  await wait(1100);
+  commitFile(projectCwd, 'src/real-work.js', 'hello', 'fix real-work');
+  commitFile(projectCwd, 'src/main/hotfile.js', 'hello', 'fix hotfile too');
+
+  const job = { slug: '42-both-paths', cwd: projectCwd, queuedAt };
+  const commits = await findSatisfyingCommitOnMain(job);
+  assert.ok(commits.length >= 1, 'full path coverage must be treated as satisfied');
+});
+
+test('findSatisfyingCommitOnMain: no queuedAt on the job → [] without querying git', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-no-queued-at');
+  initRepoOnMain(projectCwd);
+  registerActiveProject(projectCwd, 'proj-no-queued-at-slug');
+  writePrd(projectCwd, '43-no-queued-at', [
+    '# Implementation notes',
+    'Edit `src/thing.js`.',
+  ].join('\n'));
+
+  const job = { slug: '43-no-queued-at', cwd: projectCwd };
+  const commits = await findSatisfyingCommitOnMain(job);
+  assert.deepEqual(commits, []);
+});
+
 test('computeLooksDone: non-git cwd → null without throwing (git-unavailable)', async () => {
   const notARepo = fs.mkdtempSync(path.join(tmpHome, 'not-a-repo-'));
   writePrd(notARepo, '11-no-repo', [

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

@@ -0,0 +1,222 @@
+/**
+ * scheduler-mechanical-recovery.test.cjs — PRD 1130: a fix-plan job parked
+ * needs_review at investigationDepth >= 2 (isFixPlanBeyondDepthCap,
+ * scheduler.cjs) gets no further investigation, and resume-first recovery
+ * (selectResumeRecoveryTarget) is hard-gated on verdict 'uncommitted_changes'
+ * — so a depth-capped job whose failure is fully mechanical (verdict
+ * 'worktree_integration_failed') was previously stranded needs_review
+ * forever (216-jupiter-sand-kazekage, 2026-09-06). This adds one bounded,
+ * model-free recovery rung, evaluated independently of depth.
+ *
+ * selectMechanicalRecoveryTarget is the pure eligibility rule (no I/O, no
+ * depth check); performMechanicalRecovery is the git plumbing + queue
+ * transition, exercised against a real throwaway repo under os.tmpdir()
+ * (same pattern as scheduler-leftover-quarantine.test.cjs and
+ * scheduler-reap-dead-running-jobs.test.cjs).
+ *
+ * HOME is overridden to a tmp dir BEFORE requiring scheduler.cjs, since
+ * queue.json I/O (mutate/readQueue/writeQueue) is baked into a top-level
+ * ROOT const derived from os.homedir() at require time — this test must
+ * never touch real state.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-mechanical-recovery.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-mechanical-recovery-test-'));
+process.env.HOME = tmpHome;
+
+const scheduler = require('../scheduler.cjs');
+const {
+  selectMechanicalRecoveryTarget, performMechanicalRecovery, MECHANICALLY_RESOLVABLE_VERDICTS,
+} = scheduler;
+const jobWorktree = require('../lib/jobWorktree.cjs');
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'original a\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+function writeProjectQueue(cwd, jobs) {
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs }, null, 2));
+  return path.join(stateDir, 'queue.json');
+}
+
+function registerActiveProject(cwd, slugDirName) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, slugDirName);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+let originalDisable;
+
+beforeEach(() => {
+  originalDisable = process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+  delete process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+});
+
+afterEach(() => {
+  if (originalDisable === undefined) delete process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+  else process.env.SM_MECHANICAL_RECOVERY_DISABLE = originalDisable;
+});
+
+// ──────────────────────────────────────────── selectMechanicalRecoveryTarget (pure)
+
+function eligibleJob(overrides = {}) {
+  return {
+    slug: 'depth-capped-fix-plan',
+    cwd: '/tmp/whatever-not-read-by-the-selector',
+    status: 'needs_review',
+    verifierVerdict: 'worktree_integration_failed',
+    investigationDepth: 2,
+    ...overrides,
+  };
+}
+
+test('selectMechanicalRecoveryTarget: eligible depth-2 worktree_integration_failed job returns a target, depth never disqualifies it', () => {
+  const target = selectMechanicalRecoveryTarget(eligibleJob({ investigationDepth: 5 }));
+  expect(target).not.toBeNull();
+  expect(target.slug).toBe('depth-capped-fix-plan');
+  expect(target.branch).toBe(jobWorktree.branchNameFor('depth-capped-fix-plan'));
+});
+
+test('selectMechanicalRecoveryTarget: already-attempted job is not eligible', () => {
+  expect(selectMechanicalRecoveryTarget(eligibleJob({ mechanicalRecoveryAttempted: true }))).toBeNull();
+});
+
+test('selectMechanicalRecoveryTarget: a verdict outside the closed set is not eligible', () => {
+  expect(selectMechanicalRecoveryTarget(eligibleJob({ verifierVerdict: 'uncommitted_changes' }))).toBeNull();
+  expect(selectMechanicalRecoveryTarget(eligibleJob({ verifierVerdict: 'transcript_errors' }))).toBeNull();
+});
+
+test('selectMechanicalRecoveryTarget: wrong status is not eligible', () => {
+  expect(selectMechanicalRecoveryTarget(eligibleJob({ status: 'failed' }))).toBeNull();
+  expect(selectMechanicalRecoveryTarget(eligibleJob({ status: 'completed' }))).toBeNull();
+});
+
+test('selectMechanicalRecoveryTarget: kill-switch SM_MECHANICAL_RECOVERY_DISABLE=1 always returns null', () => {
+  process.env.SM_MECHANICAL_RECOVERY_DISABLE = '1';
+  expect(selectMechanicalRecoveryTarget(eligibleJob())).toBeNull();
+});
+
+test('MECHANICALLY_RESOLVABLE_VERDICTS: closed set contains exactly worktree_integration_failed', () => {
+  expect(Array.from(MECHANICALLY_RESOLVABLE_VERDICTS)).toEqual(['worktree_integration_failed']);
+});
+
+// ──────────────────────────────────────────── performMechanicalRecovery (real git + queue)
+
+test('performMechanicalRecovery: successful re-integration transitions needs_review -> completed, clears verifierVerdict, deletes the branch', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-success');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd, 'proj-success-slug');
+
+  const slug = 'fix-plan-depth2';
+  const branch = jobWorktree.branchNameFor(slug);
+  // Simulate a job whose worktree branch has one committed change, preserved
+  // (never deleted) because its earlier integration attempt failed.
+  git(['checkout', '-q', '-b', branch], projectCwd);
+  fs.writeFileSync(path.join(projectCwd, 'b.txt'), 'from the fix plan\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'fix plan work'], projectCwd);
+  git(['checkout', '-q', 'master'], projectCwd);
+
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug,
+      status: 'needs_review',
+      cwd: projectCwd,
+      verifierVerdict: 'worktree_integration_failed',
+      investigationDepth: 2,
+      error: 'worktree branch integration FAILED (merge failed) — branch preserved for manual recovery',
+    },
+  ]);
+
+  const target = selectMechanicalRecoveryTarget({ slug, cwd: projectCwd, status: 'needs_review', verifierVerdict: 'worktree_integration_failed' });
+  expect(target).not.toBeNull();
+
+  await performMechanicalRecovery({ slug, cwd: projectCwd }, target);
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  expect(jobs).toHaveLength(1);
+  expect(jobs[0].status).toBe('completed');
+  expect(jobs[0].verifierVerdict).toBeUndefined();
+  expect(jobs[0].mechanicalRecoveryAttempted).toBe(true);
+  expect(jobs[0].statusHistory.at(-1).source).toBe('scheduler:mechanicalRecovery');
+  expect(fs.readFileSync(path.join(projectCwd, 'b.txt'), 'utf8')).toBe('from the fix plan\n');
+  // The branch, now merged, is cleaned up.
+  const branchList = git(['branch', '--list', branch], projectCwd);
+  expect(branchList.trim()).toBe('');
+});
+
+test('performMechanicalRecovery: a real merge conflict keeps the job needs_review, stamps mechanicalRecoveryAttempted, appends the failure text', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-conflict');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd, 'proj-conflict-slug');
+
+  const slug = 'fix-plan-conflict';
+  const branch = jobWorktree.branchNameFor(slug);
+  git(['checkout', '-q', '-b', branch], projectCwd);
+  fs.writeFileSync(path.join(projectCwd, 'a.txt'), 'branch version\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'branch edits a.txt'], projectCwd);
+  git(['checkout', '-q', 'master'], projectCwd);
+  // Main tree diverges on the SAME line — a genuine, unresolvable conflict.
+  fs.writeFileSync(path.join(projectCwd, 'a.txt'), 'main version\n', 'utf8');
+  git(['add', '-A'], projectCwd);
+  git(['commit', '-q', '-m', 'main edits a.txt'], projectCwd);
+
+  const queuePath = writeProjectQueue(projectCwd, [
+    { slug, status: 'needs_review', cwd: projectCwd, verifierVerdict: 'worktree_integration_failed', investigationDepth: 3, error: 'prior failure note' },
+  ]);
+
+  const target = selectMechanicalRecoveryTarget({ slug, cwd: projectCwd, status: 'needs_review', verifierVerdict: 'worktree_integration_failed' });
+  await performMechanicalRecovery({ slug, cwd: projectCwd }, target);
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  expect(jobs[0].status).toBe('needs_review');
+  expect(jobs[0].mechanicalRecoveryAttempted).toBe(true);
+  expect(jobs[0].error).toMatch(/prior failure note/);
+  expect(jobs[0].error).toMatch(/Mechanical recovery retry failed/);
+  // The branch is preserved for manual recovery, exactly like the original failure.
+  const branchList = git(['branch', '--list', branch], projectCwd);
+  expect(branchList.trim()).not.toBe('');
+});
+
+test('performMechanicalRecovery: a branch that no longer exists is handled without throwing, and stamps an explicit reason', async () => {
+  const projectCwd = path.join(tmpHome, 'proj-missing-branch');
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd, 'proj-missing-branch-slug');
+
+  const slug = 'fix-plan-already-merged';
+  const queuePath = writeProjectQueue(projectCwd, [
+    { slug, status: 'needs_review', cwd: projectCwd, verifierVerdict: 'worktree_integration_failed', investigationDepth: 2 },
+  ]);
+
+  const target = selectMechanicalRecoveryTarget({ slug, cwd: projectCwd, status: 'needs_review', verifierVerdict: 'worktree_integration_failed' });
+
+  await expect(performMechanicalRecovery({ slug, cwd: projectCwd }, target)).resolves.not.toThrow();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  expect(jobs[0].status).toBe('needs_review');
+  expect(jobs[0].mechanicalRecoveryAttempted).toBe(true);
+  expect(jobs[0].error).toMatch(/not found/);
+});

package/src/main/__tests__/scheduler-rate-limit-pause.test.cjs

@@ -0,0 +1,81 @@
+/**
+ * scheduler-rate-limit-pause.test.cjs — PRD 1118: pause against the BINDING
+ * rate-limit window read off a run's own log, not refreshNextReset()'s
+ * five_hour-only assumption, and never leave an indefinite pause with no
+ * resume timer when both the log and the billing endpoint come up empty
+ * (the live failure mode: the usage endpoint itself 429s).
+ *
+ * These test the PURE decision functions scheduler.cjs's setPaused() and the
+ * spawnJob() rateLimited branch delegate to — never the real setPaused/mutate
+ * path, which writes the machine's live scheduler queue.json at a fixed
+ * homedir path (~/.claude/session-manager/scheduled-plans) and must not be
+ * touched by a test run.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-rate-limit-pause.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {
+  resolveRateLimitPauseReset,
+  computeEffectiveResumeAt,
+  computeResumeDelay,
+} = require('../scheduler.cjs');
+
+// Repo-tracked, byte-for-byte copy of the real 2026-09-05 starry-night-ships
+// incident log (see src/main/lib/__tests__/rateLimitWindow.test.cjs for the
+// live-path parity check) — kept hermetic rather than pointed at the
+// machine-local live path directly.
+const FIXTURE = path.join(__dirname, '..', 'lib', '__tests__', 'fixtures', '204-mercury-steam-horse.log.txt');
+const FIVE_HOUR_ISO = new Date(1788643800 * 1000).toISOString(); // what refreshNextReset() would have returned
+const SEVEN_DAY_ISO = new Date(1789059600 * 1000).toISOString(); // the actually-binding window
+
+test('resolveRateLimitPauseReset: prefers the log-derived seven-day reset over the billing five_hour reset', () => {
+  const resetIso = resolveRateLimitPauseReset(FIXTURE, FIVE_HOUR_ISO);
+  assert.strictEqual(resetIso, SEVEN_DAY_ISO);
+  assert.notStrictEqual(resetIso, FIVE_HOUR_ISO);
+});
+
+test('resolveRateLimitPauseReset: falls back to the billing reset when the log yields none', () => {
+  const resetIso = resolveRateLimitPauseReset('/nonexistent/path/job.log', FIVE_HOUR_ISO);
+  assert.strictEqual(resetIso, FIVE_HOUR_ISO);
+});
+
+test('resolveRateLimitPauseReset: null when BOTH the log and the billing endpoint are unavailable', () => {
+  assert.strictEqual(resolveRateLimitPauseReset('/nonexistent/path/job.log', null), null);
+});
+
+test('computeEffectiveResumeAt: rate_limit with no resumeAt gets the same bounded 30-minute fallback as network', () => {
+  const now = Date.parse('2026-09-05T16:32:00.000Z');
+  const resumeAt = computeEffectiveResumeAt('rate_limit', null, now);
+  assert.strictEqual(resumeAt, new Date(now + 30 * 60_000).toISOString());
+});
+
+test('computeEffectiveResumeAt: an explicit resumeAt (the log-derived reset) is never overridden', () => {
+  const resumeAt = computeEffectiveResumeAt('rate_limit', SEVEN_DAY_ISO, Date.now());
+  assert.strictEqual(resumeAt, SEVEN_DAY_ISO);
+});
+
+test('computeEffectiveResumeAt: other reasons (e.g. auth) get no fallback — stays indefinite', () => {
+  assert.strictEqual(computeEffectiveResumeAt('auth', null, Date.now()), null);
+});
+
+test('computeResumeDelay: a seven-day-out reset (~5 days from now) is armed, not treated as too-far', () => {
+  const now = Date.parse('2026-09-05T16:32:00.000Z');
+  // ~5 days out — comfortably under the 0x7fffffff (~24.8 day) setTimeout cap.
+  const fiveDaysOut = new Date(now + 5 * 24 * 60 * 60_000).toISOString();
+  const { delayMs, tooFar } = computeResumeDelay(fiveDaysOut, now);
+  assert.strictEqual(tooFar, false);
+  assert.ok(delayMs < 0x7fffffff, `expected delay under setTimeout cap, got ${delayMs}`);
+  assert.ok(delayMs > 400_000_000, `expected ~5 days in ms, got ${delayMs}`);
+});
+
+test('computeResumeDelay: a reset far enough out DOES trip the overflow guard', () => {
+  const now = Date.parse('2026-09-05T16:32:00.000Z');
+  const thirtyDaysOut = new Date(now + 30 * 24 * 60 * 60_000).toISOString();
+  const { tooFar } = computeResumeDelay(thirtyDaysOut, now);
+  assert.strictEqual(tooFar, true);
+});