claude-code-session-manager 0.75.0 → 0.75.2

package/src/main/scheduler.cjs

@@ -100,7 +100,7 @@ const queueOps = require('./queueOps.cjs');
 // home-dir layout.
 const { resolvePrdsDirs, resolveArchivedPrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
 const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
-const { transitionJob } = require('./lib/scheduleJobTransitions.cjs');
+const { transitionJob, STATUS_HISTORY_CAP } = require('./lib/scheduleJobTransitions.cjs');
 const { buildContextDigest, composeExecutorPrompt } = require('./lib/epicContextDigest.cjs');
 const { JOB_STATUSES } = require('./lib/scheduleJobSchema.cjs');
 const { appendAuditEvent } = require('./lib/auditLog.cjs');
@@ -1424,7 +1424,7 @@ async function reconcile(state) {
         seen.add(job.slug);
         next.push({ ...job });
         console.warn(`[scheduler] reconcile: keeping ${job.status} job ${job.slug} — PRD source not visible in any candidate dir`);
-      } else if (job.status === 'completed' || job.status === 'failed') {
+      } else if (job.status === 'completed' || job.status === 'failed' || job.status === 'skipped') {
         terminalDroppedNeedingHistoryCheck.push(job);
       }
       continue;
@@ -2104,7 +2104,7 @@ async function clearPause(source) {
  * already-'completed' job, and that path is exactly what this guards.
  */
 function resetJobFields(job, errorMsg, opts = {}) {
-  if (job.status === 'completed' && opts.force !== true) return false;
+  if ((job.status === 'completed' || job.status === 'skipped') && opts.force !== true) return false;
   if (!transitionJob(job, 'pending', { reason: errorMsg ?? 'reset to pending', source: opts.source ?? 'resetJobFields' })) return false;
   job.runId = null;
   job.startedAt = null;
@@ -2289,6 +2289,37 @@ async function resolveVerifyPrdPath(job) {
   return liveDir ? safeSlugPathIn(liveDir, job.slug) : null;
 }
 
+/**
+ * resolveFixPlanPath(failedJob) → { fixPath, fixSlug, group, livePrdDir }
+ *
+ * Where spawnInvestigation's auto-fix plan for `failedJob` must be written.
+ * The plan belongs in the SAME dir the original PRD lives in right now
+ * (`livePrdDir`, from resolveVerifyPrdPath's live-dir search — usually the
+ * originating Epic's `epics/<epicId>/prds/`), never the retired flat dir:
+ * consolidateFlatPrds (prdMigration.cjs) sweeps only the flat dir and
+ * archives any `.md` there with no live queue row, which a freshly-authored
+ * fix plan never has yet — so writing it flat means the very next
+ * reconcile() pass (src/main/scheduler.cjs's consolidateAllFlatPrds call)
+ * archives it before it can ever be enqueued. `livePrdDir` is null (and the
+ * flat dir, `prdDirForCwd`, is used instead) only when the original PRD
+ * can't be found live anywhere on disk — an archived twin is deliberately
+ * NOT treated as a live location for this purpose.
+ *
+ * Exported as a pure(ish) helper (one fs-free branch, one await) so tests
+ * can prove the round trip — fix plan lands beside its original and
+ * survives a consolidateFlatPrds(cwd) pass — without spawning a real
+ * investigation.
+ */
+async function resolveFixPlanPath(failedJob) {
+  const livePrdPath = await resolveVerifyPrdPath(failedJob);
+  const livePrdDir = livePrdPath ? path.dirname(livePrdPath) : null;
+  const baseSlug = failedJob.slug.replace(/^\d+-/, '');
+  const group = failedJob.parallelGroup ?? 99;
+  const fixSlug = `${String(group).padStart(2, '0')}-fix-${baseSlug}`;
+  const fixPath = path.join(livePrdDir ?? prdDirForCwd(failedJob.cwd), `${fixSlug}.md`);
+  return { fixPath, fixSlug, group, livePrdDir };
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -2980,6 +3011,16 @@ function isFixPlanSlug(slug) {
   return /^\d+-fix-/.test(slug);
 }
 
+/**
+ * The fix-plan slug spawnInvestigation authors for a given failed job —
+ * shared by selectAutoFixTargets (queue-membership check) and
+ * reverifyNeedsReview's autofix_plan_unqueued annotation (same check, run
+ * one or more passes later) so both use one slug formula.
+ */
+function fixSlugFor(job) {
+  return `${String(job.parallelGroup ?? 99).padStart(2, '0')}-fix-${job.slug.replace(/^\d+-/, '')}`;
+}
+
 /**
  * Returns true for statuses that a fix-plan completion should promote
  * (clear) on the original job. Both 'failed' and 'needs_review' are
@@ -3165,9 +3206,18 @@ async function spawnInvestigation(failedJob, runDir) {
   const failedLogPath = path.join(runDir, `${failedJob.slug}.log`);
   const investigationLogPath = path.join(runDir, `${failedJob.slug}.investigation.log`);
 
+  // livePrdDir is the SAME dir the original PRD lives in right now (usually
+  // its Epic-scoped `epics/<epicId>/prds/`) — the fix plan must land there
+  // too, since consolidateFlatPrds only ever sweeps the retired flat dir
+  // (prdDirForCwd) and would archive a freshly-authored fix plan on the very
+  // next reconcile() pass before it ever gets a queue row. Only fall back to
+  // the flat dir when the original PRD can't be found on disk at all — an
+  // archived twin (archivedPrdPathForJob) is deliberately NOT used for the
+  // write dir, only for reading originalBody below.
   let originalBody = '';
+  const { fixPath, fixSlug, group, livePrdDir } = await resolveFixPlanPath(failedJob);
   try {
-    const originalPath = (await resolveVerifyPrdPath(failedJob)) ?? archivedPrdPathForJob(failedJob);
+    const originalPath = livePrdDir ? path.join(livePrdDir, `${failedJob.slug}.md`) : archivedPrdPathForJob(failedJob);
     originalBody = (await parsePrd(originalPath)).body;
   } catch {
     originalBody = failedJob.bodyPreview || '(original PRD missing from disk)';
@@ -3175,11 +3225,6 @@ async function spawnInvestigation(failedJob, runDir) {
 
   const logTail = readTail(failedLogPath, 16 * 1024) || '(failed to read log)';
 
-  const baseSlug = failedJob.slug.replace(/^\d+-/, '');
-  const group = failedJob.parallelGroup ?? 99;
-  const fixSlug = `${String(group).padStart(2, '0')}-fix-${baseSlug}`;
-  const fixPath = path.join(prdDirForCwd(failedJob.cwd), `${fixSlug}.md`);
-
   if (fs.existsSync(fixPath)) {
     console.log(`[scheduler] skip investigation: fix plan already exists at ${fixPath}`);
     releaseSlot();
@@ -3281,6 +3326,13 @@ async function spawnInvestigation(failedJob, runDir) {
           ? `investigation spawn failed: ${error?.message ?? String(error)}`
           : `investigation error: ${error.message}`;
         sl(`\n[scheduler] ${errMsg}\n`);
+        // Stamp the outcome even on this early exit — otherwise the job is
+        // left with autoFixAttempted: true and no outcome, which used to
+        // read as a permanent dead-end (see selectAutoFixTargets).
+        mutate((s) => {
+          const j = s.jobs.find((x) => x.slug === failedJob.slug);
+          if (j) j.autoFixOutcome = 'error';
+        }).catch(() => {});
         return;
       }
       sl(`\n[scheduler] investigation exit code=${exitCode}\n`);
@@ -3301,6 +3353,10 @@ async function spawnInvestigation(failedJob, runDir) {
       }
       if (fs.existsSync(fixPath)) {
         console.log(`[scheduler] investigation produced fix plan: ${fixSlug}`);
+        mutate((s) => {
+          const j = s.jobs.find((x) => x.slug === failedJob.slug);
+          if (j) j.autoFixOutcome = 'plan';
+        }).catch(() => {});
       } else {
         console.log(`[scheduler] investigation finished WITHOUT producing fix plan (slug=${failedJob.slug}, code=${exitCode})`);
         // Record the no-plan outcome so selectAutoFixTargets can offer one
@@ -3430,13 +3486,18 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     // Stale queue entry: the PRD was archived (already shipped) or is gone
     // from disk entirely (deleted before dispatch). Both are retire-not-fail
     // results from prdArchivedSkipResult with exitCode 0 and no transcript —
-    // treat any truthy skip reason as a plain completion: no verify pass, no
-    // commit guard, no RCA feedback item.
+    // no verify pass, no commit guard, no RCA feedback item — but only
+    // 'prd-archived' actually means the work shipped (archivedTwinExists
+    // found the file under a prds-archived/ dir). 'prd-missing' means no
+    // executor ever ran at all, so it must NOT land on the same 'completed'
+    // status a genuine successful run produces — that conflation is what let
+    // 20 never-executed sigma PRDs read as shipped (2026-08-30 incident).
     if (res.skipped) {
+      const targetStatus = res.skipped === 'prd-missing' ? 'skipped' : 'completed';
       await mutate((s) => {
         const idx = s.jobs.findIndex((x) => x.slug === job.slug);
         if (idx >= 0) {
-          transitionJob(s.jobs[idx], 'completed', { reason: res.note ?? 'PRD archived or missing — treated as already-shipped', source: 'spawnJob:skip-archived' });
+          transitionJob(s.jobs[idx], targetStatus, { reason: res.note ?? 'PRD archived or missing — treated as already-shipped', source: 'spawnJob:skip-archived' });
           s.jobs[idx].finishedAt = new Date().toISOString();
           s.jobs[idx].exitCode = 0;
           s.jobs[idx].error = null;
@@ -3711,10 +3772,10 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
               process.env.SM_AUTOFIX_DISABLE !== '1' &&
               isEligibleForImmediateAutoFix(s.jobs[i2], s.jobs, fixSlugExists)
             ) {
-              const isNoPlanRetry = s.jobs[i2].autoFixAttempted && s.jobs[i2].autoFixOutcome === 'no-plan';
+              const isRetryAttempt = s.jobs[i2].autoFixAttempted === true;
               s.jobs[i2].autoFixAttempted = true;
               if (!s.jobs[i2].runId) s.jobs[i2].runId = runId;
-              if (isNoPlanRetry) {
+              if (isRetryAttempt) {
                 s.jobs[i2].autoFixRetries = (s.jobs[i2].autoFixRetries ?? 0) + 1;
                 delete s.jobs[i2].autoFixOutcome;
               }
@@ -4241,7 +4302,7 @@ async function pollLoop() {
 // callers/tests that only pass `jobs` are unaffected.
 function selectHistoryJobs(jobs, limit, historyEntries = []) {
   const cap = Math.max(1, Math.min(500, Number.isFinite(limit) ? Math.floor(limit) : 50));
-  const hot = (Array.isArray(jobs) ? jobs : []).filter((j) => j && (j.status === 'completed' || j.status === 'failed'));
+  const hot = (Array.isArray(jobs) ? jobs : []).filter((j) => j && (j.status === 'completed' || j.status === 'failed' || j.status === 'skipped'));
   const seen = new Set(hot.map((j) => `${j.slug}|${j.runId ?? ''}`));
   const archived = (Array.isArray(historyEntries) ? historyEntries : []).filter((j) => {
     if (!j) return false;
@@ -4337,6 +4398,35 @@ function isUnresolvableNeedsReview(job, { hasRunDir }) {
   return !!job && job.status === 'needs_review' && !job.runId && !hasRunDir;
 }
 
+/**
+ * Pure predicate: an auto-fix attempt whose one bounded retry is already
+ * spent, and whose outcome was NOT 'plan' (a produced plan is judged by
+ * isPlanUnqueued instead — a plan is never retried, only annotated if it
+ * never reaches the queue). Covers all three exhaustible outcomes
+ * ('no-plan', 'error', and unstamped/undefined) — mirrors the retry
+ * eligibility rule in selectAutoFixTargets so a job can never be retry-
+ * eligible there and simultaneously un-annotatable here.
+ */
+function isExhaustedAutoFix(job) {
+  return !!job && job.status === 'needs_review'
+    && job.autoFixAttempted === true
+    && job.autoFixOutcome !== 'plan'
+    && (job.autoFixRetries ?? 0) >= 1;
+}
+
+/**
+ * Pure predicate: an investigation produced a fix plan (autoFixOutcome ===
+ * 'plan') but its fix-plan slug is not present among `queuedSlugs` — the
+ * plan file failed to become a queue row (write failure, or some other
+ * reason reconcile() never ingested it). `queuedSlugs` is the caller's
+ * current job-slug set, passed in rather than read here so this stays pure.
+ */
+function isPlanUnqueued(job, queuedSlugs) {
+  if (!job || job.status !== 'needs_review') return false;
+  if (job.autoFixOutcome !== 'plan') return false;
+  return !queuedSlugs.has(fixSlugFor(job));
+}
+
 /**
  * Pure predicate: is this job eligible for the boot re-verify self-heal? Only
  * needs_review jobs with a run log (own or backfilled via resolveRunId) AND a
@@ -4417,9 +4507,13 @@ function isRescanCandidate(job) {
  *   - a runId, own or backfilled via resolveJobRunId (need a run log to investigate)
  *   - not itself a fix-plan slug (avoids infinite recursion)
  *   - autoFixAttempted cap: a job with no prior attempt is eligible; a job
- *     whose prior attempt outcome was 'no-plan' gets ONE bounded retry
- *     (autoFixRetries < 1); any other attempted job (or an exhausted
- *     no-plan retry) is excluded
+ *     whose prior attempt outcome was 'no-plan', 'error', or UNSTAMPED
+ *     (investigation exited without recording any outcome — unknown is not
+ *     "succeeded") gets ONE bounded retry (autoFixRetries < 1); a job whose
+ *     outcome was 'plan' (a fix plan was produced) is never retried here —
+ *     it either lands as a queue row on its own or gets flagged
+ *     autofix_plan_unqueued by reverifyNeedsReview's annotation pass; an
+ *     exhausted retry is excluded
  *   - no fix sibling on disk (fixSlugExists) or already in the queue
  */
 function selectAutoFixTargets(jobs, { fixSlugExists, resolveJobRunId = resolveRunId }) {
@@ -4430,10 +4524,13 @@ function selectAutoFixTargets(jobs, { fixSlugExists, resolveJobRunId = resolveRu
     if (!runId) return false;
     if (isFixPlanBeyondDepthCap(job.slug, job.investigationDepth)) return false;
     if (job.autoFixAttempted) {
-      if (job.autoFixOutcome !== 'no-plan') return false;
+      const retryEligible = job.autoFixOutcome === 'no-plan'
+        || job.autoFixOutcome === 'error'
+        || job.autoFixOutcome == null;
+      if (!retryEligible) return false;
       if ((job.autoFixRetries ?? 0) >= 1) return false;
     }
-    const fixSlug = `${String(job.parallelGroup ?? 99).padStart(2, '0')}-fix-${job.slug.replace(/^\d+-/, '')}`;
+    const fixSlug = fixSlugFor(job);
     if (fixSlugExists(fixSlug)) return false;
     if (slugsInQueue.has(fixSlug)) return false;
     return true;
@@ -4561,20 +4658,29 @@ async function reverifyNeedsReview() {
 
   // Surface needs_review jobs that can never self-heal or get an auto-fix
   // investigation (no runId, no backfillable run dir) instead of leaving
-  // them silently stranded. Also surface no-plan auto-fix jobs whose one
-  // bounded retry is already exhausted. Both are annotated, never looped on.
+  // them silently stranded. Also surface auto-fix jobs whose one bounded
+  // retry is already exhausted (outcome 'no-plan', 'error', or unstamped —
+  // selectAutoFixTargets treats all three as retry-eligible, so all three
+  // must also be annotatable once the retry is spent), and jobs whose
+  // investigation DID produce a fix plan that never became a queue row
+  // (write failed, or reconcile hasn't picked it up for some other reason).
+  // All three classes are annotated, never looped on — a needs_review job
+  // must not exit this pass both un-retried and un-annotated.
   const afterHealForAnnotate = await readQueue();
   const unresolvable = afterHealForAnnotate.jobs.filter(
     (j) => isUnresolvableNeedsReview(j, { hasRunDir: !!resolveRunId(j) }) && j.verifierVerdict !== 'no_run_artifacts',
   );
-  const exhaustedNoPlan = afterHealForAnnotate.jobs.filter(
-    (j) => j.status === 'needs_review'
-      && j.autoFixAttempted && j.autoFixOutcome === 'no-plan' && (j.autoFixRetries ?? 0) >= 1
-      && j.verifierVerdict !== 'autofix_no_plan',
+  const exhaustedAutoFix = afterHealForAnnotate.jobs.filter(
+    (j) => isExhaustedAutoFix(j) && j.verifierVerdict !== 'autofix_no_plan',
+  );
+  const queuedSlugs = new Set(afterHealForAnnotate.jobs.map((j) => j.slug));
+  const planUnqueued = afterHealForAnnotate.jobs.filter(
+    (j) => isPlanUnqueued(j, queuedSlugs) && j.verifierVerdict !== 'autofix_plan_unqueued',
   );
-  if (unresolvable.length || exhaustedNoPlan.length) {
+  if (unresolvable.length || exhaustedAutoFix.length || planUnqueued.length) {
     const unresolvableSet = new Set(unresolvable.map((j) => j.slug));
-    const exhaustedSet = new Set(exhaustedNoPlan.map((j) => j.slug));
+    const exhaustedSet = new Set(exhaustedAutoFix.map((j) => j.slug));
+    const planUnqueuedSet = new Set(planUnqueued.map((j) => j.slug));
     await mutate((s) => {
       for (const j of s.jobs) {
         if (unresolvableSet.has(j.slug)) {
@@ -4583,14 +4689,22 @@ async function reverifyNeedsReview() {
         } else if (exhaustedSet.has(j.slug)) {
           j.verifierVerdict = 'autofix_no_plan';
           j.error = 'auto-fix investigation produced no fix plan after retry — manual review';
+        } else if (planUnqueuedSet.has(j.slug)) {
+          j.verifierVerdict = 'autofix_plan_unqueued';
+          j.error = 'auto-fix investigation produced a fix plan that never reached the queue — manual review';
         }
       }
     });
     if (unresolvable.length) {
       console.log(`[scheduler] boot reverify: no run artifacts for ${unresolvable.map((j) => j.slug).join(', ')} — flagged for manual review`);
     }
-    if (exhaustedNoPlan.length) {
-      console.log(`[scheduler] boot reverify: auto-fix retry exhausted for ${exhaustedNoPlan.map((j) => j.slug).join(', ')} — flagged for manual review`);
+    if (exhaustedAutoFix.length) {
+      console.log(`[scheduler] boot reverify: auto-fix retry exhausted for ${exhaustedAutoFix.map((j) => j.slug).join(', ')} — flagged for manual review`);
+    }
+    if (planUnqueued.length) {
+      for (const j of planUnqueued) {
+        console.log(`[scheduler] boot reverify: auto-fix plan never queued for ${j.slug} — flagged for manual review`);
+      }
     }
     await broadcast();
   }
@@ -4608,7 +4722,7 @@ async function reverifyNeedsReview() {
     for (const job of targets) {
       const runId = job.runId || resolveRunId(job);
       const runDir = path.join(RUNS_DIR, runId);
-      const isNoPlanRetry = job.autoFixAttempted && job.autoFixOutcome === 'no-plan';
+      const isRetryAttempt = job.autoFixAttempted === true;
       // Persist the attempt BEFORE spawning — a crash mid-investigation still
       // counts it (mirrors orphanRetries). Safe even when the slot is busy: the
       // investigation is queued and drained as slots free, so it is genuinely
@@ -4618,13 +4732,13 @@ async function reverifyNeedsReview() {
         if (j) {
           j.autoFixAttempted = true;
           if (!j.runId && runId) j.runId = runId;
-          if (isNoPlanRetry) {
+          if (isRetryAttempt) {
             j.autoFixRetries = (j.autoFixRetries ?? 0) + 1;
             delete j.autoFixOutcome;
           }
         }
       });
-      console.log(`[scheduler] auto-fix: needs_review ${job.slug} → authoring fix-plan (${isNoPlanRetry ? 'retry' : '1/1'})`);
+      console.log(`[scheduler] auto-fix: needs_review ${job.slug} → authoring fix-plan (${isRetryAttempt ? 'retry' : '1/1'})`);
       spawnInvestigation(job, runDir).catch((e) => {
         console.error('[scheduler] auto-fix spawnInvestigation error', job.slug, e);
       });
@@ -4634,6 +4748,43 @@ async function reverifyNeedsReview() {
   return { rescanned: candidates.length, healed, leftForReview };
 }
 
+/**
+ * schedule:clear-queue's core state mutation, split out so it's testable
+ * without ipcMain/electron: every victim (non-running job whose slug is in
+ * `victimSlugs`) must leave a durable history.jsonl record before it
+ * disappears from queue.json — a manual clear used to just filter the row
+ * out with no trace (a job could vanish with zero audit trail; see the
+ * 2026-08-30 sigma `788-pr-sweep-final-gate` incident). Non-terminal victims
+ * (pending/investigating/needs_review/quarantined) are force-transitioned to
+ * 'skipped' — never 'completed', since a manually-cleared job did not ship.
+ * Victims already terminal (completed/failed/skipped) keep their real
+ * status; they just get a statusHistory note + a history row so they don't
+ * silently drop before aging past HISTORY_RETENTION_MS.
+ *
+ * Mutates `state.jobs` in place (drops the victims, same contract as
+ * reconcile()) and returns the job snapshots to append to history.jsonl.
+ */
+function applyClearQueueVictims(state, victimSlugs, archiveNoteBySlug, archiveDir) {
+  const historyEntries = [];
+  for (const job of state.jobs) {
+    if (!victimSlugs.has(job.slug)) continue;
+    const reason = archiveNoteBySlug?.get(job.slug) ?? `PRD archived to ${archiveDir}`;
+    if (job.status === 'completed' || job.status === 'failed' || job.status === 'skipped') {
+      // Already terminal — keep the real status, just record the clear.
+      const history = Array.isArray(job.statusHistory) ? job.statusHistory : [];
+      history.push({ from: job.status, to: job.status, reason, source: 'clear-queue', at: new Date().toISOString() });
+      while (history.length > STATUS_HISTORY_CAP) history.shift();
+      job.statusHistory = history;
+    } else {
+      transitionJob(job, 'skipped', { reason, source: 'clear-queue' });
+    }
+    if (!job.finishedAt) job.finishedAt = new Date().toISOString();
+    historyEntries.push({ ...job });
+  }
+  state.jobs = state.jobs.filter((j) => !victimSlugs.has(j.slug));
+  return historyEntries;
+}
+
 function registerScheduleHandlers() {
   ensureDirs();
   supervisor.registerHandlers();
@@ -4796,10 +4947,6 @@ function registerScheduleHandlers() {
     return { ok: true, kind: 'info', message };
   });
 
-  // Archive every non-running PRD and drop its entry from queue.json.
-  // Running entries are kept (would orphan an in-flight job). PRD files are
-  // moved (not deleted) to prds-archived/<ISO>/ so the user can recover them.
-  // Path containment is enforced — only files inside PRDS_DIR are moved.
   ipcMain.handle('schedule:clear-queue', async () => {
     ensureDirs();
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
@@ -4811,6 +4958,7 @@ function registerScheduleHandlers() {
     }
     await fsp.mkdir(archiveDir, { recursive: true });
     let archived = 0;
+    const archiveNoteBySlug = new Map();
     for (const job of victims) {
       const srcDir = await findPrdDir(job.slug) ?? prdDirForCwd(job.cwd);
       const src = path.resolve(path.join(srcDir, `${job.slug}.md`));
@@ -4819,17 +4967,27 @@ function registerScheduleHandlers() {
       try {
         await fsp.rename(src, dst);
         archived++;
+        archiveNoteBySlug.set(job.slug, `PRD file archived to ${archiveDir}`);
       } catch (e) {
         // ENOENT: the .md is already gone (reconcile would drop it on next
         // read anyway). Either way, fall through and remove from queue.
         if (e?.code !== 'ENOENT') {
           logs.writeLine({ level: 'warn', scope: 'scheduler', message: 'clear-queue: rename failed', meta: { slug: job.slug, error: e?.message } });
         }
+        archiveNoteBySlug.set(job.slug, `PRD file already gone (ENOENT) when archiving to ${archiveDir}`);
       }
     }
     await mutate(async (s) => {
       const victimSlugs = new Set(victims.map((j) => j.slug));
-      s.jobs = s.jobs.filter((j) => !victimSlugs.has(j.slug));
+      const historyEntries = applyClearQueueVictims(s, victimSlugs, archiveNoteBySlug, archiveDir);
+      // Append BEFORE this mutate's writeQueue persists s.jobs without the
+      // victims (mutate() only writes after this callback resolves) — same
+      // append-before-drop ordering queueHistory.cjs's reconcile() callers
+      // use, so a crash right after this handler returns can never leave a
+      // row gone from queue.json with nothing in history.jsonl yet.
+      if (historyEntries.length > 0) {
+        await queueHistory.appendHistory(historyEntries);
+      }
       await reconcile(s);
       return null;
     });
@@ -5244,6 +5402,20 @@ async function init() {
   }
 }
 
+// Measured against this repo's own live+archived PRD set (868 entries
+// across every local project — the admin route has no cwd filter by
+// default): no single field dominates a listPrdsInternal() entry: title is
+// the largest at ~30% of payload bytes, followed by slug/cwd/sourcePromptId/
+// epicId at 12-14% each — the 353KB the route was shipping came from
+// returning the full unbounded row count, not from one oversized field.
+// This trims the fields an agent doesn't need to answer "what PRDs are
+// there" (parallelGroup/estimateMinutes/sourcePromptId/epicId/
+// archivedStatus); `fields=full` restores them.
+function toCompactPrdEntry(entry) {
+  const { slug, title, cwd, mtimeMs, archived, status } = entry;
+  return { slug, title, cwd, mtimeMs, archived, status };
+}
+
 /**
  * listPrdsInternal() → every live + archived PRD across every project,
  * with each entry's real job status folded in (`status`: the live queue
@@ -5503,15 +5675,25 @@ const remote = {
 
   // Every live+archived PRD across every project (listPrdsInternal, shared
   // with the renderer's schedule:list-prds IPC handler), filtered by the
-  // admin route's cwd/epicId/status query params.
+  // admin route's cwd/epicId/status query params and paged by
+  // limit/offset. Sort order is listPrdsInternal's own slug.localeCompare
+  // (numeric) — stable across calls since it's a pure string sort, so
+  // paging by offset can't skip or duplicate an entry between requests as
+  // long as the underlying PRD set doesn't change mid-page.
   async listPrds(filter = {}) {
     const all = await listPrdsInternal();
-    return all.filter((entry) => {
+    const filtered = all.filter((entry) => {
       if (filter.cwd && entry.cwd !== filter.cwd) return false;
       if (filter.epicId && entry.epicId !== filter.epicId) return false;
       if (filter.status && entry.status !== filter.status) return false;
       return true;
     });
+    const total = filtered.length;
+    const limit = filter.limit ?? 100;
+    const offset = filter.offset ?? 0;
+    const page = filtered.slice(offset, offset + limit);
+    const prds = filter.fields === 'full' ? page : page.map(toCompactPrdEntry);
+    return { prds, total, limit, offset, hasMore: offset + page.length < total };
   },
 
   // Full body + parsed frontmatter for one PRD, live or archived. Mirrors
@@ -5650,7 +5832,7 @@ const remote = {
     const state = await readQueue();
     const job = state.jobs.find((j) => j.slug === slug);
     if (!job) return { ok: false, error: 'not found' };
-    if (job.status === 'completed' || job.status === 'failed' || job.status === 'needs_review') {
+    if (job.status === 'completed' || job.status === 'failed' || job.status === 'needs_review' || job.status === 'skipped') {
       return { ok: false, error: `job already terminal (status: "${job.status}") — nothing to cancel` };
     }
     const wasRunning = job.status === 'running';
@@ -5712,4 +5894,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { findOverrunningJobs, JOB_OVERRUN_FACTOR, JOB_OVERRUN_FLOOR_MS, registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, isGitRepoSync, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, resolveVerifyPrdPath, resolveNotifyPrd, runPrdMigration, consolidateAllFlatPrds, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult, spawnJob, listPrdsInternal, computeStallSummary, findStaleQuarantinedJobs, QUARANTINE_ESCALATE_MS };
+module.exports = { findOverrunningJobs, JOB_OVERRUN_FACTOR, JOB_OVERRUN_FLOOR_MS, registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, isExhaustedAutoFix, isPlanUnqueued, fixSlugFor, healTargetForFix, buildInvestigationPrompt, isGitRepoSync, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, resolveVerifyPrdPath, resolveFixPlanPath, resolveNotifyPrd, runPrdMigration, consolidateAllFlatPrds, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult, spawnJob, listPrdsInternal, computeStallSummary, findStaleQuarantinedJobs, QUARANTINE_ESCALATE_MS, applyClearQueueVictims };

package/src/preload/api.d.ts

@@ -391,7 +391,7 @@ export interface ScheduleConfig {
  *  so this union is a manually-kept copy; drift from JOB_STATUSES (and from
  *  the renderer's own mirrors in StatusBadge.tsx/SchedulePanel.tsx) is
  *  caught by src/main/__tests__/scheduleJobStatusDrift.test.cjs. */
-export type ScheduleJobStatus = 'pending' | 'running' | 'investigating' | 'completed' | 'failed' | 'needs_review' | 'quarantined';
+export type ScheduleJobStatus = 'pending' | 'running' | 'investigating' | 'completed' | 'skipped' | 'failed' | 'needs_review' | 'quarantined';
 
 export interface ScheduleJobRuntime {
   pid: number;