claude-code-session-manager 0.86.0 → 0.87.0

package/src/main/lib/prdLocations.cjs

@@ -12,12 +12,22 @@
  * live. Active-project discovery reuses activeSessions.cjs's
  * activeProjectCwds (the same discovery watchdogHelpers.cjs's sweep() uses)
  * rather than re-implementing transcript scanning here.
+ *
+ * CACHING NOTE (PRD adding mtime-keyed memoization to this module): what's
+ * cached here is only WHICH DIRECTORIES EXIST, never their CONTENTS. A new
+ * PRD .md file dropped into an already-known `prds/` dir does not change
+ * that dir's own existence, so it needs no cache invalidation here at all —
+ * `schedule:rescan` (scheduler.cjs's `ipcMain.handle('schedule:rescan', …)`)
+ * still reports it because the actual file-listing happens one layer down,
+ * in scheduler/prdParser.cjs's `listPrdFiles(dir)`, which has its OWN
+ * separate mtime cache keyed on that specific dir's mtime (bumped by the new
+ * file) and is unaffected by anything cached in this module.
  */
 'use strict';
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { activeProjectCwds, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { activeProjectCwds, allProjectCwds } = require('./activeSessions.cjs');
 
 const { opsPath, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 
@@ -53,18 +63,49 @@ function resolveEpicPrdWriteDir(cwd, epicId) {
   return path.join(resolveEpicsRoot(cwd), epicId, 'prds');
 }
 
+// listEpicPrdDirs' readdir-the-Epics-root-plus-existsSync-per-subdir walk is
+// the expensive half of prdLocations' per-reconcile()-pass cost (159/166
+// dirs, ~430ms/~400ms measured). A new Epic's prds/ dir is always created in
+// the SAME recursive mkdirSync call that creates `epics/<newId>/` itself
+// (epicMint.cjs's ensureEpic, both the mint branch and the join branch's
+// belt-and-suspenders mkdirSync) — so a brand-new `epics/<id>/prds` dir
+// first coming into existence always bumps the Epics root's OWN mtime (a
+// new directory entry under it), never just an existing subdir's mtime.
+// Cache keyed on that mtime, same dir-mtime idiom as
+// scheduler/prdParser.cjs's dirCache — no TTL, so the very next call after a
+// mint sees the new dir with no wait.
+const epicPrdDirsCache = new Map(); // epicsRootPath -> { mtimeMs, result }
+
 /** Enumerate every existing `epics/<id>/prds` dir under one project cwd. */
 function listEpicPrdDirs(cwd) {
   let root;
   try { root = resolveEpicsRoot(cwd); } catch { return []; }
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(root).mtimeMs;
+  } catch {
+    // Missing/unreadable root: nothing to scan, and any prior cache entry
+    // must not survive to be handed back once the dir later appears.
+    epicPrdDirsCache.delete(root);
+    return [];
+  }
+  const cached = epicPrdDirsCache.get(root);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.result;
+
   let entries;
-  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    epicPrdDirsCache.delete(root);
+    return [];
+  }
   const dirs = [];
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
     const prdDir = path.join(root, ent.name, 'prds');
     if (fs.existsSync(prdDir)) dirs.push(prdDir);
   }
+  epicPrdDirsCache.set(root, { mtimeMs, result: dirs });
   return dirs;
 }
 
@@ -101,6 +142,83 @@ function resolvePrdWriteDir(cwd) {
   return opsPath(cwd, ...PRD_SUBPATH);
 }
 
+// resolvePrdsDirs/resolveArchivedPrdsDirs each redo a fs.existsSync(dir) +
+// listEpicPrdDirs(cwd) walk across EVERY project on every call, and
+// reconcile() calls each of them once per pass. Cache the assembled result
+// keyed on the caller's own (maxAgeMin, opts) tuple — a call with an
+// explicit `{ projectsDir }` opts object is a DIFFERENT key from the
+// no-opts default, so the two never read or write each other's entry — PLUS
+// a freshness key built from every visited project's Epics-root mtimeMs,
+// same composite-mtime-key idiom as queueHistory.cjs's historyCacheKey. The
+// freshness key is cheap to rebuild every call (one statSync per project,
+// far cheaper than the readdir+existsSync-per-Epic walk it guards), so a
+// cache hit still costs O(projects) stats but skips the expensive walk
+// entirely — "one filesystem walk" per reconcile() pass, not the full
+// listEpicPrdDirs cost N times over.
+//
+// The Epics-root mtime alone has a real blind spot: `prds-archived/` is
+// created (archiveCompletedPrd, scheduler.cjs) as a NEW entry INSIDE an
+// ALREADY-EXISTING `epics/<id>/` dir — unlike a brand-new Epic's `prds/`,
+// which is always created in the SAME mkdirSync call as `epics/<id>/`
+// itself (see listEpicPrdDirs's header), that does not bump the Epics
+// root's own mtime. Re-stating every Epic subdirectory's own mtime on every
+// call to close that gap would cost about what the walk itself costs,
+// defeating the cache — so this cache pairs the mtime key (instant
+// invalidation for the case the non-negotiable freshness test covers: a
+// brand-new Epic's `prds/` dir) with the SAME short TTL backstop
+// src/main/lib/activeSessions.cjs's cwdScanCache already established for
+// this exact module chain, bounding the archived-dir blind spot to one
+// TTL window instead of leaving it stale indefinitely. Nothing reads
+// resolveArchivedPrdsDirs off the dispatch-correctness path — the
+// archived-twin stale-queue-row guard (scheduler.cjs's archivedTwinExists)
+// calls listArchivedPrdDirs directly, uncached — so this is purely a
+// reporting-freshness bound (schedule:list-prds's per-Epic PRD/run counts).
+const ASSEMBLED_DIRS_CACHE_TTL_MS = 30_000;
+const assembledPrdsDirsCache = new Map(); // callerKey -> { freshnessKey, cachedAt, result }
+const assembledArchivedPrdsDirsCache = new Map();
+
+// Sorted-keys JSON.stringify: a plain JSON.stringify(opts) would key
+// { a: 1, b: 2 } and { b: 2, a: 1 } as two different cache entries — a real
+// (if currently latent, since every caller today passes at most one opts
+// key) correctness trap for a cache key.
+function stableStringify(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+
+function callerOptsKey(maxAgeMin, opts) {
+  return `${maxAgeMin}::${opts ? stableStringify(opts) : ''}`;
+}
+
+// mtimeMs of each visited project's Epics root, joined into one string. Any
+// project whose root doesn't exist/isn't readable contributes a stable
+// sentinel so the key still changes the moment that root is created.
+function epicsRootsFreshnessKey(cwds) {
+  return cwds
+    .map((cwd) => {
+      let root;
+      try { root = resolveEpicsRoot(cwd); } catch { return `${cwd}:noroot`; }
+      try { return `${root}:${fs.statSync(root).mtimeMs}`; } catch { return `${root}:-1`; }
+    })
+    .join('|');
+}
+
+function memoizedAssembledDirs(cache, maxAgeMin, opts, compute) {
+  const callerKey = callerOptsKey(maxAgeMin, opts);
+  const allCwds = allProjectCwds(opts);
+  const activeCwds = activeProjectCwds(maxAgeMin, opts);
+  const cwdUnion = [...new Set([...allCwds, ...activeCwds])];
+  const freshnessKey = `${allCwds.join(',')}#${activeCwds.join(',')}#${epicsRootsFreshnessKey(cwdUnion)}`;
+
+  const cached = cache.get(callerKey);
+  if (cached && cached.freshnessKey === freshnessKey && Date.now() - cached.cachedAt < ASSEMBLED_DIRS_CACHE_TTL_MS) {
+    return cached.result;
+  }
+
+  const result = compute(allCwds, activeCwds);
+  cache.set(callerKey, { freshnessKey, cachedAt: Date.now(), result });
+  return result;
+}
+
 /**
  * resolvePrdsDirs(maxAgeMin?, opts?) → string[]
  *
@@ -122,34 +240,36 @@ function resolvePrdWriteDir(cwd) {
  * underlying scan (e.g. `projectsDir` override for tests).
  */
 function resolvePrdsDirs(maxAgeMin, opts) {
-  const dirs = [];
-  const seen = new Set();
-  const add = (dir) => {
-    if (seen.has(dir)) return;
-    seen.add(dir);
-    dirs.push(dir);
-  };
-
-  // Every historical project that has a PRD dir on disk — the set that
-  // matters for discovery, regardless of when it was last touched.
-  for (const cwd of allProjectCwds(opts)) {
-    let dir;
-    try { dir = resolvePrdWriteDir(cwd); } catch { continue; }
-    if (fs.existsSync(dir)) add(dir);
-    // Epic-scoped dirs (the write layout for all new PRDs) are first-class
-    // scan sources alongside the legacy flat dir.
-    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
-  }
+  return memoizedAssembledDirs(assembledPrdsDirsCache, maxAgeMin, opts, (allCwds, activeCwds) => {
+    const dirs = [];
+    const seen = new Set();
+    const add = (dir) => {
+      if (seen.has(dir)) return;
+      seen.add(dir);
+      dirs.push(dir);
+    };
 
-  // Active projects are added unconditionally: a brand-new project has no
-  // prds/ dir yet, and callers that resolve a write destination must still
-  // find it. Scans over a non-existent dir are a harmless ENOENT no-op.
-  for (const cwd of activeProjectCwds(maxAgeMin, opts)) {
-    try { add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
-    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
-  }
+    // Every historical project that has a PRD dir on disk — the set that
+    // matters for discovery, regardless of when it was last touched.
+    for (const cwd of allCwds) {
+      let dir;
+      try { dir = resolvePrdWriteDir(cwd); } catch { continue; }
+      if (fs.existsSync(dir)) add(dir);
+      // Epic-scoped dirs (the write layout for all new PRDs) are first-class
+      // scan sources alongside the legacy flat dir.
+      for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
+    }
 
-  return dirs;
+    // Active projects are added unconditionally: a brand-new project has no
+    // prds/ dir yet, and callers that resolve a write destination must still
+    // find it. Scans over a non-existent dir are a harmless ENOENT no-op.
+    for (const cwd of activeCwds) {
+      try { add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
+      for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
+    }
+
+    return dirs;
+  });
 }
 
 /**
@@ -163,26 +283,28 @@ function resolvePrdsDirs(maxAgeMin, opts) {
  * history, not something list-prds should stop counting.
  */
 function resolveArchivedPrdsDirs(maxAgeMin, opts) {
-  const dirs = [];
-  const seen = new Set();
-  const add = (dir) => {
-    if (seen.has(dir)) return;
-    seen.add(dir);
-    dirs.push(dir);
-  };
-
-  for (const cwd of allProjectCwds(opts)) {
-    for (const dir of listArchivedPrdDirs(cwd)) {
-      if (fs.existsSync(dir)) add(dir);
+  return memoizedAssembledDirs(assembledArchivedPrdsDirsCache, maxAgeMin, opts, (allCwds, activeCwds) => {
+    const dirs = [];
+    const seen = new Set();
+    const add = (dir) => {
+      if (seen.has(dir)) return;
+      seen.add(dir);
+      dirs.push(dir);
+    };
+
+    for (const cwd of allCwds) {
+      for (const dir of listArchivedPrdDirs(cwd)) {
+        if (fs.existsSync(dir)) add(dir);
+      }
     }
-  }
-  for (const cwd of activeProjectCwds(maxAgeMin, opts)) {
-    for (const dir of listArchivedPrdDirs(cwd)) {
-      if (fs.existsSync(dir)) add(dir);
+    for (const cwd of activeCwds) {
+      for (const dir of listArchivedPrdDirs(cwd)) {
+        if (fs.existsSync(dir)) add(dir);
+      }
     }
-  }
 
-  return dirs;
+    return dirs;
+  });
 }
 
 /**

package/src/main/lib/projectHomeAdminRoutes.cjs

@@ -7,8 +7,8 @@
  * first) — which is exactly why generation silently hung on a foreign
  * machine with no repo checked out. These four routes make the app itself
  * the authority on paths/schema/catalog/rendering, reusing the shipped
- * assets PRD 1088 put in the npm tarball (scripts/render-project-pages/dist/
- * renderer.cjs, scripts/project-pages-logic/dist/logic.cjs,
+ * assets PRD 1088 put in the npm tarball (web/project-pages/renderer/dist/
+ * renderer.cjs, web/project-pages/logic/dist/logic.cjs,
  * src/main/templates/project-pages-catalog.json,
  * src/main/templates/project-pages-pipeline.md) rather than reimplementing
  * any of them.
@@ -40,8 +40,8 @@ const LENSES = ['home', 'marketing', 'feature', 'architecture', 'brief'];
 // requires an app restart to pick up during dev, same as that module).
 const CATALOG_PATH = path.join(__dirname, '..', 'templates', 'project-pages-catalog.json');
 const SPEC_PATH = path.join(__dirname, '..', 'templates', 'project-pages-pipeline.md');
-const RENDERER_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'scripts', 'render-project-pages', 'dist', 'renderer.cjs');
-const LOGIC_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'scripts', 'project-pages-logic', 'dist', 'logic.cjs');
+const RENDERER_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'web', 'project-pages', 'renderer', 'dist', 'renderer.cjs');
+const LOGIC_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'web', 'project-pages', 'logic', 'dist', 'logic.cjs');
 
 let cachedCatalog = null;
 function loadCatalog() {

package/src/main/lib/projectPageSummarySchema.cjs

@@ -7,7 +7,7 @@
  *
  * 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
+ * in web/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

package/src/main/lib/projectRootResolve.cjs

@@ -34,7 +34,7 @@
  */
 
 const path = require('node:path');
-const { projectRootOf, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { projectRootOf, allProjectCwds } = require('./activeSessions.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
 

package/src/main/lib/queueHistory.cjs

@@ -53,8 +53,15 @@ function historyPathFor(entry) {
   return HISTORY_PATH;
 }
 
+// `kind` keeps a needs_review_entry/needs_review_resolution line (see
+// needsReviewLedger.cjs) from colliding with a TERMINAL row that shares the
+// same slug+runId — an entry and its resolution deliberately reference the
+// SAME runId (that's how they're paired), so without `kind` in the dedupe
+// key the second append would look like a replay of the first and silently
+// never be written. Absent `kind` (every existing terminal row) buckets
+// under 'terminal', so today's on-disk rows and callers are unaffected.
 function jobKey(job) {
-  return `${job?.slug ?? ''}|${job?.runId ?? ''}`;
+  return `${job?.slug ?? ''}|${job?.runId ?? ''}|${job?.kind ?? 'terminal'}`;
 }
 
 /**
@@ -259,6 +266,12 @@ async function historyTerminalBySlug() {
       if (!line.trim()) continue;
       try {
         const j = JSON.parse(line);
+        // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
+        // share this file but aren't a job's terminal record — skip them, or a
+        // needs_review episode logged for a slug AFTER its real terminal row
+        // (e.g. it re-parked on a later run) would overwrite a true 'completed'
+        // with a kind-less, status-less row read as "not terminal".
+        if (j?.kind && j.kind !== 'terminal') continue;
         if (j?.slug) map.set(j.slug, { status: j.status, finishedAt: j.finishedAt, landedCommit: j.landedCommit ?? null });
       } catch {
         // corrupt/partial line — ignore
@@ -301,6 +314,11 @@ async function completedSlugsForCwd(cwd) {
     if (!line.trim()) continue;
     try {
       const j = JSON.parse(line);
+      // Skip needs_review ledger lines (needsReviewLedger.cjs) — they carry
+      // no `status` field, so treating them as a real record would let a
+      // later needs_review park/resolution silently blank out this slug's
+      // last true terminal status.
+      if (j?.kind && j.kind !== 'terminal') continue;
       if (j?.slug) statusBySlug.set(j.slug, j.status);
     } catch {
       // corrupt/partial line — ignore

package/src/main/lib/queueStore.cjs

@@ -33,7 +33,7 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
-const { allProjectCwds, activeProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { allProjectCwds, activeProjectCwds, bustProjectCwdCache } = require('./activeSessions.cjs');
 const { assertOpsWrite, resolveOpsRoot, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 const { ScheduleJobSchema } = require('./scheduleJobSchema.cjs');
 
@@ -211,6 +211,11 @@ function stateCwds(opts) {
 
 function bustCwdCache() {
   cwdCache = { at: 0, cwds: [] };
+  // Without this chain, activeSessions' own scan cache hands stateCwds a
+  // stale list even after this bust — turning a caller's "I just wrote a
+  // brand-new project's first state file, make it visible now" into a
+  // no-op until activeSessions' independent TTL expires.
+  bustProjectCwdCache();
 }
 
 // ---------- merged read ----------

package/src/main/lib/reaperHelpers.cjs

@@ -36,26 +36,37 @@ function claudePidAlive(pid) {
 }
 
 /**
- * findLiveProcessForJob(job, { worktreeDir }) → pid | null
+ * findLiveProcessForJob(job, { worktreeDir, runCwd }) → pid | null
  *
  * Positive liveness scan for a 'running' row whose `runtime.pid` is missing —
  * the case a missing pid must NOT be read as "the process is gone" (2026-09-06
  * incident: 234-uranus-eight-tails-ox marked failed/never_ran while PID
  * 2174739 was a live `claude -p` still writing to that job's own worktree).
  *
- * Linux-`/proc` only. Scans every numeric `/proc/<pid>` entry and matches
- * either: `/proc/<pid>/cwd` resolves to `worktreeDir` (or a path nested under
- * it), or `/proc/<pid>/cmdline` contains both `claude` and the job's slug
- * (fallback for a worktree-disabled/in-place run, where there is no dedicated
- * worktreeDir to match against). Returns the first matching pid, or null if
- * none is found.
+ * Linux-`/proc` only. Scans every numeric `/proc/<pid>` entry and matches any
+ * of, in order:
+ *  - `/proc/<pid>/cwd` resolves to `worktreeDir` (or a path nested under it)
+ *    — sufficient alone, no cmdline check needed.
+ *  - `/proc/<pid>/cmdline` contains both `claude` and the job's slug —
+ *    fallback for a worktree-disabled/in-place run with no dedicated
+ *    worktreeDir to match against.
+ *  - `/proc/<pid>/cwd` resolves to `runCwd` (or nested under it) AND
+ *    `/proc/<pid>/cmdline` contains `claude` (2026-09-13 incident:
+ *    runId 2026-09-13T16-15-56-818Z ran in-place in the shared tree — no
+ *    worktree, and dispatch never puts the slug into argv — so neither of
+ *    the above could ever match a live pid 3138458). `runCwd` is deliberately
+ *    NEVER matched alone: several concurrent jobs commonly share one tree's
+ *    cwd, so a bare cwd match without the process-identity check would
+ *    cross-match the wrong job's process.
+ *
+ * Returns the first matching pid, or null if none is found.
  *
  * Safe fallback by construction: on any platform without `/proc` (macOS,
  * Windows) `fs.readdirSync('/proc')` throws and this returns null immediately
  * — i.e. exactly today's behaviour (fail toward terminalizing), never a hang
  * or a thrown error propagating to the caller.
  */
-function findLiveProcessForJob(job, { worktreeDir } = {}) {
+function findLiveProcessForJob(job, { worktreeDir, runCwd } = {}) {
   const slug = job?.slug;
   let entries;
   try {
@@ -67,27 +78,107 @@ function findLiveProcessForJob(job, { worktreeDir } = {}) {
     if (!/^\d+$/.test(name)) continue;
     const pid = Number(name);
     if (!pid || pid <= 1) continue;
-    if (worktreeDir) {
+
+    let cwdLink = null;
+    if (worktreeDir || runCwd) {
       try {
-        const cwdLink = fs.readlinkSync(`/proc/${pid}/cwd`);
-        if (cwdLink === worktreeDir || cwdLink.startsWith(worktreeDir + path.sep)) return pid;
+        cwdLink = fs.readlinkSync(`/proc/${pid}/cwd`);
       } catch {
         // Process exited mid-scan, or permission denied — try the argv
         // fallback below before giving up on this pid.
       }
     }
-    if (slug) {
+
+    if (worktreeDir && cwdLink && (cwdLink === worktreeDir || cwdLink.startsWith(worktreeDir + path.sep))) {
+      return pid;
+    }
+
+    let cmd = null;
+    if (slug || (runCwd && cwdLink)) {
       try {
-        const cmd = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
-        if (/\bclaude\b/.test(cmd) && cmd.includes(slug)) return pid;
+        cmd = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
       } catch {
         // Same as above — process gone or unreadable, keep scanning.
       }
     }
+
+    if (slug && cmd && /\bclaude\b/.test(cmd) && cmd.includes(slug)) return pid;
+
+    if (runCwd && cwdLink && cmd && /\bclaude\b/.test(cmd) &&
+        (cwdLink === runCwd || cwdLink.startsWith(runCwd + path.sep))) {
+      return pid;
+    }
   }
   return null;
 }
 
+/**
+ * readSpawnedPidFromLog(logPath) → pid | null
+ *
+ * Recovers the pid a pidless row's spawn actually produced by reading the
+ * run's own log — proof of life that pre-dates and is independent of the
+ * `runtime.pid` persistence this reap path exists to route around (2026-09-13
+ * incident: the mutate that stamps runtime.pid failed silently while the
+ * spawn itself, and this exact log line, succeeded). Reads only the first
+ * ~8KB — scheduler.cjs's spawnJob writes `[scheduler] spawned pid=<n> ...`
+ * synchronously right after fork, always near the top of the log — so this
+ * stays cheap against a multi-MB log. Pure IO, never throws: a missing file,
+ * an empty file, or a log with no such line all return null.
+ */
+function readSpawnedPidFromLog(logPath) {
+  if (!logPath) return null;
+  let fd;
+  try {
+    fd = fs.openSync(logPath, 'r');
+    const buf = Buffer.alloc(8192);
+    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+    const text = buf.toString('utf8', 0, bytesRead);
+    const match = text.match(/\[scheduler\] spawned pid=(\d+)/);
+    if (!match) return null;
+    const pid = Number(match[1]);
+    return Number.isFinite(pid) && pid > 1 ? pid : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* already closed / never opened */ }
+    }
+  }
+}
+
+/**
+ * readLogMtimeMs(logPath) → number | null
+ *
+ * Same never-throws IO contract as logHasOutput — returns the run log's
+ * last-modified time, or null when it can't be statted (missing file,
+ * permission denied).
+ */
+function readLogMtimeMs(logPath) {
+  if (!logPath) return null;
+  try {
+    return fs.statSync(logPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * isLogFresh(logMtimeMs, now, windowMs) → boolean
+ *
+ * Pure predicate: true when a run log was modified within `windowMs` of
+ * `now`. A log that grew recently is positive, independent proof its process
+ * is still alive — stronger evidence than "no runtime.pid recorded", which is
+ * only bookkeeping about a side-channel write that can fail on its own (see
+ * readSpawnedPidFromLog's header). Returns false for a missing/invalid mtime
+ * or window so a caller that couldn't stat the log falls through to the
+ * existing reap logic rather than treating "unknown" as "fresh".
+ */
+function isLogFresh(logMtimeMs, now, windowMs) {
+  if (typeof logMtimeMs !== 'number' || Number.isNaN(logMtimeMs)) return false;
+  if (typeof windowMs !== 'number' || windowMs <= 0) return false;
+  return (now - logMtimeMs) < windowMs;
+}
+
 /**
  * True when `logPath` exists and has non-zero content — the literal "did the
  * run dir produce any log output" check that gates whether a pidless reap may
@@ -224,6 +315,20 @@ const ORPHAN_REQUEUE_CAP = 5;
  * work (2026-09-06 incident — see findLiveProcessForJob's header). Omitting
  * `findLiveProcess` (existing callers/tests) preserves prior behaviour
  * exactly: every pidless row past grace reaps, none are ever recovered.
+ *
+ * Two more optional injections, checked BEFORE `findLiveProcess`, for a
+ * pidless row past grace (2026-09-13 incident — see readSpawnedPidFromLog's
+ * and isLogFresh's own headers):
+ *  - `getLogMtimeMs` (`(job) → number | null`): if the row's run log was
+ *    modified within `logFreshWindowMs`, the row is skipped entirely — not
+ *    pushed to `reapable` OR `recovered` — because a growing log is positive
+ *    proof of life even with no pid evidence at all. One `warnings` entry is
+ *    still emitted so a permanently-pidless-but-chatty row stays visible.
+ *  - `getLogPid` (`(job) → pid | null`): reads the run's own log for the pid
+ *    its spawn actually produced. If `pidAlive(pid)` is true, the row is
+ *    diverted into `recovered` exactly like a `findLiveProcess` hit.
+ * Both default to a no-op when omitted, so existing callers/tests are
+ * unaffected.
  */
 /**
  * Pure, never-throws formatter for the dispatch-phase breadcrumb appended to
@@ -246,7 +351,47 @@ function formatDispatchPhaseSuffix(j) {
     : ` (last dispatch phase: ${j.dispatchPhase})`;
 }
 
-function selectReapableJobs(jobs, now, { pidAlive, grace, findLiveProcess } = {}) {
+/**
+ * resolvePidlessFailureOverride(job) → { verdict, landedCommit, reason } | null
+ *
+ * The evidence-before-failure guard this PRD adds (1173): a pidless reap
+ * about to stamp 'failed' purely because `runtime.pid` was never recorded
+ * must first check whether THIS ROW already carries a `landedCommit` — proof
+ * (from an earlier dispatch of the same slug, since `landedCommit` is
+ * deliberately never cleared by a reset — see scheduler.cjs's comment near
+ * resetJobFields) that a real commit landed on the branch. Returns null when
+ * there is no such evidence, leaving the existing 'failed' transition for a
+ * genuinely-never-spawned row completely untouched.
+ *
+ * DESTINATION CHOICE — needs_review, never completed. `landedCommit` is
+ * real git evidence (it is only ever stamped from an actual HEAD advance or
+ * a proven branch-integration — see jobLandedCommitThisRun / the dead-pid
+ * reap's own isBranchAlreadyIntegrated+computeCommittedDuringRun proof in
+ * scheduler.cjs), so it is never speculative in the sense of "guessed before
+ * the work ran". But the pidless-reap path performs NO fresh integration
+ * check of its own for the CURRENT run (that proof only runs for the dead-pid
+ * branch's `dead` entries with outcome==='success' — see
+ * scheduler.cjs's integrationResults loop) — so at this call site there is no
+ * re-verified guarantee that the recorded commit corresponds to *this*
+ * dispatch rather than surviving, unreaped, from an earlier one. Real
+ * evidence that under-specifies correspondence to the current run is exactly
+ * the needs_review shape, not completed: a human (or the finish-protocol
+ * commit-guard on the next dispatch) can resolve it conclusively with
+ * `git show <sha>`, but this pure predicate must not guess.
+ */
+function resolvePidlessFailureOverride(job) {
+  const landedCommit = job?.landedCommit || null;
+  if (!landedCommit) return null;
+  return {
+    verdict: 'pidless_reap_with_landed_commit',
+    landedCommit,
+    reason: `pidless reap found no runtime.pid, but this row already carries landedCommit ${landedCommit} — routing to needs_review instead of failed; verify with \`git show ${landedCommit}\``,
+  };
+}
+
+function selectReapableJobs(jobs, now, {
+  pidAlive, grace, findLiveProcess, getLogMtimeMs, getLogPid, logFreshWindowMs,
+} = {}) {
   const reapable = [];
   const warnings = [];
   const recovered = [];
@@ -265,6 +410,22 @@ function selectReapableJobs(jobs, now, { pidAlive, grace, findLiveProcess } = {}
     }
     const ageMs = now - startedAt;
     if (ageMs < grace) continue; // spawn may still be mid-flight
+
+    const logMtimeMs = typeof getLogMtimeMs === 'function' ? getLogMtimeMs(j) : null;
+    if (isLogFresh(logMtimeMs, now, logFreshWindowMs)) {
+      warnings.push({
+        slug: j.slug,
+        reason: `pidless row skipped — run log modified ${Math.round((now - logMtimeMs) / 1000)}s ago, still alive by log evidence`,
+      });
+      continue; // neither reapable nor recovered — the log proves it's alive
+    }
+
+    const logPid = typeof getLogPid === 'function' ? getLogPid(j) : null;
+    if (logPid && pidAlive(logPid)) {
+      recovered.push({ slug: j.slug, pid: logPid });
+      continue;
+    }
+
     const livePid = typeof findLiveProcess === 'function' ? findLiveProcess(j) : null;
     if (livePid) {
       recovered.push({ slug: j.slug, pid: livePid });
@@ -275,6 +436,7 @@ function selectReapableJobs(jobs, now, { pidAlive, grace, findLiveProcess } = {}
       pid: null,
       pidless: true,
       reason: `reaped: no runtime.pid recorded after ${Math.round(grace / 60_000)}m — spawn never completed${formatDispatchPhaseSuffix(j)}`,
+      failureOverride: resolvePidlessFailureOverride(j),
     });
   }
   return { reapable, warnings, recovered };
@@ -343,7 +505,11 @@ module.exports = {
   findLiveProcessForJob,
   logHasOutput,
   resolvePidlessGateOutcome,
+  resolvePidlessFailureOverride,
   isAlreadySatisfiedOnMain,
   resolveCommitGuardOutcome,
   formatDispatchPhaseSuffix,
+  readSpawnedPidFromLog,
+  readLogMtimeMs,
+  isLogFresh,
 };

package/src/main/lib/scheduleJobSchema.cjs

@@ -124,6 +124,14 @@ const ScheduleJobSchema = z
     // finalize (both the normal completion path and reapDeadRunningJobs).
     dispatchPhase: z.string().optional(),
     dispatchPhaseAt: z.string().optional(),
+    // needs_review episode bookkeeping (needsReviewLedger.cjs / PRD: needs_review
+    // durability): stamped by scheduleJobTransitions.cjs the instant a job
+    // transitions INTO 'needs_review', so the RESOLUTION line written when it
+    // later transitions back OUT can reference the same runId and compute a
+    // truthful dwell time — same lifecycle as heldReason/dispatchPhase (stamped
+    // at entry, deleted at resolution).
+    needsReviewEntryRunId: z.string().nullable().optional(),
+    needsReviewEnteredAt: z.string().nullable().optional(),
   })
   .passthrough();