claude-code-session-manager 0.65.0 → 0.67.0

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,

package/src/main/lib/scheduleJobSchema.cjs

@@ -0,0 +1,114 @@
+/**
+ * Canonical runtime schema for a ScheduleJob record, mirroring the TS
+ * `ScheduleJob` interface at src/preload/api.d.ts:375-422 field-for-field.
+ *
+ * Modelled directly on promptSessionSchema.cjs's "zod schema asserted at the
+ * main-process boundary" pattern: the Epic entity has had this guarantee
+ * since epicMint.cjs:243, but the Job entity had none — `shapeJobs` in
+ * queueStore.cjs was `JSON.parse` + `Array.isArray` with zero field checks,
+ * which is how two PRDs sat invisible for 4+ hours on 2026-08-07 with
+ * `"status": "queued"`, a value outside `ScheduleJobStatus`, silently
+ * skipped by every picker that filters on `status === 'pending'` exactly.
+ *
+ * `JOB_STATUSES` is the single source of truth for the status enum. The
+ * renderer can't import this .cjs file directly, so
+ * src/preload/api.d.ts's `ScheduleJobStatus` union and the renderer's
+ * `JobStatus`/`FilterStatus` mirrors are kept in sync against this array by
+ * src/main/__tests__/scheduleJobSchema.test.cjs.
+ *
+ * Plain CJS, no Electron dependency, so it's requirable from queueStore.cjs
+ * (which itself must load outside the Electron app, e.g. from watchdog
+ * scripts).
+ */
+'use strict';
+
+const { z } = require('zod');
+
+const JOB_STATUSES = ['pending', 'running', 'investigating', 'completed', 'failed', 'needs_review', 'quarantined'];
+
+const ScheduleJobStatusSchema = z.enum(JOB_STATUSES);
+
+const ScheduleJobRuntimeSchema = z
+  .object({
+    pid: z.number().optional(),
+    runId: z.string().optional(),
+    startedAt: z.string().nullable().optional(),
+    sessionId: z.string().optional(),
+    cwd: z.string().optional(),
+  })
+  .passthrough();
+
+// One entry per accepted status transition (scheduleJobTransitions.cjs).
+// Bounded to STATUS_HISTORY_CAP entries there; this schema just validates
+// shape, not length, since the cap is enforced at write time.
+const ScheduleJobStatusHistoryEntrySchema = z
+  .object({
+    from: z.string().nullable(),
+    to: z.string(),
+    reason: z.string().nullable(),
+    source: z.string().nullable(),
+    at: z.string(),
+  })
+  .passthrough();
+
+// Only `slug` and `status` are required. Every other ScheduleJob field
+// (src/preload/api.d.ts:375-422) is declared here for documentation and type
+// checking when present, but kept optional: a job row moves through several
+// legitimate partial shapes across its life (freshly minted with nulls,
+// mid-run with runtime fields, terminal with exitCode/error) and plenty of
+// call sites — including this repo's own test fixtures — construct a row
+// with only the fields relevant to what they're exercising. The 2026-08-07
+// incident this schema exists to catch was an invalid `status` value, not a
+// missing optional field, so `status` is where the strictness belongs.
+// Unknown extra fields are preserved (.passthrough()) rather than stripped —
+// this schema's job is to gate on shape/status validity, not to be the sole
+// place new ScheduleJob fields get declared before they're usable.
+const ScheduleJobSchema = z
+  .object({
+    slug: z.string(),
+    title: z.string().optional(),
+    cwd: z.string().nullable().optional(),
+    parallelGroup: z.number().optional(),
+    estimateMinutes: z.number().nullable().optional(),
+    bodyPreview: z.string().optional(),
+    status: ScheduleJobStatusSchema,
+    runId: z.string().nullable().optional(),
+    startedAt: z.string().nullable().optional(),
+    finishedAt: z.string().nullable().optional(),
+    exitCode: z.number().nullable().optional(),
+    error: z.string().nullable().optional(),
+    sessionId: z.string().optional(),
+    runtime: ScheduleJobRuntimeSchema.optional(),
+    verifierVerdict: z.string().optional(),
+    dependsOn: z.array(z.string()).optional(),
+    originSessionId: z.string().nullable().optional(),
+    sourceTabId: z.string().nullable().optional(),
+    sourcePromptId: z.string().nullable().optional(),
+    epicId: z.string().nullable().optional(),
+    statusHistory: z.array(ScheduleJobStatusHistoryEntrySchema).optional(),
+  })
+  .passthrough();
+
+/**
+ * Throws a clear, descriptive error (not a raw ZodError dump) when `job`
+ * doesn't match ScheduleJobSchema. Mirrors assertValidPromptSession's shape.
+ */
+function assertValidScheduleJob(job) {
+  const result = ScheduleJobSchema.safeParse(job);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ');
+    throw new Error(`assertValidScheduleJob: invalid ScheduleJob shape — ${issues}`);
+  }
+  return result.data;
+}
+
+module.exports = {
+  ScheduleJobSchema,
+  ScheduleJobRuntimeSchema,
+  ScheduleJobStatusSchema,
+  ScheduleJobStatusHistoryEntrySchema,
+  JOB_STATUSES,
+  assertValidScheduleJob,
+};