claude-code-session-manager 0.57.1 → 0.59.0

package/src/main/scheduler.cjs

@@ -63,6 +63,7 @@ const prdParser = require('./scheduler/prdParser.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 const { enqueueExternalPrompt } = require('./chatRunner.cjs');
 const { appendResponseEventIfKnown } = require('./promptSessionEvents.cjs');
+const { maybeEnqueueValidationPrompt } = require('./lib/epicValidationHook.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { verifyRun } = require('./runVerify.cjs');
 const { latestTerminalOutcomeForSlug, COMPLETED_EQUIVALENT_VERDICTS } = require('./lib/terminalRunOutcome.cjs');
@@ -77,7 +78,7 @@ const {
 } = require('./lib/schedulerConfig.cjs');
 const { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD } = require('./lib/schedulerBatch.cjs');
 const { runDefinitionOfDoneOnDrain } = require('./lib/dodDrainHook.cjs');
-const { fileRcaFeedback, extractRcaBlock } = require('./lib/rcaFeedbackHook.cjs');
+const { writeRcaReport, extractRcaBlock } = require('./lib/rcaReport.cjs');
 const queueHistory = require('./lib/queueHistory.cjs');
 const queueOps = require('./queueOps.cjs');
 // Feedback-auto-PRD sweep — formerly only run by the external scheduler-watchdog
@@ -87,6 +88,7 @@ const queueOps = require('./queueOps.cjs');
 // home-dir layout.
 const { resolvePrdsDirs, resolveArchivedPrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
 const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+const { buildContextDigest } = require('./lib/epicContextDigest.cjs');
 
 // ---------- origin session resolution (PRD 832) ----------
 // An Epic IS a tagged claude session — job rows carry the originating
@@ -358,15 +360,6 @@ const HEARTBEAT_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'sc
 const HEARTBEAT_MAX_BYTES = 1024 * 1024;
 // DEFAULT_PROJECT_CWD imported from lib/schedulerBatch.cjs (single source of truth).
 
-// Read lazily (not captured at module-load time) so tests can stub the env
-// per-case without vi.resetModules(); production behavior is unaffected
-// since the env var never changes mid-process.
-function getEnvCap() {
-  return process.env.SM_SCHEDULER_MAX_CONCURRENCY
-    ? Math.max(1, Math.min(20, parseInt(process.env.SM_SCHEDULER_MAX_CONCURRENCY, 10) || 3))
-    : null;
-}
-
 // Each headless claude -p job can shell out to tsc/vite/pytest and grow well
 // past 1 GB at peak; reserve 2.5 GB per running+pending slot. Raised from 1.5 GB
 // after the 2026-06-16 OOM: 3 concurrent cross-project jobs + their build
@@ -391,7 +384,6 @@ const OOM_SCORE_ADJ_JOB = 500;
 
 const DEFAULT_CONFIG = {
   offsetMinutes: 15,
-  concurrencyCap: getEnvCap() ?? 3,
   defaultCwd: DEFAULT_PROJECT_CWD,
   // 'when-available' = poll usage and fire whenever utilization < threshold.
   // 'on-reset'        = fire offsetMinutes after the next 5h reset (legacy).
@@ -756,6 +748,16 @@ async function runPrdMigration() {
           meta: { cwd, reason: f.reason },
         });
       }
+      // Deliberately left behind because a live job still points at them
+      // (PRD 992). Logged so a permanently-stuck flat PRD is visible rather
+      // than looking like a clean consolidation.
+      for (const s of c.skipped ?? []) {
+        logs.writeLine({
+          level: 'info', scope: 'scheduler',
+          message: `flat-PRD consolidation: left ${s.file} in place`,
+          meta: { cwd, reason: s.reason },
+        });
+      }
     } catch (e) {
       logs.writeLine({ level: 'warn', scope: 'scheduler', message: 'flat-PRD consolidation failed', meta: { cwd, error: e?.message } });
     }
@@ -1421,8 +1423,8 @@ let heartbeatInterval = null;
 // (The 5-minute feedback sweep that used to piggyback on this heartbeat is
 // gone: it scanned each active project's session-manager-operations/feedback/
 // and auto-queued a /process-feedback PRD. Both the folder and that skill are
-// retired — agents now file a `proposed` Epic that waits for human approval,
-// so there is nothing to sweep for. See lib/rcaFeedbackHook.cjs.)
+// retired, and nothing auto-creates work any more — a parked job is surfaced
+// back into the Epic that authored its PRD instead. See lib/rcaReport.cjs.)
 // In-memory set of slugs currently spawned in this process. Prevents
 // double-spawn when runDueJobs() is called while jobs are in flight.
 const runningSet = new Set();
@@ -1449,6 +1451,18 @@ let cancelToken = { cancelled: false };
 // Last memory-gate observation; included in snapshot for renderer visibility.
 let lastMemGate = null;
 
+// Last tickQueue outcome, kept for the UI. tickQueue already computes a precise
+// reason for every way a batch can come back empty (dependency holds, slot
+// exhaustion, the memory gate, pause, manual policy) and used to throw all of
+// it into console.log — so the Home slot count read "5" while the queue was
+// actually pinned at 1 with nothing on screen explaining why. This is that
+// explanation, recorded once per tick and broadcast with the rest of the state.
+let lastTick = null;
+function recordTick(outcome, extra = {}) {
+  lastTick = { ...outcome, ...extra, at: new Date().toISOString() };
+  return outcome;
+}
+
 /**
  * Pure: applies clearPause()'s effect on the tick cancel-token.
  *
@@ -1504,10 +1518,19 @@ function buildScheduleStatePayload(state, { withPaths = false } = {}) {
       lastFailureKind,
     },
     memGate: lastMemGate,
-    effectiveConcurrency: {
-      cap: getEnvCap() ?? state.config.concurrencyCap,
-      source: getEnvCap() != null ? 'env' : 'config',
-    },
+    lastTick,
+    // The machine-wide slot pool IS the concurrency limit — there is no
+    // separate scheduler cap any more. `source` distinguishes the
+    // SM_SESSION_SLOTS env override from the persisted Home-tab value so the
+    // UI can disable its own control when the env has taken over.
+    effectiveConcurrency: (() => {
+      const snap = sessionSlots.snapshot();
+      return {
+        cap: snap.total,
+        free: Math.max(0, snap.total - snap.inUse),
+        source: snap.envOverride ? 'env' : 'pool',
+      };
+    })(),
   };
   if (withPaths) {
     payload.paths = { root: ROOT, prds: PRDS_DIR, runs: RUNS_DIR, queue: queueStore.MACHINE_STATE_PATH };
@@ -1796,6 +1819,43 @@ function extractResultTextFromLog(logPath) {
   }
 }
 
+/**
+ * resolveNotifyPrd(job, parsePrdRaw) → Promise<parsed PRD | null>
+ *
+ * Locate and parse a finishing job's PRD for the notification path, trying
+ * the live Epic-scoped dir first (findPrdDir scans candidatePrdsDirs) and
+ * then the archived twin (archivedPrdPathForJob scans listArchivedPrdDirs).
+ *
+ * Both lookups are required, and `prdPathForJob` is deliberately NOT used
+ * here (PRD 985). It resolves to `resolvePrdWriteDir(cwd)` — the RETIRED
+ * flat `<cwd>/session-manager-operations/scheduler/prds/` dir, which today
+ * holds only zero-byte `.reserved-NNN` number stubs and no PRD at all, so it
+ * ENOENT'd for every Epic-scoped PRD. On top of that, archiveCompletedPrd
+ * renames the file into `prds-archived/` immediately BEFORE the notify call
+ * (see tickQueue's newlyCompletedPrds loop), so even a correct live-dir
+ * lookup finds nothing by the time we run. The net effect was that `prd`
+ * was always null on the completed path: sourcePromptId never resolved, no
+ * transcript turn was written, no response event was appended, and the
+ * completed PRD silently never reported back to the Epic that authored it.
+ * Verified live: PRDs 961/962/963/964/967 all completed 2026-08-03 and not
+ * one response event landed on either authoring Epic's chain.
+ *
+ * Never throws — an unreadable/absent PRD returns null and each caller
+ * falls back to the job's own `epicId`.
+ */
+async function resolveNotifyPrd(job, parsePrdRaw) {
+  if (!job || !job.slug) return null;
+  const liveDir = await findPrdDir(job.slug).catch(() => null);
+  const livePath = liveDir ? safeSlugPathIn(liveDir, job.slug) : null;
+  if (livePath) {
+    const parsed = await parsePrdRaw(livePath).catch(() => null);
+    if (parsed) return parsed;
+  }
+  const archivedPath = archivedPrdPathForJob(job);
+  if (!archivedPath) return null;
+  return await parsePrdRaw(archivedPath).catch(() => null);
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -1834,18 +1894,38 @@ async function notifyOriginatingTab(job, {
   appendResponseEvent = appendResponseEventIfKnown,
   appendTranscriptTurn = promptSessionTranscript.appendTurn,
   readResultFromLog = extractResultTextFromLog,
+  enqueueValidation = maybeEnqueueValidationPrompt,
 } = {}) {
   try {
-    const prdPath = prdPathForJob(job);
-    const prd = await parsePrdRaw(prdPath).catch(() => null);
+    const prd = await resolveNotifyPrd(job, parsePrdRaw);
     const message = `PRD ${job.slug} finished: ${job.status}. Check Scheduler for details.`;
 
+    // The EPIC this check-in belongs to. Deliberately does NOT consider
+    // `sourceTabId` — that is a Terminal tab id, not an Epic id, and
+    // appending an Epic event chain onto one would be a category error (a
+    // pre-813 PRD carrying only sourceTabId must still take the
+    // chat:external-send path below; covered by the 'no sourcePromptId at
+    // all (pre-813 PRD)' test).
+    //
+    // `job.epicId` is the last resort and is what makes the notification
+    // survive an entirely unreadable PRD: the queue row carries the Epic FK
+    // independently of the .md on disk (20 of 21 history rows had it when
+    // PRD 985 was written), so a parse failure degrades to "notified without
+    // frontmatter detail" instead of "silently dropped". Mirrors
+    // notifyNeedsReview, which has had this fallback since PRD 854 — which
+    // is precisely why needs_review routing kept working while
+    // completed/failed routing did not.
+    const epicId = prd?.sourcePromptId || job.epicId || null;
+
     // Persist the job's real result text (not just the short status chip
     // above) to the durable per-Epic transcript, keyed off whichever id
-    // notifyOriginatingTab would otherwise notify. Best-effort: a missing
-    // cwd/epic id, an unreadable run log, or an IPC error here must never
-    // block the notification below.
-    const epicIdForTranscript = prd?.sourcePromptId || prd?.sourceTabId || null;
+    // notifyOriginatingTab would otherwise notify. Unlike the event append
+    // above, this one DOES accept sourceTabId — the durable transcript is
+    // keyed by whatever id the run is associated with, not strictly by Epic
+    // (pre-existing behaviour, unchanged by PRD 985 apart from the epicId
+    // fallback). Best-effort: a missing cwd/epic id, an unreadable run log,
+    // or an IPC error here must never block the notification below.
+    const epicIdForTranscript = prd?.sourcePromptId || prd?.sourceTabId || job.epicId || null;
     if (epicIdForTranscript && job.cwd) {
       try {
         const logPath = job.runId ? path.join(RUNS_DIR, job.runId, `${job.slug}.log`) : null;
@@ -1859,12 +1939,46 @@ async function notifyOriginatingTab(job, {
       }
     }
 
-    if (prd?.sourcePromptId) {
-      const routed = await appendResponseEvent(job.cwd || null, prd.sourcePromptId, message).catch((e) => {
+    if (epicId) {
+      // PRD 986: the check-in event is born validation:'unvalidated' — never
+      // 'verified' — regardless of the job's self-reported outcome. The
+      // check-in is a request to validate, not an assertion of done.
+      const routed = await appendResponseEvent(job.cwd || null, epicId, message, {
+        prdSlug: job.slug,
+        outcome: job.status,
+        validation: 'unvalidated',
+      }).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab appendResponseEvent error', job?.slug, e);
         return false;
       });
-      if (routed) return;
+      if (routed) {
+        // PRD 986: a successful check-in append triggers ONE validation
+        // prompt into the authoring Epic's own session, asking it to verify
+        // every acceptance criterion against the real working tree and reply
+        // VERIFIED or REFUTED. Fire-and-forget, same convention as this
+        // function's own call site in tickQueue: a failure to enqueue is
+        // logged inside the hook, never thrown, and never blocks the job's
+        // status transition or the response-event append (which already
+        // happened above). All gating (kill-switch SM_EPIC_VALIDATION_DISABLE,
+        // active-Epic check, once-per-(epicId, prdSlug), loop guard, slot-pool
+        // routing) lives in lib/epicValidationHook.cjs.
+        try {
+          enqueueValidation(
+            {
+              cwd: job.cwd || null,
+              epicId,
+              prdSlug: job.slug,
+              prdPath: prd?.path || archivedPrdPathForJob(job) || null,
+              outcome: job.status,
+              eventValidation: 'unvalidated',
+            },
+            { sendPrompt },
+          );
+        } catch (e) {
+          console.error('[scheduler] notifyOriginatingTab enqueueValidation error', job?.slug, e);
+        }
+        return;
+      }
     }
 
     // appendResponseEvent already refused above (unknown id, completed
@@ -1873,7 +1987,7 @@ async function notifyOriginatingTab(job, {
     // re-checks against its own live PromptSession store. Deliberate
     // defense-in-depth (main's disk-backed check vs. the renderer's
     // in-memory one can disagree/race), not a redundant duplicate to prune.
-    let targetTabId = prd?.sourceTabId || prd?.sourcePromptId || null;
+    let targetTabId = prd?.sourceTabId || prd?.sourcePromptId || job.epicId || null;
     if (!targetTabId) {
       const jobCwd = job.cwd || null;
       if (jobCwd) {
@@ -1893,6 +2007,51 @@ async function notifyOriginatingTab(job, {
   }
 }
 
+/**
+ * notifyNeedsReview(job, report) → Promise<boolean>
+ *
+ * A job parked in `needs_review` is a question, not a result: something about
+ * the PRD was unclear, unverifiable, or ran past its acceptance criteria.
+ * That question belongs in the conversation that WROTE the PRD, so this
+ * appends a 'response' event to the authoring Epic's own chain (the same
+ * channel notifyOriginatingTab uses for completed/failed, which deliberately
+ * excludes needs_review — isNotifiableTerminalStatus). It resolves the Epic
+ * from the PRD's `sourcePromptId`, falling back to the job's own `epicId`.
+ *
+ * Join-only by construction: appendResponseEventIfKnown refuses an unknown or
+ * non-active session and returns false. Nothing here can create an Epic — if
+ * no open authoring Epic exists, the root-cause report in the run directory
+ * is the whole record and the Scheduler tab is where it surfaces.
+ */
+async function notifyNeedsReview(job, report, {
+  parsePrdRaw = prdParser.parsePrdRaw,
+  appendResponseEvent = appendResponseEventIfKnown,
+} = {}) {
+  try {
+    if (!job || !report || !report.filed) return false;
+    const prd = await resolveNotifyPrd(job, parsePrdRaw);
+    const epicId = prd?.sourcePromptId || job.epicId || null;
+    if (!epicId || !job.cwd) {
+      console.log(`[scheduler] notifyNeedsReview: no authoring Epic for ${job.slug}, report only`);
+      return false;
+    }
+    const message = `${report.summary}. Root-cause report: ${report.path}`;
+    // PRD 986: like every scheduler check-in, born 'unvalidated' — the RCA
+    // report is itself a question, not a verified outcome. No validation
+    // prompt is enqueued here: that fires only for the terminal
+    // completed/failed path (notifyOriginatingTab); needs_review already
+    // routes its own question via this very report.
+    return await appendResponseEvent(job.cwd, epicId, message, {
+      prdSlug: job.slug,
+      outcome: 'needs_review',
+      validation: 'unvalidated',
+    });
+  } catch (e) {
+    console.error('[scheduler] notifyNeedsReview error', job?.slug, e);
+    return false;
+  }
+}
+
 /** 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.
  *  Uses readTail() so no raw fd lifecycle is needed here. */
@@ -2109,6 +2268,25 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
     }
   }
 
+  // Prepend the Epic's own session digest (PRD 950/958) when this job traces
+  // back to a known Epic — additive only, never mutates the PRD body itself.
+  // A missing/unresolved epicId or a digest build failure is a silent no-op:
+  // the PRD's own body must remain sufficient to complete the job on its own.
+  const digestEpicId = job.epicId ?? job.sourcePromptId ?? null;
+  const originSessionId = resolveOriginSessionId(cwd, digestEpicId);
+  let contextDigestApplied = false;
+  if (originSessionId) {
+    try {
+      const digestText = await buildContextDigest({ cwd, epicId: digestEpicId });
+      if (digestText) {
+        prompt = digestText + '\n\n' + prompt;
+        contextDigestApplied = true;
+      }
+    } catch (e) {
+      safeLog(`[scheduler] context digest build failed (job still dispatches without it): ${e?.message ?? e}\n`);
+    }
+  }
+
   const promptCheck = validatePromptForSpawn(prompt, prdPath);
   if (!promptCheck.ok) {
     safeLog(`[scheduler] ${promptCheck.error}\n`);
@@ -2262,7 +2440,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
           sl(`\n[scheduler] ${errMsg}\n`);
           // Sync write: inside a Promise executor callback; must flush meta
           // before resolve() so the spawnJob mutate() that follows sees it.
-          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA });
+          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA, originSessionId, contextDigestApplied });
           resolve({ exitCode: -1, durationMs, error: errMsg, sessionId });
           return;
         }
@@ -2293,6 +2471,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
           startedAt, finishedAt: Date.now(), durationMs,
           agentResultSubtype, mappedFromSignal: mappedToSuccess ? signal || `code=${exitCode}` : null,
           schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA,
+          originSessionId, contextDigestApplied,
         });
         resolve({ exitCode: effectiveCode, durationMs, rateLimited, networkError, sessionId });
       },
@@ -2610,19 +2789,19 @@ async function spawnInvestigation(failedJob, runDir) {
         return;
       }
       sl(`\n[scheduler] investigation exit code=${exitCode}\n`);
-      // Fold the investigation's <RCA> summary into the RCA feedback item already
-      // filed for this job (needs_review jobs only — fileRcaFeedback no-ops when
+      // Fold the investigation's <RCA> summary into the root-cause report already
+      // written for this job (needs_review jobs only — writeRcaReport no-ops when
       // failedJob has no verifierVerdict, e.g. plain 'failed' jobs never got one).
       const investigationText = extractRcaBlock(readTail(investigationLogPath, 64 * 1024));
       if (investigationText) {
-        fileRcaFeedback({
+        writeRcaReport({
           job: failedJob,
           runDir,
           verdict: failedJob.verifierVerdict,
           annotations: failedJob.verifierAnnotations,
           investigationText,
         }).catch((e) => {
-          console.error('[scheduler] fileRcaFeedback (investigation enrichment) error', failedJob.slug, e);
+          console.error('[scheduler] writeRcaReport (investigation enrichment) error', failedJob.slug, e);
         });
       }
       if (fs.existsSync(fixPath)) {
@@ -3006,14 +3185,16 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     if (needsReviewRcaSnapshot) {
       // Fire-and-forget, mirroring the DoD drain hook: never blocks the status
       // transition, never throws to this caller.
-      fileRcaFeedback({
+      writeRcaReport({
         job: needsReviewRcaSnapshot,
         runDir,
         verdict: needsReviewRcaSnapshot.verifierVerdict,
         annotations: needsReviewRcaSnapshot.verifierAnnotations,
-      }).catch((e) => {
-        console.error('[scheduler] fileRcaFeedback error', job.slug, e);
-      });
+      })
+        .then((report) => notifyNeedsReview(needsReviewRcaSnapshot, report))
+        .catch((e) => {
+          console.error('[scheduler] writeRcaReport error', job.slug, e);
+        });
     }
 
     if (actuallyFailed && failedJobSnapshot) {
@@ -3125,20 +3306,34 @@ function tickQueue() {
     }
     if (state.paused) {
       console.log('[scheduler] tickQueue skipped: paused');
-      return { fired: false, reason: 'paused' };
+      return recordTick({ fired: false, reason: 'paused' }, { detail: 'scheduler paused' });
     }
     if (cancelToken.cancelled) return { fired: false, reason: 'cancelled' };
 
     await reconcile(state);
-    const cap = getEnvCap() ?? state.config.concurrencyCap;
-    const { batch, reason: holdReason } = pickNextBatch(state.jobs, runningSet, cap);
+    // Session-Manager's machine-wide slot pool is the ONLY concurrency limit
+    // the picker answers to (plus the memory gate below). The scheduler used
+    // to also carry a private `concurrencyCap` of 3 — the exact per-consumer
+    // cap that sessionSlots.cjs was written to replace — which silently
+    // ceilinged the queue at 3 while the pool the user configured said 5.
+    const freeSlots = sessionSlots.available();
+    const { batch, reason: holdReason, holds } = pickNextBatch(state.jobs, runningSet, freeSlots);
+    if (batch.length === 0 && freeSlots === 0) {
+      const snap = sessionSlots.snapshot();
+      const pendingCount = state.jobs.filter((j) => j.status === 'pending').length;
+      console.log(`[scheduler] slot gate: 0 of ${snap.total} session slots free (${snap.holders.map((h) => h.owner).join(', ')}) — deferring ${pendingCount} pending job(s)`);
+      return recordTick(
+        { fired: false, reason: 'slots-exhausted', deferredCount: pendingCount, holders: snap.holders },
+        { detail: `${snap.total} of ${snap.total} session slots busy (${snap.holders.map((h) => h.owner).join(', ')})`, holds },
+      );
+    }
     if (batch.length === 0) {
       // Queue drained — run the definition-of-done gate fire-and-forget.
       // Non-blocking: does not hold the mutate lock; errors are logged, not thrown.
       runDefinitionOfDoneOnDrain(state, { cancelToken }).catch((err) => {
         console.log(`[scheduler] dod-drain: ${err?.message ?? String(err)}`);
       });
-      if (holdReason) return { fired: false, reason: 'held', detail: holdReason };
+      if (holdReason) return recordTick({ fired: false, reason: 'held', detail: holdReason }, { holds });
       // Distinguish "genuinely nothing to do" from "the batch was already
       // fired by a concurrent tickQueue() call" (e.g. the periodic
       // when-available poll winning a race against a manual force-tick —
@@ -3151,9 +3346,9 @@ function tickQueue() {
         state.jobs.filter((j) => j.status === 'running').length,
       );
       if (runningCount > 0) {
-        return { fired: false, reason: 'already-running', runningCount };
+        return recordTick({ fired: false, reason: 'already-running', runningCount }, { holds });
       }
-      return { fired: false, reason: 'drained' };
+      return recordTick({ fired: false, reason: 'drained' }, { holds });
     }
 
     const availableMb = getAvailableMemMb();
@@ -3161,23 +3356,19 @@ function tickQueue() {
     // job is never started into the host's own headroom (that path OOM-kills
     // Electron and SIGHUPs every pty — 2026-06-16 incident).
     const jobBudgetMb = availableForJobs(availableMb, RESERVED_HOST_MB);
-    // Session-Manager's machine-wide slot pool is the outer bound: chat runs
-    // and scheduler jobs share it, so a busy chat lane shrinks this batch.
-    const slotAllowed = sessionSlots.available();
-    if (slotAllowed === 0) {
-      const snap = sessionSlots.snapshot();
-      console.log(`[scheduler] slot gate: 0 of ${snap.total} session slots free (${snap.holders.map((h) => h.owner).join(', ')}) — deferring ${batch.length} job(s)`);
-      return { fired: false, reason: 'slots-exhausted', deferredCount: batch.length, holders: snap.holders };
-    }
-    const allowed = Math.min(
-      slotAllowed,
-      memoryLimitedBatchSize(jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length),
+    // The slot pool already bounded `batch` (it was passed as freeSlots to
+    // pickNextBatch above), so only the memory gate can narrow it further.
+    const allowed = memoryLimitedBatchSize(
+      jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length,
     );
     if (allowed === 0) {
       const threshold = RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + 1);
       console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job × ${runningSet.size + 1}) — deferring ${batch.length} job(s)`);
       lastMemGate = { availableMb, threshold, deferred: true, at: new Date().toISOString() };
-      return { fired: false, reason: 'memory-deferred', deferredCount: batch.length, availableMb, threshold };
+      return recordTick(
+        { fired: false, reason: 'memory-deferred', deferredCount: batch.length, availableMb, threshold },
+        { detail: `memory gate: ${availableMb} MB free, need ${threshold} MB`, holds },
+      );
     }
     const gatedBatch = batch.slice(0, allowed);
     if (gatedBatch.length < batch.length) {
@@ -3198,7 +3389,7 @@ function tickQueue() {
       // spawnJob is fire-and-forget; it calls tickQueue() on completion.
       spawnJob(job, runId, runDir, state.config.defaultCwd).catch(() => {});
     }
-    return { fired: true, count: gatedBatch.length, group: gatedBatch[0]?.parallelGroup };
+    return recordTick({ fired: true, count: gatedBatch.length, group: gatedBatch[0]?.parallelGroup }, { holds });
   });
   tickTail = next.catch(() => {});
   return next;
@@ -3569,6 +3760,50 @@ function isUnresolvableNeedsReview(job, { hasRunDir }) {
  * commit-guard) — verifyRun can't see git, so re-scanning it would falsely
  * heal an unfinished job. Exported for tests.
  */
+/**
+ * healRefusalReason(job, verdict, committedDuringRun) → string | null
+ *
+ * Guards reverifyNeedsReview's needs_review → completed self-heal. Returns a
+ * refusal reason when the heal must NOT happen, or null to allow it.
+ *
+ * THE INCIDENT (PRD 983, 2026-08-03). Job 972 ran 34 s, edited zero files and
+ * exited 0. verifyRun correctly raised `no_verdict_sentinel` (no commit AND no
+ * SCHEDULER_VERDICT sentinel) with downgradeTo 'needs_review', and the job was
+ * parked. One minute later this self-heal pass promoted it to `completed`, and
+ * that false green shipped to the user.
+ *
+ * The mechanism is subtle and worth spelling out, because the individual parts
+ * all look correct: `no_verdict_sentinel` is in RESCANNABLE_VERDICTS, so the
+ * job was re-verified. The rescan recomputes `committedDuringRun` via
+ * `committedInWindow`, which runs `git log --all --since=<startedAt>
+ * --until=<finishedAt+60s>` with NO author, message, or slug filter — it
+ * answers "did ANY commit land in this repo during that window", not "did THIS
+ * job commit". With up to 3 concurrent scheduler jobs plus interactive
+ * sessions sharing one repo, a sibling job's commit lands inside the window
+ * routinely. `committedDuringRun` therefore flipped to true on the rescan,
+ * runVerify's `if (sentinel === null && !committedDuringRun)` no longer fired,
+ * `no_verdict_sentinel` was never re-raised, the issue list came back empty,
+ * and the verdict concluded `clean` — a COMPLETED_EQUIVALENT verdict, so the
+ * job healed. Another job's commit was silently credited to this one.
+ *
+ * The rule: a run that emitted no sentinel and landed no commit ATTRIBUTABLE
+ * TO ITSELF has produced no evidence it did anything, and repo-wide
+ * time-window evidence is not attribution. `landedCommit` is per-job and
+ * survives a resetJob (resetJobFields), so it is the honest signal here.
+ * Bias to needs_review: a false yellow costs a human glance, a false green
+ * costs a silently-unfixed bug — which is exactly what happened.
+ */
+function healRefusalReason(job, verdict, committedDuringRun) {
+  if (!job || !verdict) return null;
+  if (!COMPLETED_EQUIVALENT_VERDICTS.has(verdict.verdict)) return null;
+  if (job.verifierVerdict !== 'no_verdict_sentinel') return null;
+  // A commit this job actually recorded as its own is real evidence; the
+  // repo-wide window scan is not.
+  if (job.landedCommit) return null;
+  return 'no_verdict_sentinel with no job-attributable commit — refusing to heal'
+    + ` (committedInWindow=${committedDuringRun === true} is repo-wide, not proof this job delivered)`;
+}
+
 function isRescanCandidate(job) {
   return !!job
     && job.status === 'needs_review'
@@ -3670,7 +3905,10 @@ async function reverifyNeedsReview() {
         priorLandedCommit,
       });
     } catch { leftForReview.push({ slug: job.slug, reason: 'verifyRun threw' }); continue; }
-    if (v && COMPLETED_EQUIVALENT_VERDICTS.has(v.verdict)) {
+    const refusal = healRefusalReason(job, v, committedDuringRun);
+    if (refusal) {
+      leftForReview.push({ slug: job.slug, reason: refusal });
+    } else if (v && COMPLETED_EQUIVALENT_VERDICTS.has(v.verdict)) {
       healed.push(job.slug);
     } else {
       leftForReview.push({ slug: job.slug, reason: v ? `${v.verdict}: ${v.reason}` : 'null verdict' });
@@ -4399,12 +4637,9 @@ const remote = {
         if (candidate && fs.existsSync(candidate)) { dir = d; break; }
       }
       if (!dir) {
-        // Every PRD must join an EXISTING, already-human-approved Epic —
-        // mintIfMissing:false means this never conjures a new one. Only
-        // Epics born from explicit human intent (New Epic UI, or
-        // /propose-epic + Approve & start) may write PRDs; this write path
-        // is not itself a human-intent gate, so it must not become one by
-        // accident.
+        // Every PRD must join an EXISTING, human-created Epic — ensureEpic
+        // is join-only for every caller but the New Epic UI (epicMint.cjs's
+        // SINGLE-CREATOR LAW), so this can never conjure one.
         const { fm } = splitFrontmatter(body);
         try {
           const epic = await ensureEpic(cwd, {
@@ -4415,11 +4650,10 @@ const remote = {
             // a literal-equality join. Any other id (e.g. a PromptTicket.id)
             // simply won't match and this call throws below.
             epicId: fm.sourcePromptId,
-            mintIfMissing: false,
-            // Join-only call (mintIfMissing:false, explicit epicId): the
+            // Join-only call (no mintAuthority, explicit epicId): the
             // explicitEpicId branch in ensureEpic returns before `source` is
             // ever read, so this is a no-op today — kept for symmetry/audit
-            // trail if that join path ever grows a source-touch (PRD 902/905).
+            // trail if that join path ever grows a source-touch.
             source: { producer: 'scheduler-dispatch', prdSlug: slug },
           });
           dir = epic.prdDir;
@@ -4428,7 +4662,7 @@ const remote = {
           return {
             ok: false,
             error: `no existing Epic to join (sourcePromptId=${fm.sourcePromptId ?? 'none'}): ${e?.message ?? 'unknown error'}. `
-              + 'Create the Epic first via the New Epic UI or /propose-epic + Approve & start, then pass its id as sourcePromptId.',
+              + 'Create the Epic first via the New Epic UI, then pass its id as sourcePromptId.',
           };
         }
       }
@@ -4438,7 +4672,7 @@ const remote = {
       if (dir === PRDS_DIR) ensureDirs();
     }
 
-    // writePrd only ever JOINS an existing Epic now (mintIfMissing:false
+    // writePrd only ever JOINS an existing Epic now (no mintAuthority
     // above) — it can never mint one, so there is no orphaned-mint case left
     // to roll back here (contrast the old PRD 825/851 cleanup, removed).
     const resolved = safeSlugPathIn(dir, slug);
@@ -4540,4 +4774,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };