claude-code-session-manager 0.78.0 → 0.80.0

package/src/main/lib/prdCreate.cjs

@@ -28,6 +28,17 @@ const { appendAuditEvent } = require('./auditLog.cjs');
 const { resolveProjectContext } = require('./projectRootResolve.cjs');
 const { fixChainDepthOf, baseSlugOf } = require('./fixChainDepth.cjs');
 const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentType.cjs');
+const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
+const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
+
+// A caller-supplied slug that already starts with its own `NN-` (e.g.
+// "254-perf-x") used to silently become the double-prefixed row
+// "254-254-perf-x" once allocateParallelGroup() prepended the REAL
+// allocated NN — PRD_CREATE_SLUG_RE only enforces kebab-case shape, so it
+// never caught this. Refused outright rather than auto-stripped: silently
+// rewriting the caller's slug would hide the same mistake the old behavior
+// hid, just one layer further down.
+const SLUG_HAS_NN_PREFIX_RE = /^(\d+)-/;
 
 // Fix-chain depth cap (PRD 1113): a fix-of-a-fix (depth >= 2) is refused at
 // this shared write path rather than caught later — scheduler.cjs's
@@ -157,7 +168,7 @@ function resolveSourcePromptIdFromClaudeSession(cwd, claudeSessionId) {
  * the renderer-facing IPC handler (chat:create-prd, index.cjs) so the
  * validation/write logic lives in exactly one place (API-reuse standard).
  * `input` must already be schema-validated by the caller (schemas.schedulerCreatePrd).
- * `remote` is scheduler.cjs's remote object (allocateParallelGroup/readPrd/writePrd).
+ * `remote` is scheduler.cjs's remote object (allocateParallelGroup/readPrd/writePrd/listPrds).
  *
  * Returns `{ ok: true, nn, filename }` on success, or `{ ok: false, status, error }`
  * on failure — `status` is the HTTP status code the caller should map errors to
@@ -226,6 +237,18 @@ async function createPrd(input, remote) {
     if (fallback) input = { ...input, sourcePromptId: fallback };
   }
 
+  if (input.slug) {
+    const nnMatch = SLUG_HAS_NN_PREFIX_RE.exec(input.slug);
+    if (nnMatch) {
+      return {
+        ok: false,
+        status: 400,
+        error: `slug "${input.slug}" already starts with a numeric prefix "${nnMatch[1]}-" — the allocator ` +
+          `owns the NN- prefix, not the caller. Pass the bare name instead (e.g. "${input.slug.slice(nnMatch[0].length)}").`,
+      };
+    }
+  }
+
   const slug = input.slug || deriveSlugFromTitle(input.title);
   if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
     return { ok: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
@@ -243,10 +266,10 @@ async function createPrd(input, remote) {
   const filenameSlug = `${nn}-${slug}`;
 
   // Fix-chain depth guard (PRD 1113): refuse a fix-of-a-fix before it's ever
-  // written. depth 0/1 pass through unchanged (an ordinary PRD, or a first
-  // fix-plan, is never blocked); depth >= 2 means the base job has already
-  // failed to close via at least one prior fix attempt for reasons a repeat
-  // attempt won't resolve.
+  // written. depth >= 2 means the base job has already failed to close via
+  // at least one prior fix attempt for reasons a repeat attempt won't
+  // resolve — checked first so this distinct, human-escalation error still
+  // wins over the more general fix-plan-slug guard below for that shape.
   const chainDepth = fixChainDepthOf(filenameSlug);
   if (chainDepth > FIX_CHAIN_DEPTH_CAP) {
     const base = baseSlugOf(filenameSlug);
@@ -259,6 +282,29 @@ async function createPrd(input, remote) {
     };
   }
 
+  // Fix-plan-slug collision guard (PRD 1131): a caller-supplied or
+  // title-derived slug that happens to start with "fix-" collides with the
+  // scheduler's own NN-fix-... naming convention for fix plans it authors
+  // itself (spawnInvestigation) — and that shape carries real special-case
+  // semantics (depth-capped auto-investigation eligibility,
+  // commitGuardVerdict's zero-edit exemption) that a PRD authored through
+  // this API never asked for. Refused outright, not silently renamed, same
+  // fail-closed posture as the SLUG_HAS_NN_PREFIX_RE check above (PRD 1126:
+  // "126-fix-plan-death-reopens-parent" was wrongly stamped
+  // investigationDepth before it ever ran and had to be withdrawn). This
+  // subsumes the depth-1 case the chain-depth guard above deliberately let
+  // through (MAX_INVESTIGATION_DEPTH=1 means a first fix-plan is legitimate
+  // — but only when spawnInvestigation authors it, never through this API).
+  if (isFixPlanSlug(filenameSlug)) {
+    return {
+      ok: false,
+      status: 400,
+      error: `slug "${filenameSlug}" collides with the reserved NN-fix-... fix-plan naming convention ` +
+        '(reserved for PRDs the scheduler\'s own investigation loop authors itself). Reword the title/slug ' +
+        'so it does not start with "fix-" — e.g. "resolve-x" or "repair-x" instead of "fix-x".',
+    };
+  }
+
   // An explicit `parallelGroup` bypasses allocateParallelGroup()'s
   // collision-proof reservation, so re-check for an existing file at
   // this exact destination before writing — remote.writePrd itself has
@@ -284,6 +330,39 @@ async function createPrd(input, remote) {
     }
   }
 
+  // Write-time FK check for dependsOn (report on read / throw on write — see
+  // prdAgentType.cjs's header): every entry must resolve to a PRD that
+  // actually exists in this project, using the SAME resolution rule
+  // schedulerBatch.cjs's findBlockingDep applies at run time (exact slug,
+  // else bare-name after stripping one leading `NN-`) — a dep that
+  // validates here is guaranteed to be a dep findBlockingDep can actually
+  // see later. A listPrds() read failure is skipped-with-a-warning, never a
+  // write outage: an I/O hiccup on the read side must not block every PRD
+  // write in the project.
+  if (input.dependsOn && input.dependsOn.length) {
+    let listing;
+    try {
+      listing = await remote.listPrds({ cwd: input.cwd, limit: Number.MAX_SAFE_INTEGER });
+    } catch (e) {
+      console.warn(`[prdCreate] dependsOn validation skipped (listPrds failed): ${e?.message ?? e}`);
+      listing = null;
+    }
+    if (listing) {
+      const candidateSlugs = (listing.prds ?? []).map((p) => p.slug);
+      for (const dep of input.dependsOn) {
+        if (resolveDepSlug(dep, candidateSlugs).length > 0) continue;
+        const near = findNearMatches(dep, candidateSlugs);
+        const suggestion = near.length ? ` Closest existing slug(s): ${near.join(', ')}.` : '';
+        return {
+          ok: false,
+          status: 400,
+          error: `dependsOn entry "${dep}" does not resolve to any existing PRD in this project.${suggestion} ` +
+            'Pass the bare name (preferred) or the exact NN-prefixed slug of an existing PRD.',
+        };
+      }
+    }
+  }
+
   const body = buildPrdBody(input);
   const writeResult = await remote.writePrd(filenameSlug, body, input.cwd);
   if (!writeResult?.ok) {

package/src/main/lib/prdFrontmatter.cjs

@@ -62,7 +62,7 @@ function splitFrontmatter(raw) {
  * either surface never reorders or drops a key it didn't touch. Recognized
  * key set intentionally mirrors the TS module exactly (title, cwd,
  * estimateMinutes, parallelGroup, sourcePromptId, sourceTabId, tag,
- * agentType, createdVia, issuedAt); every other frontmatter key (e.g. dependsOn)
+ * agentType, createdVia, issuedAt, dependsOn); every other frontmatter key
  * round-trips via `extras`, same as the renderer's editor today.
  *
  * `createdVia`/`issuedAt` (PRD provenance-lockdown) are recognized here so
@@ -70,10 +70,15 @@ function splitFrontmatter(raw) {
  * after creation — see prdCreate.cjs's buildPrdBody for the create-time
  * stamp) round-trips them like any other known key rather than shunting them
  * into `extras`.
+ *
+ * `dependsOn` (PRD 1124) is the first ARRAY-valued recognized key — parsed/
+ * emitted only in its inline `[a, b]` list form (the sole form prdCreate.cjs
+ * ever writes; block-style YAML lists are out of scope). An empty array is
+ * never emitted, which is how `scheduler_update_prd` clears a dependency.
  */
 
-const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'quietMachine']);
-const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'quietMachine'];
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine'];
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 function indentOf(line) {
@@ -99,6 +104,28 @@ function parseScalar(raw) {
   return v;
 }
 
+/**
+ * Parse the inline `[a, b]` list form used by `dependsOn` — the sole form
+ * prdCreate.cjs's buildPrdBody ever writes. Returns null (not recognized as
+ * a list) when `raw` isn't bracketed, so a hand-edited non-list value is
+ * left unset rather than mis-parsed.
+ */
+function parseInlineList(raw) {
+  const v = raw.trim();
+  if (!v.startsWith('[') || !v.endsWith(']')) return null;
+  const inner = v.slice(1, -1).trim();
+  if (inner === '') return [];
+  return inner
+    .split(',')
+    .map((s) => s.trim().replace(/^(['"])(.*)\1$/, '$2'))
+    .filter((s) => s.length > 0);
+}
+
+function arraysEqual(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
 function applyKey(fm, key, after) {
   const v = parseScalar(after);
   if (v === null) return;
@@ -138,6 +165,13 @@ function applyKey(fm, key, after) {
     case 'issuedAt':
       fm.issuedAt = String(v);
       return;
+    case 'dependsOn': {
+      // Only the inline `[a, b]` list form is recognized (see parseInlineList's
+      // header) — a malformed/hand-edited non-list value is left unset.
+      const list = parseInlineList(after);
+      if (list) fm.dependsOn = list;
+      return;
+    }
     case 'quietMachine':
       // Opt-in exclusive-lease flag (PRD 1107) — only a literal `true`
       // frontmatter value opts in; anything else (including an explicit
@@ -180,10 +214,17 @@ function parsePrdFile(text) {
 
     if (RECOGNIZED_KEYS.has(key)) {
       applyKey(fm, key, after);
-      const parsed = parseScalar(after);
-      if (parsed !== null && (typeof parsed === 'string' || typeof parsed === 'number')) {
-        if (!fm._raw) fm._raw = {};
-        fm._raw[key] = { line, parsed };
+      if (key === 'dependsOn') {
+        if (fm.dependsOn) {
+          if (!fm._raw) fm._raw = {};
+          fm._raw[key] = { line, parsed: fm.dependsOn };
+        }
+      } else {
+        const parsed = parseScalar(after);
+        if (parsed !== null && (typeof parsed === 'string' || typeof parsed === 'number')) {
+          if (!fm._raw) fm._raw = {};
+          fm._raw[key] = { line, parsed };
+        }
       }
     } else {
       extras[key] = { lines: band };
@@ -218,8 +259,11 @@ function serializePrdFile(fm, body) {
   for (const key of EMIT_ORDER) {
     const v = fm[key];
     if (v === undefined || v === null || v === '') continue;
+    // An empty dependsOn array is how scheduler_update_prd CLEARS the
+    // dependency — never emitted, same as an absent key.
+    if (Array.isArray(v) && v.length === 0) continue;
     const cached = fm._raw?.[key];
-    if (cached && cached.parsed === v) {
+    if (cached && (Array.isArray(v) ? arraysEqual(cached.parsed, v) : cached.parsed === v)) {
       out.push(cached.line);
       continue;
     }
@@ -227,6 +271,10 @@ function serializePrdFile(fm, body) {
       out.push(`${key}: ${v}`);
       continue;
     }
+    if (Array.isArray(v)) {
+      out.push(`${key}: [${v.join(', ')}]`);
+      continue;
+    }
     out.push(`${key}: ${serializeScalar(v)}`);
   }
   if (fm.extras) {

package/src/main/lib/queueHistory.cjs

@@ -15,6 +15,7 @@ const path = require('path');
 const fsp = require('fs').promises;
 const { HISTORY_RETENTION_MS } = require('./schedulerConfig.cjs');
 const { projectHistoryPath, stateCwds } = require('./queueStore.cjs');
+const { resolveIsFixPlan } = require('./fixPlanSlug.cjs');
 
 // Legacy global sidecar — READ-ONLY since 2026-07-31 (federated per-project
 // history under <cwd>/session-manager-operations/scheduler/state/history.jsonl,
@@ -52,10 +53,6 @@ function historyPathFor(entry) {
   return HISTORY_PATH;
 }
 
-function isFixPlanSlug(slug) {
-  return /^\d+-fix-/.test(slug);
-}
-
 function jobKey(job) {
   return `${job?.slug ?? ''}|${job?.runId ?? ''}`;
 }
@@ -79,9 +76,13 @@ function partitionJobs(jobs, nowMs, opts = {}) {
 
   // Slugs of jobs that a still-pending/running fix-plan is going to try to
   // heal (see healTargetForFix in scheduler.cjs — same regex, kept in sync).
+  // Honors the job's own persisted `isFixPlan` provenance stamp (PRD 1131)
+  // over the slug shape, same as every other fix-plan consumer in
+  // scheduler.cjs — a slug that merely starts with "fix-" but was classified
+  // isFixPlan:false must not get treated as a real fix-plan here either.
   const protectedSlugs = new Set();
   for (const j of list) {
-    if (!j || !isFixPlanSlug(j.slug)) continue;
+    if (!j || !resolveIsFixPlan(j.slug, j.isFixPlan)) continue;
     if (j.status !== 'pending' && j.status !== 'running') continue;
     protectedSlugs.add(j.slug.replace(/^(\d+)-fix-/, '$1-'));
   }
@@ -269,10 +270,54 @@ async function historyTerminalBySlug() {
   return map;
 }
 
+/**
+ * completedSlugsForCwd(cwd) → Set<string> of every slug whose most recent
+ * appended record in THIS project's own history shard
+ * (`<cwd>/session-manager-operations/scheduler/state/history.jsonl`, via
+ * projectHistoryPath) has status 'completed'. Scoped to one project's shard
+ * — unlike historyTerminalBySlug's federated, machine-wide map — because
+ * this feeds PRD 1122's dependsOn history lookup, where a same-named PRD in
+ * an unrelated project must never count as satisfying a dep. Missing file
+ * (ENOENT) returns an empty Set, not an error — a project with no history
+ * yet is not a read failure.
+ */
+async function completedSlugsForCwd(cwd) {
+  let text = '';
+  try {
+    text = await fsp.readFile(projectHistoryPath(cwd), 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return new Set();
+    throw e;
+  }
+  // Last-line-wins per slug (file is append-only chronological) — same
+  // pattern as historyTerminalBySlug above. A slug can legitimately appear
+  // more than once (scheduler_reset_job resets a completed row back to
+  // pending, it runs again, and eventually re-retires to history) — unioning
+  // every 'completed' line ever seen, without letting a LATER 'failed' line
+  // for the same slug revoke it, would keep a since-refailed dep permanently
+  // satisfied for its dependents.
+  const statusBySlug = new Map();
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const j = JSON.parse(line);
+      if (j?.slug) statusBySlug.set(j.slug, j.status);
+    } catch {
+      // corrupt/partial line — ignore
+    }
+  }
+  const slugs = new Set();
+  for (const [slug, status] of statusBySlug) {
+    if (status === 'completed') slugs.add(slug);
+  }
+  return slugs;
+}
+
 module.exports = {
   HISTORY_PATH,
   partitionJobs,
   appendHistory,
   readHistory,
   historyTerminalBySlug,
+  completedSlugsForCwd,
 };

package/src/main/lib/rateLimitDetect.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * rateLimitDetect.cjs — the single source of truth for "did this claude -p
+ * log tail show a rate-limit death". Shared by spawnJob() (a still-running
+ * process that just exited) and reapDeadRunningJobs()/classifyRunOutcome()
+ * (a process the reaper found already dead) — see PRD 1117. Before this,
+ * only spawnJob checked this; the reaper had no rate-limit branch at all,
+ * so a rate-limited exit that the reaper won the race to finalize got
+ * stamped terminal 'failed' instead of retryable 'pending'. There must
+ * never be a second, independently-drifting regex set at either call site.
+ */
+
+const { readTail } = require('./fileTail.cjs');
+
+/** Scan the tail of a job's log for the canonical rate-limit signal. We look
+ *  at the last 16 KB — final result event always lands at the end. Covers
+ *  both unified-window rate-limit types (five_hour, seven_day), the raw
+ *  429 status, and the two human-readable limit-message phrasings the CLI
+ *  emits ("You've hit your limit" / "You've reached your <model> limit"). */
+function detectRateLimitInLog(logPath) {
+  try {
+    const text = readTail(logPath, 16384);
+    if (!text) return false;
+    return /"rateLimitType":"five_hour"/.test(text)
+      || /"rateLimitType":"seven_day"/.test(text)
+      || /"api_error_status":429/.test(text)
+      || /You'?ve hit your limit/.test(text)
+      || /You'?ve reached your .* limit/.test(text);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { detectRateLimitInLog };

package/src/main/lib/reaperHelpers.cjs

@@ -9,6 +9,7 @@
 
 const fs = require('node:fs');
 const { readTail } = require('./fileTail.cjs');
+const { detectRateLimitInLog } = require('./rateLimitDetect.cjs');
 
 /**
  * Return true if pid is alive AND its cmdline looks like a claude process.
@@ -38,11 +39,16 @@ function claudePidAlive(pid) {
  * of its log file and scanning for the LAST `{"type":"result"}` JSONL event.
  *
  * Returns:
- *   'success'   — last result event has subtype=success and is_error !== true
- *   'failed'    — last result event exists but indicates an error
- *   'no_result' — no result event found in the tail (process may have been killed
- *                 before emitting one, or the log is absent/empty)
- *   'unknown'   — unexpected error reading/parsing (outer catch)
+ *   'success'      — last result event has subtype=success and is_error !== true
+ *   'rate_limited' — the log tail shows the same rate-limit signal spawnJob's own
+ *                    live-process check uses (detectRateLimitInLog, the shared
+ *                    single source of truth) — a NEW, distinct outcome from
+ *                    'failed' (PRD 1117): a rate-limited death is retryable, not
+ *                    a genuine gate failure, and must never collapse into 'failed'
+ *   'failed'       — last result event exists but indicates a genuine error
+ *   'no_result'    — no result event found in the tail (process may have been killed
+ *                    before emitting one, or the log is absent/empty)
+ *   'unknown'      — unexpected error reading/parsing (outer catch)
  */
 function classifyRunOutcome(logPath) {
   try {
@@ -56,8 +62,27 @@ function classifyRunOutcome(logPath) {
         if (obj && obj.type === 'result') lastResult = obj;
       } catch { /* partial line at tail boundary or non-JSON scheduler log line */ }
     }
+    // ORDER IS LOAD-BEARING. The rate-limit check must come AFTER the success
+    // determination, never before it. The CLI emits an informational
+    // `rate_limit_event` with status:"allowed_warning" on essentially every
+    // run once utilization is non-zero, and detectRateLimitInLog matches its
+    // "rateLimitType" field — so checking first classified genuinely
+    // SUCCESSFUL runs as rate_limited. Measured on 2026-09-05 against the
+    // eight most recent runs whose own meta.json recorded exitCode:0 and
+    // rateLimited:false, four came back 'rate_limited' (e.g.
+    // 200-campaign-toolkit-weak-points-and-stuns: 55 turns, is_error:false,
+    // terminalReasonFromHarness:'completed', landed commit 7fd05f7 — matched
+    // purely on an allowed_warning five_hour event). In reapDeadRunningJobs
+    // that resets a finished job to 'pending' to re-run shipped work AND
+    // engages setPaused('rate_limit') with no rate limit in effect — strictly
+    // worse than the terminal-'failed' bug the rate_limit branch was added to
+    // fix. See the guard test in this file's __tests__ sibling.
+    if (lastResult && lastResult.subtype === 'success' && lastResult.is_error !== true) return 'success';
+    // Still checked ahead of 'no_result': a run killed mid-flight by a rate
+    // limit may never emit a result event at all, and that is a rate-limited
+    // death, not silence.
+    if (detectRateLimitInLog(logPath)) return 'rate_limited';
     if (!lastResult) return 'no_result';
-    if (lastResult.subtype === 'success' && lastResult.is_error !== true) return 'success';
     return 'failed';
   } catch {
     return 'unknown';

package/src/main/lib/runLogRetention.cjs

@@ -296,11 +296,84 @@ function resolveLiveKeysForApply(runsDir, opts, enabled) {
   }
 }
 
+/**
+ * Build the set of runIds currently claimed by a job in status 'running' —
+ * used by the orphan pass below to skip a directory whose spawn may be
+ * mid-flight right now (scheduler.cjs's pickRunDir mints the runId/dir pair
+ * before the child process is spawned; the directory itself is only
+ * mkdir'd, and files only start landing in it, once execution actually
+ * commits — see executeJob). Deliberately keyed by runId alone, not
+ * `${slug}|${runId}` like liveKeysFromJobs: a shared batch dir (tickQueue
+ * hands ONE runId to several jobs at once) is in flight if ANY job dispatched
+ * into it is still running, regardless of which slug.
+ */
+function runningRunIdsFromJobs(jobs) {
+  const ids = new Set();
+  for (const job of jobs || []) {
+    if (job && job.status === 'running' && job.runId) ids.add(job.runId);
+  }
+  return ids;
+}
+
+/**
+ * Resolve the running-runId protection set for applyRetention's orphan pass,
+ * mirroring resolveLiveKeysForApply's precedence: explicit opts win, then
+ * opts.jobs, then (only when deletion is actually about to happen) a direct
+ * read of the real scheduler queue.
+ */
+function resolveRunningRunIdsForApply(opts, enabled) {
+  if (opts && opts.runningRunIds) return opts.runningRunIds;
+  if (opts && opts.jobs) return runningRunIdsFromJobs(opts.jobs);
+  if (!enabled) return new Set();
+  try {
+    const queueStore = require('./queueStore.cjs');
+    const state = queueStore.readMergedSync();
+    return runningRunIdsFromJobs(state.jobs || []);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Remove every EMPTY directory directly under runsDir, at any age, except
+ * one whose runId is in runningRunIds. These are orphans left behind by a
+ * dispatch that minted a runId/dir pair (pickRunDir) but aborted before
+ * spawnJob's executeJob ever wrote into it (slot-acquire miss, worktree-cap
+ * deferral, launch-gate block, ...) — scanRunEntries never sees them (no
+ * meta.json), so the age/count policy above can't reach them either.
+ * Returns the count of directories removed.
+ */
+function sweepOrphanDirs(runsDir, runningRunIds, errors) {
+  let dirNames;
+  try {
+    dirNames = fs.readdirSync(runsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return 0;
+  }
+
+  let removed = 0;
+  for (const runId of dirNames) {
+    if (runningRunIds.has(runId)) continue;
+    const dir = path.join(runsDir, runId);
+    try {
+      if (fs.readdirSync(dir).length !== 0) continue;
+      fs.rmdirSync(dir);
+      removed += 1;
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') errors.push({ path: dir, error: e.message });
+    }
+  }
+  return removed;
+}
+
 /**
  * Compute the report, and — ONLY when isRetentionEnabled(settings) — delete
- * the eligible files and rmdir any directory left fully empty. With no
- * opt-in (the default), this is exactly computeReport(): read-only,
- * `deleted: false`, nothing removed.
+ * the eligible files, rmdir any directory left fully empty, and sweep any
+ * orphan empty run directory (see sweepOrphanDirs). With no opt-in (the
+ * default), this is exactly computeReport(): read-only, `deleted: false`,
+ * nothing removed.
  */
 function applyRetention(runsDir, settings, opts) {
   const cfg = (settings && settings.schedulerRunLogRetention) || null;
@@ -342,7 +415,10 @@ function applyRetention(runsDir, settings, opts) {
     }
   }
 
-  return { deleted: true, removedFiles, freedBytes, errors, report };
+  const runningRunIds = resolveRunningRunIdsForApply(opts, enabled);
+  const orphanDirsRemoved = sweepOrphanDirs(runsDir, runningRunIds, errors);
+
+  return { deleted: true, removedFiles, freedBytes, orphanDirsRemoved, errors, report };
 }
 
 /**
@@ -370,6 +446,8 @@ module.exports = {
   LIVE_STATUSES,
   isLiveJob,
   liveKeysFromJobs,
+  runningRunIdsFromJobs,
+  sweepOrphanDirs,
   scanRunEntries,
   computeEligibility,
   computeReport,

package/src/main/lib/scheduleJobTransitions.cjs

@@ -61,7 +61,17 @@ const STATUS_HISTORY_CAP = 20;
  *    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`
+ *    (heal on reverify, or auto-promote) — same shape as `failed`. Also
+ *    reached by source 'scheduler:mechanicalRecovery' (PRD 1130): a job
+ *    parked with a mechanically-resolvable verdict (starting with exactly
+ *    'worktree_integration_failed') gets one bounded, model-free re-attempt
+ *    of its worktree branch integration; success lands here exactly like any
+ *    other completion.
+ *  - needs_review->running (resume-first recovery, PRD 1111: a job parked
+ *    needs_review with verdict 'uncommitted_changes' gets one bounded
+ *    `claude -p --resume` dispatch through spawnJob before any fix-plan
+ *    investigation is authored — spawnJob's own dispatch mutate transitions
+ *    straight to 'running', same as any pending job)
  *  - 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)
@@ -85,7 +95,7 @@ const LEGAL_TRANSITIONS = {
   running: ['completed', 'failed', 'needs_review', 'skipped', 'pending'],
   investigating: ['failed', 'needs_review', 'completed', 'pending', 'skipped'],
   failed: ['investigating', 'pending', 'completed', 'needs_review'],
-  needs_review: ['investigating', 'pending', 'completed', 'skipped'],
+  needs_review: ['investigating', 'pending', 'completed', 'skipped', 'running'],
   completed: ['pending'],
   skipped: ['pending'],
   quarantined: ['pending', 'skipped'],