claude-code-session-manager 0.65.0 → 0.66.0

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,
+};

package/src/main/lib/scheduleJobTransitions.cjs

@@ -0,0 +1,164 @@
+/**
+ * scheduleJobTransitions.cjs — the ONE place a ScheduleJob's `status` field
+ * is assigned, mirroring epicMint.cjs's fail-closed ownership of the Epic's
+ * `proposed -> active` transition.
+ *
+ * Before this module, `j.status = '...'` was a bare mutation at 16 separate
+ * sites in scheduler.cjs — no legality table, no record of who changed a
+ * status or why. That is why the 1021/1022 stall (2026-08-07) was
+ * undiagnosable from the app: the only evidence was a heartbeat count, not a
+ * trace of what the job's status actually did over time.
+ *
+ * `transitionJob(job, toStatus, { reason, source })` is the chokepoint:
+ *  - Looks up `job.status -> toStatus` in LEGAL_TRANSITIONS. An identity
+ *    transition (status unchanged) is always accepted as a no-op — it never
+ *    mutates statusHistory or writes an audit record, since nothing changed.
+ *  - A legal transition mutates `job.status`, appends one bounded
+ *    `statusHistory` entry, and appends one record to the existing
+ *    ~/.claude/session-manager/audit-log.jsonl via auditLog.cjs (the same
+ *    writer epicMint.cjs already uses for `epic_mint`/`epic_mint_refused` —
+ *    deliberately not a second log file).
+ *  - An illegal transition is refused: the job is left untouched, an
+ *    error-level line is logged, a refusal counter increments, and a
+ *    `job_transition_refused` audit record is written. It never throws —
+ *    scheduler.cjs's tickQueue must keep running even if a call site asks
+ *    for an illegal edge (same non-blocking posture as dodDrainHook.cjs).
+ *
+ * Plain Node module (no Electron deps), like scheduleJobSchema.cjs and
+ * epicMint.cjs, so it stays requirable from watchdog scripts outside
+ * Electron.
+ */
+'use strict';
+
+const { appendAuditEvent } = require('./auditLog.cjs');
+
+// Bounded so queue.json (mutation cost, broadcast payload, pickNextBatch
+// scan) stays small — same rationale as lib/queueHistory.cjs's retention
+// window.
+const STATUS_HISTORY_CAP = 20;
+
+/**
+ * Explicit from->to edges. Every real assignment site in scheduler.cjs maps
+ * onto one of these (verified against the 16 sites this module replaces):
+ *  - pending->running (dispatch), pending->completed (archived-PRD skip,
+ *    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)
+ *  - 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
+ *    ever marks investigating on a completed job), investigating->pending
+ *    (admin reset can target a job mid-investigation)
+ *  - failed->investigating (spawn a probe), failed->pending (admin reset /
+ *    transient retry), failed->completed (auto-promote a fix-plan's healed
+ *    original)
+ *  - needs_review->investigating, needs_review->pending, needs_review->completed
+ *    (heal on reverify, or auto-promote) — same shape as `failed`
+ *  - 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)
+ *  - 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)
+ */
+const LEGAL_TRANSITIONS = {
+  pending: ['running', 'completed', 'failed'],
+  running: ['completed', 'failed', 'needs_review', 'pending'],
+  investigating: ['failed', 'needs_review', 'completed', 'pending'],
+  failed: ['investigating', 'pending', 'completed'],
+  needs_review: ['investigating', 'pending', 'completed'],
+  completed: ['pending'],
+  quarantined: ['pending'],
+};
+
+let refusedTransitionCount = 0;
+
+function isLegalTransition(from, to) {
+  if (from === to) return true;
+  const edges = LEGAL_TRANSITIONS[from];
+  return Array.isArray(edges) && edges.includes(to);
+}
+
+/**
+ * transitionJob(job, toStatus, { reason, source }) → boolean
+ *
+ * Mutates `job` in place on success. `reason` and `source` are free-text
+ * (why this transition is happening, and which call site requested it) —
+ * both are required in spirit (every call site in scheduler.cjs passes real
+ * strings) but not enforced here, since a missing reason/source is a lesser
+ * sin than a call this function refuses outright.
+ */
+function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } = {}) {
+  if (!job || typeof job !== 'object') return false;
+  const from = job.status;
+
+  // `allowAnyFrom` is a narrow escape hatch for repairing a row whose
+  // persisted `status` was never a legal value to begin with (e.g. the
+  // 1021/1022 incident's `"status": "queued"`, quarantined by
+  // scheduleJobSchema.cjs and repaired by reconcile()'s invalid-row pass).
+  // That is a data repair, not a lifecycle transition — there is no legal
+  // predecessor to check `from` against — so it still goes through this
+  // chokepoint (mutation, statusHistory, audit) without consulting
+  // LEGAL_TRANSITIONS. Every other caller leaves this false.
+  if (!allowAnyFrom && !isLegalTransition(from, toStatus)) {
+    refusedTransitionCount += 1;
+    console.error(
+      `[scheduleJobTransitions] illegal transition refused: slug=${job.slug ?? '(unknown)'} `
+      + `from=${from ?? '(none)'} to=${toStatus ?? '(none)'} reason=${reason ?? '(none)'} source=${source ?? '(none)'}`,
+    );
+    appendAuditEvent('job_transition_refused', {
+      slug: job.slug ?? null,
+      from: from ?? null,
+      to: toStatus ?? null,
+      reason: reason ?? null,
+      source: source ?? null,
+      cwd: job.cwd ?? null,
+    });
+    return false;
+  }
+
+  if (from === toStatus) return true; // identity — nothing changed, nothing to record
+
+  job.status = toStatus;
+  const entry = {
+    from: from ?? null,
+    to: toStatus,
+    reason: reason ?? null,
+    source: source ?? null,
+    at: new Date().toISOString(),
+  };
+  const history = Array.isArray(job.statusHistory) ? job.statusHistory : [];
+  history.push(entry);
+  while (history.length > STATUS_HISTORY_CAP) history.shift();
+  job.statusHistory = history;
+
+  appendAuditEvent('job_transition', {
+    slug: job.slug ?? null,
+    from: from ?? null,
+    to: toStatus,
+    reason: reason ?? null,
+    source: source ?? null,
+    cwd: job.cwd ?? null,
+  });
+  return true;
+}
+
+function getRefusedTransitionCount() {
+  return refusedTransitionCount;
+}
+
+// Test-only: reset the module-level refusal counter between test cases.
+function _resetRefusedTransitionCountForTests() {
+  refusedTransitionCount = 0;
+}
+
+module.exports = {
+  transitionJob,
+  LEGAL_TRANSITIONS,
+  STATUS_HISTORY_CAP,
+  getRefusedTransitionCount,
+  _resetRefusedTransitionCountForTests,
+};

package/src/main/scheduler/prdParser.cjs

@@ -92,6 +92,13 @@ async function parsePrdRaw(filePath) {
     // queue row is completed (a slug with no row is treated as already
     // done/archived, matching retireCompletedSlugs semantics).
     dependsOn: parseDependsOn(fm.dependsOn),
+    // Provenance stamp (PRD-authoring lockdown): set only by prdCreate.cjs's
+    // buildPrdBody (create) or the update-prd route's legacy-adopt patch
+    // (migration/manual adopt). A PRD discovered on disk with no value here
+    // was never written through the sanctioned API path — reconcile()
+    // quarantines it instead of queuing it to run.
+    createdVia: fm.createdVia || null,
+    issuedAt: fm.issuedAt || null,
     body: body.trim(),
   };
 }