claude-code-session-manager 0.58.0 → 0.59.0

package/src/main/ipcSchemas.cjs

@@ -8,7 +8,7 @@
 const { z } = require('zod');
 const os = require('node:os');
 const path = require('node:path');
-const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema } = require('./lib/promptSessionSchema.cjs');
+const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema, EpicIntakeSectionSchema } = require('./lib/promptSessionSchema.cjs');
 
 // ──────────────────────────────────────────── PTY
 const ptySpawn = z.object({
@@ -183,6 +183,23 @@ const transcriptUsageFor = z.object({
   sessionIds: z.array(z.string().regex(SESSION_UUID_RE)).max(500),
 });
 
+// Paged read over a subscribed transcript's line-offset index. Bounded line
+// numbers — a page is a scroll window, never an unbounded range request.
+const transcriptPage = z.object({
+  tabId: z.string().min(1).max(128),
+  startLine: z.number().int().min(0),
+  endLine: z.number().int().min(0),
+});
+
+// Single-line full-payload read via a classifier byte reference (expand-to-
+// full path, PRD chat-typed-event-renderers). byteLength bound mirrors
+// transcripts.cjs's MAX_REF_BYTES — one JSONL line, never a whole-file read.
+const transcriptReadRef = z.object({
+  filePath: z.string().min(1).max(4096),
+  byteOffset: z.number().int().min(0),
+  byteLength: z.number().int().min(1).max(64 * 1024 * 1024),
+});
+
 // ──────────────────────────────────────────── Config
 const configPath = z.object({ path: z.string().min(1).max(4096) });
 
@@ -285,6 +302,11 @@ const promptSessionsCreateEpic = z.object({
   tag: EpicTagSchema.optional(),
   agentType: z.string().min(1).max(256).optional(),
   source: EpicSourceSchema.optional(),
+  // The full first-prompt body + its labeled sections (epicIntake.ts's
+  // composeEpicIntake) — both optional, since not every mint caller (e.g. a
+  // future scripted Epic) composes a full opening prompt.
+  openingPrompt: z.string().max(200000).optional(),
+  sections: z.array(EpicIntakeSectionSchema).max(200).optional(),
 });
 
 // ──────────────────────────────────────────── Sessions
@@ -439,7 +461,6 @@ const home = os.homedir();
 const setConfigSchema = z.object({
   enabled: z.boolean().optional(),
   offsetMinutes: z.number().int().min(0).max(180).optional(),
-  concurrencyCap: z.number().int().min(1).max(20).optional(),
   defaultCwd: z.string().max(4096).refine(
     (s) => s === home || s.startsWith(home + path.sep),
     'defaultCwd must be inside home directory'
@@ -457,7 +478,7 @@ const setConfigSchema = z.object({
 // Machine-wide claude -p slot pool cap (sessionSlots.cjs) — deliberately its own
 // schema/channel rather than folded into setConfigSchema: it governs the shared
 // process pool, not any one project's scheduler config, and its range (0-10, 0
-// pauses new launches) differs from concurrencyCap's (1-20).
+// pauses new launches) is the single concurrency control.
 const setSessionSlotsSchema = z.object({
   cap: z.number().int().min(0).max(10),
 }).strict();
@@ -965,6 +986,8 @@ module.exports = {
     transcriptTabId,
     transcriptPath,
     transcriptUsageFor,
+    transcriptPage,
+    transcriptReadRef,
     configPath,
     configWriteJson,
     configWriteText,

package/src/main/lib/__tests__/schedulerBatchDepends.test.cjs

@@ -92,3 +92,133 @@ test('a FAILED bare-named dep holds the dependent and reports an explicit reason
   assert.match(reason, /depends-gate/);
   assert.match(reason, /874-nav-face-project-home <- leftnav-two-face-framework/);
 });
+
+// ---------------------------------------------------------------------------
+// Parallelism regression coverage.
+//
+// `parallelGroup` used to gate batch membership: the picker fired at most one
+// group per tick and held every higher group while a lower one was in flight.
+// PRD 832 made the number strictly unique per PRD, so every group became a
+// singleton and the batch was always exactly ONE job — measured max
+// concurrency 1 across 25 recorded runs against a 5-slot pool. These tests
+// pin the corrected contract: dependsOn is the only barrier, parallelGroup is
+// a priority hint.
+// ---------------------------------------------------------------------------
+
+test('fires EVERY dependency-eligible job, not one per parallelGroup', () => {
+  const jobs = [
+    job('983-a', 'pending'),
+    job('984-b', 'pending'),
+    job('985-c', 'pending'),
+    job('986-d', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  // Pre-fix this returned exactly ['983-a'] — one singleton group.
+  assert.deepEqual(batch.map((j) => j.slug), ['983-a', '984-b', '985-c', '986-d']);
+});
+
+test('a higher-numbered job is NOT held behind an in-flight lower-numbered one', () => {
+  const jobs = [
+    job('979-running', 'running'),
+    job('988-independent', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(['979-running']), 5);
+  // Pre-fix: held by the running-gate ("g979 in flight, holding g988"), which
+  // is how the fix for this very bug ended up stuck behind the bug.
+  assert.deepEqual(batch.map((j) => j.slug), ['988-independent']);
+});
+
+test('dependency-blocked jobs are excluded while independent siblings fire together', () => {
+  const jobs = [
+    job('985-foundation', 'pending'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+    job('987-independent', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['985-foundation', '987-independent']);
+});
+
+test('a FAILED job holds its transitive dependents but not unrelated jobs', () => {
+  const jobs = [
+    job('980-broken', 'failed'),
+    job('981-direct', 'pending', { dependsOn: ['broken'] }),
+    job('982-transitive', 'pending', { dependsOn: ['direct'] }),
+    job('983-unrelated', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 5);
+  // Pre-fix the cross-group failure gate held 983 too, purely for having a
+  // higher number than the failure.
+  assert.deepEqual(batch.map((j) => j.slug), ['983-unrelated']);
+});
+
+test('parallelGroup orders the batch when eligible jobs exceed free slots', () => {
+  const jobs = [
+    job('990-c', 'pending'),
+    job('988-a', 'pending'),
+    job('989-b', 'pending'),
+  ];
+  const { batch } = pick(jobs, new Set(), 2);
+  assert.deepEqual(batch.map((j) => j.slug), ['988-a', '989-b']);
+});
+
+test('zero free slots holds everything with an explicit reason', () => {
+  const jobs = [job('988-a', 'pending'), job('989-b', 'pending')];
+  const { batch, reason } = pick(jobs, new Set(), 0);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /no slots free/);
+});
+
+// ---------------------------------------------------------------------------
+// Per-job hold records (PRD 990). The picker already knew exactly which dep
+// held which row; it only ever reached console.log. These pin it as data.
+// ---------------------------------------------------------------------------
+
+test('reports a per-job hold record naming the blocking dep and its status', () => {
+  const jobs = [
+    job('985-foundation', 'pending'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['985-foundation']);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'pending' },
+  ]);
+});
+
+test('hold record carries a running dep status', () => {
+  const jobs = [
+    job('985-foundation', 'running'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { holds } = pick(jobs, new Set(['985-foundation']), 5);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'running' },
+  ]);
+});
+
+test('hold record carries a failed dep status alongside the depends-gate reason', () => {
+  const jobs = [
+    job('985-foundation', 'failed'),
+    job('986-dependent', 'pending', { dependsOn: ['foundation'] }),
+  ];
+  const { batch, reason, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /depends-gate/);
+  assert.deepEqual(holds, [
+    { slug: '986-dependent', dep: 'foundation', depStatus: 'failed' },
+  ]);
+});
+
+test('no holds when nothing is dependency-blocked', () => {
+  const jobs = [job('988-a', 'pending'), job('989-b', 'pending')];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.equal(batch.length, 2);
+  assert.deepEqual(holds, []);
+});
+
+test('an idle queue reports no holds (empty must not read as blocked)', () => {
+  const jobs = [job('988-a', 'completed')];
+  const { batch, holds } = pick(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.deepEqual(holds, []);
+});

package/src/main/lib/classifyTranscriptLine.cjs

@@ -1,17 +1,34 @@
 'use strict';
 
+// Bound on any single string field kept inline in the in-memory `raw`
+// projection stored per event (events are ring-buffered up to 500 deep,
+// see transcripts.cjs's sub.buffer). Anything longer is truncated here —
+// the full untruncated line is still recoverable via the event's `ref`
+// (byte offset/length into the transcript file on disk, see makeEvent).
 const MAX_RAW_STR = 4096;
 
-// Block types whose text/content fields are parsed structurally by
-// orchestrator.ts / race.ts — truncating them produces mid-token "…" and
-// unparseable JSON, so they are exempt from the size cap.
-const EXEMPT_TYPES = new Set(['tool_result', 'tool_use']);
+// Bound on the short human-scannable preview attached to every event.
+// Deliberately much smaller than MAX_RAW_STR — previewText is for a
+// glance, not a document; the full payload is always one disk read away
+// via `ref`.
+const PREVIEW_CHARS = 280;
+
+// Historically tool_use/tool_result blocks were exempted from the
+// MAX_RAW_STR cap so orchestrator.ts/race.ts could structurally re-parse
+// them without a truncated mid-token "…". Both files were deleted
+// 2026-07-30 (commit e3848c3, "delete Subagents-only dead code") along
+// with the rest of the Subagents tab, and no current consumer needs an
+// untruncated tool_result/tool_use block in the in-memory `raw`
+// projection — holding one verbatim (e.g. a large Read tool_result) in a
+// 500-entry ring buffer was a real memory-cliff incident. Every block
+// type is now trimmed the same way; this stays exported (empty) in case
+// a future structural consumer needs to opt a block type back out.
+const EXEMPT_TYPES = new Set();
 
 /**
- * Cap string fields in a content block array so arbitrary tool output doesn't
- * bloat the ring buffer. Blocks whose type is in EXEMPT_TYPES are passed
- * through intact so that structured result payloads survive to the digest
- * parsers in race.ts / orchestrator.ts.
+ * Cap string fields in a content block array so arbitrary tool output
+ * doesn't bloat the ring buffer. Blocks whose type is in EXEMPT_TYPES are
+ * passed through intact (currently no type is exempt — see comment above).
  */
 function trimContentArray(content) {
   if (!Array.isArray(content)) return content;
@@ -32,58 +49,124 @@ function trimContentArray(content) {
   });
 }
 
-/** Build the slim raw projection used by race.ts and orchestrator.ts. */
+/**
+ * Build the raw projection carried on every event. Preserves every
+ * top-level field on the line (attribution*, effort, gitBranch,
+ * isSidechain, isMeta, requestId, isApiErrorMessage,
+ * interruptedByShutdown, permissionMode, promptSource, toolUseResult,
+ * etc.) — not just message.content — so the renderer can surface all of
+ * it, however trivial or redundant. message.content is still run through
+ * trimContentArray to bound size in the ring buffer.
+ */
 function makeRaw(obj) {
-  const msgContent = obj?.message?.content;
-  return { message: { content: trimContentArray(msgContent) } };
+  if (!obj || typeof obj !== 'object') return {};
+  const raw = {};
+  for (const key of Object.keys(obj)) {
+    if (key === 'message') continue;
+    raw[key] = obj[key];
+  }
+  if (obj.message && typeof obj.message === 'object') {
+    raw.message = { ...obj.message, content: trimContentArray(obj.message.content) };
+  }
+  return raw;
+}
+
+/** Bounded, human-scannable preview of an event's data — never the source of truth. */
+function buildPreviewText(data) {
+  let s;
+  if (typeof data === 'string') {
+    s = data;
+  } else {
+    try {
+      s = JSON.stringify(data);
+    } catch {
+      s = String(data);
+    }
+  }
+  if (!s) return '';
+  return s.length > PREVIEW_CHARS ? s.slice(0, PREVIEW_CHARS) + '…' : s;
+}
+
+/**
+ * Build one event. `ref` (optional) is `{ filePath, byteOffset, byteLength }`
+ * pointing at the exact bytes of the source line on disk, so the full,
+ * untruncated line can be re-read on demand instead of being held in
+ * memory. classifyLine stays a pure function of (obj, ref) — callers that
+ * don't have file context (e.g. unit tests) may omit ref.
+ */
+function makeEvent(kind, data, obj, ref) {
+  return { kind, data, raw: makeRaw(obj), previewText: buildPreviewText(data), ref: ref || null };
 }
 
 /**
- * Parse one JSONL line defensively. Real schema drifts, so we pass through
- * anything that parses and tag a coarse `kind`.
+ * Classify one content block and push its event(s) onto `events`. Known
+ * tool_use names get a specific kind (todo_write/plan/agent_spawn/tool_use);
+ * tool_result blocks get 'tool_result'; text blocks inherit the message's
+ * own type (assistant/user/…) so existing type-based consumers keep
+ * working. Any other block type — including ones Anthropic hasn't shipped
+ * yet — is surfaced under its own `content_<type>` kind rather than
+ * silently dropped, so new block kinds stay visible instead of vanishing.
  */
-function classifyLine(obj) {
-  if (!obj || typeof obj !== 'object') return null;
-  // Many shapes exist — try several common fields.
+function classifyBlock(block, obj, ref, type, events) {
+  if (!block || typeof block !== 'object') return;
+  if (block.type === 'tool_use') {
+    if (block.name === 'TodoWrite') {
+      events.push(makeEvent('todo_write', block.input?.todos || block.input || [], obj, ref));
+    } else if (block.name === 'ExitPlanMode' || block.name === 'EnterPlanMode') {
+      events.push(makeEvent('plan', block.input, obj, ref));
+    } else if (block.name === 'Agent' || block.name === 'Task') {
+      // Include block.id as toolUseId so the live store can match the
+      // corresponding tool_result and update per-agent lastActivityAt.
+      events.push(makeEvent('agent_spawn', { ...block.input, toolUseId: block.id }, obj, ref));
+    } else {
+      events.push(makeEvent('tool_use', { name: block.name, input: block.input, id: block.id }, obj, ref));
+    }
+    return;
+  }
+  // tool_result carries the tool_use_id of the completed Task/Agent call.
+  // The live store uses this to update the agent's lastActivityAt bookend.
+  if (block.type === 'tool_result' && block.tool_use_id) {
+    events.push(makeEvent('tool_result', { toolUseId: block.tool_use_id }, obj, ref));
+    return;
+  }
+  if (block.type === 'text' && typeof block.text === 'string') {
+    events.push(makeEvent(type || 'text', block.text, obj, ref));
+    return;
+  }
+  events.push(makeEvent(block.type ? `content_${block.type}` : 'content_block', block, obj, ref));
+}
+
+/**
+ * Parse one JSONL line defensively. Real schema drifts, so we pass
+ * through anything that parses and tag a coarse `kind` per event.
+ *
+ * Returns an ARRAY of events (empty array for an unclassifiable line) —
+ * a single line can legitimately carry more than one event: a usage
+ * rollup alongside real content, or an assistant turn with text plus
+ * several tool calls in the same content array. No caller may assume a
+ * line produces at most one event.
+ */
+function classifyLine(obj, ref) {
+  if (!obj || typeof obj !== 'object') return [];
+  const events = [];
   const type = obj.type || obj.event || obj.role;
   const msg = obj.message || obj;
   const content = msg?.content;
+  const usage = obj.usage || msg?.usage;
 
-  // Usage rollups arrive as summary events.
-  if (obj.usage || msg?.usage) {
-    return { kind: 'usage', data: obj.usage || msg.usage, raw: makeRaw(obj) };
+  // Usage rollups arrive as summary events — emitted alongside whatever
+  // content the same line carries, never instead of it.
+  if (usage) {
+    events.push(makeEvent('usage', usage, obj, ref));
   }
 
-  // Tool uses: scan content array for tool_use blocks.
-  if (Array.isArray(content)) {
-    for (const block of content) {
-      if (block?.type === 'tool_use') {
-        if (block.name === 'TodoWrite') {
-          return { kind: 'todo_write', data: block.input?.todos || block.input || [], raw: makeRaw(obj) };
-        }
-        if (block.name === 'ExitPlanMode' || block.name === 'EnterPlanMode') {
-          return { kind: 'plan', data: block.input, raw: makeRaw(obj) };
-        }
-        if (block.name === 'Agent' || block.name === 'Task') {
-          // Include block.id as toolUseId so the live store can match the
-          // corresponding tool_result and update per-agent lastActivityAt.
-          return { kind: 'agent_spawn', data: { ...block.input, toolUseId: block.id }, raw: makeRaw(obj) };
-        }
-        return {
-          kind: 'tool_use',
-          data: { name: block.name, input: block.input, id: block.id },
-          raw: makeRaw(obj),
-        };
-      }
-      // tool_result carries the tool_use_id of the completed Task/Agent call.
-      // The live store uses this to update the agent's lastActivityAt bookend.
-      if (block?.type === 'tool_result' && block.tool_use_id) {
-        return { kind: 'tool_result', data: { toolUseId: block.tool_use_id }, raw: makeRaw(obj) };
-      }
-    }
+  if (Array.isArray(content) && content.length > 0) {
+    for (const block of content) classifyBlock(block, obj, ref, type, events);
+  } else if (!usage) {
+    events.push(makeEvent(type || 'message', obj, obj, ref));
   }
 
-  return { kind: type || 'message', data: obj, raw: makeRaw(obj) };
+  return events;
 }
 
-module.exports = { MAX_RAW_STR, EXEMPT_TYPES, trimContentArray, makeRaw, classifyLine };
+module.exports = { MAX_RAW_STR, PREVIEW_CHARS, EXEMPT_TYPES, trimContentArray, makeRaw, buildPreviewText, classifyLine };

package/src/main/lib/epicMint.cjs

@@ -141,7 +141,7 @@ function withPathLock(lockPath, task) {
  * 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, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, source = null, agentType = null, mintAuthority = null } = {}) {
+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
@@ -218,6 +218,11 @@ function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'prop
       // 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 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 } : {}),

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,
+};