claude-code-session-manager 0.64.0 → 0.66.0

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(),
   };
 }