claude-code-session-manager 0.77.0 → 0.79.0

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/index.cjs

@@ -37,7 +37,7 @@ const epicWorktreeMint = require('./lib/epicWorktreeMint.cjs');
 const epicWorktreeMerge = require('./lib/epicWorktreeMerge.cjs');
 const epicWorktreeProjectConfig = require('./lib/epicWorktreeProjectConfig.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
-const { checkDelegationReadiness, installPrdWriteGuard } = require('./lib/delegationReadiness.cjs');
+const { checkDelegationReadiness, installPrdWriteGuard, installDestructiveGitGuard } = require('./lib/delegationReadiness.cjs');
 const { MCP_TOOL_CATALOG, MCP_RECIPES } = require('./lib/mcpToolCatalog.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
@@ -513,12 +513,17 @@ ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadiness
   checkDelegationReadiness(payload)
 ));
 
-// The one readiness check with a sanctioned one-press install. Session Manager
+// The two readiness checks with a sanctioned one-press install. Session Manager
 // standardizes on the REFERENCE approach (absolute path to this repo's guard
-// script, never a vendored copy) — see installPrdWriteGuard's header.
+// script, never a vendored copy) — see installPrdWriteGuard's header. They stay
+// two handlers (and two PreToolUse entries) because the hooks have different
+// matchers: Write|Edit|NotebookEdit vs Bash — installDestructiveGitGuard's header.
 ipcMain.handle('app:install-prd-write-guard', validated(schemas.delegationReadinessCwd, (payload) =>
   installPrdWriteGuard(payload)
 ));
+ipcMain.handle('app:install-destructive-git-guard', validated(schemas.delegationReadinessCwd, (payload) =>
+  installDestructiveGitGuard(payload)
+));
 
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 

package/src/main/ipcSchemas.cjs

@@ -596,6 +596,8 @@ const projectBriefCwd = z.object({
 }).strict();
 
 // ──────────────────────────────────────────── Delegation readiness
+// Shared by app:delegation-readiness, app:install-prd-write-guard and
+// app:install-destructive-git-guard — all three take exactly { cwd }.
 const delegationReadinessCwd = z.object({
   cwd: z.string().min(1).max(4096),
 }).strict();

package/src/main/lib/__tests__/delegationReadiness.test.cjs

@@ -468,6 +468,51 @@ test('installDestructiveGitGuard: writes the canonical ABSOLUTE-path entry and t
   expect(result.checks.find((c) => c.id === 'prd-write-guard').ok).toBe(true);
 }, 15_000);
 
+// The scenario app:install-destructive-git-guard (index.cjs) serves: a project
+// that got the first guard via the New Session "Fix it" button and never the
+// second (the starry-night-ships reproduction). The handler is a pass-through
+// to this function under the shared { cwd } schema, so this is its contract.
+test('installDestructiveGitGuard: flips destructive-git-guard FAIL -> PASS on a cwd seeded with only the prd-write-guard hook, by reference, idempotently', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  await writeJson(settingsPath, {
+    hooks: {
+      PreToolUse: [
+        { matcher: 'Write|Edit|NotebookEdit', hooks: [{ type: 'command', command: `node ${PRD_WRITE_GUARD_SCRIPT}` }] },
+      ],
+    },
+  });
+
+  const before = await checkDelegationReadiness({ cwd, homeDir });
+  expect(before.checks.find((c) => c.id === 'destructive-git-guard')).toMatchObject({
+    ok: false,
+    fixAction: 'install-destructive-git-guard',
+    detail: `no guard-destructive-git PreToolUse hook in ${cwd}/.claude/settings.json`,
+  });
+
+  const first = await installDestructiveGitGuard({ cwd });
+  expect(first).toMatchObject({ ok: true, action: 'installed', settingsPath });
+
+  const written = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const bash = written.hooks.PreToolUse.filter((m) => m.matcher === 'Bash');
+  expect(bash).toHaveLength(1);
+  // By reference to THIS repo's absolute script — never a copy inside the target cwd.
+  expect(bash[0].hooks).toEqual([{ type: 'command', command: `node ${DESTRUCTIVE_GIT_GUARD_SCRIPT}` }]);
+  expect(path.isAbsolute(DESTRUCTIVE_GIT_GUARD_SCRIPT)).toBe(true);
+  expect(DESTRUCTIVE_GIT_GUARD_SCRIPT.startsWith(cwd + path.sep)).toBe(false);
+  expect(fs.existsSync(path.join(cwd, 'scripts'))).toBe(false);
+
+  const after = await checkDelegationReadiness({ cwd, homeDir });
+  expect(after.checks.find((c) => c.id === 'destructive-git-guard').ok).toBe(true);
+  expect(after.checks.find((c) => c.id === 'prd-write-guard').ok).toBe(true);
+
+  // Second press: no-op, byte-identical file.
+  const snapshot = fs.readFileSync(settingsPath, 'utf8');
+  const second = await installDestructiveGitGuard({ cwd });
+  expect(second).toMatchObject({ ok: true, action: 'already-installed', settingsPath });
+  expect(fs.readFileSync(settingsPath, 'utf8')).toBe(snapshot);
+}, 15_000);
+
 test('installDestructiveGitGuard: is idempotent — a healthy guard is a no-op', async () => {
   const { cwd } = await makeGreenFixtures();
   const before = fs.readFileSync(path.join(cwd, '.claude', 'settings.json'), 'utf8');

package/src/main/lib/__tests__/reaperHelpers.test.cjs

@@ -16,7 +16,11 @@
 // vitest, NOT node:test — this repo's suite is vitest-only (CLAUDE.md).
 import { test } from 'vitest';
 const assert = require('node:assert/strict');
-const { selectReapableJobs, mapOutcomeToGateOutcome } = require('../reaperHelpers.cjs');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { selectReapableJobs, mapOutcomeToGateOutcome, classifyRunOutcome } = require('../reaperHelpers.cjs');
+const { detectRateLimitInLog } = require('../rateLimitDetect.cjs');
 
 const NOW = Date.parse('2026-09-01T12:00:00.000Z');
 const agoMin = (m) => new Date(NOW - m * 60_000).toISOString();
@@ -131,3 +135,88 @@ test('mapOutcomeToGateOutcome: no_result -> never_ran', () => {
 test('mapOutcomeToGateOutcome: unknown -> unknown', () => {
   assert.strictEqual(mapOutcomeToGateOutcome('unknown'), 'unknown');
 });
+
+// detectRateLimitInLog / classifyRunOutcome — PRD 1117: the reaper's
+// rate-limit detection must be the SAME single source of truth spawnJob
+// uses (detectRateLimitInLog, shared via lib/rateLimitDetect.cjs), and a
+// rate-limited death must classify as a NEW, distinct 'rate_limited'
+// outcome — never collapsed into 'failed', and never re-labelling
+// 'success'/'failed'/'no_result' (which keep their prior meanings, per the
+// mapOutcomeToGateOutcome tests above, unmodified).
+
+function writeTmpLog(contents) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reaper-rate-limit-test-'));
+  const p = path.join(dir, 'run.log');
+  fs.writeFileSync(p, contents);
+  return p;
+}
+
+test('detectRateLimitInLog: rateLimitType":"five_hour" variant', () => {
+  const p = writeTmpLog('{"type":"result","rate_limit_info":{"rateLimitType":"five_hour"}}\n');
+  assert.strictEqual(detectRateLimitInLog(p), true);
+});
+
+test('detectRateLimitInLog: rateLimitType":"seven_day" variant (missed pre-PRD-1117)', () => {
+  const p = writeTmpLog('{"type":"rate_limit_event","rate_limit_info":{"rateLimitType":"seven_day","unifiedWindows":{"five_hour":{"utilization":0}}}}\n');
+  assert.strictEqual(detectRateLimitInLog(p), true);
+});
+
+test('detectRateLimitInLog: api_error_status":429 variant', () => {
+  const p = writeTmpLog('{"type":"result","is_error":true,"api_error_status":429,"result":"nope"}\n');
+  assert.strictEqual(detectRateLimitInLog(p), true);
+});
+
+test('detectRateLimitInLog: "You\'ve reached your <model> limit" variant (missed pre-PRD-1117)', () => {
+  const p = writeTmpLog('{"type":"result","result":"You\'ve reached your Fable limit. Switch to another model."}\n');
+  assert.strictEqual(detectRateLimitInLog(p), true);
+});
+
+test('detectRateLimitInLog: real evidence log (2026-09-05 204-mercury-steam-horse 429)', () => {
+  const evidencePath = '/home/bilko/.claude/session-manager/scheduled-plans/runs/2026-09-05T16-32-18-381Z/204-mercury-steam-horse.log';
+  if (!fs.existsSync(evidencePath)) return; // machine-local fixture; skip elsewhere
+  assert.strictEqual(detectRateLimitInLog(evidencePath), true);
+});
+
+test('classifyRunOutcome: a 429 log tail classifies as the new distinct rate_limited outcome, not failed', () => {
+  const p = writeTmpLog('{"type":"result","subtype":"success","is_error":true,"api_error_status":429,"rateLimitType":"seven_day","result":"You\'ve reached your Fable limit."}\n');
+  assert.strictEqual(classifyRunOutcome(p), 'rate_limited');
+});
+
+test('classifyRunOutcome: a genuine error with no rate-limit signal still classifies as failed', () => {
+  const p = writeTmpLog('{"type":"result","subtype":"error","is_error":true,"result":"Error: expected 2 but got 3"}\n');
+  assert.strictEqual(classifyRunOutcome(p), 'failed');
+});
+
+// REGRESSION GUARD (2026-09-05). The rate-limit check originally ran as the
+// FIRST statement of classifyRunOutcome, before the result event was parsed.
+// Because the CLI emits an informational rate_limit_event with
+// status:"allowed_warning" on nearly every run once utilization is non-zero,
+// that misclassified genuinely successful runs as 'rate_limited' — which in
+// reapDeadRunningJobs re-queues finished work and spuriously pauses the whole
+// machine. The fixture below is the shape of a REAL successful run log, not a
+// synthetic one-liner: the allowed_warning event that every run carries, then
+// a clean result. If someone moves the check back to the top, this goes red.
+test('classifyRunOutcome: a SUCCESSFUL run whose tail carries an allowed_warning rate_limit_event is still success', () => {
+  const p = writeTmpLog([
+    '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":1788643800,"rateLimitType":"five_hour","utilization":0.42,"isUsingOverage":false}}',
+    '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":1789059600,"rateLimitType":"seven_day","utilization":0.59,"isUsingOverage":false}}',
+    '{"type":"result","subtype":"success","is_error":false,"num_turns":55,"result":"SCHEDULER_VERDICT: PASS"}',
+  ].join('\n') + '\n');
+  assert.strictEqual(classifyRunOutcome(p), 'success');
+  assert.strictEqual(mapOutcomeToGateOutcome(classifyRunOutcome(p)), 'passed');
+});
+
+// The same tail, but the run actually errored: NOW the rate-limit signal is
+// what it claims to be, and the outcome must be the retryable one.
+test('classifyRunOutcome: the same allowed_warning tail on an ERRORED run classifies as rate_limited', () => {
+  const p = writeTmpLog([
+    '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","rateLimitType":"seven_day","utilization":0.59}}',
+    '{"type":"result","subtype":"success","is_error":true,"api_error_status":429,"result":"You\'ve reached your Fable limit."}',
+  ].join('\n') + '\n');
+  assert.strictEqual(classifyRunOutcome(p), 'rate_limited');
+});
+
+test('classifyRunOutcome: a clean success log still classifies as success', () => {
+  const p = writeTmpLog('{"type":"result","subtype":"success","is_error":false,"result":"done"}\n');
+  assert.strictEqual(classifyRunOutcome(p), 'success');
+});

package/src/main/lib/jobDirtFilter.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * jobDirtFilter.cjs — strip paths a scheduled job can NEVER be responsible
+ * for out of its post-run dirty delta.
+ *
+ * The commit guard parks a job on `needs_review` ("finish protocol
+ * incomplete: N uncommitted file(s)") whenever its run leaves tracked files
+ * dirty. That is the right rule for source files. It is wrong for
+ * `session-manager-operations/`: the SINGLE-WRITER LAW (lib/opsOwnership.cjs)
+ * says the app itself owns every namespace under that root — `scheduler`
+ * writes queue.json/history.jsonl on every dispatch and every finalize,
+ * `prompt-sessions` writes active-index.json and transcripts continuously.
+ * Those writes land DURING the job's own run, inside its own guard window,
+ * and get attributed to the job.
+ *
+ * Result before this filter: a job that did everything right and committed
+ * cleanly still parked, because the scheduler's own bookkeeping was dirty
+ * underneath it. Observed 2026-09-05 on social-signals-trader PRDs 4055 and
+ * 4056 (leftover lists led with active-index.json / queue.json /
+ * history.jsonl / .max-allocated-group) and on starry-night-ships PRD 206.
+ * Each parked row then blocked every job that dependsOn it, which is how a
+ * queue with 40 ready PRDs stops dead.
+ *
+ * Deliberately narrow: ONLY the app-owned operations root. A job that dirties
+ * real source and walks away is still a genuine finish-protocol violation and
+ * must still park.
+ */
+
+/** The one app-owned root. Matches at any depth, and only as a path segment. */
+const OPS_ROOT_SEGMENT = 'session-manager-operations';
+
+/** True when `p` lives under an app-owned operations root. Pure. */
+function isAppOwnedChurn(p) {
+  if (typeof p !== 'string' || p === '') return false;
+  // Normalise Windows-style separators defensively; git porcelain emits '/'.
+  const parts = p.replace(/\\/g, '/').split('/');
+  return parts.includes(OPS_ROOT_SEGMENT);
+}
+
+/**
+ * Remove app-owned churn from a dirty-path list.
+ *
+ * Preserves the caller's null contract: `null` means "git status itself was
+ * unavailable", which is NOT the same fact as "the job left nothing", and
+ * every caller already branches on it.
+ */
+function stripAppOwnedChurn(paths) {
+  if (paths === null || paths === undefined) return paths;
+  if (!Array.isArray(paths)) return paths;
+  return paths.filter((p) => !isAppOwnedChurn(p));
+}
+
+module.exports = { stripAppOwnedChurn, isAppOwnedChurn, OPS_ROOT_SEGMENT };

package/src/main/lib/rateLimitDetect.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * rateLimitDetect.cjs — the single source of truth for "did this claude -p
+ * log tail show a rate-limit death". Shared by spawnJob() (a still-running
+ * process that just exited) and reapDeadRunningJobs()/classifyRunOutcome()
+ * (a process the reaper found already dead) — see PRD 1117. Before this,
+ * only spawnJob checked this; the reaper had no rate-limit branch at all,
+ * so a rate-limited exit that the reaper won the race to finalize got
+ * stamped terminal 'failed' instead of retryable 'pending'. There must
+ * never be a second, independently-drifting regex set at either call site.
+ */
+
+const { readTail } = require('./fileTail.cjs');
+
+/** Scan the tail of a job's log for the canonical rate-limit signal. We look
+ *  at the last 16 KB — final result event always lands at the end. Covers
+ *  both unified-window rate-limit types (five_hour, seven_day), the raw
+ *  429 status, and the two human-readable limit-message phrasings the CLI
+ *  emits ("You've hit your limit" / "You've reached your <model> limit"). */
+function detectRateLimitInLog(logPath) {
+  try {
+    const text = readTail(logPath, 16384);
+    if (!text) return false;
+    return /"rateLimitType":"five_hour"/.test(text)
+      || /"rateLimitType":"seven_day"/.test(text)
+      || /"api_error_status":429/.test(text)
+      || /You'?ve hit your limit/.test(text)
+      || /You'?ve reached your .* limit/.test(text);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { detectRateLimitInLog };