claude-code-session-manager 0.64.0 → 0.66.0

package/src/main/lib/prdAdminRoutes.cjs

@@ -0,0 +1,175 @@
+/**
+ * prdAdminRoutes.cjs — admin HTTP routes closing the PRD-lifecycle capability
+ * gap (PRD 1024, step 1 of locking the PRD entity behind the scheduler
+ * service boundary — see that PRD's Goal). Before this file, the admin API
+ * exposed only create-prd/jobs/reset-job/send-prompt: there was no way to
+ * READ, LIST, EDIT, ARCHIVE, or CANCEL a PRD/job over HTTP, which is exactly
+ * why direct filesystem access to session-manager-operations/scheduler/ was
+ * still sanctioned. This file plumbs those operations to HTTP; it adds no
+ * enforcement/denial of direct access — that's the dependent PRD's job (see
+ * this PRD's "Out of scope").
+ *
+ * Every route here reuses an existing verified implementation rather than
+ * reimplementing it:
+ *   - list/get/update/cancel delegate to scheduler.cjs's `remote` object
+ *     (job-status-aware; remote already owns the PRD-dir search + symlink
+ *     defense patterns these need)
+ *   - archive/retag delegate to queueOps.cjs's archiveMany/retagMany
+ *     directly (job-status-agnostic bulk file ops; already used by the
+ *     renderer's schedule:archive-prd/schedule:retag-prd IPC handlers)
+ *
+ * Registered against the same injected localAdminHttp.cjs transport as
+ * scheduler.cjs's registerAdminRoutes and prdCreate.cjs's registerAdminRoute
+ * (see index.cjs) — auth, loopback-only binding, and the bearer-token
+ * lifecycle are all the transport's job, not this file's.
+ */
+'use strict';
+
+const { schemas } = require('../ipcSchemas.cjs');
+const { readBody, sendJson } = require('./localAdminHttp.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
+const queueOps = require('../queueOps.cjs');
+
+function parseJsonBody(raw) {
+  try {
+    return { ok: true, value: raw ? JSON.parse(raw) : {} };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * registerAdminRoute(adminHttp, remote) — `remote` is scheduler.cjs's
+ * `remote` object, injected (not required directly) so this file stays
+ * testable without booting Electron, matching prdCreate.cjs's and
+ * scheduler.cjs's own registerAdminRoute(s) pattern.
+ */
+function registerAdminRoute(adminHttp, remote) {
+  adminHttp.registerRoute('GET', '/admin/scheduler/prds', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminListPrdsQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      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 });
+  });
+
+  adminHttp.registerRoute('GET', '/admin/scheduler/prd', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminGetPrdQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.getPrdParsed(input.slug, input.cwd);
+    if (!result.ok) {
+      sendJson(res, 404, result);
+      return;
+    }
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/update-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminUpdatePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.updatePrd(input);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : /status is/i.test(result.error ?? '') ? 409 : 400;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_prd_update', { route: '/admin/scheduler/update-prd', slug: input.slug, cwd: input.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/archive-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleArchivePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.archiveMany(input.slugs);
+    // Audit only the slugs that actually archived — archiveMany's `results`
+    // array carries the real per-slug outcome; logging every requested slug
+    // regardless of whether it succeeded would misrepresent a partial-failure
+    // batch as a clean one in audit-log.jsonl.
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_archive', { route: '/admin/scheduler/archive-prd', slug: r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/cancel-job', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminCancelJob.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.cancelJob(input.slug);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : 409;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_job_cancel', { route: '/admin/scheduler/cancel-job', slug: input.slug, cwd: result.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/retag-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleRetagPrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.retagMany(input.items);
+    // Audit only the items that actually retagged (see the archive-prd route
+    // above for why this must read result.results rather than the request).
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_retag', { route: '/admin/scheduler/retag-prd', slug: r.newSlug ?? r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+}
+
+module.exports = { registerAdminRoute };

package/src/main/lib/prdCreate.cjs

@@ -57,6 +57,15 @@ function buildPrdBody(input) {
   // filename prefix is the single source of truth for grouping; adding a
   // second one here would let the two drift out of sync.
   const fmLines = ['---', `title: ${title}`, `cwd: ${cwd}`, `estimateMinutes: ${estimateMinutes}`];
+  // Provenance stamp (PRD-authoring lockdown): every PRD written through this
+  // function — the sole in-process implementation behind both the admin
+  // HTTP create-prd route and the renderer's chat:create-prd IPC handler —
+  // carries proof it was authored via the API, not a bare Write/Edit tool
+  // call. scheduler.cjs's reconcile() refuses to run a discovered PRD with no
+  // `createdVia` (quarantines it instead); this line is why every
+  // API-created PRD is exempt. Stamped here, not left to a caller, so the
+  // guarantee can't be forgotten by a future route.
+  fmLines.push('createdVia: scheduler-api', `issuedAt: ${new Date().toISOString()}`);
   // Optional, additive: traces this PRD back to the PromptTicket (PRD 748)
   // that was classified 'develop' and spawned it (PRD 749).
   if (sourcePromptId) fmLines.push(`sourcePromptId: ${sourcePromptId}`);
@@ -204,7 +213,24 @@ async function createPrd(input, remote) {
     sourceTabId: input.sourceTabId ?? null,
   });
 
-  return { ok: true, nn, filename: `${filenameSlug}.md` };
+  // No `status` field here, and never one named 'queued' — that string was
+  // handed straight to callers as if it were a real ScheduleJob status, and
+  // is exactly how the 1021/1022 incident's invalid `"status": "queued"`
+  // rows got onto disk (this route's own response was the most likely
+  // source). A PRD is a queue row's SOURCE, not the row itself: writePrd
+  // only ever joins an Epic and writes the .md file — the queue row is
+  // created separately, by the next reconcile() pass. `enqueued: false` is
+  // true by construction (this function never touches queue.json), so no
+  // caller can copy a fake job status out of this response again.
+  return {
+    ok: true,
+    nn,
+    filename: `${filenameSlug}.md`,
+    prdPath: writeResult.path ?? null,
+    epicId: writeResult.epicId ?? null,
+    enqueued: false,
+    note: 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
+  };
 }
 
 /**
@@ -240,7 +266,16 @@ function registerAdminRoute(adminHttp, remote) {
       return;
     }
 
-    sendJson(res, 200, { nn: result.nn, filename: result.filename, status: 'queued' });
+    // Mirror createPrd()'s own honest shape verbatim — never re-add a
+    // 'status' field here. See createPrd's return above for why.
+    sendJson(res, 200, {
+      nn: result.nn,
+      filename: result.filename,
+      prdPath: result.prdPath ?? null,
+      epicId: result.epicId ?? null,
+      enqueued: false,
+      note: result.note,
+    });
   });
 }
 

package/src/main/lib/prdFrontmatter.cjs

@@ -48,4 +48,182 @@ function splitFrontmatter(raw) {
   };
 }
 
-module.exports = { splitFrontmatter };
+/**
+ * parsePrdFile / serializePrdFile — CJS port of
+ * src/renderer/lib/prdFrontmatter.ts's round-trip parse+serialize pair, so
+ * main-process callers (the admin update-prd route, PRD 1024) get the same
+ * "unrecognized keys round-trip verbatim via `extras`, recognized keys emit
+ * in a stable order, unchanged values re-emit their original line verbatim"
+ * guarantee the renderer's PRD editor already relies on — an edit through
+ * either surface never reorders or drops a key it didn't touch. Recognized
+ * key set intentionally mirrors the TS module exactly (title, cwd,
+ * estimateMinutes, parallelGroup, sourcePromptId, sourceTabId, tag,
+ * createdVia, issuedAt); every other frontmatter key (e.g. dependsOn)
+ * round-trips via `extras`, same as the renderer's editor today.
+ *
+ * `createdVia`/`issuedAt` (PRD provenance-lockdown) are recognized here so
+ * the update-prd route (the only sanctioned way to stamp a PRD's provenance
+ * after creation — see prdCreate.cjs's buildPrdBody for the create-time
+ * stamp) round-trips them like any other known key rather than shunting them
+ * into `extras`.
+ */
+
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt'];
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+function indentOf(line) {
+  let n = 0;
+  for (const ch of line) {
+    if (ch === ' ') n++;
+    else if (ch === '\t') n += 2;
+    else break;
+  }
+  return n;
+}
+
+function parseScalar(raw) {
+  const v = raw.trim();
+  if (v === '' || v === '~' || v === 'null') return null;
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+$/.test(v)) return Number(v);
+  if (/^-?\d+\.\d+$/.test(v)) return Number(v);
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+function applyKey(fm, key, after) {
+  const v = parseScalar(after);
+  if (v === null) return;
+  switch (key) {
+    case 'estimateMinutes':
+      fm.estimateMinutes = typeof v === 'number' ? v : Number(v);
+      return;
+    case 'parallelGroup':
+      fm.parallelGroup = typeof v === 'number' ? v : Number(v);
+      return;
+    case 'title':
+      fm.title = String(v);
+      return;
+    case 'cwd':
+      fm.cwd = String(v);
+      return;
+    case 'sourcePromptId':
+      fm.sourcePromptId = String(v);
+      return;
+    case 'sourceTabId':
+      fm.sourceTabId = String(v);
+      return;
+    case 'tag':
+      // Matches the TS source's applyKey exactly: a 'discussion'-tagged
+      // ticket never reaches PRD authoring, so that value is never parsed
+      // here even if present in a hand-edited file — see this file's header
+      // comment.
+      if (v === 'feature' || v === 'bug' || v === 'build') fm.tag = v;
+      return;
+    case 'createdVia':
+      fm.createdVia = String(v);
+      return;
+    case 'issuedAt':
+      fm.issuedAt = String(v);
+      return;
+  }
+}
+
+/** Parse a full PRD file into { frontmatter, body }, same shape as the TS module. */
+function parsePrdFile(text) {
+  const m = text.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: text };
+  const fmText = m[1];
+  const body = m[2] ?? '';
+
+  const lines = fmText.split(/\r?\n/);
+  const fm = {};
+  const extras = {};
+
+  for (let i = 0; i < lines.length;) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith('#')) { i++; continue; }
+    const ind = indentOf(line);
+    if (ind !== 0) { i++; continue; }
+    const colon = line.indexOf(':');
+    if (colon < 0) { i++; continue; }
+    const key = line.slice(0, colon).trim();
+    const after = line.slice(colon + 1);
+    let j = i + 1;
+    const band = [line];
+    while (j < lines.length) {
+      const nxt = lines[j];
+      if (nxt.trim() === '' || nxt.trimStart().startsWith('#')) { band.push(nxt); j++; continue; }
+      if (indentOf(nxt) === 0 && nxt.indexOf(':') >= 0) break;
+      band.push(nxt);
+      j++;
+    }
+
+    if (RECOGNIZED_KEYS.has(key)) {
+      applyKey(fm, key, after);
+      const parsed = parseScalar(after);
+      if (parsed !== null && (typeof parsed === 'string' || typeof parsed === 'number')) {
+        if (!fm._raw) fm._raw = {};
+        fm._raw[key] = { line, parsed };
+      }
+    } else {
+      extras[key] = { lines: band };
+    }
+    i = j;
+  }
+
+  if (Object.keys(extras).length) fm.extras = extras;
+  return { frontmatter: fm, body };
+}
+
+function serializeScalar(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  const needsQuote =
+    s === '' ||
+    /^(true|false|null|~)$/.test(s) ||
+    /^-?\d+(\.\d+)?$/.test(s) ||
+    /^\s|\s$/.test(s) ||
+    s.startsWith("'") ||
+    s.startsWith('"') ||
+    s.includes('\n');
+  if (!needsQuote) return s;
+  if (s.includes("'")) return `"${s.replace(/"/g, '\\"')}"`;
+  return `'${s}'`;
+}
+
+/** Serialize { frontmatter, body } back to a full file. Byte-identical round-trip when unchanged. */
+function serializePrdFile(fm, body) {
+  const out = [];
+  for (const key of EMIT_ORDER) {
+    const v = fm[key];
+    if (v === undefined || v === null || v === '') continue;
+    const cached = fm._raw?.[key];
+    if (cached && cached.parsed === v) {
+      out.push(cached.line);
+      continue;
+    }
+    if (typeof v === 'number') {
+      out.push(`${key}: ${v}`);
+      continue;
+    }
+    out.push(`${key}: ${serializeScalar(v)}`);
+  }
+  if (fm.extras) {
+    for (const k of Object.keys(fm.extras)) {
+      const band = fm.extras[k];
+      if (!band || !band.lines.length) continue;
+      out.push(band.lines.join('\n'));
+    }
+  }
+
+  const fmText = out.join('\n');
+  return `---\n${fmText}\n---\n${body}`;
+}
+
+module.exports = { splitFrontmatter, parsePrdFile, serializePrdFile, RECOGNIZED_KEYS };

package/src/main/lib/prdMigration.cjs

@@ -16,8 +16,8 @@
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
-const { splitFrontmatter } = require('./prdFrontmatter.cjs');
-const { resolvePrdWriteDir } = require('./prdLocations.cjs');
+const { splitFrontmatter, parsePrdFile, serializePrdFile } = require('./prdFrontmatter.cjs');
+const { resolvePrdWriteDir, resolvePrdsDirs } = require('./prdLocations.cjs');
 const { projectQueuePath } = require('./queueStore.cjs');
 const { expandHome } = require('./expandHome.cjs');
 
@@ -114,7 +114,21 @@ async function migratePrds(legacyPrdsDir) {
 const LIVE_JOB_STATUSES = new Set(['pending', 'running', 'needs_review', 'investigating']);
 
 /**
- * Slugs with a live job in this project's own queue shard.
+ * Statuses that mean a job is genuinely finished and its source may be
+ * archived. Anything else — including an UNRECOGNIZED/invalid status string
+ * (e.g. the 2026-08-07 1021/1022 incident's `"status": "queued"`, which is
+ * outside ScheduleJobStatus entirely) — protects the file. reconcile() is
+ * what repairs a corrupted row back to `pending` (scheduleJobTransitions.cjs
+ * / the invalid-row-repair path); this consolidation must never race that
+ * repair by archiving the row's only source out from under it first. A slug
+ * with NO row at all (never queued, or already reaped from history) is not
+ * covered by this set and falls through to "archive" in liveSlugsForCwd.
+ */
+const TERMINAL_ARCHIVABLE_STATUSES = new Set(['completed', 'failed']);
+
+/**
+ * Slugs with a live (i.e. not safely archivable) job in this project's own
+ * queue shard.
  *
  * Returns null when liveness cannot be determined (unreadable/unparseable
  * queue.json) — the caller then FAILS CLOSED and archives nothing, since it
@@ -139,7 +153,7 @@ async function liveSlugsForCwd(cwd) {
   const jobs = Array.isArray(parsed?.jobs) ? parsed.jobs : [];
   const live = new Set();
   for (const job of jobs) {
-    if (job && typeof job.slug === 'string' && LIVE_JOB_STATUSES.has(job.status)) {
+    if (job && typeof job.slug === 'string' && !TERMINAL_ARCHIVABLE_STATUSES.has(job.status)) {
       live.add(job.slug);
     }
   }
@@ -199,4 +213,67 @@ async function consolidateFlatPrds(cwd, opts = {}) {
   return { moved, failed, skipped };
 }
 
-module.exports = { migratePrds, consolidateFlatPrds, LIVE_JOB_STATUSES };
+/**
+ * legacyAdoptExistingPrds() — one-time (per file), idempotent rollout
+ * migration for the PRD-authoring-lockdown feature: every PRD source .md
+ * already on disk when this ships has no `createdVia` frontmatter (that
+ * field didn't exist yet), and reconcile()'s new provenance gate would
+ * otherwise quarantine every single one of them the very first boot after
+ * this lands. Runs at every boot (see scheduler.cjs's runPrdMigration,
+ * BEFORE reconcile() ever gets a chance to see these files) and stamps
+ * `createdVia: legacy-adopted` + `issuedAt: <this run's timestamp>` on any
+ * `.md` under a project's PRD dirs (flat + every Epic's, live only — never
+ * the retired prds-archived/ dirs, since an archived PRD isn't reconciled
+ * again and stamping it would just be needless churn) that doesn't already
+ * carry a `createdVia` value.
+ *
+ * Idempotent by construction: a file already stamped (by this migration on
+ * a prior boot, or by prdCreate.cjs at create time) is skipped outright, so
+ * a repeat run across every subsequent boot is a cheap scan-and-skip.
+ * Failures are per-file and non-fatal — one unreadable/unwritable PRD must
+ * never abort the sweep for every other project.
+ */
+async function legacyAdoptExistingPrds() {
+  let dirs;
+  try {
+    dirs = resolvePrdsDirs();
+  } catch (e) {
+    return { stamped: 0, failed: [{ file: '(resolvePrdsDirs)', reason: e?.message ?? 'failed to enumerate PRD dirs' }] };
+  }
+
+  let stamped = 0;
+  const failed = [];
+  const issuedAt = new Date().toISOString();
+
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = await fsp.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      if (!name.endsWith('.md') || name.startsWith('.')) continue;
+      const filePath = path.join(dir, name);
+      try {
+        const raw = await fsp.readFile(filePath, 'utf8');
+        const { frontmatter: fm, body } = parsePrdFile(raw);
+        if (fm.createdVia) continue; // already stamped — nothing to do
+        fm.createdVia = 'legacy-adopted';
+        fm.issuedAt = issuedAt;
+        const newRaw = serializePrdFile(fm, body);
+        const tmp = `${filePath}.tmp-${process.pid}`;
+        await fsp.writeFile(tmp, newRaw, 'utf8');
+        await fsp.rename(tmp, filePath);
+        stamped += 1;
+      } catch (e) {
+        if (e?.code === 'ENOENT') continue; // raced with a concurrent mover/archiver
+        failed.push({ file: filePath, reason: e?.message ?? 'stamp failed' });
+      }
+    }
+  }
+
+  return { stamped, failed };
+}
+
+module.exports = { migratePrds, consolidateFlatPrds, legacyAdoptExistingPrds, LIVE_JOB_STATUSES };

package/src/main/lib/queueStore.cjs

@@ -34,6 +34,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { allProjectCwds, activeProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
+const { ScheduleJobSchema } = require('./scheduleJobSchema.cjs');
 
 const MACHINE_STATE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-machine.json');
 const LEGACY_QUEUE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'queue.json');
@@ -110,9 +111,37 @@ function shapeMachine(raw) {
   };
 }
 
-function shapeJobs(raw) {
+/**
+ * shapeJobs(raw, file) → { jobs, invalid }.
+ *
+ * Every row is validated against ScheduleJobSchema (see that module's header
+ * for why: a row with e.g. `status: 'queued'` — a value outside
+ * `ScheduleJobStatus` — silently vanished from every picker, which is the
+ * exact 2026-08-07 incident this validation exists to catch). A row that
+ * fails is quarantined into `invalid` (never dropped silently, never passed
+ * through as-is) and logged once per slug at error level naming the file,
+ * the slug, and the failing field. One bad row must not affect the others —
+ * this never throws.
+ */
+function shapeJobs(raw, file) {
   const data = JSON.parse(raw);
-  return Array.isArray(data.jobs) ? data.jobs : [];
+  const rows = Array.isArray(data.jobs) ? data.jobs : [];
+  const jobs = [];
+  const invalid = [];
+  for (const row of rows) {
+    const result = ScheduleJobSchema.safeParse(row);
+    if (result.success) {
+      jobs.push(result.data);
+      continue;
+    }
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ');
+    const slug = typeof row?.slug === 'string' ? row.slug : '(unknown slug)';
+    console.error(`[queueStore] quarantined invalid job row (file=${file || '(unknown)'}, slug=${slug}): ${issues}`);
+    invalid.push({ slug, file: file || null, issues, row });
+  }
+  return { jobs, invalid };
 }
 
 /**
@@ -125,7 +154,7 @@ function shapeJobs(raw) {
  * consulted so writeSplit can persist "this project now has zero jobs".
  */
 function readMergedSync(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, invalidJobs: [] };
   const sourceCwds = [];
   try {
     Object.assign(out, shapeMachine(fs.readFileSync(MACHINE_STATE_PATH, 'utf8')));
@@ -138,7 +167,9 @@ function readMergedSync(opts) {
   for (const cwd of stateCwds(opts)) {
     const file = projectQueuePath(cwd);
     try {
-      out.jobs.push(...shapeJobs(fs.readFileSync(file, 'utf8')));
+      const { jobs, invalid } = shapeJobs(fs.readFileSync(file, 'utf8'), file);
+      out.jobs.push(...jobs);
+      out.invalidJobs.push(...invalid);
       sourceCwds.push(cwd);
     } catch (e) {
       if (e?.code === 'ENOENT') { sourceCwds.push(cwd); continue; }
@@ -152,7 +183,7 @@ function readMergedSync(opts) {
 
 /** Async twin of readMergedSync for IPC hot paths. */
 async function readMerged(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, invalidJobs: [] };
   const sourceCwds = [];
   try {
     Object.assign(out, shapeMachine(await fsp.readFile(MACHINE_STATE_PATH, 'utf8')));
@@ -165,7 +196,9 @@ async function readMerged(opts) {
   for (const cwd of stateCwds(opts)) {
     const file = projectQueuePath(cwd);
     try {
-      out.jobs.push(...shapeJobs(await fsp.readFile(file, 'utf8')));
+      const { jobs, invalid } = shapeJobs(await fsp.readFile(file, 'utf8'), file);
+      out.jobs.push(...jobs);
+      out.invalidJobs.push(...invalid);
       sourceCwds.push(cwd);
     } catch (e) {
       if (e?.code === 'ENOENT') { sourceCwds.push(cwd); continue; }
@@ -267,7 +300,7 @@ async function migrateLegacyGlobalQueue(defaultCwd) {
   for (const [cwd, jobs] of byCwd) {
     const file = projectQueuePath(cwd);
     let existing = [];
-    try { existing = shapeJobs(await fsp.readFile(file, 'utf8')); } catch { /* fresh shard */ }
+    try { existing = shapeJobs(await fsp.readFile(file, 'utf8'), file).jobs; } catch { /* fresh shard */ }
     const have = new Set(existing.map((j) => j.slug));
     const merged = [...existing, ...jobs.filter((j) => !have.has(j.slug))];
     try {
@@ -293,6 +326,7 @@ module.exports = {
   projectHistoryPath,
   stateCwds,
   bustCwdCache,
+  shapeJobs,
   readMerged,
   readMergedSync,
   writeSplit,