claude-code-session-manager 0.75.0 → 0.75.2

package/src/main/__tests__/scheduler-autofix-select.test.cjs

@@ -11,7 +11,7 @@ const assert = require('node:assert/strict');
 const {
   selectAutoFixTargets, isUnresolvableNeedsReview, isRescanCandidate,
   healTargetForFix, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH,
-  isEligibleForImmediateAutoFix,
+  isEligibleForImmediateAutoFix, isExhaustedAutoFix, isPlanUnqueued, fixSlugFor,
 } = require('../scheduler.cjs');
 
 const noSiblingOnDisk = () => false;
@@ -34,8 +34,8 @@ test('selects a fresh needs_review job', () => {
   assert.strictEqual(result[0].slug, '05-my-feature');
 });
 
-test('excludes job with autoFixAttempted: true', () => {
-  const jobs = [makeJob({ autoFixAttempted: true })];
+test('excludes job with autoFixAttempted: true whose retry is already spent', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixRetries: 1 })];
   const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
   assert.strictEqual(result.length, 0);
 });
@@ -105,12 +105,112 @@ test('autoFixOutcome no-plan with retries=1 is exhausted (not selected)', () =>
   assert.strictEqual(result.length, 0);
 });
 
-test('autoFixAttempted true with no outcome recorded stays excluded (existing 1-attempt cap)', () => {
-  const jobs = [makeJob({ autoFixAttempted: true })];
+// ---- PRD: unstamped/error outcomes must retry once, not dead-end forever ----
+
+test('autoFixAttempted true with NO outcome recorded (unstamped — spawn threw before onExit wired) is retry-eligible once', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixRetries: 0 })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 1);
+});
+
+test('autoFixAttempted true with no outcome AND retries=1 is exhausted (not selected)', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixRetries: 1 })];
   const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
   assert.strictEqual(result.length, 0);
 });
 
+test('autoFixOutcome error with retries=0 is retry-eligible', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixOutcome: 'error', autoFixRetries: 0 })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 1);
+});
+
+test('autoFixOutcome error with retries=1 is exhausted (not selected)', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixOutcome: 'error', autoFixRetries: 1 })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+test('autoFixOutcome plan is NEVER retried, regardless of autoFixRetries', () => {
+  const jobs = [makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 0 })];
+  const result = selectAutoFixTargets(jobs, { fixSlugExists: noSiblingOnDisk });
+  assert.strictEqual(result.length, 0);
+});
+
+// ---- isExhaustedAutoFix / isPlanUnqueued (reverifyNeedsReview annotation) ----
+
+test('isExhaustedAutoFix: no-plan outcome with retries spent → true', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'no-plan', autoFixRetries: 1 });
+  assert.strictEqual(isExhaustedAutoFix(job), true);
+});
+
+test('isExhaustedAutoFix: error outcome with retries spent → true', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'error', autoFixRetries: 1 });
+  assert.strictEqual(isExhaustedAutoFix(job), true);
+});
+
+test('isExhaustedAutoFix: unstamped outcome with retries spent → true', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixRetries: 1 });
+  assert.strictEqual(isExhaustedAutoFix(job), true);
+});
+
+test('isExhaustedAutoFix: retries not yet spent → false (still eligible for its one retry)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'no-plan', autoFixRetries: 0 });
+  assert.strictEqual(isExhaustedAutoFix(job), false);
+});
+
+test('isExhaustedAutoFix: plan outcome is never "exhausted" here — isPlanUnqueued\'s job instead', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan', autoFixRetries: 1 });
+  assert.strictEqual(isExhaustedAutoFix(job), false);
+});
+
+test('isPlanUnqueued: plan outcome, fix slug absent from queue → true', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan' });
+  assert.strictEqual(isPlanUnqueued(job, new Set()), true);
+});
+
+test('isPlanUnqueued: plan outcome, fix slug present in queue → false', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan' });
+  assert.strictEqual(isPlanUnqueued(job, new Set([fixSlugFor(job)])), false);
+});
+
+test('isPlanUnqueued: no-plan outcome is never "plan unqueued"', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'no-plan' });
+  assert.strictEqual(isPlanUnqueued(job, new Set()), false);
+});
+
+// ---- invariant: every needs_review job is either an auto-fix target, or
+// classified by one of the annotation predicates (i.e. would receive a
+// non-null verifierVerdict) — no job may fall through both. ----
+
+test('invariant: attempted+no-outcome, retries spent → not a target, but IS annotatable', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixRetries: 1 });
+  const isTarget = selectAutoFixTargets([job], { fixSlugExists: noSiblingOnDisk }).length === 1;
+  const isAnnotatable = isExhaustedAutoFix(job) || isPlanUnqueued(job, new Set())
+    || isUnresolvableNeedsReview(job, { hasRunDir: true });
+  assert.strictEqual(isTarget, false);
+  assert.strictEqual(isAnnotatable, true);
+});
+
+test('invariant: plan outcome, no queue row → not a target, but IS annotatable (autofix_plan_unqueued)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan' });
+  const isTarget = selectAutoFixTargets([job], { fixSlugExists: noSiblingOnDisk }).length === 1;
+  const isAnnotatable = isExhaustedAutoFix(job) || isPlanUnqueued(job, new Set())
+    || isUnresolvableNeedsReview(job, { hasRunDir: true });
+  assert.strictEqual(isTarget, false);
+  assert.strictEqual(isAnnotatable, true);
+});
+
+test('invariant: plan outcome WITH a queue row → not a target and NOT annotated (waiting on the fix-plan job itself)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixOutcome: 'plan' });
+  const queuedSlugs = new Set([fixSlugFor(job)]);
+  const isTarget = selectAutoFixTargets([job], { fixSlugExists: noSiblingOnDisk }).length === 1;
+  const isAnnotatable = isExhaustedAutoFix(job) || isPlanUnqueued(job, queuedSlugs)
+    || isUnresolvableNeedsReview(job, { hasRunDir: true });
+  assert.strictEqual(isTarget, false);
+  assert.strictEqual(isAnnotatable, false);
+});
+
 test('excludes when fix sibling exists on disk', () => {
   const jobs = [makeJob()];
   // fixSlug = '05-fix-my-feature'
@@ -224,12 +324,18 @@ test('isEligibleForImmediateAutoFix: fresh needs_review job (fresh from spawnJob
   assert.strictEqual(result, true);
 });
 
-test('isEligibleForImmediateAutoFix: job already autoFixAttempted is excluded (prevents double-spawn with the periodic pass)', () => {
-  const job = makeJob({ autoFixAttempted: true });
+test('isEligibleForImmediateAutoFix: attempted job with retry already spent is excluded (prevents double-spawn with the periodic pass)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixRetries: 1 });
   const result = isEligibleForImmediateAutoFix(job, [job], noSiblingOnDisk);
   assert.strictEqual(result, false);
 });
 
+test('isEligibleForImmediateAutoFix: attempted job with an unstamped outcome and its retry still unspent IS eligible (bounded once)', () => {
+  const job = makeJob({ autoFixAttempted: true, autoFixRetries: 0 });
+  const result = isEligibleForImmediateAutoFix(job, [job], noSiblingOnDisk);
+  assert.strictEqual(result, true);
+});
+
 test('isEligibleForImmediateAutoFix: fix sibling already on disk excludes the job', () => {
   const job = makeJob();
   // fixSlug = '05-fix-my-feature'

package/src/main/__tests__/scheduler-clear-queue-history.test.cjs

@@ -0,0 +1,134 @@
+/**
+ * scheduler-clear-queue-history.test.cjs — schedule:clear-queue must never
+ * drop a job row with zero audit trail. Before this PRD, the handler did
+ * `s.jobs = s.jobs.filter(...)` straight over every non-running victim with
+ * no history.jsonl write at all — a queue row (e.g. the 2026-08-30 sigma
+ * `788-pr-sweep-final-gate` incident) could vanish leaving no trace anywhere.
+ *
+ * Exercises `applyClearQueueVictims` (the core mutation extracted from the
+ * `schedule:clear-queue` IPC handler so it's testable without ipcMain/
+ * electron) directly against a synthetic state, then feeds its output
+ * through the REAL `queueHistory.appendHistory`. Job fixtures carry a real
+ * absolute `cwd` under a per-test mkdtemp dir (never the live operations
+ * root) because appendHistory routes each entry to its OWN project's
+ * `<cwd>/session-manager-operations/scheduler/state/history.jsonl` shard
+ * whenever the entry has a `cwd` — SM_HISTORY_PATH_OVERRIDE only affects
+ * cwd-less entries, and the AC here requires every entry to carry a cwd.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-clear-queue-history.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const queueHistory = require('../lib/queueHistory.cjs');
+const { projectHistoryPath } = require('../lib/queueStore.cjs');
+const scheduler = require('../scheduler.cjs');
+
+let tmpCwd;
+
+beforeEach(() => {
+  tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-clear-queue-history-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpCwd, { recursive: true, force: true });
+});
+
+function pendingJob(slug, overrides = {}) {
+  return { slug, cwd: tmpCwd, status: 'pending', runId: null, finishedAt: null, ...overrides };
+}
+
+function historyPath() {
+  return projectHistoryPath(tmpCwd);
+}
+
+function readHistoryRows() {
+  const text = fs.readFileSync(historyPath(), 'utf8').trim();
+  return text ? text.split('\n').map((l) => JSON.parse(l)) : [];
+}
+
+test('applyClearQueueVictims transitions N pending jobs to skipped, drops them from state.jobs, and appendHistory writes N rows with source clear-queue', async () => {
+  const jobs = [pendingJob('101-a'), pendingJob('102-b'), pendingJob('103-c')];
+  const running = { slug: '104-running', cwd: tmpCwd, status: 'running', runId: 'run-104', finishedAt: null };
+  const state = { jobs: [...jobs, running] };
+  const victimSlugs = new Set(jobs.map((j) => j.slug));
+  const archiveNoteBySlug = new Map(jobs.map((j) => [j.slug, 'PRD file archived to /fake/archive/dir']));
+
+  const historyEntries = scheduler.applyClearQueueVictims(state, victimSlugs, archiveNoteBySlug, '/fake/archive/dir');
+
+  // Running job is untouched, exempt from clear-queue, and got no history row.
+  expect(state.jobs.map((j) => j.slug)).toEqual(['104-running']);
+  expect(historyEntries.map((e) => e.slug).sort()).toEqual(['101-a', '102-b', '103-c']);
+  for (const entry of historyEntries) {
+    expect(entry.status).toBe('skipped'); // NEVER 'completed' — a manually cleared job did not ship
+    expect(entry.cwd).toBe(tmpCwd);
+    expect(entry.finishedAt).toBeTruthy();
+    const last = entry.statusHistory[entry.statusHistory.length - 1];
+    expect(last.source).toBe('clear-queue');
+    expect(last.reason).toContain('/fake/archive/dir');
+  }
+
+  const { appended } = await queueHistory.appendHistory(historyEntries);
+  expect(appended).toBe(3);
+  const onDisk = readHistoryRows();
+  expect(onDisk.length).toBe(3);
+  expect(onDisk.every((e) => e.status === 'skipped')).toBe(true);
+  expect(onDisk.every((e) => e.statusHistory.at(-1).source === 'clear-queue')).toBe(true);
+
+  // queue.json (state.jobs, what writeQueue serializes) no longer lists them.
+  expect(state.jobs.some((j) => victimSlugs.has(j.slug))).toBe(false);
+});
+
+test('running jobs are exempt from clear-queue and never appear in the returned history entries', () => {
+  const running = { slug: '201-running', cwd: tmpCwd, status: 'running', runId: 'run-201', finishedAt: null };
+  const state = { jobs: [running] };
+  const victimSlugs = new Set(); // schedule:clear-queue never includes running jobs as victims
+
+  const historyEntries = scheduler.applyClearQueueVictims(state, victimSlugs, new Map(), '/fake/archive/dir');
+
+  expect(historyEntries).toEqual([]);
+  expect(state.jobs).toEqual([running]);
+});
+
+test('a victim already terminal (completed) keeps its real status, not skipped, but still gets a clear-queue history row', () => {
+  const completed = { slug: '301-done', cwd: tmpCwd, status: 'completed', runId: 'run-301', finishedAt: '2026-08-29T00:00:00.000Z', statusHistory: [] };
+  const state = { jobs: [completed] };
+  const victimSlugs = new Set(['301-done']);
+
+  const historyEntries = scheduler.applyClearQueueVictims(state, victimSlugs, new Map(), '/fake/archive/dir');
+
+  expect(state.jobs).toEqual([]);
+  expect(historyEntries.length).toBe(1);
+  expect(historyEntries[0].status).toBe('completed'); // real outcome preserved, not overwritten to skipped
+  const last = historyEntries[0].statusHistory.at(-1);
+  expect(last.source).toBe('clear-queue');
+  expect(last.from).toBe('completed');
+  expect(last.to).toBe('completed');
+});
+
+test('appendHistory dedupe: clearing an already-cleared queue twice does not double-write rows', async () => {
+  const jobs = [pendingJob('401-x'), pendingJob('402-y')];
+  const state = { jobs: [...jobs] };
+  const victimSlugs = new Set(jobs.map((j) => j.slug));
+
+  const historyEntries = scheduler.applyClearQueueVictims(state, victimSlugs, new Map(), '/fake/archive/dir');
+  expect(state.jobs).toEqual([]);
+
+  const r1 = await queueHistory.appendHistory(historyEntries);
+  expect(r1.appended).toBe(2);
+
+  // A crash-replay of the SAME batch through appendHistory (the dedupe
+  // queueHistory itself guards against) must not double-write — this is
+  // what protects a second clear-queue pass, or a retry after a crash
+  // between the mutate() and appendHistory calls, from duplicating rows.
+  const r2 = await queueHistory.appendHistory(historyEntries);
+  expect(r2.appended).toBe(0);
+
+  const onDisk = readHistoryRows();
+  expect(onDisk.length).toBe(2);
+});

package/src/main/__tests__/scheduler-fix-plan-path.test.cjs

@@ -0,0 +1,119 @@
+/**
+ * scheduler-fix-plan-path.test.cjs — regression test for the self-heal
+ * dead-letter bug: spawnInvestigation used to write every auto-fix plan into
+ * the RETIRED flat `<cwd>/session-manager-operations/scheduler/prds/` dir
+ * (prdDirForCwd), which reconcile()'s consolidateAllFlatPrds sweeps BEFORE
+ * scanning for queue rows — so a freshly-authored fix plan (no queue row yet
+ * by definition) was archived into `prds-archived/` on the very next pass
+ * and never enqueued. Confirmed live in starry-night-ships: job
+ * 105-arena-perf-fences produced a valid fix plan that landed in
+ * prds-archived/ having never appeared in queue.json or history.jsonl.
+ *
+ * The fix: resolveFixPlanPath resolves the write dir from the ORIGINAL job's
+ * live PRD location (findPrdDir, via resolveVerifyPrdPath) — normally the
+ * originating Epic's own `epics/<epicId>/prds/`, which consolidateFlatPrds
+ * never touches — falling back to the flat dir only when the original can't
+ * be found live anywhere on disk.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-fix-plan-path.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let resolveFixPlanPath;
+let PRDS_DIR;
+let consolidateFlatPrds;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-fix-plan-path-'));
+  process.env.HOME = tmpHome;
+
+  // Load AFTER HOME is stubbed — scheduler.cjs snapshots os.homedir() into
+  // PRDS_DIR at module load, not lazily (see scheduler-find-prd-dir.test.cjs).
+  ({ resolveFixPlanPath, PRDS_DIR } = require('../scheduler.cjs'));
+  ({ consolidateFlatPrds } = require('../lib/prdMigration.cjs'));
+
+  if (!PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+
+  // allProjectCwds()/activeProjectCwds() (consumed by findPrdDir's candidate
+  // search) discover project cwds by scanning ~/.claude/projects/*/*.jsonl
+  // for a `cwd` field — fake one project transcript pointing at the real
+  // on-disk cwd used below (mirrors scheduler-verify-prd-path.test.cjs).
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const projDir = path.join(projectsDir, 'fake-fix-plan-project-slug');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projDir, 'session.jsonl'),
+    `${JSON.stringify({ cwd: projectCwd() })}\n`,
+    'utf8',
+  );
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function projectCwd() {
+  return path.join(tmpHome, 'fix-plan-project-cwd');
+}
+
+test('resolveFixPlanPath resolves the fix plan into the SAME Epic-scoped dir as the original PRD, and it survives consolidateFlatPrds', async () => {
+  const cwd = projectCwd();
+  const epicId = 'test-epic-arena-perf';
+  const slug = `105-arena-perf-fences-${process.pid}`;
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), '---\ntitle: arena perf fences\n---\n\n# Goal\n\ntest\n', 'utf8');
+
+  const failedJob = { slug, cwd, parallelGroup: 5 };
+  const resolved = await resolveFixPlanPath(failedJob);
+
+  const expectedFixSlug = '05-fix-arena-perf-fences-' + process.pid;
+  expect(resolved.fixSlug).toBe(expectedFixSlug);
+  expect(resolved.livePrdDir).toBe(prdsDir);
+  expect(resolved.fixPath).toBe(path.join(prdsDir, `${expectedFixSlug}.md`));
+
+  // A fix plan written at the resolved path must survive a consolidateFlatPrds
+  // pass over the SAME project cwd — the sweep only ever touches the flat dir.
+  fs.writeFileSync(resolved.fixPath, `---\ntitle: Fix: arena perf fences\ncwd: ${cwd}\nparallelGroup: 5\nestimateMinutes: 30\n---\n\nfix body\n`, 'utf8');
+  await consolidateFlatPrds(cwd);
+  expect(fs.existsSync(resolved.fixPath)).toBe(true);
+});
+
+test('resolveFixPlanPath falls back to the flat dir when the original PRD cannot be found live anywhere on disk', async () => {
+  const cwd = path.join(tmpHome, 'fix-plan-project-cwd-missing');
+  const slug = `999-nonexistent-${process.pid}`;
+  const failedJob = { slug, cwd, parallelGroup: 3 };
+
+  const resolved = await resolveFixPlanPath(failedJob);
+
+  expect(resolved.livePrdDir).toBe(null);
+  const flatDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'prds');
+  expect(resolved.fixPath).toBe(path.join(flatDir, `${resolved.fixSlug}.md`));
+});
+
+test('the OLD flat-dir path (regression guard) does NOT survive consolidateFlatPrds — proves the bug this fix addresses', async () => {
+  const cwd = path.join(tmpHome, 'fix-plan-project-cwd-old-behavior');
+  const flatDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(flatDir, { recursive: true });
+  const oldFixPath = path.join(flatDir, '07-fix-old-behavior.md');
+  fs.writeFileSync(oldFixPath, `---\ntitle: Fix: old behavior\ncwd: ${cwd}\nparallelGroup: 7\nestimateMinutes: 30\n---\n\nfix body\n`, 'utf8');
+
+  // No queue.json at all — the file has no live queue row, exactly the
+  // freshly-authored-fix-plan situation the bug hit.
+  await consolidateFlatPrds(cwd);
+
+  expect(fs.existsSync(oldFixPath)).toBe(false);
+  expect(fs.existsSync(path.join(cwd, 'session-manager-operations', 'scheduler', 'prds-archived', '07-fix-old-behavior.md'))).toBe(true);
+});

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

@@ -126,7 +126,11 @@ test("spawnJob's post-run handler retires a prd-missing skip as a plain completi
     const state = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
     const row = state.jobs.find((j) => j.slug === slug);
     expect(row).toBeDefined();
-    expect(row.status).toBe('completed');
+    // A 'prd-missing' skip means no executor ever ran — it must land on the
+    // distinct 'skipped' status, never 'completed' (the status a genuine
+    // successful run produces), so unrun work can never masquerade as done.
+    expect(row.status).toBe('skipped');
+    expect(row.status).not.toBe('completed');
     expect(row.exitCode).toBe(0);
     expect(row.error).toBeNull();
     // No verify pass ran and no RCA feedback fired: a verified run always

package/src/main/ipcSchemas.cjs

@@ -369,6 +369,16 @@ const adminListPrdsQuery = z.object({
   cwd: z.string().min(1).max(4096).optional(),
   epicId: z.string().min(1).max(200).optional(),
   status: z.string().min(1).max(40).optional(),
+  // Page size — default 100, hard max 500 so an agent can't accidentally
+  // re-request the full unbounded list (PRD: the 353KB/120s-timeout
+  // incident this pagination exists to fix). Query strings arrive as text,
+  // so these coerce before the int/range checks run.
+  limit: z.coerce.number().int().min(1).max(500).optional().default(100),
+  offset: z.coerce.number().int().min(0).optional().default(0),
+  // 'compact' (default) omits the secondary detail fields (parallelGroup,
+  // estimateMinutes, sourcePromptId, epicId, archivedStatus) that aren't
+  // needed to answer "what PRDs are there"; 'full' restores them.
+  fields: z.enum(['compact', 'full']).optional().default('compact'),
 });
 
 const adminGetPrdQuery = z.object({

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

@@ -93,6 +93,18 @@ test('a FAILED bare-named dep holds the dependent and reports an explicit reason
   assert.match(reason, /874-nav-face-project-home <- leftnav-two-face-framework/);
 });
 
+test('a SKIPPED (never-ran) bare-named dep holds the dependent and reports an explicit reason', () => {
+  const jobs = [
+    job('873-leftnav-two-face-framework', 'skipped'),
+    job('874-nav-face-project-home', 'pending', { dependsOn: ['leftnav-two-face-framework'] }),
+  ];
+  const { batch, reason } = pick(jobs);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  assert.match(reason, /never-ran dependencies/);
+  assert.match(reason, /874-nav-face-project-home <- leftnav-two-face-framework/);
+});
+
 // ---------------------------------------------------------------------------
 // Parallelism regression coverage.
 //
@@ -209,6 +221,20 @@ test('hold record carries a failed dep status alongside the depends-gate reason'
   ]);
 });
 
+test('hold record carries a skipped dep status alongside the depends-gate reason', () => {
+  const jobs = [
+    job('985-foundation', 'skipped'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { batch, reason, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  assert.match(reason, /never-ran dependencies/);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'skipped' },
+  ]);
+});
+
 test('no holds when nothing is dependency-blocked', () => {
   const jobs = [job('988-a', 'pending'), job('989-b', 'pending')];
   const { batch, holds } = pick(jobs, new Set(), 5);

package/src/main/lib/prdAdminRoutes.cjs

@@ -45,6 +45,16 @@ function parseJsonBody(raw) {
  * scheduler.cjs's own registerAdminRoute(s) pattern.
  */
 function registerAdminRoute(adminHttp, remote) {
+  // GET /admin/scheduler/prds — paginated PRD listing (PRD: 353KB/120s
+  // fix). Sort order is stable and explicit: slug ascending via
+  // String.localeCompare(..., { numeric: true }) (listPrdsInternal in
+  // scheduler.cjs), so offset paging can't skip or duplicate an entry
+  // between calls as long as the underlying PRD set is unchanged.
+  // `limit`/`offset` default to 100/0 (hard max limit 500); `total` is the
+  // filtered count BEFORE the page slice, and `hasMore` is derived from
+  // `total`, not from whether the page came back full. `fields=full` opts
+  // into the secondary detail fields (parallelGroup, estimateMinutes,
+  // sourcePromptId, epicId, archivedStatus) omitted by default.
   adminHttp.registerRoute('GET', '/admin/scheduler/prds', async (req, res, query) => {
     let input;
     try {
@@ -53,8 +63,8 @@ function registerAdminRoute(adminHttp, remote) {
       sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
       return;
     }
-    const prds = await remote.listPrds(input);
-    sendJson(res, 200, { ok: true, prds });
+    const { prds, total, limit, offset, hasMore } = await remote.listPrds(input);
+    sendJson(res, 200, { ok: true, prds, total, limit, offset, hasMore });
   });
 
   adminHttp.registerRoute('GET', '/admin/scheduler/prd', async (req, res, query) => {

package/src/main/lib/queueHistory.cjs

@@ -62,9 +62,11 @@ function jobKey(job) {
 
 /**
  * O(n) over `jobs`. Splits terminal jobs into `hot` (stays in queue.json)
- * and `toArchive` (moves to history.jsonl). A completed/failed job archives
- * only when ALL of:
- *   - status is 'completed' or 'failed'
+ * and `toArchive` (moves to history.jsonl). A completed/failed/skipped job
+ * archives only when ALL of:
+ *   - status is 'completed', 'failed', or 'skipped' (skipped: a job whose
+ *     PRD source vanished before dispatch — never ran, but still terminal,
+ *     and must age out of the hot queue the same as any other finished row)
  *   - finishedAt parses and is older than opts.retentionMs (default
  *     HISTORY_RETENTION_MS)
  *   - it is not the healTargetForFix() parent of a pending/running fix-plan
@@ -90,7 +92,7 @@ function partitionJobs(jobs, nowMs, opts = {}) {
     if (!j) continue;
     const finishedMs = j.finishedAt ? Date.parse(j.finishedAt) : NaN;
     const archivable =
-      (j.status === 'completed' || j.status === 'failed') &&
+      (j.status === 'completed' || j.status === 'failed' || j.status === 'skipped') &&
       Number.isFinite(finishedMs) &&
       (nowMs - finishedMs) > retentionMs &&
       !protectedSlugs.has(j.slug);

package/src/main/lib/scheduleJobSchema.cjs

@@ -24,7 +24,7 @@
 
 const { z } = require('zod');
 
-const JOB_STATUSES = ['pending', 'running', 'investigating', 'completed', 'failed', 'needs_review', 'quarantined'];
+const JOB_STATUSES = ['pending', 'running', 'investigating', 'completed', 'skipped', 'failed', 'needs_review', 'quarantined'];
 
 const ScheduleJobStatusSchema = z.enum(JOB_STATUSES);
 

package/src/main/lib/scheduleJobTransitions.cjs

@@ -44,7 +44,10 @@ const STATUS_HISTORY_CAP = 20;
  *    manual archive of an already-shipped PRD), pending->failed (admin
  *    cancelJob on a not-yet-started job)
  *  - running->completed|failed|needs_review (normal run outcomes, reaper),
- *    running->pending (halt/rate-limit reset, transient-failure retry)
+ *    running->skipped (spawnJob:skip-archived's 'prd-missing' case — no
+ *    executor ever ran; kept distinct from 'completed' so unrun work can't
+ *    read as shipped), running->pending (halt/rate-limit reset,
+ *    transient-failure retry)
  *  - investigating->failed|needs_review (restore prior status once the
  *    investigation probe exits), investigating->completed (defensive: the
  *    restored prior status could in principle be 'completed' if a caller
@@ -58,20 +61,30 @@ const STATUS_HISTORY_CAP = 20;
  *  - completed->pending (force-only reset, gated separately by
  *    resetJobFields' own guard — this table only says the edge is
  *    structurally legal, not that every caller may take it unconditionally)
+ *  - skipped->pending (force-only reset, same resetJobFields guard as
+ *    completed->pending — 'skipped' is otherwise terminal: no further
+ *    transitions out)
  *  - quarantined->pending (reconcile()'s adopt path, PRD-authoring lockdown:
  *    a PRD discovered with no `createdVia` provenance stamp is queued
  *    'quarantined' instead of 'pending'; the ONLY way out is the PRD being
  *    stamped via the update-prd API — reconcile() detects the stamp on its
  *    next pass and promotes the row)
+ *  - pending|investigating|needs_review|quarantined -> skipped
+ *    (schedule:clear-queue: a manual queue clear force-terminates any
+ *    non-running victim row so it can leave a durable history.jsonl record
+ *    instead of vanishing — same 'never ran, don't call it completed'
+ *    rationale as running->skipped, just reachable from every pre-dispatch
+ *    or unresolved status a queued row can be sitting in)
  */
 const LEGAL_TRANSITIONS = {
-  pending: ['running', 'completed', 'failed'],
-  running: ['completed', 'failed', 'needs_review', 'pending'],
-  investigating: ['failed', 'needs_review', 'completed', 'pending'],
+  pending: ['running', 'completed', 'failed', 'skipped'],
+  running: ['completed', 'failed', 'needs_review', 'skipped', 'pending'],
+  investigating: ['failed', 'needs_review', 'completed', 'pending', 'skipped'],
   failed: ['investigating', 'pending', 'completed'],
-  needs_review: ['investigating', 'pending', 'completed'],
+  needs_review: ['investigating', 'pending', 'completed', 'skipped'],
   completed: ['pending'],
-  quarantined: ['pending'],
+  skipped: ['pending'],
+  quarantined: ['pending', 'skipped'],
 };
 
 let refusedTransitionCount = 0;

package/src/main/lib/schedulerBatch.cjs

@@ -97,6 +97,12 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
 
   const pending = [];
   const heldByFailedDep = [];
+  // A dep that never ran (its PRD source vanished before dispatch — see
+  // scheduleJobSchema.cjs's 'skipped' status) is just as blocking as a
+  // failed one and deserves the same explicit reason, not a silent fall into
+  // the generic `holds` bucket — resetting won't help here (the source file
+  // is gone), so the guidance differs from the failed-dep case.
+  const heldBySkippedDep = [];
   // Per-job hold records, surfaced to the UI so a `pending` row can say WHICH
   // dep is holding it instead of leaving the reason in console.log.
   const holds = [];
@@ -105,7 +111,9 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
     if (!dep) { pending.push(j); continue; }
     const depRows = rowsForDep(dep);
     const failed = depRows.some((d) => d.status === 'failed');
+    const skipped = depRows.some((d) => d.status === 'skipped');
     if (failed) heldByFailedDep.push({ job: j, dep });
+    else if (skipped) heldBySkippedDep.push({ job: j, dep });
     holds.push({
       slug: j.slug,
       dep,
@@ -114,9 +122,17 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
     // running/pending/needs_review dep — simply not eligible this tick.
   }
   if (pending.length === 0) {
+    const reasons = [];
     if (heldByFailedDep.length > 0) {
       const detail = heldByFailedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
-      const reason = `[scheduler] depends-gate [${projectCwd}]: holding ${heldByFailedDep.length} job(s) behind failed dependencies [${detail}]. Reset or archive the dep to unblock.`;
+      reasons.push(`holding ${heldByFailedDep.length} job(s) behind failed dependencies [${detail}]. Reset or archive the dep to unblock.`);
+    }
+    if (heldBySkippedDep.length > 0) {
+      const detail = heldBySkippedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
+      reasons.push(`holding ${heldBySkippedDep.length} job(s) behind never-ran dependencies [${detail}]. The dep's PRD source is gone — author a fresh PRD for that work to unblock.`);
+    }
+    if (reasons.length > 0) {
+      const reason = `[scheduler] depends-gate [${projectCwd}]: ${reasons.join(' ')}`;
       console.log(reason);
       return { batch: [], reason, holds };
     }