claude-code-session-manager 0.36.0 → 0.37.0

package/src/main/lib/queueHistory.cjs

@@ -0,0 +1,216 @@
+'use strict';
+
+// Moves terminal (completed/failed) scheduler jobs older than a retention
+// window out of the hot queue.json jobs[] array into an append-only
+// history.jsonl sidecar. Keeps queue.json small (mutation cost, broadcast
+// payload size, pickNextBatch/reconcile scan cost all scale with jobs[]
+// length) while preserving full history for the renderer's History view.
+//
+// Kept pure where fs isn't unavoidable: partitionJobs takes an injected
+// `nowMs` and `opts` so it's testable without touching the real clock or
+// disk. appendHistory/readHistory own the actual fs I/O.
+
+const os = require('os');
+const path = require('path');
+const fsp = require('fs').promises;
+const { HISTORY_RETENTION_MS } = require('./schedulerConfig.cjs');
+
+const HISTORY_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'history.jsonl');
+
+function isFixPlanSlug(slug) {
+  return /^\d+-fix-/.test(slug);
+}
+
+function jobKey(job) {
+  return `${job?.slug ?? ''}|${job?.runId ?? ''}`;
+}
+
+/**
+ * O(n) over `jobs`. Splits terminal jobs into `hot` (stays in queue.json)
+ * and `toArchive` (moves to history.jsonl). A completed/failed job archives
+ * only when ALL of:
+ *   - status is 'completed' or 'failed'
+ *   - finishedAt parses and is older than opts.retentionMs (default
+ *     HISTORY_RETENTION_MS)
+ *   - it is not the healTargetForFix() parent of a pending/running fix-plan
+ *     job (NN-fix-<slug> relationships stay hot together so the fix-plan
+ *     can still find and promote its original when it completes)
+ */
+function partitionJobs(jobs, nowMs, opts = {}) {
+  const retentionMs = opts.retentionMs ?? HISTORY_RETENTION_MS;
+  const list = Array.isArray(jobs) ? jobs : [];
+
+  // Slugs of jobs that a still-pending/running fix-plan is going to try to
+  // heal (see healTargetForFix in scheduler.cjs — same regex, kept in sync).
+  const protectedSlugs = new Set();
+  for (const j of list) {
+    if (!j || !isFixPlanSlug(j.slug)) continue;
+    if (j.status !== 'pending' && j.status !== 'running') continue;
+    protectedSlugs.add(j.slug.replace(/^(\d+)-fix-/, '$1-'));
+  }
+
+  const hot = [];
+  const toArchive = [];
+  for (const j of list) {
+    if (!j) continue;
+    const finishedMs = j.finishedAt ? Date.parse(j.finishedAt) : NaN;
+    const archivable =
+      (j.status === 'completed' || j.status === 'failed') &&
+      Number.isFinite(finishedMs) &&
+      (nowMs - finishedMs) > retentionMs &&
+      !protectedSlugs.has(j.slug);
+    if (archivable) toArchive.push(j);
+    else hot.push(j);
+  }
+  return { hot, toArchive };
+}
+
+/**
+ * Append-only JSONL write, deduped by slug+runId against what's already on
+ * disk. The dedupe exists for crash-safety: reconcile() appends BEFORE
+ * dropping archived jobs from state.jobs, so a crash between those two steps
+ * replays the same batch through partitionJobs on the next boot — dedupe
+ * here is what stops that replay from double-writing history.
+ */
+async function appendHistory(entries) {
+  const list = Array.isArray(entries) ? entries.filter(Boolean) : [];
+  if (list.length === 0) return { appended: 0 };
+
+  let existingText = '';
+  try {
+    existingText = await fsp.readFile(HISTORY_PATH, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  const existingKeys = new Set();
+  if (existingText) {
+    for (const line of existingText.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        existingKeys.add(jobKey(JSON.parse(line)));
+      } catch {
+        // corrupt/partial line — ignore for dedupe purposes
+      }
+    }
+  }
+
+  const fresh = list.filter((e) => !existingKeys.has(jobKey(e)));
+  if (fresh.length === 0) return { appended: 0 };
+
+  await fsp.mkdir(path.dirname(HISTORY_PATH), { recursive: true });
+  const text = fresh.map((e) => JSON.stringify(e)).join('\n') + '\n';
+  await fsp.appendFile(HISTORY_PATH, text, 'utf8');
+  return { appended: fresh.length };
+}
+
+/**
+ * Reads the newest `limit` (clamped [1,500], default 50) entries from
+ * history.jsonl, newest-first, WITHOUT loading the whole file when it's
+ * large — reads from the end in growing chunks until enough whole lines are
+ * found (or the file start is reached).
+ */
+async function readHistory({ limit } = {}) {
+  const cap = Math.max(1, Math.min(500, Number.isFinite(limit) ? Math.floor(limit) : 50));
+
+  let fh;
+  try {
+    fh = await fsp.open(HISTORY_PATH, 'r');
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+
+  try {
+    const { size } = await fh.stat();
+    if (size === 0) return [];
+
+    let readSize = Math.min(65536, size);
+    let lines = [];
+    for (;;) {
+      const start = size - readSize;
+      const buf = Buffer.alloc(readSize);
+      await fh.read(buf, 0, readSize, start);
+      let text = buf.toString('utf8');
+      if (start > 0) {
+        // The chunk may begin mid-line; drop the (possibly partial) first
+        // fragment rather than risk parsing a truncated record.
+        const firstNl = text.indexOf('\n');
+        text = firstNl === -1 ? '' : text.slice(firstNl + 1);
+      }
+      lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+      if (lines.length >= cap || readSize >= size) break;
+      readSize = Math.min(readSize * 2, size);
+    }
+
+    const tail = lines.slice(-cap);
+    const parsed = [];
+    for (const line of tail) {
+      try {
+        parsed.push(JSON.parse(line));
+      } catch {
+        // corrupt/partial line — skip
+      }
+    }
+    // File-order tail is oldest→newest; caller wants newest-first.
+    return parsed.reverse();
+  } finally {
+    await fh.close();
+  }
+}
+
+// mtime-gated cache, same convention as scheduler/prdParser.cjs's dirCache —
+// repeated reconcile() calls between appends hit the cache instead of
+// re-reading/re-parsing a JSONL file that only grows over time.
+let historyCacheMtime = -1;
+let historyCacheMap = null;
+
+/**
+ * Full-file scan of history.jsonl, returning slug -> { status, finishedAt }
+ * for the most recently appended record of each slug. O(H) where H is the
+ * line count of history.jsonl; cached by the file's mtime so a reconcile()
+ * pass with no new archives since the last call is O(1).
+ *
+ * Exists so reconcile() can tell "this on-disk PRD's job row already left
+ * jobs[] into history — do not resurrect it as a fresh pending job" apart
+ * from "this is a genuinely brand-new PRD nobody has ever queued."
+ */
+async function historyTerminalBySlug() {
+  let mtime;
+  try {
+    mtime = (await fsp.stat(HISTORY_PATH)).mtimeMs;
+  } catch {
+    mtime = -1;
+  }
+  if (mtime === historyCacheMtime && historyCacheMap) return historyCacheMap;
+
+  const map = new Map();
+  let text = '';
+  try {
+    text = await fsp.readFile(HISTORY_PATH, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (text) {
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const j = JSON.parse(line);
+        if (j?.slug) map.set(j.slug, { status: j.status, finishedAt: j.finishedAt });
+      } catch {
+        // corrupt/partial line — ignore
+      }
+    }
+  }
+  historyCacheMtime = mtime;
+  historyCacheMap = map;
+  return map;
+}
+
+module.exports = {
+  HISTORY_PATH,
+  partitionJobs,
+  appendHistory,
+  readHistory,
+  historyTerminalBySlug,
+};

package/src/main/lib/rcaFeedbackHook.cjs

@@ -0,0 +1,346 @@
+'use strict';
+
+/**
+ * rcaFeedbackHook.cjs — files a deterministic Root Cause Analysis feedback
+ * item when a scheduler job is parked in `needs_review`.
+ *
+ * Mirrors the dodDrainHook.cjs pattern: fire-and-forget, idempotent,
+ * kill-switched, never throws to the caller. Unlike the DoD gate this fires
+ * per-job at the needs_review transition, not at queue drain.
+ *
+ * No LLM calls live here — the RCA body is assembled deterministically from
+ * the run's meta.json, log tail, and the original PRD's acceptance-criteria
+ * section. When an Opus auto-fix investigation later runs (spawnInvestigation
+ * in scheduler.cjs) and produces a root-cause summary, that text is folded
+ * into this SAME file's "Investigation analysis" section via a second call
+ * with the same (slug, runId) — never a duplicate file.
+ *
+ * Kill-switch: SM_RCA_DISABLE=1 (mirrors SM_DOD_DISABLE / SM_SUPERVISOR_DISABLE).
+ *
+ * Electron-free by design (no require('electron')) so tests stay hermetic.
+ * config.cjs itself requires('electron'), but that resolves to a harmless
+ * string (not the electron module) when required outside the Electron
+ * runtime, and this lib never touches ipcMain — only the atomic-write /
+ * path-validation helpers.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const config = require('../config.cjs');
+const { splitFrontmatter } = require('./prdFrontmatter.cjs');
+const { readTail } = require('./fileTail.cjs');
+
+const PRDS_DIR = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'prds');
+
+// The one project this hook always knows how to reach, used as the fallback
+// destination when a job's own cwd has no feedback inbox.
+const SM_REPO_ROOT = path.join(os.homedir(), 'Projects', 'session-manager');
+const SM_REPO_FEEDBACK_DIR = path.join(SM_REPO_ROOT, 'session-manager-operations', 'feedback');
+
+// NEVER write here: ~/.claude/session-manager/feedback/ is the external
+// watchdog's auto-PRD intake (scripts/scheduler-watchdog.cjs `sweep()`) — it
+// converts anything dropped there into a scheduled PRD automatically. Filing
+// an RCA there would create an RCA → auto-PRD → run → needs_review → RCA
+// cycle with no human in the loop. Both real destinations below are project
+// feedback INBOXES (consumed by /process-feedback), which is a different,
+// human/agent-triaged path.
+
+// ─── VERDICT_LABELS — deliberate duplicate ──────────────────────────────────
+// Mirrors src/renderer/components/tabs/scheduler/sched-primitives.tsx:123-131.
+// The main process cannot import renderer TSX, so this vocabulary is kept in
+// sync by hand. If you change one, change the other.
+const VERDICT_LABELS = {
+  halt: 'verifier halted',
+  deps_unmet: 'dependencies unmet',
+  transcript_errors: 'transcript had errors',
+  verify_unavailable: 'verify unavailable',
+  uncommitted_changes: 'uncommitted changes',
+  no_verdict_sentinel: 'no commit or verdict sentinel',
+  pass_no_commit: 'PASS sentinel but no commit landed',
+};
+
+function humanVerdict(verdict) {
+  return VERDICT_LABELS[verdict] ?? verdict ?? 'unknown';
+}
+
+// ─── Failure-class matching (deterministic, no LLM) ─────────────────────────
+
+const FAILURE_CLASSES = {
+  STUCK_LOOP: 'stuck-loop',
+  POST_AC_OVERRUN: 'post-ac-overrun',
+  NO_SENTINEL: 'no-sentinel',
+  UNCOMMITTED: 'uncommitted-changes',
+  TRANSCRIPT_ERRORS: 'transcript-errors',
+  UNKNOWN: 'unknown',
+};
+
+const PREVENTION_HINTS = {
+  [FAILURE_CLASSES.STUCK_LOOP]:
+    'Bound every command with `timeout <N> <cmd>` — never leave an unbounded `until`/`while true`/`sleep` poll in a PRD body (PRD_AUTHORING.md loop-hang guidance).',
+  [FAILURE_CLASSES.POST_AC_OVERRUN]:
+    'Stop at the acceptance checklist — do not add "while we\'re here" work (generators, fixtures, extra polish) once the last AC item is satisfied (PRD_AUTHORING.md post-AC-overrun incident).',
+  [FAILURE_CLASSES.NO_SENTINEL]:
+    'End every run with a truthful `SCHEDULER_VERDICT: PASS`/`FAIL` sentinel as the literal last line, after the finish-protocol commit has landed.',
+  [FAILURE_CLASSES.UNCOMMITTED]:
+    'Run `git add -A && git commit` as the final finish-protocol step before printing the verdict sentinel — never end a run with a dirty working tree.',
+  [FAILURE_CLASSES.TRANSCRIPT_ERRORS]:
+    'Recover or annotate every error within ~10 lines (e.g. `# expected/handled: <why>`) instead of leaving a bare Traceback near the end of the transcript.',
+  [FAILURE_CLASSES.UNKNOWN]:
+    'Re-run the acceptance criteria gate locally against the failure log to pin down the specific break before re-queuing.',
+};
+
+/**
+ * Extract the <RCA>...</RCA> block an investigation agent is instructed to
+ * print before authoring its fix-plan PRD (see spawnInvestigation's prompt in
+ * scheduler.cjs). The investigation log is a stream-json transcript, so a
+ * literal newline inside the agent's text lands JSON-escaped as `\n` — unescape
+ * common JSON string escapes before matching so a multi-line block extracts
+ * cleanly. Returns null if no block is found.
+ */
+function extractRcaBlock(text) {
+  if (!text) return null;
+  const unescaped = text.replace(/\\n/g, '\n').replace(/\\"/g, '"');
+  const m = unescaped.match(/<RCA>([\s\S]*?)<\/RCA>/);
+  return m ? m[1].trim() : null;
+}
+
+const STUCK_LOOP_RE = /\b(until\s|while\s+true|sleep\s)/i;
+const AC_CHECKBOX_RE = /^\s*[-*]\s*\[[xX]\]/;
+const SENTINEL_PASS_RE = /SCHEDULER_VERDICT:\s*PASS/;
+const STUCK_LOOP_WINDOW = 40; // "final lines" per AC
+const POST_AC_OVERRUN_MIN_TAIL_FRACTION = 0.3;
+
+/**
+ * Classify why a job likely landed in needs_review, from the log tail plus
+ * the verifier verdict. Pure/deterministic — no LLM, no I/O.
+ *
+ * Complexity: O(n) over log-tail lines (n bounded — callers pass a tail, not
+ * a full log).
+ */
+function classifyFailure({ verdict, logTail }) {
+  const lines = (logTail || '').split('\n');
+
+  const tailWindow = lines.slice(-STUCK_LOOP_WINDOW);
+  if (tailWindow.some((l) => STUCK_LOOP_RE.test(l))) {
+    return FAILURE_CLASSES.STUCK_LOOP;
+  }
+
+  // post-AC overrun: the log shows an AC checkbox line, then keeps going
+  // (fails) well after it, with no PASS sentinel in between — i.e. the run
+  // did the acceptance work then kept working (and died) past it.
+  let lastAcIdx = -1;
+  lines.forEach((l, i) => {
+    if (AC_CHECKBOX_RE.test(l)) lastAcIdx = i;
+  });
+  if (lastAcIdx >= 0 && lines.length > 0) {
+    const tailAfterAc = lines.slice(lastAcIdx + 1);
+    const passSeenAfter = tailAfterAc.some((l) => SENTINEL_PASS_RE.test(l));
+    const remainingFraction = tailAfterAc.length / lines.length;
+    if (!passSeenAfter && remainingFraction > POST_AC_OVERRUN_MIN_TAIL_FRACTION) {
+      return FAILURE_CLASSES.POST_AC_OVERRUN;
+    }
+  }
+
+  if (verdict === 'uncommitted_changes') return FAILURE_CLASSES.UNCOMMITTED;
+  if (verdict === 'no_verdict_sentinel' || verdict === 'pass_no_commit') return FAILURE_CLASSES.NO_SENTINEL;
+  if (verdict === 'transcript_errors' || verdict === 'verify_unavailable') return FAILURE_CLASSES.TRANSCRIPT_ERRORS;
+  return FAILURE_CLASSES.UNKNOWN;
+}
+
+/**
+ * Extract the `# Acceptance criteria` section (any heading level) from a PRD
+ * body, up to the next heading or end of body. Returns null if not found.
+ */
+function extractAcceptanceCriteria(prdBody) {
+  if (typeof prdBody !== 'string') return null;
+  const lines = prdBody.split('\n');
+  const startIdx = lines.findIndex((l) => /^#{1,6}\s*Acceptance criteria\s*$/i.test(l.trim()));
+  if (startIdx === -1) return null;
+  const rest = lines.slice(startIdx + 1);
+  const endOffset = rest.findIndex((l) => /^#{1,6}\s+\S/.test(l));
+  const section = endOffset === -1 ? rest : rest.slice(0, endOffset);
+  const text = section.join('\n').trim();
+  return text || null;
+}
+
+// ─── Destination resolution ──────────────────────────────────────────────────
+
+/**
+ * Resolve where an RCA for `job` should be filed.
+ *   1. <job.cwd>/session-manager-operations/feedback/ if it exists.
+ *   2. Else session-manager's own repo inbox, naming the target project.
+ */
+function resolveDestination(job) {
+  const jobCwd = job?.cwd;
+  if (jobCwd) {
+    const candidate = path.join(jobCwd, 'session-manager-operations', 'feedback');
+    try {
+      if (fs.statSync(candidate).isDirectory()) {
+        return { dir: candidate, allowlistRoot: jobCwd, targetProjectNote: null };
+      }
+    } catch {
+      // missing/inaccessible — fall through to the session-manager fallback
+    }
+  }
+  const targetProjectNote = jobCwd
+    ? `Filed into session-manager's own feedback inbox because \`${jobCwd}\` has no ` +
+      `\`session-manager-operations/feedback/\` directory. Target project: \`${jobCwd}\`.`
+    : 'Filed into session-manager\'s own feedback inbox (job had no cwd on record).';
+  return { dir: SM_REPO_FEEDBACK_DIR, allowlistRoot: SM_REPO_ROOT, targetProjectNote };
+}
+
+function shortRunId(runId) {
+  const cleaned = String(runId ?? '').replace(/[^a-zA-Z0-9]/g, '');
+  return cleaned.slice(0, 12) || 'norun';
+}
+
+function rcaFileName(dateStr, slug, runId) {
+  return `${dateStr}-rca-${slug}-${shortRunId(runId)}.md`;
+}
+
+function lastNLines(text, n) {
+  const lines = (text || '').split('\n');
+  return lines.slice(-n).join('\n');
+}
+
+function readRunMeta(runDir, slug) {
+  if (!runDir) return null;
+  try {
+    const raw = fs.readFileSync(path.join(runDir, `${slug}.meta.json`), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function readPrdBody(slug) {
+  try {
+    const raw = fs.readFileSync(path.join(PRDS_DIR, `${slug}.md`), 'utf8');
+    return splitFrontmatter(raw).body;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Assemble the deterministic RCA markdown body (frontmatter + sections).
+ * Pure — no I/O, no LLM.
+ */
+function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, investigationText, targetProjectNote }) {
+  const title = `Root cause: ${job.slug} → needs_review (${humanVerdict(verdict)})`;
+  const fm = ['---', `title: ${title}`, 'source: scheduler-rca', 'type: rca', 'severity: normal', `prdSlug: ${job.slug}`, `runId: ${job.runId}`, `verdict: ${verdict}`, '---'].join('\n');
+
+  const last60 = lastNLines(logTail, 60);
+  const exitCode = meta?.exitCode ?? job.exitCode ?? 'unknown';
+  const durationMs = meta?.durationMs != null ? `${meta.durationMs}ms` : 'unknown';
+  const prevention = PREVENTION_HINTS[failureClass] ?? PREVENTION_HINTS[FAILURE_CLASSES.UNKNOWN];
+
+  const sections = [
+    `# What happened\n\nJob \`${job.slug}\` was parked in \`needs_review\` with verifier verdict ` +
+      `\`${verdict}\` (${humanVerdict(verdict)}).${job.error ? `\n\n${job.error}` : ''}`,
+    `# Evidence\n\n- Exit code: ${exitCode}\n- Duration: ${durationMs}\n\nLast 60 log lines:\n\n\`\`\`\n${last60 || '(no log available)'}\n\`\`\``,
+    `# The PRD's acceptance criteria\n\n${acText || '(acceptance criteria not found — original PRD may have been archived or removed)'}`,
+    `# Likely failure class\n\n**${failureClass}**\n\nPrevention: ${prevention}`,
+  ];
+  if (targetProjectNote) sections.push(`# Note\n\n${targetProjectNote}`);
+  if (investigationText) sections.push(`## Investigation analysis\n\n${investigationText.trim()}`);
+
+  return `${fm}\n\n${sections.join('\n\n')}\n`;
+}
+
+/**
+ * File (or update) a deterministic RCA feedback item for a needs_review job.
+ * Never throws — logs one line on success/skip/error and always resolves.
+ *
+ * Idempotency: the destination filename is deterministic per (slug, runId).
+ * A second call for the same (slug, runId) with no investigationText is a
+ * no-op; a second call WITH investigationText overwrites the same file to
+ * add/replace the "Investigation analysis" section rather than filing a
+ * duplicate. A different runId (new run of the same slug) files a new RCA.
+ *
+ * @param {object} opts
+ * @param {{slug: string, cwd?: string, runId: string, exitCode?: number, error?: string}} opts.job
+ * @param {string} [opts.runDir]   Run directory containing <slug>.log / <slug>.meta.json.
+ * @param {string} opts.verdict    Verifier verdict string (e.g. 'uncommitted_changes').
+ * @param {Array}  [opts.annotations]  Non-blocking verifier annotations (currently unused
+ *                                     in the body beyond being accepted for future use).
+ * @param {string} [opts.investigationText]  <RCA> block text from an Opus investigation.
+ * @param {Date}   [opts.now]      Override for the date segment of the filename (testing).
+ * @returns {Promise<{filed: boolean, path?: string, updated?: boolean, reason?: string}>}
+ */
+async function fileRcaFeedback({ job, runDir, verdict, annotations, investigationText, now } = {}) {
+  try {
+    if (process.env.SM_RCA_DISABLE === '1') {
+      console.log('[rca] skip: SM_RCA_DISABLE=1');
+      return { filed: false, reason: 'disabled' };
+    }
+    if (!job || !job.slug || !job.runId) {
+      console.log('[rca] skip: missing job.slug/job.runId');
+      return { filed: false, reason: 'missing-job-fields' };
+    }
+    // Defense-in-depth: job.slug is already constrained by the scheduler's own
+    // slug schema (ipcSchemas.cjs SCHEDULE_SLUG_RE) wherever a job is created,
+    // but this lib builds filesystem paths straight from it — a second,
+    // narrower check here costs nothing and closes off future regex laxity
+    // upstream (mirrors scheduler.cjs's safeSlugPath()).
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(job.slug)) {
+      console.log(`[rca] skip: unsafe job.slug ${JSON.stringify(job.slug)}`);
+      return { filed: false, reason: 'unsafe-slug' };
+    }
+    if (!verdict) {
+      console.log(`[rca] skip: no verdict for ${job.slug}`);
+      return { filed: false, reason: 'no-verdict' };
+    }
+
+    const dest = resolveDestination(job);
+    const dateStr = (now instanceof Date ? now : new Date()).toISOString().slice(0, 10);
+    const fileName = rcaFileName(dateStr, job.slug, job.runId);
+    const destPath = path.resolve(path.join(dest.dir, fileName));
+    if (!destPath.startsWith(path.resolve(dest.dir) + path.sep)) {
+      console.log(`[rca] skip: destPath escaped dest dir (${destPath})`);
+      return { filed: false, reason: 'unsafe-path' };
+    }
+
+    const alreadyFiled = fs.existsSync(destPath);
+    if (alreadyFiled && !investigationText) {
+      console.log(`[rca] skip: already filed for ${job.slug}@${job.runId}`);
+      return { filed: false, reason: 'duplicate', path: destPath };
+    }
+
+    const meta = readRunMeta(runDir, job.slug);
+    const logPath = runDir ? path.join(runDir, `${job.slug}.log`) : null;
+    const logTail = logPath ? readTail(logPath, 64 * 1024) : '';
+    const acText = extractAcceptanceCriteria(readPrdBody(job.slug));
+    const failureClass = classifyFailure({ verdict, logTail });
+
+    const markdown = buildRcaMarkdown({
+      job, verdict, meta, logTail, acText, failureClass, investigationText,
+      targetProjectNote: dest.targetProjectNote, annotations,
+    });
+
+    config.addAllowedRoot(dest.allowlistRoot);
+    await config.writeTextAtomic(destPath, markdown);
+
+    console.log(`[rca] ${alreadyFiled ? 'updated (investigation)' : 'filed'} ${destPath}`);
+    return { filed: true, path: destPath, updated: alreadyFiled };
+  } catch (e) {
+    console.error('[rca] error filing RCA feedback', e?.message ?? String(e));
+    return { filed: false, reason: 'error', error: e?.message ?? String(e) };
+  }
+}
+
+module.exports = {
+  fileRcaFeedback,
+  // Pure helpers, exported for unit tests.
+  humanVerdict,
+  classifyFailure,
+  extractAcceptanceCriteria,
+  extractRcaBlock,
+  resolveDestination,
+  rcaFileName,
+  buildRcaMarkdown,
+  FAILURE_CLASSES,
+  VERDICT_LABELS,
+  SM_REPO_FEEDBACK_DIR,
+};

package/src/main/lib/schedulerConfig.cjs

@@ -21,4 +21,20 @@ module.exports = {
   MAX_JOB_DURATION_MS: 4 * 60 * 60_000,
   SUPERVISOR_INTERVAL_MS: 15 * 60_000,
   SUPERVISOR_PROBE_STALE_MS: 10 * 60_000,
+  // Trailing-edge debounce window for schedule:state broadcasts. A burst of
+  // mutations (boot reverify healing several rows, poll-loop refreshes,
+  // queue-linter fixups) arms one timer and sends a single push with the
+  // latest state, instead of one full-payload IPC broadcast per mutation.
+  // Lone mutations still arrive promptly (~200ms). State-machine transitions
+  // (pause/resume, job start/finish/reap/reset) bypass this via
+  // broadcast({ flush: true }).
+  BROADCAST_COALESCE_MS: 200,
+  // Terminal (completed/failed) jobs older than this move from queue.json's
+  // hot jobs[] into the append-only history.jsonl sidecar. See
+  // src/main/lib/queueHistory.cjs.
+  HISTORY_RETENTION_MS: 7 * 24 * 60 * 60_000,
+  // Cadence for the in-app intraday refresher that keeps TODAY's History
+  // rollup line current (see historyAggregator.cjs's refreshIntradayToday).
+  // Cheap: LRU-warm live parse, no full transcript re-read.
+  HISTORY_INTRADAY_REFRESH_MS: 5 * 60_000,
 };