claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/__tests__/scheduler-heartbeat-payload.test.cjs

@@ -0,0 +1,80 @@
+/**
+ * scheduler-heartbeat-payload.test.cjs — the heartbeat line carries build
+ * identity, a subsystem throw yields a `degraded: true` line, and both
+ * watchdogHelpers.heartbeatFresh and health.readFreshHeartbeat treat a
+ * degraded line as NOT fresh.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-heartbeat-payload.test.cjs
+ */
+'use strict';
+
+import { test, expect, beforeEach, vi } from 'vitest';
+const fs = require('node:fs');
+const schedulerPaths = require('../lib/schedulerPaths.cjs');
+const scheduler = require('../scheduler.cjs');
+const { heartbeatFresh } = require('../lib/watchdogHelpers.cjs');
+const { readFreshHeartbeat } = require('../health.cjs');
+
+const HB = () => schedulerPaths.heartbeatPath();
+const lastLine = () => JSON.parse(fs.readFileSync(HB(), 'utf8').trim().split('\n').pop());
+
+beforeEach(() => {
+  fs.mkdirSync(require('node:path').dirname(HB()), { recursive: true });
+  fs.rmSync(HB(), { force: true });
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+test('healthy tick writes build {version, codeSha, builtAt} and is fresh', () => {
+  const entry = scheduler.heartbeatTick({ readQueueSync: () => ({ jobs: [], unreadable: true, paused: null }) });
+  expect(entry.degraded).toBeUndefined();
+  const line = lastLine();
+  expect(line.build).toEqual(expect.objectContaining({ version: expect.anything() }));
+  expect(Object.keys(line.build).sort()).toEqual(['builtAt', 'codeSha', 'version']);
+  expect(line.counts).toBeDefined();
+  expect(heartbeatFresh(HB())).toBe(true);
+  expect(readFreshHeartbeat(HB())).not.toBeNull();
+});
+
+test('a throwing queue read writes a degraded line with the error, never a fresh one', () => {
+  scheduler.heartbeatTick({ readQueueSync: () => { throw new Error('boom-queue'); } });
+  const line = lastLine();
+  expect(line.degraded).toBe(true);
+  expect(line.errors[0]).toEqual({ subsystem: 'queue-read-starvation-watchdog', error: 'boom-queue' });
+  expect(line.build).toBeDefined();
+  expect(line.utilization).toBeUndefined();
+  expect(heartbeatFresh(HB())).toBe(false);
+  expect(readFreshHeartbeat(HB())).toBeNull();
+});
+
+test('a throw in the stall detector degrades the line too', () => {
+  scheduler.heartbeatTick({ readQueueSync: () => ({ jobs: null, unreadable: true, paused: null }) });
+  const line = lastLine();
+  expect(line.degraded).toBe(true);
+  expect(line.errors.some((e) => e.subsystem === 'stall-detector' || e.subsystem === 'heartbeat-write')).toBe(true);
+  expect(heartbeatFresh(HB())).toBe(false);
+});
+
+test('watchdogHelpers treats a hand-written degraded line as stale', () => {
+  fs.writeFileSync(HB(), JSON.stringify({ ts: Date.now(), degraded: true }) + '\n');
+  expect(heartbeatFresh(HB())).toBe(false);
+  fs.writeFileSync(HB(), JSON.stringify({ ts: Date.now() }) + '\n');
+  expect(heartbeatFresh(HB())).toBe(true);
+});
+
+test('healthy tick carries dispatch {..., pendingDispatchable excludes blocked chains}', () => {
+  const jobs = [
+    { slug: '1-a', cwd: '/p', status: 'failed' },
+    { slug: '2-b', cwd: '/p', status: 'pending', dependsOn: ['1-a'] },
+    { slug: '3-c', cwd: '/p', status: 'pending' },
+  ];
+  const entry = scheduler.heartbeatTick({
+    readQueueSync: () => ({ jobs, unreadable: true, paused: null, lastRunAt: '2026-01-01T00:00:00.000Z' }),
+  });
+  expect(entry.dispatch).toEqual(expect.objectContaining({
+    lastRunAt: '2026-01-01T00:00:00.000Z', pendingDispatchable: 1, runningCount: 0, paused: false,
+  }));
+  expect(Object.keys(entry.dispatch).sort()).toEqual(
+    ['drain', 'lastDispatchAttemptAt', 'lastRunAt', 'lastTickReason', 'paused', 'pendingDispatchable', 'runningCount'],
+  );
+  expect(entry.dispatch.drain).toBeNull();
+});

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

@@ -18,6 +18,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 const { execFileSync } = require('node:child_process');
 
 let tmpHome;
@@ -52,6 +53,12 @@ function registerActiveProject(cwd) {
   fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
 }
 
+// Every PRD fixture below lives Epic-scoped, not in the legacy flat prds/
+// dir: the flat dir is retired and swept into prds-archived/ by
+// consolidateFlatPrds the moment a job is no longer pending/running, which
+// would strand a just-completed/failed row the instant reconcile()'s
+// auto-archive-drop path (see scheduler-reconcile-history-backfill.test.cjs)
+// treats the now-missing PRD as "archived on purpose" and drops it.
 function writeProjectQueue(cwd, jobs) {
   const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
   fs.mkdirSync(stateDir, { recursive: true });
@@ -68,16 +75,13 @@ function writeProjectQueue(cwd, jobs) {
 // which is not the scenario under test here — this must land as a genuine
 // non-zero exit.
 function writeKilledClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-killed-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     fs.writeFileSync(path.join(process.cwd(), 'README.md'), 'hello\\nedited by job\\n', 'utf8');
     fs.writeFileSync(path.join(process.cwd(), 'job-output.txt'), 'work the job produced before dying\\n', 'utf8');
     process.exit(137);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 beforeAll(() => {
@@ -117,7 +121,7 @@ test('an in-place job killed (exit 137) mid-run salvages a delta-scoped patch th
   fs.appendFileSync(path.join(projectCwd, 'human-wip.txt'), 'more human edits\n', 'utf8');
 
   const slug = `1098-test-inplace-killed-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Do a thing that gets killed mid-run.', 'utf8');
 
@@ -192,13 +196,10 @@ test('an in-place job killed (exit 137) mid-run salvages a delta-scoped patch th
 // — a job whose only working-tree dirt is pre-existing human/sibling WIP
 // present before the run even started.
 function writeNoopClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-noop-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'nothing to do', is_error: false }) + '\\n');
     process.exit(0);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 // Stub `claude` binary that blocks until a `go` marker file appears in its
@@ -206,11 +207,19 @@ function writeNoopClaudeStub() {
 // 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 = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     const { execFileSync } = require('child_process');
+    // spawnJob's dispatch path probes 'claude --version' (claudeBin.cjs)
+    // BEFORE the real dispatch — a real claude binary answers that
+    // near-instantly regardless of any in-flight work, so the stub must
+    // too, or the probe's own 8s exec timeout eats almost this whole test's
+    // poll window before the row ever advances past 'running-stamped'.
+    if (process.argv.includes('--version')) {
+      process.stdout.write('1.0.0 (stub)\\n');
+      process.exit(0);
+    }
     const goFile = path.join(process.cwd(), 'go.marker');
     const deadline = Date.now() + 10_000;
     while (!fs.existsSync(goFile) && Date.now() < deadline) {
@@ -218,9 +227,7 @@ function writeGatedClaudeStub() {
     }
     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 () => {
@@ -229,7 +236,7 @@ test('dispatchPhase breadcrumb advances to "spawned" mid-run and is gone after f
   registerActiveProject(projectCwd);
 
   const slug = `1163-test-dispatchphase-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Do a thing, gated on a marker file.', 'utf8');
 
@@ -285,7 +292,7 @@ test('a job whose tree is dirty only from pre-existing baseline WIP (human/sibli
   fs.writeFileSync(path.join(projectCwd, 'human-wip.txt'), 'human work in progress\n', 'utf8');
 
   const slug = `1098-test-inplace-noop-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Do nothing.', 'utf8');
 

package/src/main/__tests__/scheduler-investigation-prompt.test.cjs

@@ -1,12 +1,12 @@
 /**
  * scheduler-investigation-prompt.test.cjs — unit tests for buildInvestigationPrompt.
  *
- * Run: timeout 120 node --test src/main/__tests__/scheduler-investigation-prompt.test.cjs
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-investigation-prompt.test.cjs
  */
 
 'use strict';
 
-const { test } = require('node:test');
+import { test } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
@@ -93,7 +93,7 @@ test('prompt instructs that cwd must be the git repo root where the fix will lan
   assert.match(prompt, /needs_review/);
 });
 
-test('prompt frontmatter block still declares exactly the four expected keys', () => {
+test('prompt frontmatter block still declares exactly the five expected keys', () => {
   const prompt = buildInvestigationPrompt(makeArgs());
   const fenceMatch = prompt.match(/```\s*\n\s*---\n([\s\S]*?)\n\s*---\n\s*```/);
   assert.ok(fenceMatch, 'expected a fenced frontmatter block in the prompt');
@@ -101,7 +101,7 @@ test('prompt frontmatter block still declares exactly the four expected keys', (
     .split('\n')
     .filter((line) => line.trim().length > 0)
     .map((line) => line.split(':')[0].trim());
-  assert.deepEqual(keys, ['title', 'cwd', 'parallelGroup', 'estimateMinutes']);
+  assert.deepEqual(keys, ['title', 'cwd', 'parallelGroup', 'estimateMinutes', 'isFixPlan']);
 });
 
 // ─── isGitRepoSync (scheduler.cjs) ─────────────────────────────────────────────

package/src/main/__tests__/scheduler-launch-failure.test.cjs

@@ -20,6 +20,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 
 let tmpHome;
 let originalHome;
@@ -50,8 +51,7 @@ afterEach(() => {
 const THINKING_400 = 'API Error: 400 {"detail":{"error":"{\\"message\\":\\"\\\\\\"thinking.type.enabled\\\\\\" is not supported for this model. Use \\\\\\"thinking.type.adaptive\\\\\\" and \\\\\\"output_config.effort\\\\\\" to control thinking behavior.\\"}"}}';
 
 function writeStub({ mode }) {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-launch-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     fs.writeFileSync(path.join(process.cwd(), 'env.marker'), JSON.stringify({
@@ -67,9 +67,7 @@ function writeStub({ mode }) {
     }
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'error', is_error: true, num_turns: 9, usage: { input_tokens: 100, output_tokens: 250 }, result: 'Error: tests failed' }) + '\\n');
     process.exit(1);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 function mkProject() {

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

@@ -34,7 +34,7 @@ const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'looks-done-test-'));
 process.env.HOME = tmpHome;
 
 const { reverifyNeedsReview, computeLooksDone, applyNeedsReviewAutoResolve, findSatisfyingCommitOnMain } = require('../scheduler.cjs');
-const { resolvePrdWriteDir } = require('../lib/prdLocations.cjs');
+const { resolveEpicPrdWriteDir } = require('../lib/prdLocations.cjs');
 const { bustCwdCache } = require('../lib/queueStore.cjs');
 
 function git(args, cwd) {
@@ -92,13 +92,32 @@ function writeRunLog(runId, slug, lines) {
   fs.writeFileSync(path.join(runDir, `${slug}.log`), lines.join('\n') + '\n');
 }
 
+// Epic-scoped, not the legacy flat prds/ dir: the flat dir is retired and
+// swept into prds-archived/ by consolidateFlatPrds the moment a job is no
+// longer live (pending/running/needs_review/investigating), which would
+// strand a row that starts 'failed' before reverifyNeedsReview ever gets a
+// chance to decide anything about it.
 function writePrd(cwd, slug, body) {
-  const dir = resolvePrdWriteDir(cwd);
+  const dir = resolveEpicPrdWriteDir(cwd, 'test-fixture-epic');
   fs.mkdirSync(dir, { recursive: true });
   const text = `---\ntitle: Test PRD\ncwd: ${cwd}\nestimateMinutes: 30\n---\n${body}\n`;
   fs.writeFileSync(path.join(dir, `${slug}.md`), text);
 }
 
+// A job reverifyNeedsReview() heals to 'completed' has its PRD archived
+// immediately (archiveCompletedPrd) and its row backfilled to history.jsonl
+// + dropped from queue.json on the very same reconcile pass — see
+// scheduler-reconcile-history-backfill.test.cjs. Look in both places.
+function readTerminalRow(queuePath, projectCwd, slug) {
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  if (row) return row;
+  const historyPath = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'state', 'history.jsonl');
+  if (!fs.existsSync(historyPath)) return undefined;
+  const lines = fs.readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  return lines.map((l) => JSON.parse(l)).reverse().find((j) => j.slug === slug);
+}
+
 async function wait(ms) {
   await new Promise((r) => setTimeout(r, ms));
 }
@@ -220,11 +239,11 @@ test('needs_review with an in-window commit heals exactly as today (regression
 
   await reverifyNeedsReview();
 
-  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
-  assert.equal(jobs.length, 1);
-  assert.equal(jobs[0].status, 'completed', 'a clean re-verify on a RESCANNABLE verdict must still heal');
-  assert.equal(jobs[0].verifierVerdict, undefined);
-  assert.equal(jobs[0].error, null);
+  const row = readTerminalRow(queuePath, projectCwd, '20-clean-feature');
+  assert.ok(row, 'healed job must be found in queue.json or (once archived+backfilled) history.jsonl');
+  assert.equal(row.status, 'completed', 'a clean re-verify on a RESCANNABLE verdict must still heal');
+  assert.equal(row.verifierVerdict, undefined);
+  assert.equal(row.error, null);
 });
 
 test('computeLooksDone: no declared paths on the PRD → null, never fabricates evidence', async () => {

package/src/main/__tests__/scheduler-manual-pause.test.cjs

@@ -0,0 +1,118 @@
+/**
+ * scheduler-manual-pause.test.cjs — user-initiated pause (schedule:pause /
+ * POST /admin/scheduler/pause). A 'manual' pause stops NEW dispatch, never
+ * kills running jobs, survives restart, and is cleared only by an explicit
+ * Resume / Run now — never by the rate-limit reset timer or network recovery.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-manual-pause.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-manual-pause-'));
+  process.env.HOME = tmpHome;
+  process.env.SM_JOB_WORKTREE_DISABLE = '1';
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  delete process.env.SM_JOB_WORKTREE_DISABLE;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  await scheduler.clearPause('manual');
+});
+
+test('pause engages reason "manual" with no resumeAt, even inside the manual-override cooldown', async () => {
+  await scheduler.clearPause('manual'); // starts the 5-minute cooldown
+  await scheduler.setPaused('manual', null);
+  const state = await queueStore.readMerged();
+  expect(state.paused).toBeTruthy();
+  expect(state.paused.reason).toBe('manual');
+  expect(state.paused.resumeAt).toBeNull();
+});
+
+test('a manual pause never arms a resume time, even if a resumeAt is supplied', async () => {
+  await scheduler.setPaused('manual', new Date(Date.now() + 3_600_000).toISOString());
+  const state = await queueStore.readMerged();
+  expect(state.paused.resumeAt).toBeNull();
+});
+
+test('pause blocks tickQueue dispatch', async () => {
+  await scheduler.setPaused('manual', null);
+  const result = await scheduler.tickQueue();
+  expect(result.fired).toBe(false);
+  expect(result.reason).toBe('paused');
+});
+
+test('an auto rate_limit / network / auth pause cannot displace a manual pause', async () => {
+  await scheduler.setPaused('manual', null);
+  await scheduler.setPaused('rate_limit', new Date(Date.now() + 3_600_000).toISOString());
+  await scheduler.setPaused('network', null);
+  await scheduler.setPaused('auth', null);
+  const state = await queueStore.readMerged();
+  expect(state.paused.reason).toBe('manual');
+  expect(state.paused.resumeAt).toBeNull();
+});
+
+test('poll recovery and the resume-time computation never clear/arm a manual pause', () => {
+  expect(scheduler.pollRecoveryClearSource('manual', true)).toBeNull();
+  expect(scheduler.pollRecoveryClearSource('manual', false)).toBeNull();
+  expect(scheduler.computeEffectiveResumeAt('manual', null)).toBeNull();
+});
+
+test('a running job survives a pause untouched', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(tmpHome, 'pause-survivor-'));
+  const slugDir = path.join(tmpHome, '.claude', 'projects', 'pause-survivor-slug');
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd: projectCwd }) + '\n');
+  queueStore.bustCwdCache();
+  const stateDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({
+    jobs: [{ slug: 'pause-survivor', status: 'running', cwd: projectCwd, pid: process.pid, runId: 'r1', startedAt: new Date().toISOString() }],
+  }));
+  await scheduler.setPaused('manual', null);
+  const state = await queueStore.readMerged();
+  const row = state.jobs.find((j) => j.slug === 'pause-survivor');
+  expect(row.status).toBe('running');
+  expect(row.runId).toBe('r1');
+});
+
+test('a manual pause survives restart (re-read from disk; boot never clears it)', async () => {
+  await scheduler.setPaused('manual', null);
+  const onDisk = await queueStore.readMerged(); // what a fresh process reads at boot
+  expect(onDisk.paused.reason).toBe('manual');
+  // Boot only clears a pause whose resumeAt has elapsed / re-arms one with a
+  // resumeAt; a manual pause has none, so neither branch applies.
+  expect(onDisk.paused.resumeAt).toBeNull();
+});
+
+test('resume clears a manual pause', async () => {
+  await scheduler.setPaused('manual', null);
+  await scheduler.clearPause('manual');
+  const state = await queueStore.readMerged();
+  expect(state.paused).toBeNull();
+});
+
+test('remote.pause / remote.resume are the admin-route twins of the IPC handlers', async () => {
+  expect(await scheduler.remote.pause()).toEqual({ ok: true });
+  expect((await queueStore.readMerged()).paused.reason).toBe('manual');
+  expect(await scheduler.remote.resume()).toEqual({ ok: true });
+  expect((await queueStore.readMerged()).paused).toBeNull();
+});

package/src/main/__tests__/scheduler-meta-code-sha.test.cjs

@@ -5,19 +5,42 @@
  * scheduler process is otherwise invisible in the run record, which cost a
  * full investigation to diagnose a false pass_no_commit.
  *
+ * SCHEDULER_CODE_SHA now resolves through src/main/lib/buildIdentity.cjs
+ * (build-identity-stamp PRD): a production npx install ships no .git, so a
+ * runtime `git rev-parse` was structurally always null there — this file
+ * used to accept that null unconditionally, which made the dead stamp green
+ * forever. With src/main/build-info.json present (ensured below — the exact
+ * artifact scripts/write-build-info.cjs bakes at publish time), the sha must
+ * be real.
+ *
  * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-meta-code-sha.test.cjs
  */
 
 'use strict';
 
-import { test, expect } from 'vitest';
+import { test, expect, afterAll } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BUILD_INFO_PATH = path.join(__dirname, '..', 'build-info.json');
+const preexistingBuildInfo = fs.existsSync(BUILD_INFO_PATH) ? fs.readFileSync(BUILD_INFO_PATH, 'utf8') : null;
+if (preexistingBuildInfo === null) {
+  // eslint-disable-next-line global-require
+  require('../../../scripts/write-build-info.cjs').writeBuildInfo();
+}
+
 const { SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA } = require('../scheduler.cjs');
 
+afterAll(() => {
+  if (preexistingBuildInfo === null) fs.rmSync(BUILD_INFO_PATH, { force: true });
+  else fs.writeFileSync(BUILD_INFO_PATH, preexistingBuildInfo);
+});
+
 test('SCHEDULER_BOOTED_AT is a valid ISO date string', () => {
   expect(typeof SCHEDULER_BOOTED_AT).toBe('string');
   expect(Number.isNaN(new Date(SCHEDULER_BOOTED_AT).getTime())).toBe(false);
 });
 
-test('SCHEDULER_CODE_SHA is null or a short git hex SHA', () => {
-  expect(SCHEDULER_CODE_SHA === null || /^[0-9a-f]{7,40}$/.test(SCHEDULER_CODE_SHA)).toBe(true);
+test('SCHEDULER_CODE_SHA is a real short git hex SHA when build-info.json is present — never null', () => {
+  expect(SCHEDULER_CODE_SHA).toMatch(/^[0-9a-f]{7,40}$/);
 });

package/src/main/__tests__/scheduler-prd-missing-skip.test.cjs

@@ -103,6 +103,22 @@ function writeProjectQueue(cwd, jobs) {
   return path.join(stateDir, 'queue.json');
 }
 
+// This test's whole premise is a PRD source missing EVERYWHERE — so the row
+// this produces is exactly what reconcile()'s auto-archive-drop path treats
+// as "archived on purpose": backfilled to history.jsonl and dropped from
+// queue.json in the very same reconcile pass that spawnJob's own
+// broadcast({flush:true}) triggers on completion (see
+// scheduler-reconcile-history-backfill.test.cjs). Look in both places.
+function readTerminalRow(queuePath, projectCwd, slug) {
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === slug);
+  if (row) return row;
+  const historyPath = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'state', 'history.jsonl');
+  if (!fs.existsSync(historyPath)) return undefined;
+  const lines = fs.readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  return lines.map((l) => JSON.parse(l)).reverse().find((j) => j.slug === slug);
+}
+
 // This is the actual regression case: PRD 812's fix only covered executeJob's
 // own return value. The bug lived one layer up, in spawnJob's post-run
 // handler, which only short-circuited on skipped === 'prd-archived' and let
@@ -123,8 +139,7 @@ test("spawnJob's post-run handler retires a prd-missing skip as a plain completi
     const job = { slug, cwd: projectCwd };
     await spawnJob(job, 'run-spawnjob-missing', runDir, projectCwd);
 
-    const state = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-    const row = state.jobs.find((j) => j.slug === slug);
+    const row = readTerminalRow(queuePath, projectCwd, slug);
     expect(row).toBeDefined();
     // A 'prd-missing' skip means no executor ever ran — it must land on the
     // distinct 'skipped' status, never 'completed' (the status a genuine

package/src/main/__tests__/scheduler-prd-persona-spawn.test.cjs

@@ -17,6 +17,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 
 let tmpHome;
 let originalHome;
@@ -66,16 +67,13 @@ test('buildClaudeSpawnArgs: model is never omitted even without a systemPrompt',
 // stream-json success result and exits 0 — same technique as
 // scheduler-bash-timeout-env.test.cjs's env-var proof, applied to argv.
 function writeClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-argv-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     fs.writeFileSync(path.join(process.cwd(), 'argv.marker'), JSON.stringify(process.argv.slice(2)), 'utf8');
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok' }) + '\\n');
     process.exit(0);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 function writePersona(dir, name, frontmatterLines, bodyText) {

package/src/main/__tests__/scheduler-quiet-machine-lease.test.cjs

@@ -19,6 +19,7 @@ import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 const { execFileSync } = require('node:child_process');
 
 let tmpHome;
@@ -52,10 +53,41 @@ function registerActiveProject(cwd) {
   fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
 }
 
+// Every real scheduler row is born from a real PRD .md file — reconcile()'s
+// auto-archive-drop path (a terminal job whose slug has no on-disk PRD
+// anywhere is treated as "archived on purpose": dropped from queue.json and
+// backfilled to history.jsonl, see scheduler-reconcile-history-backfill.
+// test.cjs) fires the moment a completion path reconciles with
+// broadcast({flush:true}). Without a matching PRD source, a row this test
+// drives to a terminal status vanishes from queue.json before the assertions
+// below ever read it back. Epic-scoped (not the legacy flat prds/ dir) so
+// it's never swept by consolidateFlatPrds either.
+// Some tests author their own real PRD (e.g. with `quietMachine: true`
+// frontmatter) before calling writeProjectQueue — never shadow that with a
+// blank fixture, which would silently overwrite its parsed frontmatter on
+// the next reconcile() refresh (onDisk.set(slug, ...) keeps whichever file a
+// later scan pass parses).
+function prdAlreadyExists(cwd, slug) {
+  const flatPath = path.join(cwd, 'session-manager-operations', 'scheduler', 'prds', `${slug}.md`);
+  if (fs.existsSync(flatPath)) return true;
+  const epicsRoot = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics');
+  if (!fs.existsSync(epicsRoot)) return false;
+  return fs.readdirSync(epicsRoot).some((epicId) => fs.existsSync(path.join(epicsRoot, epicId, 'prds', `${slug}.md`)));
+}
+
+function writeFixturePrd(cwd, slug) {
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Test fixture PRD.', 'utf8');
+}
+
 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));
+  for (const job of jobs) {
+    if (job && job.slug && !prdAlreadyExists(job.cwd || cwd, job.slug)) writeFixturePrd(job.cwd || cwd, job.slug);
+  }
   return path.join(stateDir, 'queue.json');
 }
 
@@ -66,15 +98,12 @@ function writeProjectQueue(cwd, jobs) {
 // as a genuine kill-with-partial-work, not an auto-retryable transient blip
 // with no evidence of real execution.
 function writeKilledClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-quiet-killed-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     const fs = require('fs');
     const path = require('path');
     fs.writeFileSync(path.join(process.cwd(), 'job-output.txt'), 'work in progress when killed\\n', 'utf8');
     process.exit(137);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 let reapDeadRunningJobs;
@@ -109,7 +138,13 @@ test('a killed quietMachine job releases the exclusive lease, and an ordinary jo
 
   const quietSlug = `1107-test-quiet-killed-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
   const ordinarySlug = `1107-test-ordinary-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  // Epic-scoped, not the legacy flat prds/ dir: the flat dir is retired and
+  // swept into prds-archived/ by consolidateFlatPrds the moment a job is no
+  // longer pending/running, which would silently strip this PRD's
+  // `quietMachine: true` frontmatter from the row on the very next
+  // reconcile() refresh (or drop the row entirely once terminal — see
+  // scheduler-reconcile-history-backfill.test.cjs).
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'epics', 'test-fixture-epic', 'prds');
   fs.mkdirSync(prdsDir, { recursive: true });
   fs.writeFileSync(path.join(prdsDir, `${quietSlug}.md`), '---\nquietMachine: true\n---\nMeasure timing without contention, then get killed.', 'utf8');
   fs.writeFileSync(path.join(prdsDir, `${ordinarySlug}.md`), 'An ordinary PRD queued behind the quiet job.', 'utf8');