claude-code-session-manager 0.78.0 → 0.80.0

package/src/main/__tests__/scheduler-never-stop.test.cjs

@@ -0,0 +1,157 @@
+/**
+ * scheduler-never-stop.test.cjs — the invariant: if a queue holds ready PRDs,
+ * something must drive them.
+ *
+ * Every stall observed in this codebase was a different CAUSE with the same
+ * SHAPE — ready rows, nothing running, nobody ticking:
+ *   - a rate-limited exit stamped terminal 'failed' (2026-09-05: 42 rows)
+ *   - a spin loop past the manual-clear cooldown
+ *   - a worktree merge-back leaving the project on a job branch
+ *   - a job parked needs_review with no fix plan
+ *   - app churn under session-manager-operations/ counted as unfinished work
+ *   - the billing meter itself 429ing so utilization never reported
+ * Guarding each cause individually always lags the next one, so the watchdog
+ * guards the shape.
+ *
+ * Run: timeout 180 npx vitest run src/main/__tests__/scheduler-never-stop.test.cjs
+ */
+
+'use strict';
+
+// vitest, NOT node:test — this repo's suite is vitest-only (CLAUDE.md).
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// HOME before require: every state path is baked from os.homedir() at load.
+process.env.HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'never-stop-test-'));
+
+const {
+  classifyQueueStarvation,
+  QUEUE_STARVATION_MS,
+  stripAppOwnedChurn,
+} = require('../scheduler.cjs');
+
+const CWD = '/home/bilko/Projects/starry-night-ships';
+const NOW = Date.parse('2026-09-05T23:00:00.000Z');
+const idleFor = (ms) => NOW - ms;
+const LONG = QUEUE_STARVATION_MS + 60_000;
+
+const base = (over = {}) => ({
+  jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+  paused: null,
+  runningCount: 0,
+  lastRunAtMs: idleFor(LONG),
+  now: NOW,
+  ...over,
+});
+
+// ── the invariant ────────────────────────────────────────────────────────────
+
+test('ready work + nothing running + long idle => starved, and a tick would help', () => {
+  const v = classifyQueueStarvation(base());
+  assert.equal(v.kind, 'starved');
+  assert.equal(v.pending, 1);
+  assert.equal(v.dispatchable, 1);
+});
+
+test('the real incident shape: 40 ready rows, 0 running, idle for hours', () => {
+  const jobs = Array.from({ length: 40 }, (_, i) => ({
+    slug: `${207 + i}-step`, cwd: CWD, status: 'pending', dependsOn: [],
+  }));
+  const v = classifyQueueStarvation(base({ jobs, lastRunAtMs: idleFor(3 * 60 * 60_000) }));
+  assert.equal(v.kind, 'starved');
+  assert.equal(v.dispatchable, 40);
+});
+
+// ── it must NOT fire when the queue is legitimately quiet ────────────────────
+
+test('a running job means the queue is flowing — never starved', () => {
+  assert.equal(classifyQueueStarvation(base({ runningCount: 1 })), null);
+});
+
+test('no pending rows is not a stall', () => {
+  assert.equal(classifyQueueStarvation(base({ jobs: [{ slug: 'a', cwd: CWD, status: 'completed' }] })), null);
+});
+
+test('paused is a DECISION, not a stall — the watchdog must never override it', () => {
+  assert.equal(classifyQueueStarvation(base({ paused: { reason: 'rate_limit', resumeAt: null } })), null);
+});
+
+test('inside the idle threshold the normal path gets its chance first', () => {
+  assert.equal(classifyQueueStarvation(base({ lastRunAtMs: idleFor(QUEUE_STARVATION_MS - 1000) })), null);
+});
+
+test('a never-recorded lastRunAt counts as infinitely idle, not as healthy', () => {
+  const v = classifyQueueStarvation(base({ lastRunAtMs: NaN }));
+  assert.equal(v.kind, 'starved');
+});
+
+// ── blocked is a DIFFERENT verdict from starved ──────────────────────────────
+
+test('every pending row behind a terminal dep => blocked, not starved (a tick cannot help)', () => {
+  const jobs = [
+    { slug: '206-lava-ape', cwd: CWD, status: 'failed', dependsOn: [] },
+    { slug: '207-body', cwd: CWD, status: 'pending', dependsOn: ['206-lava-ape'] },
+    { slug: '208-docs', cwd: CWD, status: 'pending', dependsOn: ['207-body'] },
+  ];
+  const v = classifyQueueStarvation(base({ jobs }));
+  assert.equal(v.kind, 'blocked');
+  assert.equal(v.pending, 2);
+  assert.equal(v.dispatchable, 0);
+  assert.deepEqual(v.blockedChains[0].blockedBy, ['206-lava-ape']);
+});
+
+test('one dispatchable row among blocked ones still counts as starved — the queue can make progress', () => {
+  const jobs = [
+    { slug: 'x-dead', cwd: CWD, status: 'failed', dependsOn: [] },
+    { slug: 'y-blocked', cwd: CWD, status: 'pending', dependsOn: ['x-dead'] },
+    { slug: 'z-ready', cwd: CWD, status: 'pending', dependsOn: [] },
+  ];
+  const v = classifyQueueStarvation(base({ jobs }));
+  assert.equal(v.kind, 'starved');
+  assert.equal(v.dispatchable, 1);
+});
+
+test('a project blocked while ANOTHER project has ready work is still starved overall', () => {
+  const jobs = [
+    { slug: 'a-dead', cwd: '/p/one', status: 'failed', dependsOn: [] },
+    { slug: 'b-blocked', cwd: '/p/one', status: 'pending', dependsOn: ['a-dead'] },
+    { slug: 'c-ready', cwd: '/p/two', status: 'pending', dependsOn: [] },
+  ];
+  assert.equal(classifyQueueStarvation(base({ jobs })).kind, 'starved');
+});
+
+// ── app-owned churn must never be blamed on a job ────────────────────────────
+
+test('stripAppOwnedChurn drops session-manager-operations churn, keeps real source', () => {
+  const out = stripAppOwnedChurn([
+    'src/main/scheduler.cjs',
+    'session-manager-operations/scheduler/state/queue.json',
+    'session-manager-operations/scheduler/state/history.jsonl',
+    'session-manager-operations/prompt-sessions/active-index.json',
+    'dashboard/panels/outcome-stats.jsx',
+  ]);
+  assert.deepEqual(out, ['src/main/scheduler.cjs', 'dashboard/panels/outcome-stats.jsx']);
+});
+
+test('stripAppOwnedChurn preserves the null contract (git status unavailable != left nothing)', () => {
+  assert.equal(stripAppOwnedChurn(null), null);
+  assert.equal(stripAppOwnedChurn(undefined), undefined);
+});
+
+test('stripAppOwnedChurn only matches a whole path segment, never a substring', () => {
+  assert.deepEqual(
+    stripAppOwnedChurn(['docs/session-manager-operations-guide.md', 'a/session-manager-operations/x.json']),
+    ['docs/session-manager-operations-guide.md'],
+  );
+});
+
+test('a job that leaves REAL source dirty still parks — the filter must not excuse that', () => {
+  assert.deepEqual(
+    stripAppOwnedChurn(['session-manager-operations/scheduler/state/queue.json', 'scripts/arena/titan.gd']),
+    ['scripts/arena/titan.gd'],
+  );
+});

package/src/main/__tests__/scheduler-no-orphan-run-dir.test.cjs

@@ -0,0 +1,81 @@
+/**
+ * scheduler-no-orphan-run-dir.test.cjs — PRD 1120: pickRunDir() must not
+ * mkdir a run directory until a dispatch actually commits (executeJob's
+ * first write). A dispatch that aborts inside spawnJob before that point —
+ * e.g. sessionSlots.acquire() returning null, the earliest exit in spawnJob
+ * — must leave RUNS_DIR untouched.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-no-orphan-run-dir.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let originalSlots;
+let scheduler;
+let sessionSlots;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-no-orphan-rundir-'));
+  process.env.HOME = tmpHome;
+  originalSlots = process.env.SM_SESSION_SLOTS;
+  scheduler = require('../scheduler.cjs');
+  sessionSlots = require('../lib/sessionSlots.cjs');
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  if (originalSlots === undefined) delete process.env.SM_SESSION_SLOTS;
+  else process.env.SM_SESSION_SLOTS = originalSlots;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  sessionSlots.__resetForTests();
+});
+
+function runsDirEntryCount() {
+  const runsDir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs');
+  try {
+    return fs.readdirSync(runsDir).length;
+  } catch {
+    return 0;
+  }
+}
+
+test('pickRunDir() allocates a runId/dir pair without creating the directory', () => {
+  const before = runsDirEntryCount();
+  const { runId, dir } = scheduler.pickRunDir();
+  expect(runId).toBeTruthy();
+  expect(fs.existsSync(dir)).toBe(false);
+  expect(runsDirEntryCount()).toBe(before);
+});
+
+test('a dispatch that bails at slot-acquisition (earliest spawnJob exit) leaves no directory under RUNS_DIR', async () => {
+  // Force sessionSlots.acquire() to return null immediately — no slots at all.
+  process.env.SM_SESSION_SLOTS = '0';
+  const before = runsDirEntryCount();
+
+  const slug = `1120-slot-miss-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-no-orphan-rundir-project-'));
+  try {
+    await scheduler.spawnJob({ slug, cwd: projectCwd }, `run-${slug}`, path.join(
+      tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', `run-${slug}`
+    ), projectCwd);
+
+    expect(runsDirEntryCount()).toBe(before);
+    expect(fs.existsSync(path.join(
+      tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', `run-${slug}`
+    ))).toBe(false);
+  } finally {
+    delete process.env.SM_SESSION_SLOTS;
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,123 @@
+/**
+ * scheduler-rate-limit-cooldown-freshness.test.cjs — PRD 1119.
+ *
+ * setPaused()'s manual-override cooldown used to suppress WRITING any pause
+ * for 5 minutes after a human Resume/Run now, unconditionally — even when
+ * the triggering rate-limit observation came from a run that started AFTER
+ * the manual clear (i.e. brand-new evidence, not the stale auto-detection
+ * the cooldown exists to ignore). Combined with the halt-reset that resets a
+ * rate-limited job straight back to 'pending', this produced a hot dispatch
+ * loop: dispatch -> 429 in seconds -> reset to pending -> pause suppressed
+ * -> dispatch again, on a ~12s cadence, until the cooldown itself expired.
+ *
+ * isCooldownSuppressed() is the pure predicate this PRD extracts so both
+ * directions of the fix (fresh observation bypasses the cooldown; stale one
+ * stays suppressed) are directly unit-testable without touching queue.json,
+ * mutate(), or any fs state. nextRapidRateLimitCount() is the pure reducer
+ * behind the independent rapid-repeat hard-pause cap (a second circuit
+ * breaker for when the computed resumeAt is itself stale/wrong and would
+ * otherwise let the resume timer keep re-clearing the pause every ~30s,
+ * with every subsequent dispatch genuinely "fresh").
+ *
+ * Run: timeout 60 npx vitest run src/main/__tests__/scheduler-rate-limit-cooldown-freshness.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  isCooldownSuppressed,
+  nextRapidRateLimitCount,
+  CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD,
+  RAPID_RATE_LIMIT_WINDOW_MS,
+  MANUAL_PAUSE_COOLDOWN_MS,
+} = require('../scheduler.cjs');
+
+const clearedAt = 1_000_000;
+
+test('a rate_limit pause triggered by a run that STARTED AFTER the manual clear engages regardless of the cooldown', () => {
+  const now = clearedAt + 60_000; // well inside the 5-minute cooldown window
+  const observedAt = clearedAt + 5_000; // the triggering run started after the clear
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now, observedAt, force: false });
+  expect(suppressed).toBe(false);
+});
+
+test('a rate_limit pause triggered by an observation OLDER than the manual clear stays suppressed', () => {
+  const now = clearedAt + 60_000;
+  const observedAt = clearedAt - 5_000; // stale: this run started before the human cleared the pause
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now, observedAt, force: false });
+  expect(suppressed).toBe(true);
+});
+
+test('no observedAt at all (unrelated pause reasons, e.g. auth/network) is treated as stale — unchanged prior behavior', () => {
+  const now = clearedAt + 60_000;
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now, observedAt: null, force: false });
+  expect(suppressed).toBe(true);
+});
+
+test('once the cooldown window itself has elapsed, suppression lifts regardless of freshness', () => {
+  const now = clearedAt + MANUAL_PAUSE_COOLDOWN_MS + 1;
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now, observedAt: null, force: false });
+  expect(suppressed).toBe(false);
+});
+
+test('no manual clear on record never suppresses', () => {
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: null, now: Date.now(), observedAt: null, force: false });
+  expect(suppressed).toBe(false);
+});
+
+test('force always bypasses the cooldown, fresh or not', () => {
+  const now = clearedAt + 1_000;
+  const staleObservedAt = clearedAt - 5_000;
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now, observedAt: staleObservedAt, force: true });
+  expect(suppressed).toBe(false);
+});
+
+// ---------- rapid-repeat consecutive counter ----------
+
+test('a rate-limited run under the rapid window increments the counter', () => {
+  expect(nextRapidRateLimitCount(0, { rateLimited: true, durationMs: 4_000 })).toBe(1);
+  expect(nextRapidRateLimitCount(1, { rateLimited: true, durationMs: 4_000 })).toBe(2);
+});
+
+test('a rate-limited run that ran for >= the rapid window does not increment the counter', () => {
+  expect(nextRapidRateLimitCount(1, { rateLimited: true, durationMs: RAPID_RATE_LIMIT_WINDOW_MS })).toBe(1);
+});
+
+test('any non-rate-limited outcome resets the counter to 0', () => {
+  expect(nextRapidRateLimitCount(2, { rateLimited: false, durationMs: 999_999 })).toBe(0);
+});
+
+test('driving the counter to the documented threshold engages the hard-pause condition', () => {
+  let count = 0;
+  for (let i = 0; i < CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD; i += 1) {
+    count = nextRapidRateLimitCount(count, { rateLimited: true, durationMs: 3_000 });
+  }
+  expect(count).toBe(CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD);
+  expect(count >= CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD).toBe(true);
+});
+
+test('reaching the threshold forces the pause through even against a STALE observation still inside the cooldown window', () => {
+  // This is the scenario the hard cap exists for: freshness alone is not
+  // enough when the computed resumeAt is itself stale/wrong and the resume
+  // timer keeps re-clearing the pause, so a LATER dispatch's observation can
+  // legitimately look "stale" relative to the most recent clear. The
+  // rapid-repeat counter is an independent, unconditional circuit breaker.
+  let count = 0;
+  for (let i = 0; i < CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD; i += 1) {
+    count = nextRapidRateLimitCount(count, { rateLimited: true, durationMs: 3_000 });
+  }
+  const force = count >= CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD;
+  const staleObservedAt = clearedAt - 999_999;
+  const suppressed = isCooldownSuppressed({ pauseClearedManuallyAt: clearedAt, now: clearedAt + 1_000, observedAt: staleObservedAt, force });
+  expect(suppressed).toBe(false);
+});
+
+test('one non-rate-limited run in between resets the streak so the hard pause never engages', () => {
+  let count = 0;
+  count = nextRapidRateLimitCount(count, { rateLimited: true, durationMs: 3_000 });
+  count = nextRapidRateLimitCount(count, { rateLimited: true, durationMs: 3_000 });
+  count = nextRapidRateLimitCount(count, { rateLimited: false, durationMs: 60_000 }); // job actually ran fine
+  count = nextRapidRateLimitCount(count, { rateLimited: true, durationMs: 3_000 });
+  expect(count).toBeLessThan(CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD);
+});

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

@@ -0,0 +1,158 @@
+/**
+ * scheduler-rate-limit-spin-guard.test.cjs — PRD 1119 end-to-end repro of the
+ * 2026-09-05 incident: a human pressed Resume/Run now on job 204, and for the
+ * next hour the scheduler dispatched it, watched it 429 in seconds, reset it
+ * to pending (halt-reset), and dispatched it again — 291 times, one every
+ * ~12s — because setPaused()'s manual-override cooldown suppressed WRITING
+ * the rate_limit pause for the whole 5-minute window, even though every one
+ * of those 429s was a brand-new observation from a run that started AFTER
+ * the human's clear.
+ *
+ * This drives the REAL dispatch path (spawnJob, via a stub `claude` binary
+ * that always 429s in well under a second) repeatedly, immediately after a
+ * simulated manual Resume, and asserts the scheduler engages a genuine pause
+ * almost immediately — never anywhere near the 291-dispatch runaway, and
+ * never past the documented CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD hard cap
+ * even in the worst case. Compressed in wall-clock time (a stub exits in
+ * milliseconds, not the ~12s a real `claude -p` round trip took) — the
+ * assertion is on DISPATCH COUNT, which is what the fix actually bounds,
+ * not on wall-clock duration.
+ *
+ * Run: timeout 60 npx vitest run src/main/__tests__/scheduler-rate-limit-spin-guard.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-rate-limit-spin-guard-'));
+  process.env.HOME = tmpHome;
+  // Worktree isolation is irrelevant to this repro (it's about pause
+  // suppression, not tree isolation) and each real `git worktree add` adds
+  // real wall-clock overhead this test does not need to pay 40 times over.
+  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 });
+});
+
+afterEach(() => {
+  delete process.env.SM_CLAUDE_BIN;
+});
+
+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, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, 'spin-guard-project-slug');
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+  queueStore.bustCwdCache();
+}
+
+function writeProjectQueue(cwd, jobs) {
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const queuePath = path.join(stateDir, 'queue.json');
+  fs.writeFileSync(queuePath, JSON.stringify({ jobs }, null, 2));
+  return queuePath;
+}
+
+// Stub `claude` binary: always dies as a rate limit, in well under 30s (same
+// technique as scheduler-prd-persona-spawn.test.cjs's argv-marker stub) —
+// emits the canonical 429 signal detectRateLimitInLog looks for, then exits
+// non-zero almost instantly, and bumps a counter file each invocation so the
+// test can assert exactly how many times it was actually spawned.
+function writeAlways429ClaudeStub(counterPath) {
+  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-429-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    fs.appendFileSync(${JSON.stringify(counterPath)}, 'x');
+    process.stdout.write(JSON.stringify({ type: 'result', subtype: 'error', is_error: true, api_error_status: 429 }) + '\\n');
+    process.exit(1);
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+test('a manual Resume immediately followed by a permanently-429ing job never produces a runaway dispatch loop', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(tmpHome, 'spin-guard-project-'));
+  initRepo(projectCwd);
+  registerActiveProject(projectCwd);
+  const slug = `1119-spin-guard-${process.pid}`;
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'Do the thing.', 'utf8');
+
+  const counterPath = path.join(tmpHome, 'dispatch-count.txt');
+  fs.writeFileSync(counterPath, '');
+  process.env.SM_CLAUDE_BIN = writeAlways429ClaudeStub(counterPath);
+
+  writeProjectQueue(projectCwd, [
+    { slug, status: 'pending', cwd: projectCwd },
+  ]);
+
+  // The human just pressed Resume/Run now — this is the exact call clearPause
+  // makes from the IPC handlers, and it starts the 5-minute cooldown window.
+  await scheduler.clearPause('manual');
+
+  const job = { slug, cwd: projectCwd };
+
+  // Simulate the tick loop's dispatch decision being driven repeatedly "over
+  // ten minutes" — compressed here to however many cycles a permanently-429
+  // job can actually complete, since each cycle is a real (fast) subprocess
+  // spawn rather than a real 12s `claude -p` round trip. tickQueue()'s own
+  // paused early-return (unchanged by this PRD) is exactly what this loop
+  // reproduces by hand: stop dispatching the moment the queue is paused.
+  const MAX_TICKS = 40;
+  for (let i = 0; i < MAX_TICKS; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    const state = await queueStore.readMerged();
+    if (state.paused) break;
+    const row = state.jobs.find((j) => j.slug === slug);
+    if (!row || row.status !== 'pending') break;
+    const runId = `run-${i}`;
+    const runDir = path.join(scheduler.RUNS_DIR, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    // eslint-disable-next-line no-await-in-loop
+    await scheduler.spawnJob(job, runId, runDir, projectCwd);
+  }
+
+  const dispatchCount = fs.readFileSync(counterPath, 'utf8').length;
+  expect(dispatchCount).toBeLessThanOrEqual(scheduler.CONSECUTIVE_RAPID_RATE_LIMIT_THRESHOLD);
+  expect(dispatchCount).toBeGreaterThan(0);
+  expect(dispatchCount).toBeLessThan(10); // nowhere near the 291-dispatch incident
+
+  const finalState = await queueStore.readMerged();
+  expect(finalState.paused).toBeTruthy();
+  expect(finalState.paused.reason).toBe('rate_limit');
+  expect(finalState.jobs.find((j) => j.slug === slug).status).toBe('pending');
+});

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

@@ -271,6 +271,36 @@ test('reapDeadRunningJobs: a failed reap with a persisted guardBaseline names th
   assert.match(lastTransition.reason, /left 1 files uncommitted/);
 });
 
+test('reapDeadRunningJobs: a rate-limited death (api_error_status:429) is reset to pending, not stamped failed, and the reason names the rate limit (PRD 1117)', async () => {
+  const projectCwd = path.join(tmpHome, 'h-project');
+  fs.mkdirSync(projectCwd, { recursive: true });
+  registerActiveProject(projectCwd);
+
+  const runId = 'run-rate-limited';
+  const queuePath = writeProjectQueue(projectCwd, [
+    {
+      slug: 'rate-limited-job',
+      status: 'running',
+      cwd: projectCwd,
+      runId,
+      runtime: { pid: 999999 }, // guaranteed-dead pid — the reaper won the race
+    },
+  ]);
+  // Real-shape tail: a 429 result event, the exact signal the reaper
+  // previously had no branch for and stamped terminal 'failed'.
+  writeRunLog(runId, 'rate-limited-job', [
+    '{"type":"result","subtype":"success","is_error":true,"api_error_status":429,"rateLimitType":"seven_day","result":"You\'ve reached your Fable limit.","uuid":"x"}',
+  ]);
+
+  await reapDeadRunningJobs();
+
+  const jobs = JSON.parse(fs.readFileSync(queuePath, 'utf8')).jobs;
+  const row = jobs.find((j) => j.slug === 'rate-limited-job');
+  assert.equal(row.status, 'pending', 'a rate-limited reap must be retryable, never terminal failed');
+  assert.match(row.error, /rate limit/i, 'the reset reason must name the rate limit, not read as a generic reap failure');
+  assert.equal(row.runtime, undefined);
+});
+
 test('reapDeadRunningJobs skips in-place salvage (no whole-tree dump) when the row has no persisted guardBaseline', async () => {
   const projectCwd = path.join(tmpHome, 'f-project');
   initRepo(projectCwd);

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

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