claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/jobSupervisorRecord.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * jobSupervisorRecord.cjs — the one authoritative, SYNCHRONOUS record of a
+ * dispatch, written at the same point scheduler.cjs logs `[scheduler] spawned
+ * pid=`.
+ *
+ * Before this, the only durable trace of a dispatch was runtime={pid,...},
+ * written asynchronously by a mutate() inside the onPid callback, and the run
+ * dir held only the log until an exit path wrote meta.json. A booting process
+ * therefore had nothing to tell "my run, still alive" from "dead" and fell
+ * back to a ladder of inferences. `<runDir>/<slug>.supervisor.json` is that
+ * missing fact.
+ *
+ * Plain Node, no electron. The run dir is machine-wide scheduler state (not
+ * an ops namespace), so queueStore's writeJsonAtomicSync is the right writer.
+ * This module never signals a process and adds no cap accounting.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { writeJsonAtomicSync } = require('./queueStore.cjs');
+const { isDifferentProcess } = require('./procIdentity.cjs');
+
+const SUFFIX = '.supervisor.json';
+const META_SUFFIX = '.meta.json';
+const INVESTIGATION_EXIT_RE = /\[scheduler\] investigation exit code=/;
+const EXIT_TAIL_BYTES = 8 * 1024;
+
+function recordPath(runDir, slug) {
+  return path.join(runDir, `${slug}${SUFFIX}`);
+}
+
+/**
+ * Writes `<runDir>/<slug>.supervisor.json` atomically. Throws on failure —
+ * the caller owns the "never fail the dispatch" try/catch. `kind` defaults to
+ * "job"; an investigation probe passes kind: "investigation" (and a slug of
+ * `<failedSlug>.investigation`, so it never overwrites the failed job's own
+ * record in the shared run dir).
+ */
+function writeSupervisorRecord({
+  runDir, slug, cwd, runId, pid, pgid, identity, execCwd, worktreeDir, worktreeBranch,
+  sessionId, startedAt, budgetMs, maxDurationMs, idleKillMs, schedulerPid, codeSha, kind,
+}) {
+  if (!runDir || !slug) throw new Error('writeSupervisorRecord: runDir and slug are required');
+  const record = {
+    kind: kind || 'job',
+    slug, cwd: cwd ?? null, runId: runId ?? null,
+    pid: pid ?? null, pgid: pgid ?? null, identity: identity ?? null,
+    execCwd: execCwd ?? null, worktreeDir: worktreeDir ?? null, worktreeBranch: worktreeBranch ?? null,
+    sessionId: sessionId ?? null, startedAt: startedAt ?? null,
+    budgetMs: budgetMs ?? null, maxDurationMs: maxDurationMs ?? null, idleKillMs: idleKillMs ?? null,
+    schedulerPid: schedulerPid ?? null, codeSha: codeSha ?? null,
+  };
+  writeJsonAtomicSync(recordPath(runDir, slug), record);
+  return record;
+}
+
+/** Returns the parsed record, or null when absent/unparseable. Never throws. */
+function readSupervisorRecord(runDir, slug) {
+  try {
+    const rec = JSON.parse(fs.readFileSync(recordPath(runDir, slug), 'utf8'));
+    return rec && typeof rec === 'object' ? rec : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when the run has a durable exit marker: `<slug>.meta.json` for a job,
+ * the `investigation exit code=` log line for a probe. This is what separates
+ * "exited" from "dead" — a dead pid with no marker never got to write one.
+ */
+function hasExitMarker(runDir, record) {
+  try {
+    if (record.kind === 'investigation') {
+      const failedSlug = String(record.slug).replace(/\.investigation$/, '');
+      const logPath = path.join(runDir, `${failedSlug}.investigation.log`);
+      const { size } = fs.statSync(logPath);
+      const fd = fs.openSync(logPath, 'r');
+      try {
+        const len = Math.min(size, EXIT_TAIL_BYTES);
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, size - len);
+        return INVESTIGATION_EXIT_RE.test(buf.toString('utf8'));
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+    return fs.existsSync(path.join(runDir, `${record.slug}${META_SUFFIX}`));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every record under `runsDir/<runId>/` whose file was written within
+ * maxAgeMs and which has no exit marker yet. Each entry is the record plus
+ * `runDir`. Never throws; an unreadable dir yields [].
+ * Complexity: O(run dirs + files in recent dirs).
+ */
+function listLiveSupervisorRecords(runsDir, { maxAgeMs, now = Date.now() } = {}) {
+  const out = [];
+  let dirs;
+  try { dirs = fs.readdirSync(runsDir, { withFileTypes: true }); } catch { return out; }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const runDir = path.join(runsDir, d.name);
+    let files;
+    try { files = fs.readdirSync(runDir); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith(SUFFIX)) continue;
+      try {
+        if (Number.isFinite(maxAgeMs) && now - fs.statSync(path.join(runDir, f)).mtimeMs > maxAgeMs) continue;
+        const record = readSupervisorRecord(runDir, f.slice(0, -SUFFIX.length));
+        if (!record || hasExitMarker(runDir, record)) continue;
+        out.push({ ...record, runDir });
+      } catch { /* raced with a delete — skip */ }
+    }
+  }
+  return out;
+}
+
+/**
+ * Pure. What should a booting process do with this record?
+ *   - not alive + exit marker   → 'exited'   (finished; outcome is on disk)
+ *   - not alive, no marker      → 'dead'     (died without writing an outcome)
+ *   - alive, different process  → 'foreign-pid' (pid recycled; never ours)
+ *   - alive, ours, past budget or log stalled past idleKillMs → 'over-budget'
+ *   - alive, ours               → 'adopt'
+ * `identity` is the live probe of record.pid; isDifferentProcess is
+ * fail-closed, so an incomplete identity on either side reads as "same".
+ */
+function classifyAdoption(record, { identity, pidAlive, logMtimeMs, exitMarker, now = Date.now() } = {}) {
+  if (!pidAlive) return exitMarker ? 'exited' : 'dead';
+  if (exitMarker) return 'exited';
+  if (isDifferentProcess(record.identity, identity)) return 'foreign-pid';
+  const ceiling = record.budgetMs > 0 ? record.budgetMs : (record.maxDurationMs > 0 ? record.maxDurationMs : 0);
+  if (ceiling > 0 && Number.isFinite(record.startedAt) && now - record.startedAt > ceiling) return 'over-budget';
+  if (record.idleKillMs > 0 && Number.isFinite(logMtimeMs) && now - logMtimeMs > record.idleKillMs) return 'over-budget';
+  return 'adopt';
+}
+
+module.exports = {
+  writeSupervisorRecord, readSupervisorRecord, listLiveSupervisorRecords, classifyAdoption, hasExitMarker,
+  SUFFIX,
+};

package/src/main/lib/jobWorktreeBootLive.cjs

@@ -22,15 +22,19 @@
  */
 
 /**
- * @param {{ bootJobs: Array<object>, claudePidAlive: (pid: number) => boolean, hasLiveHolder: (dir: string, holders?: Set<string>) => boolean, cwdHolders?: Set<string> }} deps
+ * `rowPid(job)` resolves a running row's pid; scheduler.cjs passes the same
+ * supervisor-record → runtime.pid → run-log ladder partitionBootOrphans uses,
+ * so the two boot passes agree. Default: runtime.pid alone.
+ *
+ * @param {{ bootJobs: Array<object>, claudePidAlive: (pid: number) => boolean, hasLiveHolder: (dir: string, holders?: Set<string>) => boolean, cwdHolders?: Set<string>, rowPid?: (job: object) => number|null }} deps
  * @returns {(slug: string, entry: { worktree: string, branch: string|null }) => boolean}
  */
-function buildJobWorktreeIsLive({ bootJobs, claudePidAlive, hasLiveHolder, cwdHolders }) {
+function buildJobWorktreeIsLive({ bootJobs, claudePidAlive, hasLiveHolder, cwdHolders, rowPid = (j) => j.runtime && j.runtime.pid }) {
   const runningPidBySlug = new Map();
   for (const j of Array.isArray(bootJobs) ? bootJobs : []) {
-    if (j && j.status === 'running' && j.runtime && j.runtime.pid) {
-      runningPidBySlug.set(j.slug, j.runtime.pid);
-    }
+    if (!j || j.status !== 'running') continue;
+    const pid = rowPid(j);
+    if (pid) runningPidBySlug.set(j.slug, pid);
   }
 
   return function isLive(slug, entry) {

package/src/main/lib/launchFailure.cjs

@@ -309,9 +309,10 @@ function evaluateLaunchGate(block, { now, claudeVersion } = {}) {
  * closed set so operators never have to open a transcript to tell a
  * non-start from an implementation failure from a verifier downgrade.
  */
-function deriveTerminalReason({ effectiveStatus, exitCode, verifyResult, sigtermOverride, worktreeIntegrationFailure }) {
+function deriveTerminalReason({ effectiveStatus, exitCode, verifyResult, sigtermOverride, worktreeIntegrationFailure, budgetKill }) {
   if (worktreeIntegrationFailure) return 'worktree_integration_failed';
   if (effectiveStatus === 'completed') return 'completed';
+  if (budgetKill) return 'budget_exceeded';
   if (sigtermOverride) return 'signal_kill_with_commit';
   if (exitCode === 143 || exitCode === 137) return 'signal_kill';
   if (typeof exitCode === 'number' && exitCode !== 0) return `impl_failed:exit_${exitCode}`;

package/src/main/lib/localAdminHttp.cjs

@@ -32,40 +32,20 @@
 'use strict';
 
 const http = require('node:http');
-const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const fsp = require('node:fs/promises');
 const config = require('../config.cjs');
-
-const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.json');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 /**
- * Mode-aware token file path, resolved fresh on every call (not cached at
+ * Mode-aware token file path, resolved fresh on every call (never cached at
  * module load) so a dev/e2e launch never collides with a production
- * instance's admin-api.json. index.cjs treats SM_DEV and SM_E2E as one OR'd
- * `isDev` boolean with no ordering between them; if both happen to be set,
- * this resolves to the SM_DEV path (checked first below) — an arbitrary but
- * harmless tie-break, since real launches only ever set one or the other.
+ * instance's admin-api.json. The SM_ADMIN_TOKEN_PATH / SM_DEV / SM_E2E ladder
+ * lives in schedulerPaths.adminTokenPath() (the SM_ADMIN_TOKEN_PATH override
+ * exists because unit tests once overwrote the live app's port+token).
  */
-function resolveTokenPath() {
-  // Explicit override, highest priority. Exists because the unit tests call
-  // createAdminHttp().start() directly with neither SM_DEV nor SM_E2E set,
-  // which resolved to the PRODUCTION admin-api.json and overwrote the
-  // running app's port+token with a throwaway test server's — silently
-  // orphaning scheduler-mcp-server.cjs's access to the live app until the
-  // next app restart (confirmed live 2026-08-01: `npm run test:unit` made
-  // every scheduler_* MCP tool report "app is not running"). Tests point
-  // this at a tmp file; production never sets it.
-  if (process.env.SM_ADMIN_TOKEN_PATH) return process.env.SM_ADMIN_TOKEN_PATH;
-  if (process.env.SM_DEV === '1') {
-    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.dev.json');
-  }
-  if (process.env.SM_E2E === '1') {
-    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.e2e.json');
-  }
-  return TOKEN_PATH;
-}
+const resolveTokenPath = schedulerPaths.adminTokenPath;
 
 // Reserved health-check path, handled directly (not via registerRoute) so
 // start()'s post-boot self-check never depends on route-registration order
@@ -238,9 +218,11 @@ function createAdminHttp() {
 
 module.exports = {
   createAdminHttp,
-  TOKEN_PATH,
   resolveTokenPath,
   timingSafeEqualStrings,
   readBody,
   sendJson,
 };
+
+// Lazy getter (the token path is mode-aware and env-driven; never frozen at require).
+Object.defineProperty(module.exports, 'TOKEN_PATH', { get: () => schedulerPaths.adminTokenPath(), enumerable: true });

package/src/main/lib/mcpToolCatalog.cjs

@@ -47,6 +47,24 @@ const MCP_TOOL_CATALOG = [
     exampleArgs: { slug: 'add-mcp-tool-catalog', force: false },
     notes: 'Refuses a job whose status is already "completed" unless force:true is passed — resetting a completed job re-executes already-shipped work.',
   },
+  {
+    name: 'scheduler_pause',
+    group: 'scheduler',
+    purpose: "Pause the scheduler (user-initiated) via the session-manager app's admin API.",
+    whenToUse: 'Use to stop NEW job dispatch on request (e.g. before a risky change). Running jobs are never killed.',
+    whenNotToUse: 'Do not use to cancel a running job (use scheduler_cancel_job) or as a workaround for a stuck queue.',
+    exampleArgs: {},
+    notes: 'A manual pause survives app restart and is never auto-cleared by the rate-limit timer or network recovery — only scheduler_resume clears it.',
+  },
+  {
+    name: 'scheduler_resume',
+    group: 'scheduler',
+    purpose: "Clear any scheduler pause (manual or automatic) via the session-manager app's admin API.",
+    whenToUse: 'Use to restart dispatch after scheduler_pause, or to lift an auto-pause you have judged stale.',
+    whenNotToUse: 'Do not use to retry a parked needs_review job — that is scheduler_reset_job.',
+    exampleArgs: {},
+    notes: null,
+  },
   {
     name: 'scheduler_list_jobs',
     group: 'scheduler',
@@ -75,7 +93,10 @@ const MCP_TOOL_CATALOG = [
       + '`tag` and `agentType` are two DIFFERENT, independent fields — `tag` is WHAT KIND '
       + 'of work this PRD is (feature/bug/build/...); `agentType` is WHO executes it (a '
       + 'persona name, e.g. "dev-lead"). `agentType` defaults to "dev-lead" when omitted, '
-      + 'and is rejected at write time if it does not name a real persona file.',
+      + 'and is rejected at write time if it does not name a real persona file. '
+      + 'If this PRD has no dependsOn of its own AND the target Epic already has incomplete PRDs, '
+      + '`disposition` ("append" or "new-head") is REQUIRED — the write is refused without it (a '
+      + 'headless job caller instead gets a logged "append" default, since no human is present to ask).',
     whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
     whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
       + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '
@@ -221,65 +242,18 @@ const MCP_TOOL_CATALOG = [
       + 'delivered.',
   },
   {
-    name: 'project_home_get_contract',
-    group: 'project-home',
-    purpose: "Fetch the self-sufficient contract for generating this project's Project Home pages via the "
-      + "session-manager app's admin API — the protocol steps, the ProjectPageSummary/ProjectPagePicks JSON "
-      + 'schemas, the component catalog (all 5 lenses: home, marketing, feature, architecture, brief), the '
-      + 'absolute output paths, and the full pipeline spec text. Nothing in the response requires reading '
-      + "session-manager's own repo — this is what makes generation work on a machine with only the npm "
-      + 'package installed.',
-    whenToUse: 'Call this FIRST, before composing any ProjectPageSummary content or picking variants, whenever '
-      + 'a project-home-builder session starts generating Project Home pages for a project.',
-    whenNotToUse: 'Do not begin composing a ProjectPageSummary or choosing variants before calling this — it '
-      + 'must be the FIRST call a project-home-builder session makes; every other project_home_* tool assumes '
-      + "you already have this response's schema/catalog/paths in hand.",
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_validate_summary',
-    group: 'project-home',
-    purpose: 'Validate a composed ProjectPageSummary against the schema from project_home_get_contract via the '
-      + "session-manager app's admin API, without writing anything to disk.",
-    whenToUse: 'Use after composing (or editing) a ProjectPageSummary and before calling project_home_render — '
-      + 'fix every returned {field, message} error and re-validate until valid:true.',
-    whenNotToUse: 'Do not skip straight to project_home_render on an unvalidated summary — render does '
-      + 're-validate server-side and rejects with no writes on failure, but catching errors here first saves a '
-      + 'round trip and gives per-field detail sooner.',
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', summary: { title: 'Example Project' } },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_render',
-    group: 'project-home',
-    purpose: 'Render and write all 5 Project Home lenses (home, marketing, feature, architecture, brief) plus '
-      + "summary.json/picks.json/manifest.json via the session-manager app's admin API — the only write path "
-      + 'for Project Home generation.',
-    whenToUse: 'Use once project_home_validate_summary reports valid:true and a variant has been picked for '
-      + "every lens/slot in the contract's catalog.",
-    whenNotToUse: 'Must NOT be used to fabricate summary content — every field of the summary passed here must '
-      + 'trace to something concrete about the real project (an Epic goal, a source file/dir, a convention, a '
-      + 'git log entry). This tool re-validates the summary server-side and rejects with no writes on schema '
-      + 'failure, but it only checks shape, never truthfulness.',
-    exampleArgs: {
-      cwd: '/home/bilko/Projects/session-manager',
-      summary: { title: 'Example Project' },
-      picks: { home: { hero: 'variant-a' } },
-    },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_status',
+    name: 'project_home_write',
     group: 'project-home',
-    purpose: "Report what already exists for this project's Project Home generation via the session-manager "
-      + "app's admin API — summary.json/picks.json/each lens file's existence + mtime, and manifest.json's "
-      + 'generatedAt.',
-    whenToUse: 'Use before starting generation to see prior state, and again after project_home_render to '
-      + 'confirm the new files landed.',
-    whenNotToUse: 'Do not treat an all-absent result as an error — a project that has never generated a '
-      + 'Project Home page yet still returns a well-formed status with every exists:false rather than failing.',
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
+    purpose: "Write this project's Project Home page — ONE self-contained HTML document — to "
+      + "session-manager-operations/project-pages/home.html via the session-manager app's admin API. "
+      + 'The only write path for Project Home.',
+    whenToUse: 'Use when asked to generate or refresh the project home page. Compose the whole page yourself '
+      + '(inline <style>/<script>, data: URIs for assets) from what is really true about the project, then '
+      + 'pass the full document as `html`.',
+    whenNotToUse: 'Never fabricate content — every claim must trace to something concrete in the project. The '
+      + 'document must be self-contained: the call is rejected for empty input, more than 1MB, any '
+      + '<script src>, <link href="http…">, @import, or url(http…) — no network egress.',
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', html: '<!DOCTYPE html><html><body><h1>Example</h1></body></html>' },
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
   },
   {
@@ -332,25 +306,6 @@ const MCP_RECIPES = [
       'The call only delivers a PROPOSED session in the receiving project — nothing runs until a human there presses Approve & start; there is no reply channel.',
     ],
   },
-  {
-    id: 'generate-project-home',
-    title: "Generate a project's Project Home pages",
-    steps: [
-      "Call project_home_get_contract to get the protocol, ProjectPageSummary/ProjectPagePicks schemas, "
-        + 'component catalog, absolute output paths, and pipeline spec — the FIRST call any '
-        + 'project-home-builder session makes.',
-      'Author a ProjectPageSummary matching the contract\'s summarySchema — every field must trace to '
-        + 'something concrete about the real project; never fabricate content.',
-      'Call project_home_validate_summary with { cwd, summary } and fix every {field, message} error it '
-        + 'returns, re-validating until valid:true.',
-      "For each lens and slot in the contract's catalog, choose exactly one variant id by judging the "
-        + 'candidate variants against the summary you composed, assembling a ProjectPagePicks object '
-        + '(lensId -> slotId -> variantId).',
-      'Call project_home_render with { cwd, summary, picks } to render all 5 lenses and write '
-        + 'summary.json/picks.json/output files.',
-      "Call project_home_status to confirm the new files landed and read manifest.json's generatedAt.",
-    ],
-  },
 ];
 
 for (const entry of MCP_TOOL_CATALOG) {

package/src/main/lib/needsReviewLedger.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+/**
+ * needsReviewLedger.cjs — pure helpers that make `needs_review` episodes
+ * durable and queryable in history.jsonl.
+ *
+ * Before this module, `queueHistory.cjs` archived a job to history.jsonl
+ * only on a TERMINAL status (completed/failed/skipped) — a needs_review
+ * park never left queue.json's hot jobs[] (it isn't terminal; see
+ * queueHistory.cjs's partitionJobs), so it never reached durable history
+ * either. Profiling history.jsonl for "how much needs_review is really
+ * happening" therefore always returned zero, however loud the problem
+ * looked in the UI.
+ *
+ * Two line shapes are appended to the SAME history.jsonl a terminal row
+ * lands in, distinguished by `kind` so existing terminal-only readers can
+ * filter them out on sight (see scheduleJobTransitions.cjs, the actual
+ * write choke point, and its callers' audit in the owning PRD):
+ *   - kind: 'needs_review_entry'      — one per transition INTO needs_review
+ *   - kind: 'needs_review_resolution' — one per transition OUT of needs_review,
+ *     referencing the entry's own runId so the two can be paired
+ *
+ * Kept fs-free and pure (mirrors reaperHelpers.cjs's rationale) so the
+ * ladder-rung classification and rollup reduction are unit-testable without
+ * touching disk or importing scheduler.cjs (which requires electron).
+ */
+
+// The 6 named ladder rungs a needs_review episode can resolve through
+// (spawnJob's mechanical/resume/quarantine/auto-fix branches, the periodic
+// reverifyNeedsReview heal pass, or an explicit human/API reset). Any
+// resolution whose transitionJob `source` doesn't match a known automated
+// rung is bucketed as 'manual-reset' — the conservative default for
+// anything that isn't a recognized self-healing path.
+const LADDER_RUNGS = [
+  'mechanical-recovery',
+  'resume-recovery',
+  'quarantine',
+  'auto-fix',
+  'reverify',
+  'manual-reset',
+];
+
+/**
+ * classifyLadderRung({ source, reason }) → one of LADDER_RUNGS.
+ *
+ * Matches the exact `source` strings scheduleJobTransitions.cjs's callers in
+ * scheduler.cjs pass for each recovery-ladder rung (see that module's
+ * LEGAL_TRANSITIONS doc comment for the full call-site inventory). Pattern
+ * matching, not an exhaustive enum lookup, because 'spawnJob:dispatch' is
+ * shared between the ordinary pending->running dispatch and the
+ * needs_review->running resume-recovery dispatch — the two are only
+ * distinguishable by `reason` text.
+ */
+function classifyLadderRung({ source, reason } = {}) {
+  const s = typeof source === 'string' ? source : '';
+  const r = typeof reason === 'string' ? reason : '';
+
+  if (s === 'scheduler:mechanicalRecovery') return 'mechanical-recovery';
+  if (s === 'spawnJob:dispatch' && /resume-recovery/i.test(r)) return 'resume-recovery';
+  if (s === 'spawnInvestigation:start' || s === 'spawnJob:auto-promote' || s === 'reverifyNeedsReview:auto-promote') {
+    return 'auto-fix';
+  }
+  if (s === 'reverifyNeedsReview:heal' || s === 'needsReviewAutoResolve') return 'reverify';
+  // No transitionJob call site resolves needs_review with a 'quarantine'
+  // source today (performLeftoverQuarantine cleans up leftover paths without
+  // itself changing job.status — the row stays needs_review until a later
+  // reverify/auto-resolve pass actually resolves it), but the rung is kept
+  // in LADDER_RUNGS/this classifier so a future direct-resolving quarantine
+  // path is classified correctly without another migration.
+  return 'manual-reset';
+}
+
+/**
+ * buildNeedsReviewEntryLine(job, entry) → JSONL-ready object.
+ *
+ * `entry` is the statusHistory record scheduleJobTransitions.cjs just
+ * pushed for this transition ({ from, to, reason, source, at }). The park
+ * reason prefers the structured `verifierVerdict` (a short, bucketable
+ * code) over the free-text `heldReason`/`error` fields, since those are the
+ * only reason evidence available for parks that never went through the
+ * verifier (e.g. a pidless-reap needs_review park).
+ */
+function buildNeedsReviewEntryLine(job, entry) {
+  return {
+    kind: 'needs_review_entry',
+    slug: job?.slug ?? null,
+    cwd: job?.cwd ?? null,
+    epicId: job?.epicId ?? null,
+    runId: job?.runId ?? null,
+    at: entry?.at ?? new Date().toISOString(),
+    reason: job?.verifierVerdict ?? job?.heldReason ?? job?.error ?? null,
+    source: entry?.source ?? null,
+  };
+}
+
+/**
+ * buildNeedsReviewResolutionLine(job, entry, episode) → JSONL-ready object.
+ *
+ * `episode` is `{ runId, enteredAt }` captured off the job at entry time
+ * (needsReviewEntryRunId/needsReviewEnteredAt) — the resolution line
+ * references the ENTRY's runId (which may differ from `job.runId` by
+ * resolution time, e.g. after a resume-recovery re-dispatch minted a fresh
+ * one), not whatever runId the job carries right now.
+ */
+function buildNeedsReviewResolutionLine(job, entry, episode) {
+  const enteredAtMs = episode?.enteredAt ? Date.parse(episode.enteredAt) : NaN;
+  const resolvedAtMs = entry?.at ? Date.parse(entry.at) : NaN;
+  const dwellMs = Number.isFinite(enteredAtMs) && Number.isFinite(resolvedAtMs)
+    ? Math.max(0, resolvedAtMs - enteredAtMs)
+    : null;
+  return {
+    kind: 'needs_review_resolution',
+    slug: job?.slug ?? null,
+    cwd: job?.cwd ?? null,
+    epicId: job?.epicId ?? null,
+    runId: episode?.runId ?? job?.runId ?? null,
+    at: entry?.at ?? new Date().toISOString(),
+    resolvedTo: entry?.to ?? null,
+    ladderRung: classifyLadderRung({ source: entry?.source, reason: entry?.reason }),
+    source: entry?.source ?? null,
+    dwellMs,
+  };
+}
+
+function percentile(sortedValues, p) {
+  if (!sortedValues.length) return null;
+  const idx = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil((p / 100) * sortedValues.length) - 1));
+  return sortedValues[idx];
+}
+
+/**
+ * reduceNeedsReviewLedger(lines) → rollup.
+ *
+ * Pure O(n log n) reduction (the log n is the dwell-time sort for the
+ * percentiles) over a flat array of already-parsed history.jsonl rows
+ * (mixing needs_review_entry/needs_review_resolution/terminal rows is fine —
+ * anything that isn't one of the two kinds this module writes is ignored).
+ *
+ * Pairs an entry with its resolution by (slug, runId) — the same pairing
+ * key buildNeedsReviewResolutionLine's `episode.runId` guarantees matches
+ * the entry line's `runId`. A slug that parks twice (two different runIds)
+ * produces two independent pairs, matching two independent recovery
+ * episodes rather than being conflated into one.
+ *
+ * Returns:
+ *   - byReason:     { [reason]: entryCount }   (reason = entry line's `reason`, or 'unknown')
+ *   - byLadderRung: { [rung]: resolutionCount } (rung = one of LADDER_RUNGS)
+ *   - unresolvedCount: entries with no matching resolution line yet
+ *   - dwellMsP50 / dwellMsP90: percentiles over resolved episodes' dwellMs (null if none)
+ */
+function reduceNeedsReviewLedger(lines) {
+  const list = Array.isArray(lines) ? lines : [];
+  const entriesByKey = new Map();
+  const resolutionsByKey = new Map();
+
+  for (const line of list) {
+    if (!line || typeof line !== 'object') continue;
+    const key = `${line.slug ?? ''}|${line.runId ?? ''}`;
+    if (line.kind === 'needs_review_entry') {
+      entriesByKey.set(key, line);
+    } else if (line.kind === 'needs_review_resolution') {
+      resolutionsByKey.set(key, line);
+    }
+  }
+
+  const byReason = {};
+  let unresolvedCount = 0;
+  for (const [key, entry] of entriesByKey) {
+    const reason = entry.reason ?? 'unknown';
+    byReason[reason] = (byReason[reason] ?? 0) + 1;
+    if (!resolutionsByKey.has(key)) unresolvedCount += 1;
+  }
+
+  const byLadderRung = {};
+  const dwellMsValues = [];
+  for (const [key, resolution] of resolutionsByKey) {
+    const rung = LADDER_RUNGS.includes(resolution.ladderRung) ? resolution.ladderRung : 'manual-reset';
+    byLadderRung[rung] = (byLadderRung[rung] ?? 0) + 1;
+    // Only count dwell for episodes that actually matched an entry — a
+    // resolution line with no paired entry (e.g. history truncated by
+    // retention before the entry aged out — never happens for needs_review
+    // rows today since they're excluded from partitionJobs' archivable set,
+    // but this stays defensive) has no truthful dwell to report.
+    if (entriesByKey.has(key) && typeof resolution.dwellMs === 'number' && Number.isFinite(resolution.dwellMs)) {
+      dwellMsValues.push(resolution.dwellMs);
+    }
+  }
+  dwellMsValues.sort((a, b) => a - b);
+
+  return {
+    byReason,
+    byLadderRung,
+    unresolvedCount,
+    dwellMsP50: percentile(dwellMsValues, 50),
+    dwellMsP90: percentile(dwellMsValues, 90),
+  };
+}
+
+module.exports = {
+  LADDER_RUNGS,
+  classifyLadderRung,
+  buildNeedsReviewEntryLine,
+  buildNeedsReviewResolutionLine,
+  reduceNeedsReviewLedger,
+};

package/src/main/lib/opsErrorLog.cjs

@@ -107,7 +107,7 @@ function writeLocalLine({ cwd, scope, level, tabId, epicId, tags, message, meta
 function reportToTelemetry({ cwd, scope, level, tabId, epicId, tags, message }) {
   try {
     const telemetryClient = require('./telemetryClient.cjs');
-    const { projectRootOf } = require('../../../scripts/lib/activeSessions.cjs');
+    const { projectRootOf } = require('./activeSessions.cjs');
     const normalizedCwd = projectRootOf(cwd) || cwd;
     const autoTags = [
       `scope:${scope || 'unknown'}`,