claude-code-session-manager 0.117.0 → 0.119.0

package/src/main/lib/epic/epicValidationHook.cjs

@@ -1,58 +1,29 @@
 'use strict';
 
 /**
- * epicValidationHook.cjs — a PRD check-in triggers validation in the
- * authoring Epic; it never asserts the PRD is done (PRD 986).
+ * epicValidationHook.cjs — the Epic settle runner: once an Epic has no
+ * pending/running PRD it either queues ONE headless sweep validator for
+ * unchecked completed PRDs, or sends ONE plan digest into the Epic's chat.
  *
- * WHY: PRD 972 ran 34 s, made zero edits, exited 0, and the queue recorded
- * `completed`. Three layers of scheduler-side automation failed to notice.
- * The party with the context to judge whether the work is right is the Epic
- * that WROTE the PRD — so a check-in is inverted from "assertion of done"
- * into a REQUEST TO VALIDATE: when the scheduler appends a check-in response
- * event to the authoring Epic's chain, this hook enqueues ONE validation
- * prompt into that Epic's own chat session instructing it to independently
- * verify each acceptance criterion against the real working tree and answer
- * VERIFIED or REFUTED with evidence. The job's self-reported status is an
- * input to that check, never a substitute for it.
+ * WHY validation exists (PRD 986): PRD 972 ran 34 s, made zero edits, exited 0,
+ * and the queue recorded `completed` — a job's self-report is never proof.
  *
- * Shape mirrors lib/scheduler/dodDrainHook.cjs: fire-and-forget (never throws to the
- * caller — errors are logged), kill-switched, idempotent.
+ * Kill-switch: SM_EPIC_VALIDATION_DISABLE=1 turns the whole runner off.
+ * SM_EPIC_SETTLE_SECONDS sets the debounce before a settle run (default 120).
  *
- * Kill-switch: SM_EPIC_VALIDATION_DISABLE=1 (mirrors the SM_DOD_DISABLE
- * precedent) — turns the whole hook off without a code change.
- *
- * SESSION SLOT POOL: this module spawns NOTHING. The prompt is enqueued via
- * chatRunner.cjs's enqueueExternalPrompt → `chat:external-send` → the
- * renderer's chat queue → chatRunner's pump, which acquires a slot from the
- * machine-wide lib/scheduler/sessionSlots.cjs pool (chatRunner.cjs pump()) before any
- * `claude -p` process starts. So the validation session cannot start outside
- * the pool — if the pool is exhausted the prompt simply waits in the chat
- * lane's FIFO, it never fans out into an extra parallel process (the
- * 2026-06-10 OOM shape this AC exists to prevent).
- *
- * Cost note: this spends tokens per PRD check-in — intended trade. The
- * once-per-(epicId, prdSlug) guard and the kill-switch keep it bounded.
+ * This module spawns NO process itself: the sweep validator is a PRD queued
+ * through the scheduler (which acquires a lib/scheduler/sessionSlots.cjs slot),
+ * and the digest goes through the chat queue's pump, which does the same.
  *
  * Join-only: nothing here can create an Epic (epicMint.cjs's SINGLE-CREATOR
- * LAW). If no active authoring Epic exists, log and do nothing.
+ * LAW). If no active authoring Epic exists, do nothing.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
-
-/**
- * LOOP GUARD + once-per-pair bookkeeping.
- *
- * `_fired` records every (epicId, prdSlug) pair this process has already
- * enqueued a validation prompt for — the fast in-memory half of the
- * once-per-pair guard (the durable half re-reads the Epic's own event chain,
- * see maybeEnqueueValidationPrompt below).
- */
-const _fired = new Set();
-
-function pairKey(epicId, prdSlug) {
-  return `${epicId}::${prdSlug}`;
-}
+const { evaluateEpicSettle } = require('./epicSettle.cjs');
+const { buildSweepValidatorInput, isSweepValidatorSlug } = require('./epicSweepValidator.cjs');
+const { bareSlug } = require('../prd/depSlugResolve.cjs');
 
 /**
  * Default active-index reader: the same on-disk file
@@ -71,123 +42,182 @@ function defaultReadActiveIndex(cwd) {
 }
 
 /**
- * buildValidationPrompt — pure prompt builder.
- *
- * The prompt must carry: the PRD slug, the absolute path to its .md, the
- * job's self-reported outcome explicitly labelled as an UNVERIFIED CLAIM,
- * the instruction to check every Acceptance Criterion against the actual
- * working tree, and the VERIFIED/REFUTED reply contract with per-criterion
- * evidence. It also warns against the exact failure mode that produced
- * PRD 986: exit 0 / a green queue row / a confident report are not evidence.
+ * buildSettledDigest — pure builder for the ONE plan-digest prompt.
+ * Empty sections are omitted. `notValidatedReason` explains why the
+ * settle.uncovered slugs were not sent to a sweep validator.
  */
-function buildValidationPrompt({ prdSlug, prdPath, outcome }) {
-  const pathLine = prdPath
-    ? `PRD file (absolute path): ${prdPath}`
-    : 'PRD file: path could not be resolved — locate it under session-manager-operations/scheduler/epics/*/prds-archived/ by slug.';
-  return [
-    `VALIDATION REQUEST for PRD ${prdSlug} — this is a request to validate, NOT a completion notice.`,
-    pathLine,
-    `The scheduler job self-reported outcome "${outcome}". Treat that strictly as an UNVERIFIED CLAIM — it carries no authority about whether the work actually landed.`,
-    '',
-    'Do the following, independently:',
-    `1. Read the PRD's own "Acceptance criteria" section from the file above.`,
-    '2. Check EACH criterion against the actual working tree (read the real files, run the real commands).',
-    '3. Run `git diff --stat` over the run window (and `git log --stat` for commits landed during the run). An empty diff on an implementation PRD means the work did not land — treat that as REFUTED.',
-    '',
-    'WARNING — the failure mode this validation exists to catch: an exit code of 0, a green queue row, or a confident completion report are NOT evidence that anything shipped. Only the working tree is evidence. (A prior PRD reported "completed" having made zero edits.)',
-    '',
-    'Reply with exactly one verdict word, VERIFIED or REFUTED, followed by per-criterion evidence: for each acceptance criterion cite file:line or paste the command output that proves or disproves it.',
-  ].join('\n');
+function buildSettledDigest(settle, { epicId, notValidatedReason } = {}) {
+  const s = settle || {};
+  const verified = s.verified || [];
+  const refuted = s.refuted || [];
+  const failed = s.failed || [];
+  const parked = s.parked || [];
+  const notValidated = (s.uncovered || []).map((u) => (typeof u === 'string' ? u : u.slug));
+  const lines = [
+    `PLAN SETTLED — no PRD of this session is pending or running. This is ONE digest, not a per-PRD request.`,
+    `Validation record folder: session-manager-operations/reviews/validation/${epicId}/`,
+    'Do NOT re-verify VERIFIED PRDs — a validator already checked them.',
+  ];
+  if (verified.length) {
+    lines.push('', `Verified (${verified.length}):`, ...verified.map((v) => `- ${v}`));
+  }
+  if (refuted.length) {
+    lines.push('', `REFUTED (${refuted.length}):`, ...refuted.map((r) => `- ${r.slug}${r.reason ? ` — ${r.reason}` : ''}`));
+  }
+  if (failed.length) {
+    lines.push('', `Failed (${failed.length}):`, ...failed.map((f) => `- ${f}`));
+  }
+  if (parked.length) {
+    lines.push('', `Parked (needs_review) (${parked.length}):`, ...parked.map((p) => `- ${p}`));
+  }
+  if (notValidated.length) {
+    lines.push(
+      '', `Not validated (${notValidated.length}) — ${notValidatedReason || 'no validator checked them'}:`,
+      ...notValidated.map((n) => `- ${n}`),
+      `Validate these here: read each PRD file under session-manager-operations/scheduler/epics/${epicId}/prds-archived/ by slug, check every acceptance criterion against the working tree, and reply VERIFIED or REFUTED per slug.`,
+    );
+  }
+  return lines.join('\n');
 }
 
-/**
- * maybeEnqueueValidationPrompt(args, deps) → { enqueued: boolean, reason?: string }
- *
- * Called by scheduler.cjs's notifyOriginatingTab immediately after a
- * SUCCESSFUL appendResponseEventIfKnown for a terminal (completed/failed)
- * PRD outcome. Fire-and-forget: never throws; every refusal returns a
- * reason so tests (and log lines) can tell the gates apart.
- *
- * Guards, in order (all four AC gates):
- *   1. SM_EPIC_VALIDATION_DISABLE=1 kill-switch → skip.
- *   2. LOOP GUARD — how the guard distinguishes a check-in from a
- *      validation result: a scheduler check-in event is born with
- *      `validation: 'unvalidated'` (stamped by appendResponseEventIfKnown's
- *      meta), while a validation RESULT event carries 'validating' /
- *      'verified' / 'refuted' (and a plain chat response carries no
- *      validation field at all). Only `eventValidation === 'unvalidated'`
- *      may trigger a prompt, so an appended validation result can never
- *      enqueue a further prompt — no loop.
- *   3. Epic must exist AND have status 'active' in the on-disk
- *      active-index.json (re-checked here even though the append already
- *      enforced it, so the gate holds for any future call site too).
- *   4. Once per (epicId, prdSlug): in-memory `_fired` Set for the common
- *      path, plus a durable re-check of the Epic's own event chain — the
- *      check-in event just appended for this pair accounts for ONE
- *      validation-stamped response event with this prdSlug; two or more
- *      means an earlier check-in already requested validation (e.g. a
- *      re-notify after an app restart emptied `_fired`), so skip.
- *
- * (Gate: slot pool — see the module doc comment; no spawn happens here.)
- *
- * Complexity: O(n) over the Epic's event chain for the durable dedup scan.
- */
-function maybeEnqueueValidationPrompt(
-  { cwd, epicId, prdSlug, prdPath = null, outcome, eventValidation },
-  { sendPrompt, readActiveIndex = defaultReadActiveIndex, log = console } = {},
-) {
-  try {
-    // Gate 1: kill-switch (SM_EPIC_VALIDATION_DISABLE, per SM_DOD_DISABLE precedent).
-    if (process.env.SM_EPIC_VALIDATION_DISABLE === '1') return { enqueued: false, reason: 'disabled' };
+const DEFAULT_SETTLE_SECONDS = 120;
 
-    // Gate 2: LOOP GUARD (see doc comment above for how the field value
-    // distinguishes a check-in from a validation result).
-    if (eventValidation !== 'unvalidated') return { enqueued: false, reason: 'not-a-checkin' };
+function settleDelayMs() {
+  const raw = process.env.SM_EPIC_SETTLE_SECONDS;
+  const n = /^\d+$/.test(String(raw || '').trim()) ? parseInt(String(raw).trim(), 10) : 0;
+  return (n > 0 ? n : DEFAULT_SETTLE_SECONDS) * 1000;
+}
 
-    if (!cwd || !epicId || !prdSlug || typeof sendPrompt !== 'function') {
-      return { enqueued: false, reason: 'missing-args' };
-    }
+const _rowInEpic = (r, epicId) => r && (r.epicId === epicId || r.sourcePromptId === epicId);
 
-    // Gate 4a: in-memory once-per-pair (checked before the disk read — cheap first).
-    const key = pairKey(epicId, prdSlug);
-    if (_fired.has(key)) return { enqueued: false, reason: 'already-fired' };
+/**
+ * runEpicSettle({ cwd, epicId }, deps) → { action, reason?, slug? }
+ * Never throws. Actions: 'none' | 'sweep-queued' | 'digest-sent'.
+ */
+async function runEpicSettle({ cwd, epicId } = {}, deps = {}) {
+  const {
+    readActiveIndex = defaultReadActiveIndex,
+    loadJobs = async () => [],
+    loadHistory = async () => [],
+    createPrd,
+    resolveBaseSha = async () => null,
+    sendPrompt,
+    appendResponseEvent,
+    now = Date.now,
+    log = console,
+  } = deps;
+  try {
+    if (process.env.SM_EPIC_VALIDATION_DISABLE === '1') return { action: 'none', reason: 'disabled' };
+    if (!cwd || !epicId) return { action: 'none', reason: 'missing-args' };
 
-    // Gate 3: authoring Epic must be a known, still-active session.
     const index = readActiveIndex(cwd);
     const session = index && index.sessions && index.sessions[epicId];
-    if (!session || session.status !== 'active') {
-      return { enqueued: false, reason: 'epic-not-active' };
-    }
+    if (!session || session.status !== 'active') return { action: 'none', reason: 'epic-not-active' };
 
-    // Gate 4b: durable once-per-pair — the just-appended check-in accounts
-    // for one validation-stamped response event for this prdSlug; a second
-    // one means a previous check-in already asked.
     const events = (index.events && index.events[epicId]) || [];
-    const priorCheckins = events.filter(
-      (e) => e && e.kind === 'response' && e.prdSlug === prdSlug && e.validation !== undefined,
-    );
-    if (priorCheckins.length >= 2) {
-      _fired.add(key); // remember so later re-notifies skip the disk read too
-      return { enqueued: false, reason: 'already-fired-durable' };
+    const jobs = (await loadJobs()) || [];
+    const history = (await loadHistory()) || [];
+    const settle = evaluateEpicSettle({ epicId, cwd, events, jobs, now: now() });
+    if (!settle.settled) return { action: 'none', reason: 'not-settled' };
+    if (!settle.hasContent) return { action: 'none', reason: 'no-content' };
+
+    let newestDigest = null;
+    for (const e of events) if (e && e.outcome === 'digest') newestDigest = e;
+    if (newestDigest && newestDigest.digestKey === settle.digestKey) {
+      return { action: 'none', reason: 'already-digested' };
     }
 
-    const prompt = buildValidationPrompt({ prdSlug, prdPath, outcome });
+    let notValidatedReason = null;
+    let digestSettle = settle;
+    if (settle.uncovered.length) {
+      const swept = new Set();
+      for (const r of [...jobs, ...history]) {
+        if (!_rowInEpic(r, epicId) || !isSweepValidatorSlug(r.slug) || !Array.isArray(r.dependsOn)) continue;
+        for (const d of r.dependsOn) swept.add(bareSlug(d));
+      }
+      const candidates = settle.uncovered.filter((u) => !swept.has(u.bareSlug || bareSlug(u.slug)));
+      if (candidates.length) {
+        const byBare = new Map();
+        for (const h of history) {
+          if (!h || !h.landedCommit || (h.cwd != null && h.cwd !== cwd)) continue;
+          const b = bareSlug(h.slug);
+          const prev = byBare.get(b);
+          if (!prev || String(h.finishedAt) < String(prev.finishedAt)) byBare.set(b, h);
+        }
+        let earliest = null;
+        for (const c of candidates) {
+          const h = byBare.get(c.bareSlug || bareSlug(c.slug));
+          if (h && (!earliest || String(h.finishedAt) < String(earliest.finishedAt))) earliest = h;
+        }
+        let baseSha = null;
+        try { baseSha = earliest ? await resolveBaseSha(cwd, earliest.landedCommit) : null; } catch { baseSha = null; }
+        const { input } = buildSweepValidatorInput({ epicId, cwd, uncovered: candidates, baseSha, now: now() });
+        let res;
+        try {
+          res = await createPrd(input);
+        } catch (e) {
+          res = { ok: false, error: e && e.message ? e.message : String(e) };
+        }
+        if (res && res.ok) return { action: 'sweep-queued', slug: input.slug };
+        notValidatedReason = `the validator persona could not be queued: ${(res && res.error) || 'unknown error'}`;
+      } else {
+        notValidatedReason = 'a sweep validator already ran and did not check them';
+      }
+    }
+
+    const prompt = buildSettledDigest(digestSettle, { epicId, notValidatedReason });
     sendPrompt(epicId, prompt);
-    _fired.add(key);
-    return { enqueued: true };
+    await appendResponseEvent(
+      cwd, epicId,
+      `Plan digest sent: ${settle.verified.length} verified, ${settle.refuted.length} refuted, ${settle.uncovered.length} not validated`,
+      { outcome: 'digest', digestKey: settle.digestKey },
+    );
+    return { action: 'digest-sent' };
   } catch (e) {
-    try { (log || console).error('[epicValidationHook] enqueue error', prdSlug, e); } catch { /* noop */ }
-    return { enqueued: false, reason: 'error' };
+    try { (log || console).error('[epicValidationHook] settle error', epicId, e); } catch { /* noop */ }
+    return { action: 'none', reason: 'error' };
   }
 }
 
-/** Test hook: clear the once-per-pair memory. */
-function __resetForTests() {
-  _fired.clear();
+const _settle = new Map(); // `${cwd}::${epicId}` -> { timer, running }
+
+/**
+ * scheduleEpicSettle({ cwd, epicId }, run, { delayMs }) — debounce per
+ * (cwd, epicId): a new call resets the timer; timers are unref'd; a run in
+ * flight is never started twice.
+ */
+function scheduleEpicSettle({ cwd, epicId } = {}, run, { delayMs } = {}) {
+  if (!cwd || !epicId || typeof run !== 'function') return;
+  const key = `${cwd}::${epicId}`;
+  const entry = _settle.get(key) || { timer: null, running: false };
+  _settle.set(key, entry);
+  if (entry.timer) clearTimeout(entry.timer);
+  const delay = Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : settleDelayMs();
+  entry.timer = setTimeout(async () => {
+    entry.timer = null;
+    if (entry.running) return;
+    entry.running = true;
+    try {
+      await run({ cwd, epicId });
+    } catch (e) {
+      try { console.error('[epicValidationHook] settle run error', epicId, e); } catch { /* noop */ }
+    } finally {
+      entry.running = false;
+      if (!entry.timer) _settle.delete(key);
+    }
+  }, delay);
+  if (entry.timer && typeof entry.timer.unref === 'function') entry.timer.unref();
+}
+
+/** Test hook: clear pending settle timers. */
+function __resetSettleForTests() {
+  for (const e of _settle.values()) if (e.timer) clearTimeout(e.timer);
+  _settle.clear();
 }
 
 module.exports = {
-  buildValidationPrompt,
-  maybeEnqueueValidationPrompt,
-  __resetForTests,
+  buildSettledDigest,
+  runEpicSettle,
+  scheduleEpicSettle,
+  __resetSettleForTests,
 };

package/src/main/lib/prd/prdCreate.cjs

@@ -32,6 +32,8 @@ const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('../scheduler/fixPlanSlug.cjs');
 const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
 const { sizingWarnings } = require('./prdSizing.cjs');
+const { execGit } = require('../git/gitExec.cjs');
+const { extractRepoPathCandidates, worktreeReachWarnings } = require('./prdWorktreeReach.cjs');
 const { validateGate, validateFiles, renderFilesSection, renderGateSection } = require('./prdGateFiles.cjs');
 const { resolveGate, parseChain, isNoneGate } = require('../scheduler/definitionOfDone.cjs');
 
@@ -186,6 +188,26 @@ function resolveSourcePromptIdFromClaudeSession(cwd, claudeSessionId) {
   return null;
 }
 
+
+/**
+ * Advisory: which relative paths the PRD names are gitignored in `cwd` (so absent from the job
+ * worktree). execGit has no stdin, so candidates go as argv after `--` (still one call). Exit 1 =
+ * nothing ignored; any other failure (not a repo, timeout) is swallowed — never blocks the write.
+ */
+async function worktreeReachAdvisory(input, cwd) {
+  try {
+    const text = [input.goal, ...(Array.isArray(input.acceptanceCriteria) ? input.acceptanceCriteria : []),
+      input.implementationNotes].filter((s) => typeof s === 'string').join('\n');
+    const candidates = extractRepoPathCandidates(text);
+    if (candidates.length === 0) return [];
+    const out = await execGit(cwd, ['check-ignore', '--', ...candidates], { timeout: 10000 });
+    const ignored = out.split('\n').map((l) => l.trim()).filter(Boolean);
+    return worktreeReachWarnings(input, ignored);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Core create-PRD orchestration: cwd validation, slug derivation, NN
  * allocation, existing-file collision check, body build, write. Shared by
@@ -419,6 +441,7 @@ async function createPrd(input, remote) {
   } else {
     extraWarnings.push('No files list: the executor is not told which files it may change.');
   }
+  extraWarnings.push(...await worktreeReachAdvisory(input, cwd));
 
   const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;

package/src/main/lib/prd/prdWorktreeReach.cjs

@@ -0,0 +1,77 @@
+/**
+ * prdWorktreeReach.cjs — pure PRD worktree-reach advisory rule.
+ *
+ * Incident: burrow PRD 1516-fb-bilko-first-pumpkin named a gitignored runtime path by RELATIVE
+ * path (downloads/fb-tracker.db) and an install-cron.sh that baked a worktree path. Scheduled
+ * PRDs run in an isolated git job worktree holding only tracked files plus symlinked dependency
+ * dirs (DEFAULT_DEP_DIRS), so that path pointed at a file that did not exist there and the job
+ * parked needs_human.
+ *
+ * Two exports: `extractRepoPathCandidates(text)` pulls repo-relative path-looking tokens out of
+ * PRD prose; `worktreeReachWarnings(input, ignoredPaths)` turns the ones the caller found
+ * gitignored (via `git check-ignore` — not done here) into one advisory warning. No I/O.
+ * Warnings never block a write.
+ */
+'use strict';
+
+const { DEFAULT_DEP_DIRS } = require('../git/worktreeDeps.cjs');
+
+const MAX_CANDIDATES = 200;
+const MAX_NAMED_PATHS = 5;
+
+const LEADING_JUNK_RE = /^[`'"([<]+/;
+const TRAILING_JUNK_RE = /[`'")\]>.,:;]+$/;
+
+function isCandidate(token) {
+  if (!token.includes('/')) return false;
+  if (/^[/~$-]/.test(token)) return false;
+  if (token.includes('://')) return false;
+  if (token.split('/').includes('..')) return false;
+  return true;
+}
+
+/** Pure. Deduped repo-relative tokens containing a '/', capped at 200. */
+function extractRepoPathCandidates(text) {
+  const seen = new Set();
+  for (const raw of String(text == null ? '' : text).split(/\s+/)) {
+    if (!raw) continue;
+    const token = raw.replace(LEADING_JUNK_RE, '').replace(TRAILING_JUNK_RE, '');
+    if (!token || !isCandidate(token)) continue;
+    seen.add(token);
+    if (seen.size >= MAX_CANDIDATES) break;
+  }
+  return [...seen];
+}
+
+function normalize(p) {
+  return String(p).replace(/^(\.\/)+/, '');
+}
+
+/**
+ * Pure. `input` mirrors createPrd()'s shape; missing fields are treated as empty.
+ * `ignoredPaths` is the caller's list of gitignored repo-relative paths. Returns `[]` when none
+ * remain after exempting symlinked dependency dirs, else exactly one warning string.
+ */
+function worktreeReachWarnings(input, ignoredPaths) {
+  const { goal, acceptanceCriteria, implementationNotes } = input || {};
+  const ac = Array.isArray(acceptanceCriteria) ? acceptanceCriteria.filter((l) => typeof l === 'string') : [];
+  const ignored = (Array.isArray(ignoredPaths) ? ignoredPaths : [])
+    .filter((p) => typeof p === 'string' && p)
+    .map(normalize)
+    .filter((p) => !DEFAULT_DEP_DIRS.includes(p.split('/')[0]));
+  if (ignored.length === 0) return [];
+
+  const text = [goal, ...ac, implementationNotes].filter((s) => typeof s === 'string').join('\n');
+  const mentioned = new Set(extractRepoPathCandidates(text).map(normalize));
+  const offending = [...new Set(ignored)].filter((p) => mentioned.has(p) || mentioned.has(p.replace(/\/+$/, '')));
+  const named = (offending.length ? offending : [...new Set(ignored)]).slice(0, MAX_NAMED_PATHS);
+
+  return [
+    `This PRD references gitignored path(s) by relative path: ${named.join(', ')}. `
+    + 'The job runs in an isolated worktree where gitignored files do not exist, so those paths will '
+    + 'be missing (or a baked-in worktree path will dangle). Address the main checkout by absolute path '
+    + 'in an artifact-only PRD (or split the PRD) — see PRD_AUTHORING.md section 7.',
+  ];
+}
+
+module.exports = { extractRepoPathCandidates, worktreeReachWarnings };

package/src/main/lib/scheduler/rcaReport.cjs

@@ -73,6 +73,7 @@ const FAILURE_CLASSES = {
   TRANSCRIPT_ERRORS: 'transcript-errors',
   ABANDONED_BACKGROUND_TASK: 'abandoned-background-task',
   BLOCKED_BY_FOREIGN_WIP: 'blocked-by-foreign-wip',
+  NEEDS_HUMAN: 'needs-human',
   UNKNOWN: 'unknown',
 };
 
@@ -82,8 +83,11 @@ const FAILURE_CLASSES = {
 // nothing to investigate, and re-queuing is already owned by
 // reconcile()'s requeueForeignWipBlockedJobs, not this action), 'resume-and-commit'
 // (PRD 1111's --resume dispatch owns this), 'verify-and-close' (the work
-// likely landed, just missing its sentinel), 'investigate' (the only class
-// that still buys a fix-plan investigation).
+// likely landed, just missing its sentinel), 'ask-human' (the executor
+// correctly stopped on a step only a person can do — answer the job's
+// humanQuestion, then update + reset the PRD; never a fix-plan, and the review
+// ladder never auto-fixes it), 'investigate' (the only class that still buys a
+// fix-plan investigation).
 const RECOVERY_ACTIONS = {
   [FAILURE_CLASSES.ALREADY_SHIPPED]: 'archive',
   [FAILURE_CLASSES.SELF_QUEUE]: 'investigate',
@@ -104,6 +108,7 @@ const RECOVERY_ACTIONS = {
   // guidance into that cold-read investigation.
   [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]: 'investigate',
   [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]: 'archive',
+  [FAILURE_CLASSES.NEEDS_HUMAN]: 'ask-human',
   [FAILURE_CLASSES.UNKNOWN]: 'investigate',
 };
 
@@ -131,6 +136,8 @@ const PREVENTION_HINTS = {
     'A headless run cannot receive a background-task completion notification — never let a long Bash command auto-background past its foreground timeout and then wait for it. Run long commands with an explicit bound (`timeout <N> <cmd>`) so they finish in the foreground, or poll their output file directly instead of waiting on Monitor/notification.',
   [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]:
     'This job correctly reported `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` against a sibling job\'s in-flight, uncommitted files three times in a row — auto-requeue is exhausted (reconcile() only clears this once the blocked paths go clean). This is not a defect in this PRD\'s own work: check on the sibling job/human that owns the still-dirty path(s) named on the job row, and either wait for them to commit or manually reset this job to `pending` once the tree is clear. Do not author a fix-plan PRD against it.',
+  [FAILURE_CLASSES.NEEDS_HUMAN]:
+    'The run stopped on a step that needs a person or live runtime state — the executor was right to stop, so this is not a defect to fix-plan. Answer the job\'s humanQuestion, then update and reset the PRD. If the reason is that the job worktree lacks gitignored runtime state (databases, browser profile, downloads/, crontab paths), re-author the step as an artifact-only PRD that addresses the main checkout by absolute path, per PRD_AUTHORING.md section 7.',
   [FAILURE_CLASSES.UNKNOWN]:
     'Re-run the acceptance criteria gate locally against the failure log to pin down the specific break before re-queuing.',
 };
@@ -192,6 +199,11 @@ function classifyFailure({ verdict, logTail: rawLogTail }) {
   const logTail = stripHarnessInitEvents(rawLogTail);
   const lines = logTail.split('\n');
 
+  // Checked before every other rule, log-tail heuristics included: the
+  // executor deliberately stopped on a human-only step, so words like
+  // "sleep"/"until" in its tail say nothing about the cause.
+  if (verdict === 'needs_human') return FAILURE_CLASSES.NEEDS_HUMAN;
+
   // Checked before every other rule: an unambiguous, materially-checked
   // verdict (the scheduler itself validated the executor's claimed paths
   // against the job's disclosed foreign-WIP manifest before ever landing

package/src/main/promptSessionEvents.cjs

@@ -69,7 +69,9 @@ function mintEventId() {
  * meta arg (not a fifth positional parameter) with `validation`: a
  * scheduler check-in is born `'unvalidated'` — never `'verified'` —
  * regardless of the job's self-reported outcome; the authoring Epic's own
- * validation pass is what may later move it to 'verified'/'refuted'. All
+ * validation pass is what may later move it to 'verified'/'refuted'. `agentType`
+ * (the job's agent) and `digestKey` (the settle digest's stable key) ride the
+ * same meta arg and are copied the same way. All
  * keys are added to the event object only when present in `meta`, never as
  * `undefined`-valued keys, so events appended without them serialize
  * identically to before.
@@ -99,6 +101,8 @@ async function appendResponseEventWithReason(cwd, sourcePromptId, text, meta = {
       if (meta && meta.prdSlug) event.prdSlug = meta.prdSlug;
       if (meta && meta.outcome) event.outcome = meta.outcome;
       if (meta && meta.validation) event.validation = meta.validation;
+      if (meta && meta.agentType) event.agentType = meta.agentType;
+      if (meta && meta.digestKey) event.digestKey = meta.digestKey;
       data.events[sourcePromptId] = [...events, event];
       await config.writeJson(path, data, { writer: 'scheduler' });
       broadcast(EVENT_APPENDED_CHANNEL, { cwd, promptSessionId: sourcePromptId, event });