claude-code-session-manager 0.76.0 → 0.77.0

package/src/main/lib/projectPageSummarySchema.cjs

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * projectPageSummarySchema.cjs — hand-authored JSON Schema description of
+ * `ProjectPageSummary` (src/renderer/lib/projectPages/summaryType.ts), for
+ * the /admin/project-home/contract route (PRD: project-home-admin-routes).
+ *
+ * This schema is DESCRIPTIVE, not the enforcement mechanism — the actual
+ * gate a posted summary must pass is `validateProjectPageSummary` (shipped
+ * in scripts/project-pages-logic/dist/logic.cjs, called by
+ * /admin/project-home/validate-summary and /admin/project-home/render).
+ * Kept hand-written rather than derived at runtime so the contract route
+ * never needs to load the TypeScript source; if summaryType.ts's shape
+ * changes, update this alongside it (same discipline as any other
+ * TS-type-mirrored constant in this codebase).
+ */
+
+const PROJECT_PAGE_SUMMARY_JSON_SCHEMA = Object.freeze({
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  title: 'ProjectPageSummary',
+  type: 'object',
+  required: ['identity', 'stats', 'pillars', 'feature', 'architecture', 'quotes'],
+  properties: {
+    identity: {
+      type: 'object',
+      required: ['name', 'tag', 'version', 'oneLine', 'claim', 'sub', 'audience', 'install'],
+      properties: {
+        name: { type: 'string' },
+        tag: { type: 'string' },
+        version: { type: 'string' },
+        oneLine: { type: 'string' },
+        claim: { type: 'string' },
+        sub: { type: 'string' },
+        audience: { type: 'string' },
+        install: { type: 'string' },
+      },
+      description: 'Every string field must be non-empty and must not be the literal "TODO".',
+    },
+    stats: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['v', 'k', 'n'],
+        properties: { v: { type: 'string' }, k: { type: 'string' }, n: { type: 'string' } },
+      },
+    },
+    pillars: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['t', 'd', 'k'],
+        properties: { t: { type: 'string' }, d: { type: 'string' }, k: { type: 'string' } },
+      },
+    },
+    quotes: {
+      type: 'array',
+      description: 'Never fabricate testimonials — omit entirely rather than invent a quote.',
+      items: {
+        type: 'object',
+        required: ['q', 'a', 'r'],
+        properties: { q: { type: 'string' }, a: { type: 'string' }, r: { type: 'string' } },
+      },
+    },
+    feature: {
+      type: 'object',
+      required: ['name', 'kicker', 'status', 'owner', 'oneLine', 'problem', 'solution', 'steps', 'rules', 'specs', 'faq', 'timeline'],
+      properties: {
+        name: { type: 'string' },
+        kicker: { type: 'string' },
+        status: { type: 'string' },
+        owner: { type: 'string' },
+        oneLine: { type: 'string' },
+        problem: { type: 'string' },
+        solution: { type: 'string' },
+        steps: { type: 'array', items: { type: 'object', required: ['t', 'd'], properties: { t: { type: 'string' }, d: { type: 'string' } } } },
+        rules: { type: 'array', items: { type: 'object', required: ['t', 'd'], properties: { t: { type: 'string' }, d: { type: 'string' } } } },
+        specs: { type: 'array', items: { type: 'array', description: '[label, value, note]', items: { type: 'string' }, minItems: 3, maxItems: 3 } },
+        faq: { type: 'array', items: { type: 'object', required: ['q', 'a'], properties: { q: { type: 'string' }, a: { type: 'string' } } } },
+        timeline: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['w', 't', 's'],
+            properties: { w: { type: 'string' }, t: { type: 'string' }, s: { type: 'string', enum: ['done', 'next', 'idea'] } },
+          },
+        },
+      },
+    },
+    architecture: {
+      type: 'object',
+      required: ['summary', 'principles', 'layers', 'modules', 'flow', 'decisions', 'risks'],
+      properties: {
+        summary: { type: 'string' },
+        principles: { type: 'array', items: { type: 'object', required: ['t', 'd'], properties: { t: { type: 'string' }, d: { type: 'string' } } } },
+        layers: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['n', 'd', 'f', 'tone'],
+            properties: { n: { type: 'string' }, d: { type: 'string' }, f: { type: 'string' }, tone: { type: 'string', enum: ['accent', 'butter', 'sage', 'mute'] } },
+          },
+        },
+        modules: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['n', 'd', 'f', 'dep', 'heat'],
+            properties: { n: { type: 'string' }, d: { type: 'string' }, f: { type: 'number' }, dep: { type: 'array', items: { type: 'string' } }, heat: { type: 'number' } },
+          },
+        },
+        flow: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['a', 'b', 't', 'n'],
+            properties: { a: { type: 'string' }, b: { type: 'string' }, t: { type: 'string' }, n: { type: 'string' } },
+          },
+        },
+        decisions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['id', 't', 'w', 's'],
+            properties: { id: { type: 'string' }, t: { type: 'string' }, w: { type: 'string' }, s: { type: 'string', enum: ['accepted', 'proposed', 'superseded'] } },
+          },
+        },
+        risks: {
+          type: 'array',
+          description: 'No clean source in the Brief — leave empty rather than invent.',
+          items: {
+            type: 'object',
+            required: ['t', 'd', 's'],
+            properties: { t: { type: 'string' }, d: { type: 'string' }, s: { type: 'string', enum: ['open', 'watching', 'mitigated'] } },
+          },
+        },
+      },
+    },
+    brief: {
+      type: 'object',
+      description: 'OPTIONAL — omit entirely when this project has no generated brief.json yet.',
+      required: ['purpose', 'what', 'areas', 'scope', 'conventions'],
+      properties: {
+        purpose: { type: 'string' },
+        what: { type: 'array', items: { type: 'string' } },
+        areas: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['name', 'files', 'note', 'epic', 'heat'],
+            properties: { name: { type: 'string' }, files: { type: 'number' }, note: { type: 'string' }, epic: { type: ['string', 'null'] }, heat: { type: 'number' } },
+          },
+        },
+        scope: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['when', 'kind', 'text', 'src'],
+            properties: { when: { type: 'string' }, kind: { type: 'string', enum: ['added', 'narrowed', 'decided'] }, text: { type: 'string' }, src: { type: 'string' } },
+          },
+        },
+        conventions: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  },
+});
+
+// ProjectPagePicks — Record<lensId, Record<slotId, variantId>>. Matched
+// against each lens's own catalog.slots[].variants[].id at render time by
+// the renderer bundle itself, so this schema only bounds the wire shape.
+const PROJECT_PAGE_PICKS_JSON_SCHEMA = Object.freeze({
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  title: 'ProjectPagePicks',
+  type: 'object',
+  additionalProperties: {
+    type: 'object',
+    additionalProperties: { type: 'string' },
+  },
+  description: 'lensId -> slotId -> variantId. Every lensId/slotId/variantId must match one from the catalog.',
+});
+
+module.exports = { PROJECT_PAGE_SUMMARY_JSON_SCHEMA, PROJECT_PAGE_PICKS_JSON_SCHEMA };

package/src/main/lib/queueHealth.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * queueHealth.cjs — pure per-project rollup for the periodic queue-health
+ * sweep (PRD 1109). Kept separate from scheduler.cjs so it can be unit
+ * tested without importing electron/ipcMain, matching reaperHelpers.cjs.
+ */
+
+// Non-terminal statuses that mean a row is parked waiting on a human rather
+// than actively progressing (pending/running are expected to move on their
+// own; investigating is mid-flight and already tracked by
+// findStrandedInvestigations).
+const STUCK_STATUSES = new Set(['needs_review', 'quarantined']);
+
+/**
+ * computeQueueHealth(jobs) → [{ cwd, neverRan, looksDone, stuck }]
+ *
+ * Read-only: never mutates a row. Counts, per project cwd, how many rows
+ * carry `gateOutcome === 'never_ran'`, how many carry a `looksDone`
+ * annotation, and how many sit in a stuck (parked, non-terminal) status.
+ * Only projects with a non-zero total are returned — the sweep logs one
+ * line per non-zero project, nothing for a clean queue.
+ */
+function computeQueueHealth(jobs) {
+  const byCwd = new Map();
+  for (const j of Array.isArray(jobs) ? jobs : []) {
+    if (!j) continue;
+    const cwd = j.cwd || '(unknown)';
+    if (!byCwd.has(cwd)) byCwd.set(cwd, { cwd, neverRan: 0, looksDone: 0, stuck: 0 });
+    const bucket = byCwd.get(cwd);
+    if (j.gateOutcome === 'never_ran') bucket.neverRan += 1;
+    if (j.looksDone) bucket.looksDone += 1;
+    if (STUCK_STATUSES.has(j.status)) bucket.stuck += 1;
+  }
+  return [...byCwd.values()].filter((b) => b.neverRan + b.looksDone + b.stuck > 0);
+}
+
+module.exports = { computeQueueHealth, STUCK_STATUSES };

package/src/main/lib/queueStore.cjs

@@ -183,6 +183,11 @@ function shapeMachine(raw) {
     scheduledFor: data.scheduledFor ?? null,
     lastRunAt: data.lastRunAt ?? null,
     paused: data.paused ?? null,
+    // Launch circuit breaker (lib/launchFailure.cjs): per-persona blocks and
+    // the degraded-mode env a persona is currently launching with. Machine
+    // state, not per-project: the broken thing is the installed CLI.
+    launchBlocks: data.launchBlocks && typeof data.launchBlocks === 'object' ? data.launchBlocks : {},
+    launchMitigations: data.launchMitigations && typeof data.launchMitigations === 'object' ? data.launchMitigations : {},
   };
 }
 
@@ -229,7 +234,7 @@ function shapeJobs(raw, file) {
  * consulted so writeSplit can persist "this project now has zero jobs".
  */
 function readMergedSync(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
   const sourceCwds = [];
   try {
     Object.assign(out, shapeMachine(fs.readFileSync(MACHINE_STATE_PATH, 'utf8')));
@@ -259,7 +264,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, invalidJobs: [] };
+  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, paused: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [] };
   const sourceCwds = [];
   try {
     Object.assign(out, shapeMachine(await fsp.readFile(MACHINE_STATE_PATH, 'utf8')));
@@ -309,6 +314,8 @@ async function writeSplit(state, defaultCwd) {
     scheduledFor: state.scheduledFor ?? null,
     lastRunAt: state.lastRunAt ?? null,
     paused: state.paused ?? null,
+    launchBlocks: state.launchBlocks ?? {},
+    launchMitigations: state.launchMitigations ?? {},
   });
 
   const byCwd = new Map();

package/src/main/lib/quietMachineLease.cjs

@@ -0,0 +1,48 @@
+/**
+ * quietMachineLease.cjs — the exclusive, machine-wide dispatch lock a
+ * `quietMachine: true` PRD holds for the duration of its run (PRD 1107).
+ *
+ * Process-local, like sessionSlots.cjs's holder map — reset on restart by
+ * design; a crashed lease must never wedge the queue permanently. This is
+ * NOT a second concurrency pool: sessionSlots.cjs remains the sole slot
+ * pool. This module only answers "is a quiet-machine job currently running,
+ * and if so, hold every other dispatch until it releases?" — schedulerBatch
+ * .cjs's pickNextBatch reads isHeld() to gate the WHOLE tick, not just one
+ * project.
+ */
+'use strict';
+
+// slug of the job currently holding the lease, or null.
+let heldBySlug = null;
+
+function isHeld() {
+  return heldBySlug !== null;
+}
+
+/** acquire(slug) → true if the lease was free and is now held by `slug`. */
+function acquire(slug) {
+  if (heldBySlug !== null) return false;
+  heldBySlug = String(slug);
+  return true;
+}
+
+/** release(slug) — idempotent; releasing when not held, or held by a
+ * different slug, is a no-op (mirrors sessionSlots.release's tolerance for
+ * an already-released token). */
+function release(slug) {
+  if (heldBySlug === null) return false;
+  if (heldBySlug !== String(slug)) return false;
+  heldBySlug = null;
+  return true;
+}
+
+function holder() {
+  return heldBySlug;
+}
+
+/** Test hook: force the lease back to free. */
+function __resetForTests() {
+  heldBySlug = null;
+}
+
+module.exports = { isHeld, acquire, release, holder, __resetForTests };

package/src/main/lib/rcaReport.cjs

@@ -47,6 +47,7 @@ const VERDICT_LABELS = {
   verify_unavailable: 'verify unavailable',
   uncommitted_changes: 'uncommitted changes',
   no_verdict_sentinel: 'no commit or verdict sentinel',
+  abandoned_background_task: 'abandoned auto-backgrounded task',
   pass_no_commit: 'PASS sentinel but no commit landed',
   pass_no_commit_already_shipped: 'PASS with no commit — deliverables already shipped',
   pass_no_commit_prior_run_verified: 'PASS with no commit — prior run of this slug already landed the work',
@@ -67,9 +68,42 @@ const FAILURE_CLASSES = {
   NO_SENTINEL: 'no-sentinel',
   UNCOMMITTED: 'uncommitted-changes',
   TRANSCRIPT_ERRORS: 'transcript-errors',
+  ABANDONED_BACKGROUND_TASK: 'abandoned-background-task',
   UNKNOWN: 'unknown',
 };
 
+// ─── Recovery actions — one per failure class, machine-readable ────────────
+// Closed set the scheduler routes on: 'archive' (stale re-run, do not
+// re-queue), 'resume-and-commit' (PRD 1111's --resume dispatch owns this),
+// 'verify-and-close' (the work likely landed, just missing its sentinel),
+// 'investigate' (the only class that still buys a fix-plan investigation).
+const RECOVERY_ACTIONS = {
+  [FAILURE_CLASSES.ALREADY_SHIPPED]: 'archive',
+  [FAILURE_CLASSES.SELF_QUEUE]: 'investigate',
+  [FAILURE_CLASSES.STUCK_LOOP]: 'investigate',
+  [FAILURE_CLASSES.POST_AC_OVERRUN]: 'investigate',
+  [FAILURE_CLASSES.NO_SENTINEL]: 'verify-and-close',
+  [FAILURE_CLASSES.UNCOMMITTED]: 'resume-and-commit',
+  [FAILURE_CLASSES.TRANSCRIPT_ERRORS]: 'investigate',
+  // NOT 'resume-and-commit': that action is only ever actually dispatched by
+  // selectResumeRecoveryTarget in scheduler.cjs, which gates strictly on
+  // verifierVerdict === 'uncommitted_changes' plus a sessionId + recorded
+  // uncommittedPaths — none of which an abandoned_background_task job has.
+  // Labeling it 'resume-and-commit' here would be pure telemetry fiction (the
+  // RCA report / job.rcaRecoveryAction would claim a resume attempt that
+  // never happens); 'investigate' is what actually runs (spawnInvestigation),
+  // and buildInvestigationPrompt's abandoned-background-task note is what
+  // carries the "check for salvaged work, commit before re-implementing"
+  // guidance into that cold-read investigation.
+  [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]: 'investigate',
+  [FAILURE_CLASSES.UNKNOWN]: 'investigate',
+};
+
+/** Pure — returns the closed-set recovery action for a failure class, defaulting to 'investigate'. */
+function recoveryActionFor(failureClass) {
+  return RECOVERY_ACTIONS[failureClass] ?? 'investigate';
+}
+
 const PREVENTION_HINTS = {
   [FAILURE_CLASSES.ALREADY_SHIPPED]:
     "This run found its acceptance criteria already satisfied by a prior commit and correctly made no change, so no commit landed and the verifier returned `pass_no_commit`. This is a stale re-run, not an execution failure — the PRD's `.md` was never moved out of `session-manager-operations/scheduler/prds/` after the work shipped. Archive the PRD into `session-manager-operations/scheduler/prds-archived/` instead of re-queuing or re-running it.",
@@ -85,6 +119,8 @@ const PREVENTION_HINTS = {
     'Stage the exact paths you created or modified — never a blanket/wildcard git-add of the whole tree, since the queue can run sibling jobs against this same working tree and a blanket add sweeps up their in-flight edits — and `git commit` as the final finish-protocol step before printing the verdict sentinel; never end a run with a dirty working tree.',
   [FAILURE_CLASSES.TRANSCRIPT_ERRORS]:
     'Recover or annotate every error within ~10 lines (e.g. `# expected/handled: <why>`) instead of leaving a bare Traceback near the end of the transcript.',
+  [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]:
+    'A headless run cannot receive a background-task completion notification — never let a long Bash command auto-background past its foreground timeout and then wait for it. Run long commands with an explicit bound (`timeout <N> <cmd>`) so they finish in the foreground, or poll their output file directly instead of waiting on Monitor/notification.',
   [FAILURE_CLASSES.UNKNOWN]:
     'Re-run the acceptance criteria gate locally against the failure log to pin down the specific break before re-queuing.',
 };
@@ -139,6 +175,16 @@ function classifyFailure({ verdict, logTail }) {
     return FAILURE_CLASSES.ALREADY_SHIPPED;
   }
 
+  // Checked before SELF_QUEUE/STUCK_LOOP: the verifier already did the real
+  // detection work (scanning for the harness's own auto-background marker
+  // text) to produce this verdict — trust it rather than re-deriving from the
+  // log tail, which can otherwise false-match SELF_QUEUE_WAKEUP_RE/STUCK_LOOP_RE
+  // on words like "sleep"/"background" that appear in the harness's own
+  // auto-background tool_result.
+  if (verdict === 'abandoned_background_task') {
+    return FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK;
+  }
+
   // Checked before STUCK_LOOP: a backgrounded command + ScheduleWakeup
   // (variant b) can land words like "sleep"/"poll" in the tail via the PRD's
   // own AC text, which would otherwise false-match STUCK_LOOP_RE (see PRD 771).
@@ -226,7 +272,8 @@ function readPrdBody(cwd, slug) {
  */
 function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, investigationText }) {
   const title = `Root cause: ${job.slug} → needs_review (${humanVerdict(verdict)})`;
-  const fm = ['---', `title: ${title}`, 'source: scheduler-rca', 'type: rca', 'severity: normal', `prdSlug: ${job.slug}`, `runId: ${job.runId}`, `verdict: ${verdict}`, '---'].join('\n');
+  const recoveryAction = recoveryActionFor(failureClass);
+  const fm = ['---', `title: ${title}`, 'source: scheduler-rca', 'type: rca', 'severity: normal', `prdSlug: ${job.slug}`, `runId: ${job.runId}`, `verdict: ${verdict}`, `failure-class: ${failureClass}`, `recovery-action: ${recoveryAction}`, '---'].join('\n');
 
   const last60 = lastNLines(logTail, 60);
   const exitCode = meta?.exitCode ?? job.exitCode ?? 'unknown';
@@ -315,8 +362,9 @@ async function writeRcaReport({ job, runDir, verdict, annotations, investigation
     fs.renameSync(tmp, reportPath);
 
     const summary = rcaSummaryLine(job, verdict);
-    console.log(`[rca] wrote ${reportPath} (${failureClass})`);
-    return { filed: true, path: reportPath, summary, failureClass };
+    const recoveryAction = recoveryActionFor(failureClass);
+    console.log(`[rca] wrote ${reportPath} (${failureClass} → ${recoveryAction})`);
+    return { filed: true, path: reportPath, summary, failureClass, recoveryAction };
   } catch (e) {
     console.error('[rca] error writing RCA report', e?.message ?? String(e));
     return { filed: false, reason: 'error', error: e?.message ?? String(e) };
@@ -334,4 +382,6 @@ module.exports = {
   buildRcaMarkdown,
   FAILURE_CLASSES,
   VERDICT_LABELS,
+  RECOVERY_ACTIONS,
+  recoveryActionFor,
 };

package/src/main/lib/reaperHelpers.cjs

@@ -64,6 +64,23 @@ function classifyRunOutcome(logPath) {
   }
 }
 
+/**
+ * Map classifyRunOutcome()'s four-way result onto the smaller, persisted
+ * `gateOutcome` a job row carries. 'no_result' really means the verdict gate
+ * never fired — the process died or was killed before it could emit one —
+ * a different fact from 'failed' (a verdict event exists and says error,
+ * i.e. the gate ran and went red). Collapsing both behind the same free-text
+ * `error` string is exactly the ambiguity this field exists to remove.
+ */
+function mapOutcomeToGateOutcome(outcome) {
+  switch (outcome) {
+    case 'success': return 'passed';
+    case 'failed': return 'failed';
+    case 'no_result': return 'never_ran';
+    default: return 'unknown';
+  }
+}
+
 // Max times an orphaned job may be re-queued before giving up (marking failed).
 // Single source of truth: both the in-app reaper (scheduler.cjs) and the external
 // offline watchdog (watchdogHelpers.cjs) import this so their give-up budgets can
@@ -116,4 +133,4 @@ function selectReapableJobs(jobs, now, { pidAlive, grace } = {}) {
   return { reapable, warnings };
 }
 
-module.exports = { claudePidAlive, classifyRunOutcome, ORPHAN_REQUEUE_CAP, selectReapableJobs };
+module.exports = { claudePidAlive, classifyRunOutcome, mapOutcomeToGateOutcome, ORPHAN_REQUEUE_CAP, selectReapableJobs };

package/src/main/lib/scheduleJobSchema.cjs

@@ -77,6 +77,11 @@ const ScheduleJobSchema = z
     finishedAt: z.string().nullable().optional(),
     exitCode: z.number().nullable().optional(),
     error: z.string().nullable().optional(),
+    // Structured terminal-outcome label set alongside the free-text `error`
+    // (never replacing it) so a queue reader can tell "the gate ran and went
+    // red" (failed) apart from "the gate never got to run" (never_ran) —
+    // see reaperHelpers.cjs's mapOutcomeToGateOutcome (PRD 1109).
+    gateOutcome: z.enum(['passed', 'failed', 'never_ran', 'unknown']).optional(),
     sessionId: z.string().optional(),
     runtime: ScheduleJobRuntimeSchema.optional(),
     verifierVerdict: z.string().optional(),
@@ -86,6 +91,32 @@ const ScheduleJobSchema = z
     sourcePromptId: z.string().nullable().optional(),
     epicId: z.string().nullable().optional(),
     statusHistory: z.array(ScheduleJobStatusHistoryEntrySchema).optional(),
+    // Opt-in exclusive-lease PRD flag (PRD 1107) — serializes this job against
+    // every other job machine-wide for its run so a timing-sensitive gate
+    // (frame time, performance fence) measures without CPU contention. See
+    // quietMachineLease.cjs + schedulerBatch.cjs's pickNextBatch.
+    quietMachine: z.boolean().optional(),
+    // Set true when the job was dispatched anyway after waiting past
+    // quietMachineWaitMs without the machine going quiet — tells a reader the
+    // job's measurements ran under contention, not on a quiet machine.
+    quietLeaseDegraded: z.boolean().optional(),
+    // Salvaged uncommitted diff patch path (PRD 1098).
+    salvagePatch: z.string().nullable().optional(),
+    // Leftover-attribution fields: the newly-dirty paths a terminal run left
+    // uncommitted, diffed against the persisted pre-run baseline
+    // (guardBaseline/guardHeadBefore below). Set on EVERY terminal outcome
+    // that left dirt (completed/failed/needs_review alike), not just the
+    // exit=0 commit-guard path — deleted when the run left nothing. Capped
+    // at LEFTOVER_PATHS_CAP paths (leftoverCount carries the true total).
+    leftoverPaths: z.array(z.string()).optional(),
+    leftoverCount: z.number().optional(),
+    leftoverPathsTruncated: z.boolean().optional(),
+    // Pre-run working-tree snapshot, persisted at dispatch so a finalizer
+    // that never reaches spawnJob's own completion path (reapDeadRunningJobs)
+    // can still compute a truthful newly-dirty delta. Cleared once the run
+    // finalizes — never meant to outlive one run.
+    guardBaseline: z.array(z.string()).optional(),
+    guardHeadBefore: z.string().nullable().optional(),
   })
   .passthrough();
 

package/src/main/lib/scheduleJobTransitions.cjs

@@ -55,7 +55,11 @@ const STATUS_HISTORY_CAP = 20;
  *    (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)
+ *    original), failed->needs_review (reverifyNeedsReview's looksDone pass,
+ *    PRD 1102: an unverified-shaped failed row — no sentinel, no result
+ *    event — with a commit landed after its run window that touches its own
+ *    declared paths is surfaced to a human as needs_review, never silently
+ *    auto-completed)
  *  - 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
@@ -80,7 +84,7 @@ const LEGAL_TRANSITIONS = {
   pending: ['running', 'completed', 'failed', 'skipped'],
   running: ['completed', 'failed', 'needs_review', 'skipped', 'pending'],
   investigating: ['failed', 'needs_review', 'completed', 'pending', 'skipped'],
-  failed: ['investigating', 'pending', 'completed'],
+  failed: ['investigating', 'pending', 'completed', 'needs_review'],
   needs_review: ['investigating', 'pending', 'completed', 'skipped'],
   completed: ['pending'],
   skipped: ['pending'],