claude-code-session-manager 0.40.2 → 0.41.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 promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { verifyRun } = require('./runVerify.cjs');
 const { latestTerminalOutcomeForSlug, COMPLETED_EQUIVALENT_VERDICTS } = require('./lib/terminalRunOutcome.cjs');
 const logs = require('./logs.cjs');
@@ -84,9 +85,8 @@ const queueOps = require('./queueOps.cjs');
 // Plain Node module, no Electron dependency; queuePath/prdsDir defaults already
 // match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
 // home-dir layout.
-const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
-const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs } = require('./lib/prdLocations.cjs');
-const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
+const { ensureEpic, appendPrdCreatedEvent, removeEpic, readActiveIndex } = require('./lib/epicMint.cjs');
 
 // ---------- origin session resolution (PRD 832) ----------
 // An Epic IS a tagged claude session — job rows carry the originating
@@ -144,6 +144,10 @@ const POST_RESULT_GRACE_MS = 90_000;
 const POST_RESULT_KILL_MS = 30_000;
 const RESULT_TAIL_POLL_MS = 5_000;
 const RESULT_TAIL_BYTES = 8 * 1024;
+// Wider than RESULT_TAIL_BYTES (which only needs the subtype near the
+// boundary) — a real `result` string can be a full paragraph, so
+// extractResultTextFromLog scans more of the tail to find it whole.
+const RESULT_TEXT_TAIL_BYTES = 64 * 1024;
 
 // Idle-output watchdog: if the log file mtime stops advancing for this long
 // while the process is still alive, the agent is hung mid-work (network
@@ -492,23 +496,43 @@ function prdPathForJob(job) {
   return path.join(prdDirForCwd(job && job.cwd), `${job && job.slug}.md`);
 }
 
-/** Absolute path to the sibling `prds-archived/<slug>.md` twin of a job's PRD. */
+/**
+ * Absolute path to a job's archived-twin `<slug>.md`. Resolves to the first
+ * archive dir (across the flat legacy layout and every Epic's own sibling
+ * archive — see listArchivedPrdDirs) that actually contains the slug, falling
+ * back to the flat `prds-archived/<slug>.md` path when none do (this fallback
+ * is only ever used for its string value — logging/note text in
+ * prdArchivedSkipResult — never as an existence check).
+ */
 function archivedPrdPathForJob(job) {
-  return path.join(prdDirForCwd(job && job.cwd), '..', 'prds-archived', `${job && job.slug}.md`);
+  const slug = job && job.slug;
+  const flatPath = path.join(prdDirForCwd(job && job.cwd), '..', 'prds-archived', `${slug}.md`);
+  for (const dir of listArchivedPrdDirs((job && job.cwd) || DEFAULT_PROJECT_CWD)) {
+    const candidate = safeSlugPathIn(dir, slug);
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return flatPath;
 }
 
 /**
- * True if a job's PRD has already been archived (sibling `prds-archived/<slug>.md`
- * exists). A queue entry whose PRD moved there is stale — the work already shipped
- * — not a genuine missing-PRD failure.
+ * True if a job's PRD has already been archived — in the flat legacy
+ * `prds-archived/` dir OR in the Epic-scoped sibling archive dir every new
+ * PRD actually lands in (archiveCompletedPrd archives into the source PRD's
+ * OWN parent's prds-archived/, which for an Epic PRD is inside that Epic).
+ * A queue entry whose PRD moved to either is stale — the work already
+ * shipped — not a genuine missing-PRD failure.
  */
 async function archivedTwinExists(job) {
-  try {
-    await fsp.access(archivedPrdPathForJob(job));
-    return true;
-  } catch {
-    return false;
+  const slug = job && job.slug;
+  for (const dir of listArchivedPrdDirs((job && job.cwd) || DEFAULT_PROJECT_CWD)) {
+    const candidate = safeSlugPathIn(dir, slug);
+    if (!candidate) continue;
+    try {
+      await fsp.access(candidate);
+      return true;
+    } catch { /* not here — try the next archive dir */ }
   }
+  return false;
 }
 
 /**
@@ -1106,9 +1130,13 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: reconcileSourcePromptId(job, p.sourcePromptId),
       sourceTabId: p.sourceTabId,
+      // Unlike sourcePromptId (frozen once a row leaves 'pending'), epicId is
+      // refreshed from disk every pass: the PRD's directory IS its Epic
+      // membership, so moving the file between Epic dirs must re-point the row.
+      epicId: p.epicId ?? job.epicId ?? null,
       dependsOn: p.dependsOn,
       originSessionId: job.originSessionId
-        ?? resolveOriginSessionId(p.cwd, reconcileSourcePromptId(job, p.sourcePromptId)),
+        ?? resolveOriginSessionId(p.cwd, p.epicId ?? reconcileSourcePromptId(job, p.sourcePromptId)),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
     });
   }
@@ -1167,8 +1195,9 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: p.sourcePromptId,
       sourceTabId: p.sourceTabId,
+      epicId: p.epicId ?? null,
       dependsOn: p.dependsOn,
-      originSessionId: resolveOriginSessionId(p.cwd, p.sourcePromptId),
+      originSessionId: resolveOriginSessionId(p.cwd, p.epicId ?? p.sourcePromptId),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
       status: 'pending',
       runId: null,
@@ -1267,17 +1296,11 @@ let resumeTimer = null;
 let pollLoopTimer = null;
 let rescheduleInterval = null;
 let heartbeatInterval = null;
-// Feedback sweep piggybacks on the 60s heartbeat tick but runs far less often —
-// every Nth tick — since it's a readdir-per-active-project scan, not free.
-// 5 ticks = 5 minutes; well inside sweep()/activeProjectCwds()'s 90-minute
-// active-session window, so no active project can be missed between sweeps.
-const FEEDBACK_SWEEP_TICK_INTERVAL = 5;
-let feedbackSweepTickCount = 0;
-/** Pure gate for the tick counter above — exported so the wiring is testable
- *  without waiting on real setInterval timers. */
-function feedbackSweepDue(tickCount, interval = FEEDBACK_SWEEP_TICK_INTERVAL) {
-  return tickCount >= interval;
-}
+// (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.)
 // 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();
@@ -1623,6 +1646,34 @@ function isNotifiableTerminalStatus(effectiveStatus) {
   return effectiveStatus === 'completed' || effectiveStatus === 'failed';
 }
 
+/**
+ * Scans a run log's tail for the last `{"type":"result",...}` JSONL event
+ * (the claude harness's final message) and returns its `result` string, or
+ * null if the log is missing, unreadable, or has no parseable result line.
+ * Never throws — a missing/torn log must not break notifyOriginatingTab.
+ */
+function extractResultTextFromLog(logPath) {
+  if (!logPath) return null;
+  try {
+    const tail = readTail(logPath, RESULT_TEXT_TAIL_BYTES);
+    if (!tail) return null;
+    const lines = tail.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line || !line.includes('"type":"result"')) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed.result === 'string') return parsed.result;
+      } catch {
+        // torn/partial line — keep scanning backward
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -1630,31 +1681,62 @@ function isNotifiableTerminalStatus(effectiveStatus) {
  * rateLimited auto-pause, which resets the job to pending instead), publish
  * a short status notification for the PRD that queued this job.
  *
- * Resolution order (PRD 814): (1) if the PRD's `sourcePromptId` resolves to
- * a known, still-active PromptSession (minted for a dev-work dispatch, PRD
- * 813) under the job's cwd, append a 'response' PromptSessionEvent to THAT
- * session's own event chain — its own scoped PromptSessionConversation, not
- * whatever tab happens to be active — and stop; (2) otherwise, fall back to
- * today's behavior: push a short status prompt into the chat tab that queued
- * this PRD via enqueueExternalPrompt (PRD 753), resolved via the PRD's own
- * `sourceTabId` frontmatter, then the first open tab (per sessionsStore's
- * persisted tabs.json) whose cwd matches the job's cwd — first match only,
- * no fan-out to multiple matching tabs; (3) no-op. Never throws to the
- * caller (fire-and-forget from spawnJob). Deps are injectable (mirrors
- * partitionBootOrphans's isAlive param) so unit tests can exercise the
- * resolution logic without touching disk/electron.
+ * Resolution order (PRD 814, extended by PRD 854): (1) if the PRD's
+ * `sourcePromptId` resolves to a known, still-active PromptSession (minted
+ * for a dev-work dispatch, PRD 813) under the job's cwd, append a 'response'
+ * PromptSessionEvent to THAT session's own event chain — its own scoped Epic
+ * conversation (EpicDetail.tsx), not whatever tab happens to be active — and
+ * stop; (2) otherwise, fall back to pushing a short status prompt via
+ * enqueueExternalPrompt (PRD 753) at a target id resolved from, in order,
+ * the PRD's own `sourceTabId` frontmatter, then `sourcePromptId` again (a PRD
+ * dispatched straight from an Epic's composer, dispatchPromptSessionToPrd,
+ * never sets sourceTabId — sourcePromptId IS the Epic id and is a valid
+ * chat:external-send target too, which the renderer now resolves against
+ * both open tabs and known Epics, refusing a completed one), then the first
+ * open tab (per sessionsStore's persisted tabs.json) whose cwd matches the
+ * job's cwd — first match only, no fan-out to multiple matching tabs; (3)
+ * no-op. The cwd-match step only runs when NEITHER sourceTabId nor
+ * sourcePromptId is present in frontmatter at all — `sendPrompt` (
+ * enqueueExternalPrompt) is fire-and-forget IPC with no ack, so once step
+ * (2) picks either id it is not retried even if the renderer can't resolve
+ * it either (e.g. a stale/garbage id) — same non-guaranteed-delivery
+ * tradeoff this function already accepted for sourceTabId pre-PRD-854.
+ * Never throws to the caller (fire-and-forget from spawnJob). Deps are
+ * injectable (mirrors partitionBootOrphans's isAlive param) so unit tests
+ * can exercise the resolution logic without touching disk/electron.
  */
 async function notifyOriginatingTab(job, {
   parsePrdRaw = prdParser.parsePrdRaw,
   loadSessions = sessionsStore.load,
   sendPrompt = enqueueExternalPrompt,
   appendResponseEvent = appendResponseEventIfKnown,
+  appendTranscriptTurn = promptSessionTranscript.appendTurn,
+  readResultFromLog = extractResultTextFromLog,
 } = {}) {
   try {
     const prdPath = prdPathForJob(job);
     const prd = await parsePrdRaw(prdPath).catch(() => null);
     const message = `PRD ${job.slug} finished: ${job.status}. Check Scheduler for details.`;
 
+    // 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;
+    if (epicIdForTranscript && job.cwd) {
+      try {
+        const logPath = job.runId ? path.join(RUNS_DIR, job.runId, `${job.slug}.log`) : null;
+        const resultText = readResultFromLog(logPath);
+        await appendTranscriptTurn(job.cwd, epicIdForTranscript, {
+          role: 'assistant',
+          text: resultText || message,
+        });
+      } catch (e) {
+        console.error('[scheduler] notifyOriginatingTab transcript append error', job?.slug, e);
+      }
+    }
+
     if (prd?.sourcePromptId) {
       const routed = await appendResponseEvent(job.cwd || null, prd.sourcePromptId, message).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab appendResponseEvent error', job?.slug, e);
@@ -1663,7 +1745,13 @@ async function notifyOriginatingTab(job, {
       if (routed) return;
     }
 
-    let targetTabId = prd?.sourceTabId || null;
+    // appendResponseEvent already refused above (unknown id, completed
+    // Epic, or disk error) — the sourcePromptId fallback below re-sends to
+    // the SAME id via chat:external-send, which the renderer independently
+    // 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;
     if (!targetTabId) {
       const jobCwd = job.cwd || null;
       if (jobCwd) {
@@ -1673,7 +1761,7 @@ async function notifyOriginatingTab(job, {
       }
     }
     if (!targetTabId) {
-      console.log(`[scheduler] notifyOriginatingTab: no target tab for ${job.slug}, skipping`);
+      console.log(`[scheduler] notifyOriginatingTab: no open tab and no Epic for ${job.slug}, skipping`);
       return;
     }
 
@@ -1838,8 +1926,13 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
   }
 
   // Read full PRD body fresh from disk (queue stored only the preview).
+  // Resolve through findPrdDir's full candidate search (legacy flat dir +
+  // every project's Epic-scoped dirs) first, so the common case — a live
+  // Epic-scoped PRD — is a first-try hit instead of probing the retired flat
+  // dir and only then falling back.
   let prompt;
-  let prdPath = prdPathForJob(job);
+  const resolvedDir = await findPrdDir(job.slug);
+  let prdPath = resolvedDir ? path.join(resolvedDir, `${job.slug}.md`) : prdPathForJob(job);
   try {
     const parsed = await parsePrd(prdPath);
     // Centrally enforce the review → security-review → verify → commit finish
@@ -3757,7 +3850,7 @@ function registerScheduleHandlers() {
     const resolved = safeSlugPathIn(dir, data.slug);
     if (!resolved) return { ok: false, error: 'invalid slug' };
     try {
-      await config.writeTextAtomic(resolved, data.body);
+      await config.writeTextAtomic(resolved, data.body, { writer: 'scheduler' });
     } catch (e) {
       return { ok: false, error: e?.message ?? 'write failed' };
     }
@@ -3795,6 +3888,7 @@ function registerScheduleHandlers() {
             cwd: parsed.cwd || '',
             estimateMinutes: parsed.estimateMinutes,
             sourcePromptId: parsed.sourcePromptId,
+            epicId: parsed.epicId ?? null,
             mtimeMs: stat.mtimeMs,
           });
         } catch (e) {
@@ -3822,116 +3916,137 @@ function registerScheduleHandlers() {
 
 async function init() {
   ensureDirs();
-  // A slot freed anywhere (e.g. a chat run settled) may unblock a deferred
-  // batch — advance the queue without waiting for the next 60s poll.
-  sessionSlots.subscribe(() => { tickQueue().catch(() => {}); });
-  // Retire the global queue.json: split its rows into per-project shards
-  // BEFORE the first read below, so boot reconciliation sees the shards.
+  // Boot phase — reconciliation, migrations, self-heal, first reset probe.
+  // Guarded as a unit: everything below installs the timers that ARE the
+  // running scheduler (poll loop, heartbeat, supervisor). A throw in here
+  // used to reject init() and silently skip all of them, leaving an app
+  // that looks up and holds the ownership lock but never ticks and never
+  // writes a heartbeat — indistinguishable from a hung queue. Most of this
+  // work is best-effort recovery; none of it is worth trading the scheduler
+  // itself for. rescheduleTimer() in particular reaches the billing API,
+  // which fails whenever the OAuth token is stale.
   try {
-    const m = await queueStore.migrateLegacyGlobalQueue(DEFAULT_PROJECT_CWD);
-    if (m.migrated) {
-      console.log(`[scheduler] legacy global queue retired: ${m.moved} row(s) split across ${m.projects} project shard(s)`);
+    // A slot freed anywhere (e.g. a chat run settled) may unblock a deferred
+    // batch — advance the queue without waiting for the next 60s poll.
+    sessionSlots.subscribe(() => { tickQueue().catch(() => {}); });
+    // Retire the global queue.json: split its rows into per-project shards
+    // BEFORE the first read below, so boot reconciliation sees the shards.
+    try {
+      const m = await queueStore.migrateLegacyGlobalQueue(DEFAULT_PROJECT_CWD);
+      if (m.migrated) {
+        console.log(`[scheduler] legacy global queue retired: ${m.moved} row(s) split across ${m.projects} project shard(s)`);
+      }
+    } catch (e) {
+      console.error('[scheduler] legacy queue split failed', e?.message);
     }
-  } catch (e) {
-    console.error('[scheduler] legacy queue split failed', e?.message);
-  }
-  await runPrdMigration();
-  sweepQueueBackups().catch((e) => console.warn('[scheduler] backup sweep failed', e?.message));
-
-  // Hydrate cached state from the sidecar before any scheduling decisions.
-  loadSchedulerState();
-  bootedAt = Date.now();
-
-  // Boot reconciliation: finalize any job that was 'running' when the app died.
-  // Check the run log first — a job that emitted result/success before the crash
-  // should be marked 'completed', not 'failed', so it doesn't wedge the queue
-  // via the failure-gate. Also kill any still-live orphan claude child to prevent
-  // it from continuing to write to the project unsupervised (2026-05-21 incident).
-  //
-  // classifyRunOutcome calls readTail → fs.readFileSync (up to 64 KB per job).
-  // Pre-compute all outcomes BEFORE entering the mutate lock so the blocking I/O
-  // does not stall the event loop or hold the mutateTail chain during startup.
-  //
-  // Jobs whose recorded pid is still alive are deferred (not classified here) —
-  // see partitionBootOrphans. Everything else (dead pid or no pid) is safe to
-  // classify immediately below.
-  const bootSnap = readQueueSync();
-  const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
-  const bootOutcomes = new Map();
-  for (const j of bootSnap.jobs) {
-    if (!immediateSlugs.includes(j.slug)) continue;
-    const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
-    bootOutcomes.set(j.slug, logPath ? classifyRunOutcome(logPath) : 'unknown');
-  }
-  const bootReconciledCompletions = [];
-  await mutate((state) => {
-    for (const j of state.jobs) {
-      if (j.status !== 'running' || !immediateSlugs.includes(j.slug)) continue;
-      const outcome = bootOutcomes.get(j.slug) ?? 'unknown';
-      const pid = j.runtime?.pid;
-      const killNote = pid ? ` (orphan pid=${pid}: dead)` : '';
-      applyOrphanOutcome(j, outcome, killNote);
-      if (j.status === 'completed') bootReconciledCompletions.push({ slug: j.slug, cwd: j.cwd });
-      console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → status=${j.status}`);
+    await runPrdMigration();
+    sweepQueueBackups().catch((e) => console.warn('[scheduler] backup sweep failed', e?.message));
+
+    // Hydrate cached state from the sidecar before any scheduling decisions.
+    loadSchedulerState();
+    bootedAt = Date.now();
+
+    // Boot reconciliation: finalize any job that was 'running' when the app died.
+    // Check the run log first — a job that emitted result/success before the crash
+    // should be marked 'completed', not 'failed', so it doesn't wedge the queue
+    // via the failure-gate. Also kill any still-live orphan claude child to prevent
+    // it from continuing to write to the project unsupervised (2026-05-21 incident).
+    //
+    // classifyRunOutcome calls readTail → fs.readFileSync (up to 64 KB per job).
+    // Pre-compute all outcomes BEFORE entering the mutate lock so the blocking I/O
+    // does not stall the event loop or hold the mutateTail chain during startup.
+    //
+    // Jobs whose recorded pid is still alive are deferred (not classified here) —
+    // see partitionBootOrphans. Everything else (dead pid or no pid) is safe to
+    // classify immediately below.
+    const bootSnap = readQueueSync();
+    const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
+    const bootOutcomes = new Map();
+    for (const j of bootSnap.jobs) {
+      if (!immediateSlugs.includes(j.slug)) continue;
+      const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
+      bootOutcomes.set(j.slug, logPath ? classifyRunOutcome(logPath) : 'unknown');
+    }
+    const bootReconciledCompletions = [];
+    await mutate((state) => {
+      for (const j of state.jobs) {
+        if (j.status !== 'running' || !immediateSlugs.includes(j.slug)) continue;
+        const outcome = bootOutcomes.get(j.slug) ?? 'unknown';
+        const pid = j.runtime?.pid;
+        const killNote = pid ? ` (orphan pid=${pid}: dead)` : '';
+        applyOrphanOutcome(j, outcome, killNote);
+        if (j.status === 'completed') bootReconciledCompletions.push({ slug: j.slug, cwd: j.cwd });
+        console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → status=${j.status}`);
+      }
+    });
+    for (const { slug, cwd } of bootReconciledCompletions) {
+      await archiveCompletedPrd(slug, cwd);
     }
-  });
-  for (const { slug, cwd } of bootReconciledCompletions) {
-    await archiveCompletedPrd(slug, cwd);
-  }
 
-  // Still-alive orphans: SIGTERM (+ killOrphanClaudePid's own deferred SIGKILL
-  // follow-up) now, but classification waits until BOOT_ORPHAN_KILL_GRACE_MS
-  // later — reading the log while the orphan might still be writing to it
-  // could misclassify an about-to-succeed run as no_result and double-run the
-  // same PRD (2026-05-21 incident this guard exists for).
-  for (const slug of deferredSlugs) {
-    const j = bootSnap.jobs.find((x) => x.slug === slug);
-    const pid = j?.runtime?.pid;
-    const bootRunId = j?.runId ?? null; // captured now — guards against reconciling a DIFFERENT later run of the same slug
-    if (!pid) continue;
-    const result = killOrphanClaudePid(pid);
-    const killNote = ` (orphan pid=${pid}: ${result})`;
-    if (result === 'killed') {
-      console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${slug} — deferring finalize ${BOOT_ORPHAN_KILL_GRACE_MS}ms`);
+    // Still-alive orphans: SIGTERM (+ killOrphanClaudePid's own deferred SIGKILL
+    // follow-up) now, but classification waits until BOOT_ORPHAN_KILL_GRACE_MS
+    // later — reading the log while the orphan might still be writing to it
+    // could misclassify an about-to-succeed run as no_result and double-run the
+    // same PRD (2026-05-21 incident this guard exists for).
+    for (const slug of deferredSlugs) {
+      const j = bootSnap.jobs.find((x) => x.slug === slug);
+      const pid = j?.runtime?.pid;
+      const bootRunId = j?.runId ?? null; // captured now — guards against reconciling a DIFFERENT later run of the same slug
+      if (!pid) continue;
+      const result = killOrphanClaudePid(pid);
+      const killNote = ` (orphan pid=${pid}: ${result})`;
+      if (result === 'killed') {
+        console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${slug} — deferring finalize ${BOOT_ORPHAN_KILL_GRACE_MS}ms`);
+      }
+      setTimeout(() => {
+        const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
+        const outcome = logPath ? classifyRunOutcome(logPath) : 'unknown';
+        let deferredCompletedCwd;
+        mutate((state) => {
+          const cur = state.jobs.find((x) => x.slug === slug);
+          // Race guard: bail if the job already resolved, OR if it's already been
+          // re-picked into a NEW run (different runId) within the grace window —
+          // that new run is not the boot orphan we SIGTERM'd and must not be
+          // touched by this stale classification.
+          if (!cur || cur.status !== 'running' || cur.runId !== bootRunId) return;
+          applyOrphanOutcome(cur, outcome, killNote);
+          console.log(`[scheduler] boot reconcile (deferred): slug=${slug} outcome=${outcome} → status=${cur.status}`);
+          deferredCompletedCwd = cur.status === 'completed' ? cur.cwd : undefined;
+        }).then(() => {
+          if (deferredCompletedCwd !== undefined) return archiveCompletedPrd(slug, deferredCompletedCwd);
+        }).catch((e) => console.error(`[scheduler] deferred boot reconcile failed for ${slug}:`, e?.message));
+      }, BOOT_ORPHAN_KILL_GRACE_MS).unref?.();
     }
-    setTimeout(() => {
-      const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
-      const outcome = logPath ? classifyRunOutcome(logPath) : 'unknown';
-      let deferredCompletedCwd;
-      mutate((state) => {
-        const cur = state.jobs.find((x) => x.slug === slug);
-        // Race guard: bail if the job already resolved, OR if it's already been
-        // re-picked into a NEW run (different runId) within the grace window —
-        // that new run is not the boot orphan we SIGTERM'd and must not be
-        // touched by this stale classification.
-        if (!cur || cur.status !== 'running' || cur.runId !== bootRunId) return;
-        applyOrphanOutcome(cur, outcome, killNote);
-        console.log(`[scheduler] boot reconcile (deferred): slug=${slug} outcome=${outcome} → status=${cur.status}`);
-        deferredCompletedCwd = cur.status === 'completed' ? cur.cwd : undefined;
-      }).then(() => {
-        if (deferredCompletedCwd !== undefined) return archiveCompletedPrd(slug, deferredCompletedCwd);
-      }).catch((e) => console.error(`[scheduler] deferred boot reconcile failed for ${slug}:`, e?.message));
-    }, BOOT_ORPHAN_KILL_GRACE_MS).unref?.();
-  }
 
-  // If we boot up while paused with a resumeAt in the past, clear it. This
-  // happens when the app was closed across the reset window.
-  const boot = await readQueue();
-  if (boot.paused && boot.paused.resumeAt && new Date(boot.paused.resumeAt).getTime() <= Date.now()) {
-    await clearPause('boot-elapsed');
-  } else if (boot.paused && boot.paused.resumeAt) {
-    // Re-arm the resume timer (lost across restart).
-    await setPaused(boot.paused.reason, boot.paused.resumeAt);
-  }
+    // If we boot up while paused with a resumeAt in the past, clear it. This
+    // happens when the app was closed across the reset window.
+    const boot = await readQueue();
+    if (boot.paused && boot.paused.resumeAt && new Date(boot.paused.resumeAt).getTime() <= Date.now()) {
+      await clearPause('boot-elapsed');
+    } else if (boot.paused && boot.paused.resumeAt) {
+      // Re-arm the resume timer (lost across restart).
+      await setPaused(boot.paused.reason, boot.paused.resumeAt);
+    }
 
-  // Self-heal stale needs_review flags using the current verifier (see
-  // reverifyNeedsReview). Runs once on boot so a shipped verifier fix clears
-  // its own historical false positives without manual retagging.
-  await reverifyNeedsReview().catch((e) => {
-    console.error(`[scheduler] boot reverify failed: ${e?.message ?? e}`);
-  });
+    // Self-heal stale needs_review flags using the current verifier (see
+    // reverifyNeedsReview). Runs once on boot so a shipped verifier fix clears
+    // its own historical false positives without manual retagging.
+    await reverifyNeedsReview().catch((e) => {
+      console.error(`[scheduler] boot reverify failed: ${e?.message ?? e}`);
+    });
 
-  await rescheduleTimer();
+    await rescheduleTimer();
+  } catch (e) {
+    console.error('[scheduler] boot phase failed — starting timers anyway:', e?.message);
+    try {
+      require('./logs.cjs').writeLine({
+        scope: 'scheduler',
+        level: 'error',
+        message: 'boot phase failed; timers started anyway',
+        meta: { error: e?.message },
+      });
+    } catch { /* logging must never be the thing that stops the scheduler */ }
+  }
   // Refresh next-reset every 10 minutes — billing window can shift if usage
   // resets early or the auth token rotates. Tracked so re-init doesn't leak.
   if (rescheduleInterval) clearInterval(rescheduleInterval);
@@ -3985,16 +4100,6 @@ async function init() {
       utilization: cachedUtilization,
       consecutiveFailures,
     });
-
-    feedbackSweepTickCount++;
-    if (feedbackSweepDue(feedbackSweepTickCount, FEEDBACK_SWEEP_TICK_INTERVAL)) {
-      feedbackSweepTickCount = 0;
-      try {
-        sweepFeedback();
-      } catch (e) {
-        console.warn('[scheduler] feedback sweep failed', e?.message);
-      }
-    }
   }, 60_000);
   if (heartbeatInterval.unref) heartbeatInterval.unref();
 
@@ -4104,10 +4209,16 @@ const remote = {
       if (!dir) {
         try {
           const { fm } = splitFrontmatter(body);
-          const epic = ensureEpic(cwd, {
+          const epic = await ensureEpic(cwd, {
             goalText: fm.title || slug,
             tag: fm.tag,
             // An Epic-conversation dispatch already has its Epic — join it.
+            // fm.sourcePromptId must be an existing Epic's promptSessionId
+            // (== its active-index.json sessions key), NOT a
+            // PromptTicket.id — epicMint.cjs's ensureEpic looks it up via
+            // `index.sessions[explicitEpicId]` (see epicMint.cjs ~line 73),
+            // a literal-equality join. Any other id (e.g. a PromptTicket.id)
+            // simply won't match and mints a sibling Epic instead of joining.
             epicId: fm.sourcePromptId,
           });
           dir = epic.prdDir;
@@ -4130,16 +4241,22 @@ const remote = {
     // PRD 825: if this call minted a brand-new Epic (ensureEpic's `created`)
     // and the write below never lands, don't strand an empty Epic dir —
     // best-effort remove `<epic>/prds` then `<epic>` itself, only when empty.
+    // PRD 851: also drop the Epic's active-index.json entry (sessions/events)
+    // so an orphaned seed-prompt-only Epic doesn't linger in the Epics nav.
+    // Gated on epicCreated (never fires when ensureEpic joined an existing
+    // Epic) so a pre-existing Epic's history is never touched.
     const cleanupEmptyMintedEpic = async () => {
       if (!epicCreated || !epicId) return;
       try {
         const entries = await fsp.readdir(dir);
-        if (entries.length > 0) return;
-        await fsp.rmdir(dir);
-        const epicRootDir = path.dirname(dir);
-        const epicRootEntries = await fsp.readdir(epicRootDir);
-        if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+        if (entries.length === 0) {
+          await fsp.rmdir(dir);
+          const epicRootDir = path.dirname(dir);
+          const epicRootEntries = await fsp.readdir(epicRootDir);
+          if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+        }
       } catch { /* best-effort only */ }
+      try { removeEpic(cwd, epicId); } catch { /* best-effort only */ }
     };
 
     const resolved = safeSlugPathIn(dir, slug);
@@ -4164,11 +4281,11 @@ const remote = {
         await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
-      await config.writeTextAtomic(resolved, body);
+      await config.writeTextAtomic(resolved, body, { writer: 'scheduler' });
       const stat = await fsp.stat(resolved);
       if (epicTrace) {
         // Best-effort: record the dispatch on the minted Epic's event chain.
-        try { appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
+        try { await appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
       }
       return { ok: true, bytesWritten: stat.size };
     } catch (e) {
@@ -4267,4 +4384,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, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };
+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, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };

package/src/main/templates/PRD_AUTHORING.md

@@ -437,7 +437,7 @@ not be re-proposed:
 
 ### Reference implementation of this exact loop
 
-`/process-feedback`'s step 0b (source → triage → `/develop` → queue) is a working example of this
+The proposal → approve → `/develop` → queue path is a working example of this
 shape, landed 2026-07-14 (`feat(process-feedback): sync open GitHub issues into the feedback
 intake`, commit `352b89c`). It syncs open GitHub issues into `session-manager-operations/feedback/`
 (deduped on a `gh-issue-<N>` token), then processes each item through the same triage → `/develop`