claude-code-session-manager 0.78.0 → 0.80.0

package/src/main/__tests__/scheduler-autofix-outcome.test.cjs

@@ -10,6 +10,13 @@
  * coverage in scheduler-autofix-select.test.cjs (node --test) exercises the
  * same helpers in more granular detail.
  *
+ * PRD 1129 added one sub-shape to case (d): "outcome 'plan' WITH a queue
+ * row is neither retried nor annotated" only holds while that queue row
+ * (the fix-plan child) is still alive. Once the child itself reaches a
+ * terminal, non-completed status, isFixPlanDead makes the parent eligible
+ * for exactly one further attempt (stamped autoFixReopened: true), after
+ * which it is permanently excluded and annotated again.
+ *
  * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-autofix-outcome.test.cjs
  */
 
@@ -17,7 +24,7 @@
 
 import { test, expect } from 'vitest';
 const {
-  selectAutoFixTargets, isExhaustedAutoFix, isPlanUnqueued, fixSlugFor,
+  selectAutoFixTargets, isExhaustedAutoFix, isPlanUnqueued, isFixPlanDead, fixSlugFor,
 } = require('../scheduler.cjs');
 
 const noSiblingOnDisk = () => false;
@@ -82,6 +89,71 @@ test("(d) outcome 'plan' with the fix slug present in the queue is neither retri
   expect(isAnnotatable(job, queuedSlugs)).toBe(false);
 });
 
+// (e) dead fix-plan child: outcome 'plan' whose fix-plan row itself died —
+// the parent is eligible again, exactly once.
+test('(e) a dead fix-plan child makes the parent eligible for one further attempt', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 });
+  const deadChild = { slug: fixSlugFor(job), status: 'needs_review', parallelGroup: job.parallelGroup };
+  const jobs = [job, deadChild];
+  expect(isFixPlanDead(job, jobs)).toBe(true);
+  expect(selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(true);
+  expect(isAnnotatable(job, new Set(jobs.map((j) => j.slug)))).toBe(false);
+});
+
+test('(e) a failed, quarantined, or skipped fix-plan child also counts as dead', () => {
+  for (const status of ['failed', 'quarantined', 'skipped']) {
+    const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 });
+    const deadChild = { slug: fixSlugFor(job), status, parallelGroup: job.parallelGroup };
+    expect(isFixPlanDead(job, [job, deadChild])).toBe(true);
+  }
+});
+
+test('(e) an already-reopened parent is annotated, never eligible again — even with another dead child', () => {
+  const job = makeJob({
+    autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 1, autoFixReopened: true,
+  });
+  const deadChild = { slug: fixSlugFor(job), status: 'needs_review', parallelGroup: job.parallelGroup };
+  const jobs = [job, deadChild];
+  expect(isFixPlanDead(job, jobs)).toBe(false);
+  expect(selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(false);
+  expect(isExhaustedAutoFix(job)).toBe(true);
+  expect(isAnnotatable(job, new Set(jobs.map((j) => j.slug)))).toBe(true);
+});
+
+test('(e) a reopened parent whose second attempt is still in flight (outcome cleared) is untouched — not re-eligible, not yet annotated', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixRetries: 1, autoFixReopened: true });
+  expect(isFixPlanDead(job, [job])).toBe(false);
+  expect(selectAutoFixTargets([job], { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(false);
+  expect(isExhaustedAutoFix(job)).toBe(false);
+});
+
+test('(e) a fix-plan child that is still pending leaves the parent untouched', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 });
+  const pendingChild = { slug: fixSlugFor(job), status: 'pending', parallelGroup: job.parallelGroup };
+  const jobs = [job, pendingChild];
+  expect(isFixPlanDead(job, jobs)).toBe(false);
+  expect(selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(false);
+  expect(isAnnotatable(job, new Set(jobs.map((j) => j.slug)))).toBe(false);
+});
+
+test('(e) a fix-plan child that is still running leaves the parent untouched', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 });
+  const runningChild = { slug: fixSlugFor(job), status: 'running', parallelGroup: job.parallelGroup };
+  const jobs = [job, runningChild];
+  expect(isFixPlanDead(job, jobs)).toBe(false);
+  expect(selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(false);
+  expect(isAnnotatable(job, new Set(jobs.map((j) => j.slug)))).toBe(false);
+});
+
+test('(e) a fix-plan child that completed leaves the parent untouched (unchanged from today)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 });
+  const completedChild = { slug: fixSlugFor(job), status: 'completed', parallelGroup: job.parallelGroup };
+  const jobs = [job, completedChild];
+  expect(isFixPlanDead(job, jobs)).toBe(false);
+  expect(selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk }).some((j) => j.slug === job.slug)).toBe(false);
+  expect(isAnnotatable(job, new Set(jobs.map((j) => j.slug)))).toBe(false);
+});
+
 // (invariant) every needs_review job is either an auto-fix target or
 // annotatable (would receive a non-null verifierVerdict) — never both false.
 test('invariant: fresh, retry-eligible, exhausted, and plan-unqueued jobs are always selected or annotatable', () => {

package/src/main/__tests__/scheduler-autofix-select.test.cjs

@@ -308,6 +308,23 @@ test('isFixPlanBeyondDepthCap: fix-plan at depth 1 is not capped, depth 2 is', (
   assert.strictEqual(isFixPlanBeyondDepthCap('05-fix-foo', MAX_INVESTIGATION_DEPTH + 1), true);
 });
 
+// PRD 1131: classification is now provenance-aware (isFixPlan), not slug-only.
+// A legacy row with no `isFixPlan` argument at all still falls back to the
+// slug-only heuristic above (no re-classification of live history).
+
+test('isFixPlanBeyondDepthCap: a scheduler-authored fix plan (isFixPlan:true) is still classified as one and capped at the same depth', () => {
+  assert.strictEqual(isFixPlanBeyondDepthCap('05-fix-foo', MAX_INVESTIGATION_DEPTH, true), false);
+  assert.strictEqual(isFixPlanBeyondDepthCap('05-fix-foo', MAX_INVESTIGATION_DEPTH + 1, true), true);
+});
+
+test('isFixPlanBeyondDepthCap: a human-authored PRD (isFixPlan:false) whose slug merely matches "fix-" is never capped, even with no investigationDepth (PRD 1126 regression)', () => {
+  assert.strictEqual(isFixPlanBeyondDepthCap('126-fix-plan-death-reopens-parent', undefined, false), false);
+});
+
+test('isFixPlanBeyondDepthCap: a legacy row (isFixPlan argument omitted/undefined) with a fix- slug and no depth field is still treated as a fix plan via the slug fallback', () => {
+  assert.strictEqual(isFixPlanBeyondDepthCap('05-fix-foo', undefined, undefined), true);
+});
+
 test('healTargetForFix: depth-2 fix-of-a-fix slug resolves back to the depth-1 fix job (521-fix-recorder-export-footer-redesign)', () => {
   // Depth-1 fix job: originally authored to fix job 521, itself in needs_review.
   const depth1FixJob = {

package/src/main/__tests__/scheduler-commit-guard-noop.test.cjs

@@ -24,6 +24,7 @@
 
 import { test, expect } from 'vitest';
 const { commitGuardVerdict } = require('../scheduler.cjs');
+const { resolveIsFixPlan } = require('../lib/fixPlanSlug.cjs');
 
 test('commitGuardVerdict: legitimate no-op verdict (pass_no_commit_already_shipped) + concurrent dirt → no flag (655 incident)', () => {
   const verifyResult = {
@@ -102,6 +103,25 @@ test('commitGuardVerdict: fix-plan job (523-fix-bounded-fix-plan-retry incident)
   expect(verdict).toBeNull();
 });
 
+test('commitGuardVerdict: a zero-edit run of a human-authored PRD whose slug merely starts with "fix-" still yields silent_no_op (PRD 1131 — not exempted by name alone)', () => {
+  // Mirrors PRD 1126: authored via scheduler_create_prd (isFixPlan stamped
+  // false at reconcile time), slug happens to read "fix-...". Feeding the
+  // job's own persisted isFixPlan through resolveIsFixPlan (the same call
+  // spawnJob makes) must NOT exempt this zero-edit run from the guard.
+  const job = { slug: '126-fix-plan-death-reopens-parent', isFixPlan: false };
+  const verdict = commitGuardVerdict({
+    newlyDirty: [],
+    siblingRunning: false,
+    jobSelfCommitted: false,
+    legitimateNoOp: false,
+    isFixPlanJob: resolveIsFixPlan(job.slug, job.isFixPlan),
+    verifyResult: null,
+  });
+  expect(verdict).not.toBeNull();
+  expect(verdict.verdict).toBe('silent_no_op');
+  expect(verdict.downgradeTo).toBe('needs_review');
+});
+
 test('commitGuardVerdict: fix-plan job that DID leave real dirt behind is still flagged (isFixPlanJob only exempts the zero-edit case)', () => {
   const verdict = commitGuardVerdict({
     newlyDirty: ['src/main/someFeature.cjs'],

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-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/);
+});