claude-code-session-manager 0.78.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/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 };

package/src/main/lib/reaperHelpers.cjs

@@ -9,6 +9,7 @@
 
 const fs = require('node:fs');
 const { readTail } = require('./fileTail.cjs');
+const { detectRateLimitInLog } = require('./rateLimitDetect.cjs');
 
 /**
  * Return true if pid is alive AND its cmdline looks like a claude process.
@@ -38,11 +39,16 @@ function claudePidAlive(pid) {
  * of its log file and scanning for the LAST `{"type":"result"}` JSONL event.
  *
  * Returns:
- *   'success'   — last result event has subtype=success and is_error !== true
- *   'failed'    — last result event exists but indicates an error
- *   'no_result' — no result event found in the tail (process may have been killed
- *                 before emitting one, or the log is absent/empty)
- *   'unknown'   — unexpected error reading/parsing (outer catch)
+ *   'success'      — last result event has subtype=success and is_error !== true
+ *   'rate_limited' — the log tail shows the same rate-limit signal spawnJob's own
+ *                    live-process check uses (detectRateLimitInLog, the shared
+ *                    single source of truth) — a NEW, distinct outcome from
+ *                    'failed' (PRD 1117): a rate-limited death is retryable, not
+ *                    a genuine gate failure, and must never collapse into 'failed'
+ *   'failed'       — last result event exists but indicates a genuine error
+ *   'no_result'    — no result event found in the tail (process may have been killed
+ *                    before emitting one, or the log is absent/empty)
+ *   'unknown'      — unexpected error reading/parsing (outer catch)
  */
 function classifyRunOutcome(logPath) {
   try {
@@ -56,8 +62,27 @@ function classifyRunOutcome(logPath) {
         if (obj && obj.type === 'result') lastResult = obj;
       } catch { /* partial line at tail boundary or non-JSON scheduler log line */ }
     }
+    // ORDER IS LOAD-BEARING. The rate-limit check must come AFTER the success
+    // determination, never before it. The CLI emits an informational
+    // `rate_limit_event` with status:"allowed_warning" on essentially every
+    // run once utilization is non-zero, and detectRateLimitInLog matches its
+    // "rateLimitType" field — so checking first classified genuinely
+    // SUCCESSFUL runs as rate_limited. Measured on 2026-09-05 against the
+    // eight most recent runs whose own meta.json recorded exitCode:0 and
+    // rateLimited:false, four came back 'rate_limited' (e.g.
+    // 200-campaign-toolkit-weak-points-and-stuns: 55 turns, is_error:false,
+    // terminalReasonFromHarness:'completed', landed commit 7fd05f7 — matched
+    // purely on an allowed_warning five_hour event). In reapDeadRunningJobs
+    // that resets a finished job to 'pending' to re-run shipped work AND
+    // engages setPaused('rate_limit') with no rate limit in effect — strictly
+    // worse than the terminal-'failed' bug the rate_limit branch was added to
+    // fix. See the guard test in this file's __tests__ sibling.
+    if (lastResult && lastResult.subtype === 'success' && lastResult.is_error !== true) return 'success';
+    // Still checked ahead of 'no_result': a run killed mid-flight by a rate
+    // limit may never emit a result event at all, and that is a rate-limited
+    // death, not silence.
+    if (detectRateLimitInLog(logPath)) return 'rate_limited';
     if (!lastResult) return 'no_result';
-    if (lastResult.subtype === 'success' && lastResult.is_error !== true) return 'success';
     return 'failed';
   } catch {
     return 'unknown';