claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/lib/projectRootResolve.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * projectRootResolve.cjs — server-side project/Epic resolution for every
+ * cwd-accepting ops-root entry point (PRD: worktree-cwd Epic-lookup hazard).
+ *
+ * Problem this closes. An agent running inside an Epic's git worktree has
+ * `pwd` = `/tmp/session-manager-epic-worktrees/<hash>/<epicId>` and naturally
+ * passes that as `cwd` to `scheduler_create_prd` / `feedback_open_session`.
+ * `active-index.json` (the Epic registry) is git-tracked, so the worktree's
+ * copy is a snapshot frozen at branch time — it usually does NOT contain the
+ * very Epic the agent is running inside. Verified live 2026-09-01 on
+ * starry-night-ships: main's index had 5 rows including the running Epic; the
+ * worktree's copy had 1 row and did not contain it, so a naive per-cwd lookup
+ * returns null and the write is refused with "create/approve an Epic first" —
+ * reading to the human as "the Epic got lost", when it never did.
+ *
+ * `resolveProjectContext` fixes this at the API boundary, not by trying to
+ * keep every cwd-accepting caller worktree-aware individually:
+ *   1. Normalizes any supplied cwd through `activeSessions.projectRootOf`
+ *      (worktree -> main tree, ops-internal path -> project root).
+ *   2. When an `originClaudeSessionId` (or explicit `epicId`) is known,
+ *      searches for the owning Epic first in the normalized cwd's own
+ *      active-index, then across every project this machine has ever opened
+ *      (`activeSessions.allProjectCwds`) — because the Epic's OWN project may
+ *      not even be the cwd the agent guessed (e.g. a worktree whose gitdir
+ *      pointer is stale/unresolvable, or a cross-project mixup).
+ *   3. A resolved Epic's own project cwd (`epicCwd`) always wins over the
+ *      supplied/hinted cwd when they differ — the Epic is the ground truth.
+ *
+ * Pure, synchronous, fs-only — no Electron deps — so it can be required from
+ * the standalone scheduler-mcp-server.cjs process and from every ops-root
+ * path helper a sibling PRD (ops-root-single-resolver) folds in later.
+ */
+
+const path = require('node:path');
+const { projectRootOf, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
+
+/**
+ * resolveProjectContext({ cwd, originClaudeSessionId, epicId, originProjectRoot }, deps?)
+ *   → { cwd, epicId, epicCwd, source }
+ *
+ * `cwd` — the caller-supplied cwd (may be inside a worktree/ops-internal path,
+ *   or absent entirely when the caller is relying purely on Epic resolution).
+ * `originClaudeSessionId` — the calling session's own claude session id
+ *   (chatRunner.cjs's SM_CHAT_SESSION_ID / pty.cjs's tabId) — matched against
+ *   each Epic's `claudeSessionId`.
+ * `epicId` — an explicit already-known Epic id (e.g. a caller-supplied
+ *   `sourcePromptId`) — matched against each Epic's `id`. Either identifier
+ *   (or both) may be supplied; a match on either counts.
+ * `originProjectRoot` — a trusted hint (e.g. SM_PROJECT_ROOT env, stamped by
+ *   the process that actually knows the real project root) — normalized the
+ *   same way as `cwd` and preferred over it when both are given, but still
+ *   loses to a resolved Epic's own `epicCwd`.
+ *
+ * `source` records which path produced the returned `cwd`/`epicId`:
+ *   'cwd'                — no Epic identifier given, or none resolved; cwd is
+ *                          just the normalized supplied/hinted value.
+ *   'epic-index'          — the Epic was found in the (single) normalized
+ *                          base cwd's own active-index.
+ *   'cross-project-scan'  — the Epic was found only by scanning other known
+ *                          projects (or a duplicate id required tie-breaking).
+ *
+ * Never throws: an unresolvable cwd/hint/Epic id just yields a smaller
+ * result, never an error — refusal is the caller's decision, not this
+ * resolver's.
+ */
+function resolveProjectContext({ cwd, originClaudeSessionId, epicId: wantedEpicId, originProjectRoot } = {}, deps = {}) {
+  const projectRootOfFn = deps.projectRootOf || projectRootOf;
+  const allProjectCwdsFn = deps.allProjectCwds || allProjectCwds;
+  const readActiveIndexFn = deps.readActiveIndex || readActiveIndex;
+  const isEphemeralCwdFn = deps.isEphemeralCwd || isEphemeralCwd;
+  const warn = deps.warn || console.warn;
+
+  let baseCwd = null;
+  if (cwd && typeof cwd === 'string') {
+    baseCwd = projectRootOfFn(path.resolve(cwd));
+  }
+  if (originProjectRoot && typeof originProjectRoot === 'string') {
+    const hintRoot = projectRootOfFn(path.resolve(originProjectRoot));
+    // A trusted hint outranks the agent-supplied cwd, but a resolved Epic
+    // (below) still outranks both.
+    if (hintRoot) baseCwd = hintRoot;
+  }
+
+  const result = { cwd: baseCwd, epicId: null, epicCwd: null, source: 'cwd' };
+
+  if (!originClaudeSessionId && !wantedEpicId) return result;
+
+  const candidates = [];
+  if (baseCwd) candidates.push(baseCwd);
+  for (const p of allProjectCwdsFn()) {
+    if (!candidates.includes(p)) candidates.push(p);
+  }
+
+  const matches = [];
+  for (const projectCwd of candidates) {
+    const { sessions } = readActiveIndexFn(projectCwd);
+    for (const session of Object.values(sessions)) {
+      if (!session) continue;
+      const idHit = wantedEpicId && session.id === wantedEpicId;
+      const claudeHit = originClaudeSessionId && session.claudeSessionId === originClaudeSessionId;
+      if (idHit || claudeHit) {
+        matches.push({ projectCwd, epicId: session.id, status: session.status ?? null });
+        break;
+      }
+    }
+  }
+
+  if (matches.length === 0) return result;
+
+  let chosen = matches[0];
+  if (matches.length > 1) {
+    const score = (m) => (isEphemeralCwdFn(m.projectCwd) ? 0 : 2) + (m.status === 'active' ? 1 : 0);
+    chosen = matches.reduce((best, m) => (score(m) > score(best) ? m : best), matches[0]);
+    warn(
+      `[projectRootResolve] Epic id ${chosen.epicId} matched in multiple projects: `
+      + `${matches.map((m) => m.projectCwd).join(', ')} — choosing ${chosen.projectCwd} `
+      + '(prefers a non-worktree/tmp project with status=active)',
+    );
+  }
+
+  result.epicId = chosen.epicId;
+  result.epicCwd = chosen.projectCwd;
+  result.cwd = chosen.projectCwd;
+  result.source = matches.length > 1
+    ? 'cross-project-scan'
+    : (chosen.projectCwd === baseCwd ? 'epic-index' : 'cross-project-scan');
+  return result;
+}
+
+module.exports = { resolveProjectContext };

package/src/main/lib/promptSessionSchema.cjs

@@ -79,6 +79,13 @@ const PromptSessionSchema = z.object({
   // Passthrough only as of PRD 1032 — nothing populates this yet; the next
   // PRD in this chain wires Epic worktree minting.
   worktree: EpicWorktreeSchema.optional(),
+  // Status-mirror fields (epicStatusMirror.cjs) written onto prompt-sessions/
+  // <id>.json alongside the active-index.json row — never onto the index row
+  // itself, so a plain PromptSession read from active-index.json normally
+  // omits them. Optional here only so activeIndexRebuild.cjs can validate a
+  // mirrored file's reconstructed row against this same schema.
+  archivedAt: z.string().nullable().optional(),
+  indexedAt: z.string().optional(),
 });
 
 /**

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

@@ -33,13 +33,13 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { allProjectCwds, activeProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
-const { assertOpsWrite } = require('./opsOwnership.cjs');
+const { assertOpsWrite, resolveOpsRoot, OPS_ROOT_DIR } = 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');
-const OPS_DIRNAME = 'session-manager-operations';
-const STATE_SUBPATH = [OPS_DIRNAME, 'scheduler', 'state'];
+const OPS_DIRNAME = OPS_ROOT_DIR;
+const STATE_SUBPATH = ['scheduler', 'state'];
 
 /**
  * A project's `session-manager-operations/scheduler/state/` directory.
@@ -75,7 +75,29 @@ function projectStateDir(cwd) {
       `projectStateDir: cwd must be a project root, not a path inside ${OPS_DIRNAME}/, got "${cwd}"`,
     );
   }
-  return path.join(cwd, ...STATE_SUBPATH);
+  // ...and it must not be an EPHEMERAL cwd (inside os.tmpdir(), or a linked
+  // git worktree root) — a worktree is torn down when its Epic/job ends, so
+  // any state written there is silently destroyed (verified live 2026-09-01
+  // as a scheduler shard rewritten every reconcile pass inside a since-deleted
+  // epic worktree). That check, and the worktree → main-tree normalization,
+  // live in opsOwnership.resolveOpsRoot (PRD 1082) — the one resolver every
+  // ops-root reader/writer goes through. `opsInternal: 'refuse'` keeps this
+  // WRITER fail-closed on an ops-internal cwd (the guard above shapes the
+  // message; the resolver is the backstop).
+  let opsRoot;
+  try {
+    opsRoot = resolveOpsRoot(cwd, { opsInternal: 'refuse' });
+  } catch (e) {
+    if (e?.ephemeral) {
+      const err = new Error(
+        `projectStateDir: refusing ephemeral cwd (tmpdir or linked git worktree), got "${cwd}"`,
+      );
+      err.ephemeral = true;
+      throw err;
+    }
+    throw e;
+  }
+  return path.join(opsRoot, ...STATE_SUBPATH);
 }
 
 function projectQueuePath(cwd) {
@@ -97,7 +119,11 @@ function queuePathOrSkip(cwd, context) {
   try {
     return projectQueuePath(cwd);
   } catch (e) {
-    console.error(`[queueStore] ${context}: skipping invalid project cwd — ${e?.message}`);
+    if (e?.ephemeral) {
+      console.warn(`[queueStore] ${context}: refusing ephemeral cwd "${cwd}" — ${e.message}`);
+    } else {
+      console.error(`[queueStore] ${context}: skipping invalid project cwd — ${e?.message}`);
+    }
     return null;
   }
 }
@@ -157,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 : {},
   };
 }
 
@@ -203,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')));
@@ -233,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')));
@@ -283,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,14 +68,47 @@ 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.",
   [FAILURE_CLASSES.SELF_QUEUE]:
-    "This run either invoked /develop or /process-feedback from inside its own headless execution, or backgrounded a long-running command and called ScheduleWakeup to check back later — both are the 'you ARE the executor — never re-queue or self-schedule' anti-pattern. A headless PRD run must perform its own acceptance criteria directly and has no next turn to resume it (standards.md → Execution discipline).",
+    "This run either invoked /develop or /process-feedback from inside its own headless execution, or backgrounded a long-running command (e.g. a verification/test run) and called Monitor, TaskOutput, or ScheduleWakeup to check back later — all are the 'you ARE the executor — never re-queue or self-schedule' anti-pattern. A headless PRD run must perform its own acceptance criteria directly and has no next turn to resume it (standards.md → Execution discipline).",
   [FAILURE_CLASSES.STUCK_LOOP]:
     'Bound every command with `timeout <N> <cmd>` — never leave an unbounded `until`/`while true`/`sleep` poll in a PRD body (PRD_AUTHORING.md loop-hang guidance).',
   [FAILURE_CLASSES.POST_AC_OVERRUN]:
@@ -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,10 +64,73 @@ 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
 // never drift apart (they increment the SAME j.orphanRetries field).
 const ORPHAN_REQUEUE_CAP = 5;
 
-module.exports = { claudePidAlive, classifyRunOutcome, ORPHAN_REQUEUE_CAP };
+/**
+ * selectReapableJobs(jobs, now, { pidAlive, grace }) → { reapable, warnings }
+ *
+ * Pure predicate (no IO — `pidAlive` is injected) deciding which 'running'
+ * rows reapDeadRunningJobs() should finalize this cycle. Two distinct dead
+ * shapes:
+ *  - has a runtime.pid, but the process is gone (pidAlive(pid) === false):
+ *    the existing, unchanged behaviour.
+ *  - has NO runtime.pid at all: previously skipped forever ("spawn may be
+ *    mid-flight; give it a cycle" with no age bound). Now reaped once
+ *    `startedAt` is older than `grace` — the spawn never got far enough to
+ *    record a pid and nothing pid-bound can ever catch it (see
+ *    PIDLESS_SPAWN_GRACE_MS's header for why the grace window is safe).
+ *
+ * A pidless row whose `startedAt` is missing or unparseable is neither
+ * reaped nor skipped silently — age can't be proven, so it is surfaced in
+ * `warnings` instead (the caller logs it) and left alone.
+ */
+function selectReapableJobs(jobs, now, { pidAlive, grace } = {}) {
+  const reapable = [];
+  const warnings = [];
+  for (const j of jobs ?? []) {
+    if (j.status !== 'running') continue;
+    const pid = j.runtime?.pid;
+    if (pid) {
+      if (pidAlive(pid)) continue;
+      reapable.push({ slug: j.slug, pid, pidless: false });
+      continue;
+    }
+    const startedAt = Date.parse(j.startedAt ?? '');
+    if (Number.isNaN(startedAt)) {
+      warnings.push({ slug: j.slug, reason: 'pidless row with missing/unparseable startedAt — cannot prove age' });
+      continue;
+    }
+    const ageMs = now - startedAt;
+    if (ageMs < grace) continue; // spawn may still be mid-flight
+    reapable.push({
+      slug: j.slug,
+      pid: null,
+      pidless: true,
+      reason: `reaped: no runtime.pid recorded after ${Math.round(grace / 60_000)}m — spawn never completed`,
+    });
+  }
+  return { reapable, warnings };
+}
+
+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'],