claude-code-session-manager 0.57.1 → 0.59.0

package/src/main/lib/epicMint.cjs

@@ -1,10 +1,20 @@
 /**
- * epicMint.cjs — auto-mint an Epic (PromptSession) for a PRD dispatch.
+ * epicMint.cjs — resolve the Epic (PromptSession) a PRD dispatch belongs to,
+ * and mint the one Epic-creation path there is.
  *
  * Domain rule (CLAUDE.md "Domain model"): every PRD belongs to an Epic; the
- * hierarchy TAB → operations-root → EPIC → PRD is total. Dispatch paths that
- * have no Epic in hand (feedback sweep, ad-hoc /develop, admin/MCP create)
- * call ensureEpic() to create-or-join one instead of writing epicless PRDs.
+ * hierarchy TAB → operations-root → EPIC → PRD is total. Dispatch paths call
+ * ensureEpic() to JOIN the Epic they already belong to instead of writing
+ * epicless PRDs — they can never create one.
+ *
+ * SINGLE-CREATOR LAW (fail-closed, mirrors opsOwnership.cjs's assertOpsWrite):
+ * an Epic comes into existence in exactly ONE place — the human pressing
+ * "New Epic" in the app. That is the only caller allowed to pass
+ * `mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI` (today: lib/
+ * promptSessionsCreateEpic.cjs, the New Epic card's IPC handler). Every other
+ * caller is join-only and throws rather than conjuring an Epic. Agents that
+ * are sure work is needed run /develop inside the Epic they are already in;
+ * agents that are not sure say so and let the human open an Epic.
  *
  * The Epic registry is the renderer's own store: the per-cwd
  * `session-manager-operations/prompt-sessions/active-index.json`
@@ -23,6 +33,17 @@ const crypto = require('node:crypto');
 const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
+// Required as the module object (not destructured) so a test can
+// monkeypatch promptSessionSchema.assertValidPromptSession in place to
+// simulate a corrupted construction — the real construction below is
+// hardcoded and always valid.
+const promptSessionSchema = require('./promptSessionSchema.cjs');
+
+// The one token that unlocks ensureEpic's mint branch. Held by
+// lib/promptSessionsCreateEpic.cjs (the New Epic card's IPC handler) and
+// nothing else — grep for it before adding a second holder, that is a
+// deliberate domain-model change, not a convenience.
+const MINT_AUTHORITY_NEW_EPIC_UI = 'new-epic-ui';
 
 function activeIndexPath(cwd) {
   return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
@@ -63,7 +84,7 @@ function writeActiveIndex(cwd, index) {
 // "constructor" resolves through the prototype chain to a truthy
 // Object.prototype member even though no such Epic was ever written,
 // bypassing every "does this Epic exist" gate below (including the
-// mintIfMissing:false join-only check that PRD-authoring paths rely on).
+// join-only existence check that PRD-authoring paths rely on).
 // Always use this instead of `obj[key]`/`!obj[key]` for existence checks.
 function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
@@ -77,85 +98,6 @@ function slugify(text) {
     .slice(0, 48) || 'epic';
 }
 
-const STOPWORDS = new Set([
-  'the', 'a', 'an', 'is', 'of', 'to', 'for', 'and', 'in', 'on', 'at', 'this', 'that',
-]);
-
-// Lowercase, strip punctuation, split on whitespace, drop stopwords — shared
-// by findJoinableEpic's similarity check. Kept standalone so its behavior is
-// independently testable rather than inlined into the Jaccard computation.
-function tokenize(text) {
-  return String(text || '')
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]+/g, ' ')
-    .split(/\s+/)
-    .filter((token) => token && !STOPWORDS.has(token));
-}
-
-function jaccardSimilarity(tokensA, tokensB) {
-  const setA = new Set(tokensA);
-  const setB = new Set(tokensB);
-  if (setA.size === 0 && setB.size === 0) return 0;
-  let intersection = 0;
-  for (const token of setA) {
-    if (setB.has(token)) intersection += 1;
-  }
-  const union = setA.size + setB.size - intersection;
-  return union === 0 ? 0 : intersection / union;
-}
-
-const JOIN_SIMILARITY_THRESHOLD = 0.35;
-
-/**
- * findJoinableEpicInIndex(index, { goalText, preferEpicId, status }) → { epicId, matchedBy, score? } | null
- *
- * Same contract as findJoinableEpic() but takes an already-loaded index —
- * lets ensureEpic() consult this without a second readActiveIndex() call
- * inside its own withPathLock critical section. Two strategies, in order:
- *  1. `preferEpicId` — an explicitly-known origin Epic the caller already has
- *     in hand. Joined immediately (no similarity check) as long as it exists
- *     and is still open ('proposed' or 'active') — a 'completed' or unknown
- *     preferEpicId falls through to strategy 2 rather than joining a dead Epic.
- *  2. Keyword-similarity — Jaccard token-set overlap between `goalText` and
- *     every other OPEN Epic's goalText in the same cwd (open = 'proposed' or
- *     'active', regardless of the specific requested `status` — a proposed
- *     RCA report and an active one about the same topic are still the same
- *     underlying issue). Highest score wins if it clears
- *     JOIN_SIMILARITY_THRESHOLD; otherwise no join. `status` is accepted for
- *     signature symmetry with ensureEpic()/reuseByGoal but only participates
- *     in strategy 1's preferEpicId open-check, not the similarity filter.
- */
-function findJoinableEpicInIndex(index, { goalText, preferEpicId = null, status: _status = 'proposed' } = {}) {
-  if (preferEpicId && hasOwn(index.sessions, preferEpicId)) {
-    const preferred = index.sessions[preferEpicId];
-    if (preferred && (preferred.status === 'proposed' || preferred.status === 'active')) {
-      return { epicId: preferEpicId, matchedBy: 'preferEpicId' };
-    }
-  }
-
-  const candidateTokens = tokenize(goalText);
-  let best = null;
-  for (const s of Object.values(index.sessions)) {
-    if (!s || (s.status !== 'proposed' && s.status !== 'active')) continue;
-    const score = jaccardSimilarity(candidateTokens, tokenize(s.goalText));
-    if (score >= JOIN_SIMILARITY_THRESHOLD && (!best || score > best.score)) {
-      best = { epicId: s.id, matchedBy: 'similarity', score };
-    }
-  }
-  return best;
-}
-
-/**
- * findJoinableEpic(cwd, { goalText, preferEpicId, status }) → { epicId, matchedBy, score? } | null
- *
- * Public entry point for callers outside ensureEpic()'s own critical section
- * (tests, future PRD 899/900 wiring) — loads the index itself. See
- * findJoinableEpicInIndex() for the matching logic.
- */
-function findJoinableEpic(cwd, opts = {}) {
-  return findJoinableEpicInIndex(readActiveIndex(cwd), opts);
-}
-
 // Serializes read-modify-write cycles per active-index.json path, mirroring
 // promptSessionEvents.cjs's own pendingWritesByPath/withPathLock. The current
 // read/write pair below is synchronous (fs.readFileSync/writeFileSync), so
@@ -180,40 +122,26 @@ function withPathLock(lockPath, task) {
 }
 
 /**
- * ensureEpic(cwd, { goalText, tag?, reuseByGoal?, status?, openingPrompt?, mintIfMissing?, source?, forceNewEpic? }) → Promise<{ epicId, prdDir, created }>
- *
- * Before minting brand-new, the mint branch consults findJoinableEpic() —
- * minting is the LAST resort, not the default, for automated callers. Pass
- * `forceNewEpic: true` to skip that check and always mint (the one
- * legitimate case being explicit human-authored creation).
+ * ensureEpic(cwd, { epicId?, goalText, tag?, status?, openingPrompt?, source?, agentType?, mintAuthority? }) → Promise<{ epicId, prdDir, created }>
  *
- * `status` defaults to 'proposed' — a fail-safe default so any caller that
- * forgets to pass it files an Epic that waits for human approval rather than
- * one that starts running immediately. Every Epic is BORN 'proposed' — the
- * mint branch below ignores/rejects any other requested status; it is
- * fail-closed, mirroring opsOwnership.cjs's assertOpsWrite. Activation
- * ('proposed' → 'active') happens exactly once, entirely in the renderer
- * store's `approveProposed` (`state/promptSessions.ts`) — that code path
- * never calls ensureEpic(). Joining an already-'active' Epic (this function's
- * join branches, above the mint branch) remains legal and unchanged.
+ * Two behaviors, and only two:
+ *  - JOIN (the default, for every automated caller): `epicId` names an Epic
+ *    that already exists and is still open ('proposed'/'active') → its prds/
+ *    directory is returned with `created: false`. Anything else throws.
+ *  - MINT (the New Epic UI alone): `mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI`
+ *    creates a brand-new Epic. No similarity/keyword matching runs first — the
+ *    human asked for a new Epic, so they get a new Epic.
  *
- * `mintIfMissing` defaults to true for the small set of callers that are
- * themselves the human-intent gate (propose-epic, the RCA hook, the feedback
- * sweep — all of which pass `status: 'proposed'`, so "minting" here still
- * never starts anything without a human's Approve & start). Callers that are
- * NOT themselves a human-intent gate (an automated PRD-write path acting on
- * a session's behalf) must pass `mintIfMissing: false` — that path may only
- * JOIN an Epic that already exists; it throws instead of silently creating a
- * new one, so no PRD-authoring surface can conjure Epics on its own.
- *
- * Mints a new Epic — or, with `reuseByGoal`, joins the existing Epic (of the
- * same `status`) whose goalText matches (used by the recurring feedback sweep
- * so successive sweeps chain into one Epic instead of minting one per tick).
+ * Every Epic is BORN 'proposed'; `status` defaults to it and the mint branch
+ * rejects any other value outright (fail-closed, mirroring opsOwnership.cjs's
+ * assertOpsWrite). Activation ('proposed' → 'active') happens exactly once, in
+ * the renderer store's `approveProposed` (`state/promptSessions.ts`) — a path
+ * that never calls ensureEpic().
  *
  * The Epic's id doubles as its directory name under scheduler/epics/, so the
  * PromptSession ↔ on-disk Epic mapping is 1:1 with no lookup table.
  */
-function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, mintIfMissing = true, source = null, forceNewEpic = false } = {}) {
+function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, sections = null, source = null, agentType = null, mintAuthority = null } = {}) {
   if (!cwd || typeof cwd !== 'string') throw new Error('ensureEpic: cwd is required');
   // A relative cwd (e.g. a caller passing '.') would otherwise get stored
   // verbatim on the minted Epic's `cwd` field — the renderer's EpicsWorkspace
@@ -230,8 +158,7 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
     // let a stale/hallucinated sourcePromptId silently attach a PRD (and its
     // follow-on events/chat activity) to an unrelated or even completed
     // Epic — the "this session ran again without my knowledge, and it was
-    // really another Epic's prompt" cross-contamination bug. Mirrors
-    // findJoinableEpicInIndex()'s preferEpicId open-check (line ~124).
+    // really another Epic's prompt" cross-contamination bug.
     if (explicitEpicId && hasOwn(index.sessions, explicitEpicId)) {
       const preferred = index.sessions[explicitEpicId];
       if (preferred && (preferred.status === 'proposed' || preferred.status === 'active')) {
@@ -239,57 +166,26 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
         fs.mkdirSync(prdDir, { recursive: true });
         return { epicId: explicitEpicId, prdDir, created: false };
       }
-      console.warn(`[epicMint] ensureEpic: explicit epicId ${explicitEpicId} exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join, falling through`);
+      console.warn(`[epicMint] ensureEpic: explicit epicId ${explicitEpicId} exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join`);
       appendAuditEvent('epic_mint_refused', {
         cwd,
         epicId: explicitEpicId,
         status,
-        reason: `explicit epicId exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join, falling through to mint`,
+        reason: `explicit epicId exists but is not open (status=${preferred?.status ?? 'unknown'}) — refusing to join`,
       });
     }
 
-    if (reuseByGoal) {
-      for (const s of Object.values(index.sessions)) {
-        // Match the status being requested so repeat proposals chain into
-        // one proposal instead of spawning a duplicate per trigger.
-        if (s && s.status === status && s.goalText === goalText) {
-          // A PROPOSED Epic has not started, so its opening prompt is still
-          // mutable: a re-trigger carrying richer detail (e.g. the RCA hook's
-          // later investigation pass) enriches the pending proposal in place
-          // rather than filing a duplicate. Never done for an active Epic —
-          // its first turn is already history.
-          if (s.status === 'proposed' && openingPrompt && openingPrompt !== s.openingPrompt) {
-            s.openingPrompt = String(openingPrompt);
-            const chain = index.events[s.id];
-            if (Array.isArray(chain) && chain[0] && chain[0].kind === 'prompt') {
-              chain[0].text = String(openingPrompt);
-            }
-            writeActiveIndex(cwd, index);
-          }
-          const prdDir = resolveEpicPrdWriteDir(cwd, s.id);
-          fs.mkdirSync(prdDir, { recursive: true });
-          return { epicId: s.id, prdDir, created: false };
-        }
-      }
-    }
-
-    if (!mintIfMissing) {
-      const reason = 'no existing Epic found and mintIfMissing is false — a new Epic can only be created by '
-        + 'explicit human intent (New Epic UI, or /propose-epic + Approve & start), never implicitly by a '
-        + 'PRD-authoring path';
+    // SINGLE-CREATOR LAW (see this file's header). Only the New Epic UI may
+    // mint; every other caller reaching this line was trying to JOIN an Epic
+    // that isn't there, which is a bug in the caller, not a cue to create one.
+    if (mintAuthority !== MINT_AUTHORITY_NEW_EPIC_UI) {
+      const reason = 'no open Epic to join — an Epic is created in exactly one place, the New Epic UI '
+        + '(mintAuthority). Agents that are sure the work is needed run /develop inside the Epic they are '
+        + 'already in; a PRD-authoring path may never conjure one';
       appendAuditEvent('epic_mint_refused', { cwd, epicId: explicitEpicId ?? null, status, reason });
       throw new Error(`ensureEpic: ${reason} (epicId=${explicitEpicId ?? 'none'})`);
     }
 
-    if (!forceNewEpic) {
-      const joinable = findJoinableEpicInIndex(index, { goalText, preferEpicId: explicitEpicId, status });
-      if (joinable) {
-        const prdDir = resolveEpicPrdWriteDir(cwd, joinable.epicId);
-        fs.mkdirSync(prdDir, { recursive: true });
-        return { epicId: joinable.epicId, prdDir, created: false };
-      }
-    }
-
     // BORN-PROPOSED LAW (fail-closed, mirrors opsOwnership.cjs's
     // assertOpsWrite): a mint always writes 'proposed', regardless of what
     // status the caller requested. A caller explicitly asking to mint
@@ -313,9 +209,8 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
       // Independently minted, never shared with a SessionTab — same invariant
       // as renderer-created PromptSessions (state/promptSessions.ts).
       claudeSessionId: crypto.randomUUID(),
-      // 'proposed' files the Epic WITHOUT starting it — nothing runs until a
-      // human approves it in the Epics workspace. This is the sink that
-      // replaced the feedback-folder intake (see lib/rcaFeedbackHook.cjs).
+      // 'proposed' files the Epic WITHOUT starting it — nothing runs until the
+      // human presses Approve & start in the Epics workspace.
       status,
       createdAt: now,
       completedAt: null,
@@ -323,10 +218,39 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
       // Full body for a proposal whose goalText is only a one-line title;
       // sent verbatim as the first prompt when a human approves it.
       ...(openingPrompt ? { openingPrompt: String(openingPrompt) } : {}),
-      // Structured trace of which automated producer minted this Epic — see
-      // EpicSource in state/promptSessions.ts.
+      // Structured slices of the same openingPrompt (composeEpicIntake's
+      // EpicIntakeSection[]) — carried alongside it so the Epic's first turn
+      // can render an AIM briefing card instead of re-parsing the flat
+      // string. Absent whenever openingPrompt is absent too.
+      ...(Array.isArray(sections) && sections.length ? { sections } : {}),
+      // Structured trace of which surface minted this Epic — see EpicSource in
+      // state/promptSessions.ts.
       ...(source ? { source } : {}),
+      // Display-only "who is working" persona name (New Epic card's Agent
+      // picker). The renderer no longer constructs a PromptSession itself —
+      // PRD 955 / commit ba54269 routed createPromptSession through this same
+      // ensureEpic IPC path (state/promptSessions.ts). Never affects which
+      // claude CLI spawns.
+      ...(agentType ? { agentType } : {}),
     };
+
+    // Validate the constructed record against the canonical PromptSession
+    // schema (promptSessionSchema.cjs) before it ever reaches disk — closes
+    // the drift risk between this hand-constructed literal and the
+    // renderer's own createPromptSession, same fail-closed spirit as the
+    // BORN-PROPOSED LAW check above.
+    try {
+      promptSessionSchema.assertValidPromptSession(session);
+    } catch (err) {
+      appendAuditEvent('epic_mint_refused', {
+        cwd,
+        epicId,
+        status,
+        reason: `constructed session object failed PromptSession schema validation: ${err.message}`,
+      });
+      throw err;
+    }
+
     const firstEvent = {
       id: crypto.randomUUID(),
       promptSessionId: epicId,
@@ -339,9 +263,8 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
     index.events[epicId] = [firstEvent];
     writeActiveIndex(cwd, index);
 
-    // Every mint is logged, whether the Epic starts 'proposed' (human gate
-    // ahead) or 'active' (started immediately) — this is the trace-back point
-    // for "who/what created this Epic" (see auditLog.cjs).
+    // Every mint is logged — the trace-back point for "who created this Epic"
+    // (see auditLog.cjs).
     appendAuditEvent('epic_mint', { cwd, epicId, status, tag: tag ?? null, goalText: session.goalText, source: source ?? null });
 
     const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
@@ -399,12 +322,11 @@ function removeEpic(cwd, epicId) {
 
 module.exports = {
   ensureEpic,
+  MINT_AUTHORITY_NEW_EPIC_UI,
   appendPrdCreatedEvent,
   removeEpic,
   activeIndexPath,
   readActiveIndex,
-  findJoinableEpic,
-  tokenize,
   // Exported so lib/activeIndexMerge.cjs's renderer-facing merge IPC handler
   // serializes through the SAME lock instance as ensureEpic/
   // appendPrdCreatedEvent (module-level Map, shared via Node's require

package/src/main/lib/epicValidationHook.cjs

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * epicValidationHook.cjs — a PRD check-in triggers validation in the
+ * authoring Epic; it never asserts the PRD is done (PRD 986).
+ *
+ * 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.
+ *
+ * Shape mirrors lib/dodDrainHook.cjs: fire-and-forget (never throws to the
+ * caller — errors are logged), kill-switched, idempotent.
+ *
+ * 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/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.
+ *
+ * Join-only: nothing here can create an Epic (epicMint.cjs's SINGLE-CREATOR
+ * LAW). If no active authoring Epic exists, log and 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}`;
+}
+
+/**
+ * Default active-index reader: the same on-disk file
+ * promptSessionEvents.cjs writes. Read-only here (no lock needed — a torn
+ * read degrades to "skip", never to a bad write). Returns null on any
+ * error/missing file so callers treat it as "no active Epic".
+ */
+function defaultReadActiveIndex(cwd) {
+  try {
+    const p = path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+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');
+}
+
+/**
+ * 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' };
+
+    // 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' };
+
+    if (!cwd || !epicId || !prdSlug || typeof sendPrompt !== 'function') {
+      return { enqueued: false, reason: 'missing-args' };
+    }
+
+    // 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' };
+
+    // 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' };
+    }
+
+    // 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 prompt = buildValidationPrompt({ prdSlug, prdPath, outcome });
+    sendPrompt(epicId, prompt);
+    _fired.add(key);
+    return { enqueued: true };
+  } catch (e) {
+    try { (log || console).error('[epicValidationHook] enqueue error', prdSlug, e); } catch { /* noop */ }
+    return { enqueued: false, reason: 'error' };
+  }
+}
+
+/** Test hook: clear the once-per-pair memory. */
+function __resetForTests() {
+  _fired.clear();
+}
+
+module.exports = {
+  buildValidationPrompt,
+  maybeEnqueueValidationPrompt,
+  __resetForTests,
+};

package/src/main/lib/prdMigration.cjs

@@ -18,6 +18,7 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
+const { projectQueuePath } = require('./queueStore.cjs');
 const { expandHome } = require('./expandHome.cjs');
 
 /**
@@ -95,22 +96,92 @@ async function migratePrds(legacyPrdsDir) {
  * Name collisions in prds-archived/ get a `-legacy-<n>` suffix, never an
  * overwrite. Idempotent: an emptied flat dir is a no-op readdir.
  *
- * Returns { moved, failed: [{ file, reason }] }.
+ * LIVE JOBS ARE NEVER ARCHIVED (PRD 992). The scheduler still scans this flat
+ * dir as a PRD *source* (prdLocations.cjs's resolvePrdsDirs, "scan sources
+ * alongside the legacy flat dir"), so a file sitting here can legitimately
+ * have a pending/running job. Archiving it out from under that job strands the
+ * queue row with no resolvable source. Observed live 2026-08-02:
+ * `980-fix-chat-typed-event-renderers.md` sat in this dir with status
+ * `running` — a restart in that window would have moved its source mid-run.
+ * Such files are left in place and reported as `skipped`, mirroring how the
+ * sibling migratePrds() reports `unresolved` rather than dropping anything.
+ *
+ * Returns { moved, failed: [{ file, reason }], skipped: [{ file, reason }] }.
+ */
+
+/** Job statuses that mean "this PRD's source must survive". `needs_review` is
+ *  live on purpose: it is awaiting human action and will be re-read. */
+const LIVE_JOB_STATUSES = new Set(['pending', 'running', 'needs_review', 'investigating']);
+
+/**
+ * Slugs with a live job in this project's own queue shard.
+ *
+ * Returns null when liveness cannot be determined (unreadable/unparseable
+ * queue.json) — the caller then FAILS CLOSED and archives nothing, since it
+ * cannot prove a file is safe to move. A merely ABSENT queue.json is not an
+ * error: a project with no scheduler state has no jobs, so an empty set is
+ * the correct answer and consolidation proceeds normally.
  */
-async function consolidateFlatPrds(cwd) {
+async function liveSlugsForCwd(cwd) {
+  let raw;
+  try {
+    raw = await fsp.readFile(projectQueuePath(cwd), 'utf8');
+  } catch (e) {
+    if (e?.code === 'ENOENT') return new Set(); // fresh project — nothing queued
+    return null; // unreadable — caller fails closed
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null; // corrupt — caller fails closed
+  }
+  const jobs = Array.isArray(parsed?.jobs) ? parsed.jobs : [];
+  const live = new Set();
+  for (const job of jobs) {
+    if (job && typeof job.slug === 'string' && LIVE_JOB_STATUSES.has(job.status)) {
+      live.add(job.slug);
+    }
+  }
+  return live;
+}
+
+/** A queue job's slug is its PRD filename minus the `.md` suffix. */
+function slugForPrdFile(name) {
+  return name.slice(0, -3);
+}
+
+async function consolidateFlatPrds(cwd, opts = {}) {
   const flatDir = resolvePrdWriteDir(cwd);
   const archiveDir = path.join(path.dirname(flatDir), 'prds-archived');
   let entries;
   try {
     entries = await fsp.readdir(flatDir);
   } catch {
-    return { moved: 0, failed: [] };
+    return { moved: 0, failed: [], skipped: [] };
   }
 
+  const liveSlugs = opts.liveSlugs !== undefined ? opts.liveSlugs : await liveSlugsForCwd(cwd);
+
   let moved = 0;
   const failed = [];
+  const skipped = [];
+
+  // Fail closed: liveness unknown means every file might belong to a live job.
+  if (liveSlugs === null) {
+    for (const name of entries) {
+      if (!name.endsWith('.md') || name.startsWith('.')) continue;
+      skipped.push({ file: name, reason: 'queue state unreadable — cannot prove no live job' });
+    }
+    return { moved: 0, failed, skipped };
+  }
+
   for (const name of entries) {
     if (!name.endsWith('.md') || name.startsWith('.')) continue;
+    if (liveSlugs.has(slugForPrdFile(name))) {
+      skipped.push({ file: name, reason: 'live queue job — source must survive' });
+      continue;
+    }
     const src = path.join(flatDir, name);
     try {
       await fsp.mkdir(archiveDir, { recursive: true });
@@ -125,7 +196,7 @@ async function consolidateFlatPrds(cwd) {
       failed.push({ file: name, reason: e?.message ?? 'move failed' });
     }
   }
-  return { moved, failed };
+  return { moved, failed, skipped };
 }
 
-module.exports = { migratePrds, consolidateFlatPrds };
+module.exports = { migratePrds, consolidateFlatPrds, LIVE_JOB_STATUSES };