claude-code-session-manager 0.82.0 → 0.84.0

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

@@ -0,0 +1,72 @@
+/**
+ * scheduleJobTransitionsTelemetryTap.test.cjs — transitionJob() is the ONE
+ * chokepoint every job status change flows through (scheduleJobTransitions.
+ * cjs's own header); this asserts it fires the 'scheduler.job.finish'
+ * counter exactly once when a run genuinely finishes (running -> a terminal
+ * status), and not on other legal edges (retries, admin resets).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduleJobTransitionsTelemetryTap.test.cjs
+ */
+'use strict';
+
+import { test, expect, afterEach, beforeEach } from 'vitest';
+
+const countersPath = require.resolve('../lib/telemetryCounters.cjs');
+const transitionsPath = require.resolve('../lib/scheduleJobTransitions.cjs');
+
+let calls;
+
+beforeEach(() => {
+  calls = [];
+  require.cache[countersPath] = {
+    id: countersPath,
+    filename: countersPath,
+    loaded: true,
+    exports: { trackSchedulerJobFinish: (props) => calls.push(props) },
+  };
+  delete require.cache[transitionsPath];
+});
+
+afterEach(() => {
+  delete require.cache[countersPath];
+  delete require.cache[transitionsPath];
+});
+
+function freshJob(status) {
+  return { slug: 'test-slug', status, cwd: '/tmp/whatever' };
+}
+
+test('running -> completed fires scheduler.job.finish once with { status: "completed" }', () => {
+  const { transitionJob } = require('../lib/scheduleJobTransitions.cjs');
+  const job = freshJob('running');
+  expect(transitionJob(job, 'completed', { reason: 'run succeeded', source: 'test' })).toBe(true);
+  expect(calls).toEqual([{ status: 'completed' }]);
+});
+
+test('running -> failed fires scheduler.job.finish once with { status: "failed" }', () => {
+  const { transitionJob } = require('../lib/scheduleJobTransitions.cjs');
+  const job = freshJob('running');
+  transitionJob(job, 'failed', { reason: 'run failed', source: 'test' });
+  expect(calls).toEqual([{ status: 'failed' }]);
+});
+
+test('running -> pending (retry) does NOT fire scheduler.job.finish', () => {
+  const { transitionJob } = require('../lib/scheduleJobTransitions.cjs');
+  const job = freshJob('running');
+  transitionJob(job, 'pending', { reason: 'transient retry', source: 'test' });
+  expect(calls).toEqual([]);
+});
+
+test('pending -> running (dispatch) does NOT fire scheduler.job.finish', () => {
+  const { transitionJob } = require('../lib/scheduleJobTransitions.cjs');
+  const job = freshJob('pending');
+  transitionJob(job, 'running', { reason: 'dispatch', source: 'test' });
+  expect(calls).toEqual([]);
+});
+
+test('an illegal (refused) transition does NOT fire scheduler.job.finish', () => {
+  const { transitionJob } = require('../lib/scheduleJobTransitions.cjs');
+  const job = freshJob('completed');
+  expect(transitionJob(job, 'running', { reason: 'bogus', source: 'test' })).toBe(false);
+  expect(calls).toEqual([]);
+});

package/src/main/__tests__/scheduler-inplace-salvage.test.cjs

@@ -201,6 +201,80 @@ function writeNoopClaudeStub() {
   return stubPath;
 }
 
+// Stub `claude` binary that blocks until a `go` marker file appears in its
+// cwd (polled), THEN emits a success result and exits 0 — gives the test a
+// window to read the queue row's intermediate dispatchPhase before the run
+// finalizes and deletes it.
+function writeGatedClaudeStub() {
+  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-gated-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    const path = require('path');
+    const { execFileSync } = require('child_process');
+    const goFile = path.join(process.cwd(), 'go.marker');
+    const deadline = Date.now() + 10_000;
+    while (!fs.existsSync(goFile) && Date.now() < deadline) {
+      try { execFileSync('sleep', ['0.02']); } catch {}
+    }
+    process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok', is_error: false }) + '\\n');
+    process.exit(0);
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+test('dispatchPhase breadcrumb advances to "spawned" mid-run and is gone after finalize', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-inplace-salvage-project-'));
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+
+  const slug = `1163-test-dispatchphase-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Do a thing, gated on a marker file.', 'utf8');
+
+  const queuePath = writeProjectQueue(projectCwd, [
+    { slug, status: 'pending', cwd: projectCwd },
+  ]);
+
+  process.env.SM_CLAUDE_BIN = writeGatedClaudeStub();
+
+  const runId = `run-${slug}`;
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(runDir, { recursive: true });
+
+  const readRow = () => JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs.find((j) => j.slug === slug);
+
+  try {
+    const spawnPromise = spawnJob({ slug, cwd: projectCwd }, runId, runDir, projectCwd);
+
+    // Poll the row until dispatchPhase reaches 'spawned' (the onPid mutate),
+    // proving the breadcrumb advanced through the dispatch region while the
+    // stub is deliberately blocked mid-run.
+    const pollDeadline = Date.now() + 8_000;
+    let row = readRow();
+    while (row?.dispatchPhase !== 'spawned' && Date.now() < pollDeadline) {
+      await new Promise((r) => setTimeout(r, 25));
+      row = readRow();
+    }
+    expect(row?.dispatchPhase).toBe('spawned');
+    expect(typeof row.dispatchPhaseAt).toBe('string');
+    expect(Number.isNaN(Date.parse(row.dispatchPhaseAt))).toBe(false);
+
+    // Let the gated stub finish.
+    fs.writeFileSync(path.join(projectCwd, 'go.marker'), 'go\n', 'utf8');
+    await spawnPromise;
+
+    const finalRow = readRow();
+    expect(finalRow.exitCode).toBe(0);
+    expect(finalRow.dispatchPhase).toBeUndefined();
+    expect(finalRow.dispatchPhaseAt).toBeUndefined();
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+}, 30_000);
+
 test('a job whose tree is dirty only from pre-existing baseline WIP (human/sibling), and which itself dirties/commits nothing, gets no leftover attribution', async () => {
   const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-inplace-salvage-project-'));
   initRepo(projectCwd);

package/src/main/__tests__/scheduler-job-overrun.test.cjs

@@ -23,6 +23,7 @@ const {
   findOverrunningJobs,
   JOB_OVERRUN_FACTOR,
   JOB_OVERRUN_FLOOR_MS,
+  resetJobFields,
 } = require('../scheduler.cjs');
 
 const NOW = Date.parse('2026-08-08T12:00:00.000Z');
@@ -115,3 +116,60 @@ test('the shipped defaults are the documented ones', () => {
   assert.strictEqual(JOB_OVERRUN_FACTOR, 3);
   assert.strictEqual(JOB_OVERRUN_FLOOR_MS, 45 * 60_000);
 });
+
+// The escalation loop in scheduler.cjs (~8700) stamps job.overrun straight
+// from findOverrunningJobs' own return shape — these tests exercise that
+// exact shape against the live starry-night-ships incident fixture
+// (estimateMinutes: 22, ranMs: 6379556, ratio: 4.83) rather than duplicating
+// the threshold math the escalation loop itself must not recompute.
+
+test('the live incident fixture (4.9x over a 22m estimate) is stamped', () => {
+  const startedAt = new Date(NOW - 6379556).toISOString();
+  const jobs = [
+    { slug: '231-saturn-record-and-docs', cwd: '/starry', status: 'running', estimateMinutes: 22, startedAt },
+  ];
+  const over = findOverrunningJobs(jobs, NOW);
+  assert.strictEqual(over.length, 1);
+  const [hit] = over;
+  assert.ok(hit.ratio >= 4.8 && hit.ratio <= 4.9, `expected ~4.83x, got ${hit.ratio}`);
+
+  // Mirror the escalation loop's own stamp assignment (job.overrun = {...}) —
+  // same fields the ScheduleJobLite renderer type now carries.
+  const job = jobs[0];
+  job.overrun = { ratio: hit.ratio, ranMs: hit.ranMs, estimateMinutes: hit.estimateMinutes, at: new Date(NOW).toISOString() };
+  assert.strictEqual(job.overrun.estimateMinutes, 22);
+  assert.strictEqual(job.overrun.ranMs, 6379556);
+  assert.ok(job.overrun.ratio >= 4.8 && job.overrun.ratio <= 4.9);
+
+  // Idempotent re-escalation: a later sweep overwrites in place, never appends.
+  const laterNow = NOW + 10 * 60_000;
+  const laterOver = findOverrunningJobs(jobs, laterNow)[0];
+  job.overrun = {
+    ratio: laterOver.ratio, ranMs: laterOver.ranMs, estimateMinutes: laterOver.estimateMinutes, at: new Date(laterNow).toISOString(),
+  };
+  assert.strictEqual(typeof job.overrun, 'object');
+  assert.ok(job.overrun.ranMs > hit.ranMs, 'ranMs should have advanced on re-escalation, not duplicated');
+});
+
+test('a job with no usable estimate is never in the escalation list, so it is never stamped', () => {
+  const jobs = [
+    { slug: 'no-est', cwd: '/p1', status: 'running', startedAt: agoMin(300) },
+  ];
+  assert.deepStrictEqual(findOverrunningJobs(jobs, NOW), []);
+  assert.strictEqual(jobs[0].overrun, undefined);
+});
+
+test('resetJobFields clears a stamped overrun badge — this run\'s outcome, not durable across a reset', () => {
+  const job = {
+    slug: '231-saturn-record-and-docs',
+    status: 'running',
+    statusHistory: [],
+    runId: 'r1',
+    startedAt: agoMin(180),
+    overrun: { ratio: 4.83, ranMs: 6379556, estimateMinutes: 22, at: new Date(NOW).toISOString() },
+  };
+  const ok = resetJobFields(job, 'reset for test');
+  assert.strictEqual(ok, true);
+  assert.strictEqual(job.status, 'pending');
+  assert.strictEqual('overrun' in job, false);
+});

package/src/main/__tests__/scheduler-notify-originating-tab-transcript.test.cjs

@@ -32,6 +32,7 @@ test('appends the job result text to the transcript store when sourcePromptId is
   expect(appendTranscriptTurn).toHaveBeenCalledWith('/some/cwd', 'psess-abc', {
     role: 'assistant',
     text: 'the real agent result text',
+    eventId: 'prd-result:863-transcript:run-1',
   });
 });
 

package/src/main/__tests__/scheduler-periodic-reverify-guard.test.cjs

@@ -13,6 +13,18 @@
  *
  * These tests pin the guard to isRescanCandidate so the two cannot drift again.
  *
+ * Reopened 2026-09-12 through a different door (starry-night-ships
+ * 231-saturn-record-and-docs / 243-neptune-kurama-mode): the guard also gates
+ * reverifyNeedsReview's auto-fix loop, not just its re-verification arm, but
+ * only checked isRescanCandidate — so a needs_review row whose mechanical
+ * recovery already ran and failed (verdict 'worktree_integration_failed',
+ * mechanicalRecoveryAttempted: true — not itself a RESCANNABLE_VERDICTS
+ * member) never got a chance at the next rung (a fix-plan investigation via
+ * selectAutoFixTargets). The guard is now widened to OR in every live target
+ * of the recovery ladder the periodic pass actually drives
+ * (selectMechanicalRecoveryTarget / selectResumeRecoveryTarget /
+ * selectAutoFixTargets).
+ *
  * HOME is overridden to a tmp dir BEFORE requiring scheduler.cjs — see
  * scheduler-reap-dead-running-jobs.test.cjs's comment for why.
  *
@@ -29,7 +41,12 @@ const path = require('node:path');
 const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'reverify-guard-test-'));
 process.env.HOME = tmpHome;
 
-const { shouldRunPeriodicReverify, isRescanCandidate } = require('../scheduler.cjs');
+const {
+  shouldRunPeriodicReverify,
+  isRescanCandidate,
+  selectAutoFixTargets,
+  selectMechanicalRecoveryTarget,
+} = require('../scheduler.cjs');
 
 function writeRunLog(runId, slug, lines) {
   const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
@@ -70,12 +87,44 @@ test('needs_review with a rescannable verdict still fires; a non-rescannable ver
     ]),
     true,
   );
+  // A verdict outside RESCANNABLE_VERDICTS is not itself enough to suppress
+  // the pass: with no sessionId, this row also fails selectResumeRecoveryTarget's
+  // eligibility check, so it falls through as a genuine selectAutoFixTargets
+  // candidate (a fix-plan investigation, not a rescan) — and the widened guard
+  // must fire for that too.
   assert.equal(
     shouldRunPeriodicReverify([
       { slug: '300-nr', status: 'needs_review', runId: 'run-guard-3', verifierVerdict: 'uncommitted_changes' },
     ]),
-    false,
+    true,
+  );
+});
+
+test('a needs_review row with no rescan/recovery/autofix eligibility at all does not fire the pass', () => {
+  // Genuinely nothing to do: already has a fix-plan outcome recorded as
+  // 'plan' (never retried by selectAutoFixTargets — see its autoFixOutcome
+  // exclusion), so selectAutoFixTargets excludes it regardless of
+  // fixSlugExists; not a rescan candidate (RESCANNABLE_VERDICTS); not
+  // resume/mechanical eligible either.
+  writeRunLog('run-guard-3b', '301-nr', ['[scheduler] starting 301-nr']);
+  const jobs = [
+    {
+      slug: '301-nr',
+      status: 'needs_review',
+      runId: 'run-guard-3b',
+      verifierVerdict: 'uncommitted_changes',
+      autoFixAttempted: true,
+      autoFixOutcome: 'plan',
+    },
+  ];
+  assert.equal(isRescanCandidate(jobs[0]), false);
+  assert.equal(selectMechanicalRecoveryTarget(jobs[0]), null);
+  assert.equal(
+    selectAutoFixTargets(jobs, { fixSlugExists: () => false }).length,
+    0,
+    'sanity: selectAutoFixTargets itself must exclude this row (cheap-guard stub matches production: fixSlugExists always false)',
   );
+  assert.equal(shouldRunPeriodicReverify(jobs), false);
 });
 
 test('a queue with nothing rescannable, or a non-array, does not fire the pass', () => {
@@ -83,3 +132,86 @@ test('a queue with nothing rescannable, or a non-array, does not fire the pass',
   assert.equal(shouldRunPeriodicReverify([]), false);
   assert.equal(shouldRunPeriodicReverify(undefined), false);
 });
+
+// Live reproduction fixture (verbatim, verdict from the machine 2026-09-12):
+// starry-night-ships 231-saturn-record-and-docs, needs_review,
+// worktree_integration_failed, mechanical recovery already spent.
+function liveFixtureRow(overrides = {}) {
+  return {
+    slug: '231-saturn-record-and-docs',
+    cwd: '/home/bilko/Projects/starry-night-ships',
+    status: 'needs_review',
+    verifierVerdict: 'worktree_integration_failed',
+    mechanicalRecoveryAttempted: true,
+    autoFixAttempted: undefined,
+    runId: '2026-09-11T23-58-26-007Z',
+    ...overrides,
+  };
+}
+
+test('live fixture: mechanical recovery spent, autofix never attempted — guard now fires (was false)', () => {
+  writeRunLog(liveFixtureRow().runId, liveFixtureRow().slug, ['[scheduler] starting 231-saturn-record-and-docs']);
+  const jobs = [liveFixtureRow()];
+  assert.equal(isRescanCandidate(jobs[0]), false, 'worktree_integration_failed is deliberately NOT in RESCANNABLE_VERDICTS');
+  assert.equal(selectMechanicalRecoveryTarget(jobs[0]), null, 'mechanical recovery is spent (mechanicalRecoveryAttempted: true)');
+  assert.equal(shouldRunPeriodicReverify(jobs), true);
+});
+
+test('live fixture is authored as a selectAutoFixTargets candidate once mechanical recovery is spent', () => {
+  const jobs = [liveFixtureRow()];
+  const targets = selectAutoFixTargets(jobs, { fixSlugExists: () => false });
+  assert.deepEqual(targets.map((t) => t.slug), ['231-saturn-record-and-docs']);
+});
+
+test('a row whose mechanical recovery is still PENDING is excluded from selectAutoFixTargets (both rungs never fire together)', () => {
+  const jobs = [liveFixtureRow({ mechanicalRecoveryAttempted: undefined })];
+  assert.notEqual(selectMechanicalRecoveryTarget(jobs[0]), null, 'still eligible for its one mechanical retry');
+  const targets = selectAutoFixTargets(jobs, { fixSlugExists: () => false });
+  assert.deepEqual(targets, [], 'a mechanical-recovery-pending row must not also become a fix-plan target');
+  // The guard still fires for this row — via the mechanical-recovery rung, not autofix.
+  assert.equal(shouldRunPeriodicReverify(jobs), true);
+});
+
+test('one-attempt caps are unchanged by the widened guard', () => {
+  // mechanicalRecoveryAttempted still permits exactly one retry: once true, selectMechanicalRecoveryTarget is spent forever.
+  assert.equal(selectMechanicalRecoveryTarget(liveFixtureRow({ mechanicalRecoveryAttempted: true })), null);
+  assert.notEqual(selectMechanicalRecoveryTarget(liveFixtureRow({ mechanicalRecoveryAttempted: undefined })), null);
+  // autoFixRetries < 1 still bounds the fix-plan retry inside selectAutoFixTargets.
+  const exhausted = [liveFixtureRow({ autoFixAttempted: true, autoFixOutcome: 'error', autoFixRetries: 1 })];
+  assert.deepEqual(selectAutoFixTargets(exhausted, { fixSlugExists: () => false }), [], 'exhausted retry budget must stay excluded');
+  const withBudget = [liveFixtureRow({ autoFixAttempted: true, autoFixOutcome: 'error', autoFixRetries: 0 })];
+  assert.equal(selectAutoFixTargets(withBudget, { fixSlugExists: () => false }).length, 1, 'one bounded retry is still available');
+});
+
+test('kill-switches still fully disable their respective paths', () => {
+  const jobs = [liveFixtureRow()];
+  const prevAutofix = process.env.SM_AUTOFIX_DISABLE;
+  const prevMechanical = process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+  try {
+    // SM_REVERIFY_PERIODIC_DISABLE is enforced by the interval callback around
+    // shouldRunPeriodicReverify (scheduler.cjs's rescheduleInterval body), not
+    // inside the guard itself — the guard stays a pure predicate over jobs.
+    assert.equal(process.env.SM_REVERIFY_PERIODIC_DISABLE, undefined, 'sanity: not set in this test process');
+
+    // SM_MECHANICAL_RECOVERY_DISABLE=1 makes selectMechanicalRecoveryTarget
+    // always return null, which is exactly what the widened guard consults.
+    process.env.SM_MECHANICAL_RECOVERY_DISABLE = '1';
+    const pendingMechanicalJob = [liveFixtureRow({ mechanicalRecoveryAttempted: undefined })];
+    assert.equal(selectMechanicalRecoveryTarget(pendingMechanicalJob[0]), null);
+    delete process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+
+    // SM_AUTOFIX_DISABLE gates reverifyNeedsReview's own auto-fix dispatch
+    // loop (scheduler.cjs ~8207), not selectAutoFixTargets/the guard — the
+    // guard's job is only to decide whether the pass should run at all, and
+    // it must still fire so the disabled loop's own no-op is reached (rather
+    // than the periodic pass never running and other reverify semantics,
+    // e.g. rescan candidates elsewhere in the same tick, being starved too).
+    process.env.SM_AUTOFIX_DISABLE = '1';
+    assert.equal(shouldRunPeriodicReverify(jobs), true);
+  } finally {
+    if (prevAutofix === undefined) delete process.env.SM_AUTOFIX_DISABLE;
+    else process.env.SM_AUTOFIX_DISABLE = prevAutofix;
+    if (prevMechanical === undefined) delete process.env.SM_MECHANICAL_RECOVERY_DISABLE;
+    else process.env.SM_MECHANICAL_RECOVERY_DISABLE = prevMechanical;
+  }
+});

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

@@ -148,6 +148,39 @@ test('reapDeadRunningJobs reaps a pidless row older than PIDLESS_SPAWN_GRACE_MS
   assert.ok(pidlessEvent, 'reaping a pidless row must leave an audit trace');
 });
 
+test('reapDeadRunningJobs clears runId on a pidless reap whose run dir holds only a sibling slug\'s files', async () => {
+  const projectCwd = path.join(tmpHome, 'c2-project-batch-sibling');
+  fs.mkdirSync(projectCwd, { recursive: true });
+  registerActiveProject(projectCwd);
+
+  const staleStartedAt = new Date(Date.now() - PIDLESS_SPAWN_GRACE_MS - 60_000).toISOString();
+  // Both jobs were dispatched into the SAME batch runId dir (pickRunDir's
+  // header: "tickQueue hands ONE shared batch dir to every spawnJob in the
+  // batch"). 'sibling-that-ran' actually spawned and wrote its own log;
+  // 'never-spawned' never got a pid and never wrote anything of its own.
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: 'zzq8712-pidless-batch-row',
+      status: 'running',
+      cwd: projectCwd,
+      runId: 'run-shared-batch',
+      startedAt: staleStartedAt,
+      // no runtime key at all — the spawn never got far enough to record one
+    },
+  ]);
+  // Only the sibling's log exists in the shared batch dir.
+  writeRunLog('run-shared-batch', 'zzq8712-sibling-that-ran', [
+    '{"type":"result","subtype":"success","result":"done","is_error":false}',
+  ]);
+
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === 'zzq8712-pidless-batch-row');
+  assert.equal(row.status, 'failed');
+  assert.equal(row.runId, null, 'a runId whose dir holds no artifact for this slug must not survive the reap');
+});
+
 test('reapDeadRunningJobs leaves a pidless row alone while it is still within the grace window', async () => {
   const projectCwd = path.join(tmpHome, 'd-project');
   fs.mkdirSync(projectCwd, { recursive: true });

package/src/main/__tests__/scheduler-stuck-failed-escalation.test.cjs

@@ -0,0 +1,136 @@
+/**
+ * scheduler-stuck-failed-escalation.test.cjs
+ *
+ * `failed` is a fully terminal state for every automated recovery path in
+ * scheduler.cjs (selectResumeRecoveryTarget/selectAutoFixTargets require
+ * needs_review, reapDeadRunningJobs only ever writes running → failed,
+ * reconcile-repair's to-pending is for structurally invalid rows) — only a
+ * human's scheduler_reset_job ever takes failed → pending. Job
+ * 4056-outcome-stats sat `failed` for five days with no operator signal
+ * (reported 2026-09-10, social-signals-trader), even once the periodic
+ * reverify guard fix (shouldRunPeriodicReverify, commit f4125f8) made the
+ * pass actually fire on it — reverifyNeedsReview's failed branch can only
+ * annotate looksDone, never resolve a failed row.
+ *
+ * These tests cover findStuckFailedJobs (the escalation candidate finder) and
+ * stuckFailedEscalationDisabled (the kill switch gate) in isolation.
+ *
+ * HOME is overridden to a tmp dir BEFORE requiring scheduler.cjs — see
+ * scheduler-reap-dead-running-jobs.test.cjs's comment for why.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-stuck-failed-escalation.test.cjs
+ */
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'stuck-failed-escalation-test-'));
+process.env.HOME = tmpHome;
+
+const {
+  findStuckFailedJobs,
+  STUCK_FAILED_ESCALATE_MS,
+  stuckFailedEscalationDisabled,
+  isRescanCandidate,
+} = require('../scheduler.cjs');
+
+function writeRunLog(runId, slug, lines) {
+  const runDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(path.join(runDir, `${slug}.log`), lines.join('\n') + '\n');
+}
+
+const DAY_MS = 24 * 60 * 60_000;
+
+test('a failed rescan-candidate older than the threshold is reported exactly once', () => {
+  writeRunLog('run-4056', '4056-outcome-stats', ['[scheduler] starting 4056-outcome-stats']); // no result event
+  const now = Date.now();
+  const job = {
+    slug: '4056-outcome-stats',
+    status: 'failed',
+    cwd: '/home/user/social-signals-trader',
+    runId: 'run-4056',
+    statusHistory: [{ to: 'failed', at: new Date(now - 5 * DAY_MS).toISOString() }],
+  };
+  assert.equal(isRescanCandidate(job), true, 'fixture must be a genuine rescan candidate');
+
+  const found = findStuckFailedJobs([job], now, STUCK_FAILED_ESCALATE_MS);
+  assert.equal(found.length, 1);
+  assert.equal(found[0].slug, '4056-outcome-stats');
+  assert.equal(found[0].cwd, '/home/user/social-signals-trader');
+  assert.ok(found[0].ageMs >= 5 * DAY_MS - 1000);
+});
+
+test('a second pass over the same row (after the caller stamps stuckFailedNotified) produces no second notification', () => {
+  writeRunLog('run-4056b', 'repeat-offender', []);
+  const now = Date.now();
+  const job = {
+    slug: 'repeat-offender',
+    status: 'failed',
+    runId: 'run-4056b',
+    statusHistory: [{ to: 'failed', at: new Date(now - 2 * DAY_MS).toISOString() }],
+  };
+  assert.equal(findStuckFailedJobs([job], now, STUCK_FAILED_ESCALATE_MS).length, 1);
+
+  // Simulate the caller stamping the row after the first notification.
+  job.stuckFailedNotified = true;
+  assert.equal(findStuckFailedJobs([job], now, STUCK_FAILED_ESCALATE_MS).length, 0, 'idempotency flag must suppress re-notification');
+});
+
+test('a failed row younger than the threshold is not reported', () => {
+  writeRunLog('run-fresh', 'fresh-failure', []);
+  const now = Date.now();
+  const job = {
+    slug: 'fresh-failure',
+    status: 'failed',
+    runId: 'run-fresh',
+    statusHistory: [{ to: 'failed', at: new Date(now - 60_000).toISOString() }],
+  };
+  assert.equal(findStuckFailedJobs([job], now, STUCK_FAILED_ESCALATE_MS).length, 0);
+});
+
+test('a failed row with a real result event (genuine red gate, not a rescan candidate) is never reported, however old', () => {
+  writeRunLog('run-genuine-red', 'genuine-red', [
+    JSON.stringify({ type: 'result', subtype: 'success', is_error: true }),
+  ]);
+  const now = Date.now();
+  const job = {
+    slug: 'genuine-red',
+    status: 'failed',
+    runId: 'run-genuine-red',
+    statusHistory: [{ to: 'failed', at: new Date(now - 10 * DAY_MS).toISOString() }],
+  };
+  assert.equal(isRescanCandidate(job), false);
+  assert.equal(findStuckFailedJobs([job], now, STUCK_FAILED_ESCALATE_MS).length, 0);
+});
+
+test('a non-failed row, or a failed row with no recoverable failed timestamp, is skipped rather than guessed at', () => {
+  const now = Date.now();
+  assert.equal(findStuckFailedJobs([{ slug: 'a', status: 'needs_review' }], now, STUCK_FAILED_ESCALATE_MS).length, 0);
+  writeRunLog('run-no-history', 'no-history', []);
+  assert.equal(
+    findStuckFailedJobs(
+      [{ slug: 'no-history', status: 'failed', runId: 'run-no-history', statusHistory: [] }],
+      now,
+      STUCK_FAILED_ESCALATE_MS,
+    ).length,
+    0,
+  );
+});
+
+test('stuckFailedEscalationDisabled reflects SM_STUCK_FAILED_ESCALATE_DISABLE', () => {
+  const saved = process.env.SM_STUCK_FAILED_ESCALATE_DISABLE;
+  try {
+    delete process.env.SM_STUCK_FAILED_ESCALATE_DISABLE;
+    assert.equal(stuckFailedEscalationDisabled(), false);
+    process.env.SM_STUCK_FAILED_ESCALATE_DISABLE = '1';
+    assert.equal(stuckFailedEscalationDisabled(), true);
+  } finally {
+    if (saved === undefined) delete process.env.SM_STUCK_FAILED_ESCALATE_DISABLE;
+    else process.env.SM_STUCK_FAILED_ESCALATE_DISABLE = saved;
+  }
+});