claude-code-session-manager 0.98.0 → 0.101.0

package/src/main/lib/prdSizing.cjs

@@ -5,7 +5,8 @@
  * jobs finishing in <=10 min, yet nothing at the authoring gate flags an oversized PRD before
  * it lands. `sizingWarnings` is the single rule set; prdCreate.cjs's createPrd() surfaces its
  * output in the create-prd response, and scheduler-mcp-server.cjs's scheduler_create_prd
- * handler prints it as a "Sizing warnings:" block. Warnings never block a write.
+ * handler prints it as part of a "Warnings:" block (merged with the gate/files warnings
+ * from prdGateFiles.cjs). Warnings never block a write.
  */
 'use strict';
 

package/src/main/lib/projectHomeAdminRoutes.cjs

@@ -1,14 +1,22 @@
 /**
- * projectHomeAdminRoutes.cjs — the single admin route behind the
- * `project_home_write` MCP tool: POST /admin/project-home/write {cwd, html}
- * writes one self-contained HTML document to
- * `session-manager-operations/project-pages/home.html` (owner: project-home,
- * see opsOwnership.cjs). Registered against the same injected
- * localAdminHttp.cjs transport as prdAdminRoutes.cjs.
+ * projectHomeAdminRoutes.cjs — the two admin routes behind the
+ * project_home_write MCP tool and its demo-video sibling:
+ *   POST /admin/project-home/write              {cwd, html} -> project-pages/home.html
+ *   POST /admin/project-home/demo-video/write   {cwd, html} -> project-pages/demo-video/index.html
+ * both owned by writer 'project-home' (see opsOwnership.cjs). Registered
+ * against the same injected localAdminHttp.cjs transport as
+ * prdAdminRoutes.cjs.
  *
  * "Self-contained" is enforced here, not trusted: the document must not
  * reference any remote resource (`<script src>`, `<link href=http*>`,
  * remote `@import` / `url(http*)`), so opening it never causes network egress.
+ *
+ * The demo-video document runs inline JavaScript (the home page does not), so
+ * it additionally rejects network-capable APIs (fetch, WebSocket, dynamic
+ * import, …) and has a Content-Security-Policy meta stamped into <head>
+ * before it is written — the real network fence, since the viewer renders it
+ * via smfile:// in a sandboxed iframe that sends no CSP header itself. The
+ * regex checks below are defence in depth, not the control.
  */
 'use strict';
 
@@ -21,8 +29,9 @@ const config = require('../config.cjs');
 const { schemas } = require('../ipcSchemas.cjs');
 
 const MAX_HTML_BYTES = 1024 * 1024;
+const MAX_DEMO_VIDEO_BYTES = 2 * 1024 * 1024;
 
-// Each detector is a linear regex scan; the input is capped at 1MB first.
+// Each detector is a linear regex scan; the input is capped first.
 const REMOTE_REFERENCE_CHECKS = [
   { re: /<script\b[^>]*\bsrc\s*=/i, message: '<script src> is not allowed — inline all scripts' },
   { re: /<link\b[^>]*\bhref\s*=\s*["']?\s*(?:https?:)?\/\//i, message: '<link href="http(s)://…"> is not allowed — inline all styles' },
@@ -30,6 +39,43 @@ const REMOTE_REFERENCE_CHECKS = [
   { re: /url\(\s*["']?\s*(?:https?:)?\/\//i, message: 'url(http(s)://…) is not allowed — embed assets as data: URIs' },
 ];
 
+// Demo-video documents run inline JS; these reject the network-capable
+// surface a self-contained, CSP-fenced document must never reach for.
+const NETWORK_CHECKS = [
+  { re: /\bfetch\s*\(/i, message: 'fetch(...) is not allowed' },
+  { re: /\bXMLHttpRequest\b/i, message: 'XMLHttpRequest is not allowed' },
+  { re: /\bWebSocket\b/i, message: 'WebSocket is not allowed' },
+  { re: /\bEventSource\b/i, message: 'EventSource is not allowed' },
+  { re: /\bsendBeacon\b/i, message: 'sendBeacon is not allowed' },
+  { re: /\bimport\s*\(/i, message: 'import(...) is not allowed' },
+  { re: /\bimportScripts\b/i, message: 'importScripts is not allowed' },
+  { re: /<iframe\b/i, message: '<iframe> is not allowed' },
+  { re: /<object\b/i, message: '<object> is not allowed' },
+  { re: /<embed\b/i, message: '<embed> is not allowed' },
+  { re: /\bwindow\.open\b/i, message: 'window.open is not allowed' },
+  { re: /\b(?:src|href)\s*=\s*["']?\s*(?:https?:)?\/\//i, message: 'src=/href= pointing at http(s): or // is not allowed' },
+  { re: /["'`](?:fetch|XMLHttpRequest|WebSocket|EventSource|sendBeacon|open|importScripts)["'`]/i, message: 'computed/bracket access to a network API (e.g. window["fetch"]) is not allowed' },
+  { re: /\bWorker\s*\(/i, message: 'Worker(...) is not allowed' },
+  { re: /\bSharedWorker\b/i, message: 'SharedWorker is not allowed' },
+  { re: /\bserviceWorker\b/i, message: 'serviceWorker is not allowed' },
+  { re: /rel\s*=\s*["']?\s*(?:prefetch|preconnect|dns-prefetch|preload)/i, message: 'rel="prefetch|preconnect|dns-prefetch|preload" is not allowed' },
+  { re: /\beval\s*\(/i, message: 'eval(...) is not allowed' },
+  { re: /\bFunction\s*\(/i, message: 'Function(...) is not allowed' },
+  { re: /<base\b/i, message: '<base> is not allowed' },
+  { re: /<form\b/i, message: '<form> is not allowed' },
+  { re: /http-equiv\s*=\s*["']?refresh/i, message: 'meta refresh is not allowed' },
+  { re: /\blocation\s*(?:\.\s*(?:href|assign|replace)\b|=[^=])/i, message: 'location.href/assign/replace/= navigation is not allowed' },
+  { re: /\bdocument\.location\b/i, message: 'document.location is not allowed' },
+  { re: /\b(?:top|parent)\./i, message: 'top./parent. property access is not allowed' },
+  { re: /<a\b[^>]*\bhref\s*=\s*["']?\s*(?:https?:|\/\/|javascript:)/i, message: '<a href="http(s):|//|javascript:…"> is not allowed' },
+];
+
+const DURATION_META_RE = /<meta\b[^>]*\bname\s*=\s*["']sm-demo-duration["'][^>]*\bcontent\s*=\s*["'](\d+)["'][^>]*>/i;
+const MIN_DEMO_DURATION_S = 5;
+const MAX_DEMO_DURATION_S = 30;
+
+const DEMO_VIDEO_CSP = '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; script-src \'unsafe-inline\'; style-src \'unsafe-inline\'; img-src data: blob:; media-src data: blob:; font-src data:; connect-src \'none\'">';
+
 /** -> null when `html` is acceptable, else a human-readable rejection reason. */
 function validateHomeHtml(html) {
   if (typeof html !== 'string' || html.trim().length === 0) return 'html must be a non-empty string';
@@ -40,6 +86,42 @@ function validateHomeHtml(html) {
   return null;
 }
 
+/** -> null when `html` is acceptable, else a human-readable rejection reason. */
+function validateDemoVideoHtml(html) {
+  if (typeof html !== 'string' || html.trim().length === 0) return 'html must be a non-empty string';
+  if (Buffer.byteLength(html, 'utf8') > MAX_DEMO_VIDEO_BYTES) return `html exceeds the ${MAX_DEMO_VIDEO_BYTES}-byte limit`;
+  for (const { re, message } of REMOTE_REFERENCE_CHECKS) {
+    if (re.test(html)) return `html must be self-contained: ${message}`;
+  }
+  for (const { re, message } of NETWORK_CHECKS) {
+    if (re.test(html)) return `html must not be network-capable: ${message}`;
+  }
+  const match = html.match(DURATION_META_RE);
+  if (!match) {
+    return 'html must declare <meta name="sm-demo-duration" content="N"> with '
+      + `${MIN_DEMO_DURATION_S} <= N <= ${MAX_DEMO_DURATION_S}`;
+  }
+  const duration = Number(match[1]);
+  if (!Number.isFinite(duration) || duration < MIN_DEMO_DURATION_S || duration > MAX_DEMO_DURATION_S) {
+    return `sm-demo-duration must be between ${MIN_DEMO_DURATION_S} and ${MAX_DEMO_DURATION_S}, got ${match[1]}`;
+  }
+  return null;
+}
+
+/**
+ * Strips any existing CSP meta and a leading doctype, then returns the CSP
+ * as the very first element after a fresh `<!DOCTYPE html>` — a position no
+ * decoy `<head` text, HTML comment, or string literal in the document can
+ * influence. The HTML parser folds a <meta> emitted right after the doctype
+ * into the implicitly-created <head>, and a later <html>/<head> start tag is
+ * merged/ignored, so the CSP still applies to the whole document.
+ */
+function injectCsp(html) {
+  const withoutCsp = html.replace(/<meta\b[^>]*\bhttp-equiv\s*=\s*["']Content-Security-Policy["'][^>]*>\s*/gi, '');
+  const withoutDoctype = withoutCsp.replace(/^\s*<!DOCTYPE\b[^>]*>\s*/i, '');
+  return `<!DOCTYPE html>${DEMO_VIDEO_CSP}${withoutDoctype}`;
+}
+
 /** Same definition crossProjectFeedback.cjs uses for "is this a Session
  * Manager project": it already has an operations root. */
 function isSessionManagerProject(cwd) {
@@ -79,16 +161,20 @@ function resolveCwd(rawCwd) {
   return { ok: true, cwd: realCwd };
 }
 
-function registerAdminRoute(adminHttp) {
-  // POST /admin/project-home/write {cwd, html}
-  adminHttp.registerRoute('POST', '/admin/project-home/write', async (req, res) => {
-    // Allow headroom over MAX_HTML_BYTES for JSON escaping; the html byte
-    // limit itself is enforced by validateHomeHtml below.
+/**
+ * Builds a POST handler shared by both routes: read+parse the body, validate
+ * against `schema`, resolve cwd, run `validate(html)`, optionally `transform`
+ * the html (CSP injection), then write it atomically as writer 'project-home'.
+ */
+function makeWriteHandler({ schema, maxBytes, validate, transform, targetPath }) {
+  return async (req, res) => {
+    // Allow headroom over maxBytes for JSON escaping; the html byte limit
+    // itself is enforced by `validate` below.
     let raw;
     try {
-      raw = await readBody(req, MAX_HTML_BYTES * 2 + 4096);
+      raw = await readBody(req, maxBytes * 2 + 4096);
     } catch (e) {
-      sendJson(res, 400, { ok: false, error: `request body rejected: ${e?.message ?? 'unreadable'} (html limit is ${MAX_HTML_BYTES} bytes)` });
+      sendJson(res, 400, { ok: false, error: `request body rejected: ${e?.message ?? 'unreadable'} (html limit is ${maxBytes} bytes)` });
       return;
     }
     let body;
@@ -100,7 +186,7 @@ function registerAdminRoute(adminHttp) {
     }
     let input;
     try {
-      input = schemas.projectHomeAdminWriteBody.parse(body);
+      input = schema.parse(body);
     } catch (e) {
       sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
       return;
@@ -110,7 +196,7 @@ function registerAdminRoute(adminHttp) {
       sendJson(res, resolved.status, { ok: false, error: resolved.error });
       return;
     }
-    const rejection = validateHomeHtml(input.html);
+    const rejection = validate(input.html);
     if (rejection) {
       sendJson(res, 400, { ok: false, error: rejection });
       return;
@@ -118,14 +204,43 @@ function registerAdminRoute(adminHttp) {
     // Only a route that is actually about to write widens config.cjs's
     // write boundary to this project root.
     config.addAllowedRoot(resolved.cwd);
+    const finalHtml = transform ? transform(input.html) : input.html;
     try {
-      const homePath = opsPath(resolved.cwd, 'project-pages', 'home.html');
-      await config.writeTextAtomic(homePath, input.html, { writer: 'project-home' });
-      sendJson(res, 200, { ok: true, path: homePath, bytes: Buffer.byteLength(input.html, 'utf8') });
+      const abs = targetPath(resolved.cwd);
+      await fs.promises.mkdir(path.dirname(abs), { recursive: true });
+      await config.writeTextAtomic(abs, finalHtml, { writer: 'project-home' });
+      sendJson(res, 200, { ok: true, path: abs, bytes: Buffer.byteLength(finalHtml, 'utf8') });
     } catch (e) {
       sendJson(res, 500, { ok: false, error: e?.message ?? 'write failed' });
     }
-  });
+  };
+}
+
+function registerAdminRoute(adminHttp) {
+  // POST /admin/project-home/write {cwd, html}
+  adminHttp.registerRoute('POST', '/admin/project-home/write', makeWriteHandler({
+    schema: schemas.projectHomeAdminWriteBody,
+    maxBytes: MAX_HTML_BYTES,
+    validate: validateHomeHtml,
+    targetPath: (cwd) => opsPath(cwd, 'project-pages', 'home.html'),
+  }));
+
+  // POST /admin/project-home/demo-video/write {cwd, html}
+  adminHttp.registerRoute('POST', '/admin/project-home/demo-video/write', makeWriteHandler({
+    schema: schemas.projectDemoVideoAdminWriteBody,
+    maxBytes: MAX_DEMO_VIDEO_BYTES,
+    validate: validateDemoVideoHtml,
+    transform: injectCsp,
+    targetPath: (cwd) => opsPath(cwd, 'project-pages', 'demo-video', 'index.html'),
+  }));
 }
 
-module.exports = { registerAdminRoute, validateHomeHtml, MAX_HTML_BYTES };
+module.exports = {
+  registerAdminRoute,
+  validateHomeHtml,
+  validateDemoVideoHtml,
+  injectCsp,
+  DEMO_VIDEO_CSP,
+  MAX_HTML_BYTES,
+  MAX_DEMO_VIDEO_BYTES,
+};

package/src/main/lib/promptSessionSchema.cjs

@@ -14,7 +14,7 @@
 'use strict';
 
 const { z } = require('zod');
-const { WorkTypeSchema } = require('./workTypeLibrary.cjs');
+const { WorkTypeSchema, LEGACY_WORK_TYPES } = require('./workTypeLibrary.cjs');
 
 // Mirrors EpicTag (src/renderer/lib/tagLibrary.ts:10) — the Epic-level
 // mission tag. Epic tag and PRD tag (ipcSchemas.cjs's scheduleRetagPrd `tag`
@@ -23,6 +23,14 @@ const { WorkTypeSchema } = require('./workTypeLibrary.cjs');
 // own enum literal.
 const EpicTagSchema = WorkTypeSchema;
 
+// A legacy tag value (e.g. the retired 'bilko-host-publisher') must keep
+// loading on an old on-disk Epic — dropped silently (treated as absent),
+// never thrown. Any other unknown value still fails via EpicTagSchema.
+const LegacyAwareEpicTagSchema = z.preprocess(
+  (v) => (typeof v === 'string' && LEGACY_WORK_TYPES.includes(v) ? undefined : v),
+  EpicTagSchema.optional(),
+);
+
 // Mirrors EpicSource (src/renderer/state/promptSessions.ts:22-27).
 const EpicSourceSchema = z.object({
   producer: z.enum(['new-epic-ui', 'scheduler-dispatch', 'cross-project-feedback']),
@@ -69,7 +77,7 @@ const PromptSessionSchema = z.object({
   createdAt: z.string(),
   completedAt: z.string().nullable(),
   resumedFromId: z.string().nullable().optional(),
-  tag: EpicTagSchema.optional(),
+  tag: LegacyAwareEpicTagSchema,
   openingPrompt: z.string().nullable().optional(),
   source: EpicSourceSchema.optional(),
   agentType: z.string().optional(),

package/src/main/lib/rcaReport.cjs

@@ -35,6 +35,7 @@ const path = require('node:path');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { readTail } = require('./fileTail.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 // ─── VERDICT_LABELS — deliberate duplicate ──────────────────────────────────
 // Mirrors src/renderer/components/tabs/scheduler/sched-primitives.tsx:123-131.
@@ -396,15 +397,12 @@ async function writeRcaReport({ job, runDir, verdict, annotations, investigation
       job, verdict, meta, logTail, acText, failureClass, investigationText, annotations,
     });
 
-    // Raw fs (not config.cjs's writeTextAtomic) for the same reason the rest
-    // of this lib uses it: the run directory lives under
+    // atomicFs.cjs (not config.cjs's writeTextAtomic) for the same reason the
+    // rest of this lib uses it: the run directory lives under
     // ~/.claude/session-manager/scheduled-plans/runs/, which is Session-Manager
     // runtime state, not an OWNERS namespace under a project's operations root.
     const reportPath = path.join(runDir, `root-cause-${job.slug}.md`);
-    fs.mkdirSync(runDir, { recursive: true });
-    const tmp = `${reportPath}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, markdown);
-    fs.renameSync(tmp, reportPath);
+    atomicFs.writeTextAtomicSync(reportPath, markdown);
 
     const summary = rcaSummaryLine(job, verdict);
     const recoveryAction = recoveryActionFor(failureClass);

package/src/main/lib/reaperHelpers.cjs

@@ -11,6 +11,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { readTail } = require('./fileTail.cjs');
 const { detectRateLimitInLog } = require('./rateLimitDetect.cjs');
+const { pidAlive } = require('./pidAlive.cjs');
 
 /**
  * Return true if pid is alive AND its cmdline looks like a claude process.
@@ -20,12 +21,18 @@ const { detectRateLimitInLog } = require('./rateLimitDetect.cjs');
  * cmdline, so we conservatively return true — never false-reap a live PID
  * just because we can't verify its identity.
  *
+ * Existence check now delegates to the shared pidAlive() (pidAlive.cjs) so
+ * EPERM (pid exists, owned by another user) counts as alive here too — the
+ * previous bare `process.kill(pid, 0)` + catch-all-false treated EPERM the
+ * same as ESRCH (no such process), silently false-reaping a live-but-
+ * unsignalable pid.
+ *
  * Conservative by design: a false negative (live process treated as dead) is
  * far worse than a late reap.
  */
 function claudePidAlive(pid) {
   if (!pid || typeof pid !== 'number' || pid <= 1) return false;
-  try { process.kill(pid, 0); } catch { return false; }
+  if (!pidAlive(pid)) return false;
   try {
     const cmd = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
     return /\bclaude\b/.test(cmd);

package/src/main/lib/reservationExpiry.cjs

@@ -9,10 +9,15 @@
  */
 'use strict';
 
+const { pidAlive } = require('./pidAlive.cjs');
+
 const DEFAULT_GRACE_MS = 10 * 60 * 1000;
 
+// Thin alias over pidAlive.cjs's shared pidAlive() — kept as its own named
+// export (rather than inlining the require at every call site) so existing
+// imports of `defaultPidAlive` from this module keep working unchanged.
 function defaultPidAlive(pid) {
-  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === 'EPERM'; }
+  return pidAlive(pid);
 }
 
 /**

package/src/main/lib/reviewNotice.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * reviewNotice.cjs — pure helpers behind the quiet, grouped needs_review
+ * notice (this PRD).
+ *
+ * Before this module, a park into `needs_review` told the authoring Epic
+ * immediately (scheduler.cjs's notifyNeedsReview), BEFORE the scheduler's own
+ * recovery ladder (mechanical re-integration, resume, quarantine, auto-fix,
+ * gate re-run, bounded auto-resolve) ever got a chance to run. Most parks
+ * heal on their own, so that immediate message was usually a false alarm.
+ *
+ * The new rule: record a notice at park time (buildReviewNotice) and send
+ * nothing yet. Send ONE message, grouped by (cwd, Epic, cause), only once the
+ * ladder gives up on a row (an auto-resolve skip) or the row has sat
+ * `needs_review` past a hold window (selectDueReviewNotices + holdMsFromEnv).
+ * scheduler.cjs's flushDueReviewNotices is the only caller that actually
+ * sends — this module stays fs/network-free so it is unit-testable without
+ * touching queue.json or the Epic event store.
+ *
+ * Each park is one episode with one hold clock. scheduler.cjs's
+ * resetJobFields deletes `job.reviewNotice` outright, so a human reset always
+ * starts the next park's clock fresh — it never inherits a stale
+ * `firstParkedAt` from days earlier. A rung-6 ladder requeue goes through
+ * `transitionJob` directly, not `resetJobFields`, so that requeue keeps the
+ * same clock on purpose (it is still the same unresolved episode).
+ *
+ * The sent message also says plainly whether the group still blocks other
+ * work: formatReviewNotice names any `pending` row whose `dependsOn` names a
+ * still-`needs_review` row in the group, instead of always claiming nothing
+ * is waiting. And a row that is not yet due on its own only joins a due
+ * group — "sweeps in" — once it has sat for SWEEP_MIN_AGE_MINUTES, so a row
+ * that parked seconds ago is never announced before the ladder's early rungs
+ * get a chance to run.
+ */
+
+// Default hold before an un-resolved needs_review park gets its own grouped
+// notice, in minutes. Overridable via SM_REVIEW_NOTICE_HOLD_MINUTES.
+const DEFAULT_HOLD_MINUTES = 240;
+
+// Same dependsOn slug-matching rule schedulerBatch.cjs's findBlockingDep uses
+// at run time (exact slug first, else bare-name after stripping one leading
+// `NN-`) — reused here, not reimplemented, so formatReviewNotice's "blocks"
+// wording can never disagree with what actually holds a dependent `pending`
+// row in the real queue.
+const { bareSlug } = require('./depSlugResolve.cjs');
+
+/**
+ * buildReviewNotice({ job, report, epicId, now, prior }) → ReviewNotice
+ *
+ * Stamped onto a job row (`job.reviewNotice`) the moment it parks
+ * `needs_review`, in the SAME mutate that classifies the RCA report
+ * (scheduler.cjs's park path). `report` is rcaReport.cjs's writeRcaReport()
+ * result — `null`, or `{ filed: false, ... }` when the report was skipped
+ * (SM_RCA_DISABLE, no verdict, etc.) — in which case a deterministic fallback
+ * summary stands in for the one the RCA report would have carried.
+ *
+ * `firstParkedAt` is the anchor selectDueReviewNotices measures the hold
+ * window from. It is carried forward from `prior` (the job's existing
+ * reviewNotice, if any) as long as that prior notice is still unsent — a
+ * re-park of the SAME unresolved episode (e.g. one more ladder attempt that
+ * also fails) must not restart the hold clock. Once a notice has been sent,
+ * a later park starts a fresh clock — and so does a later park after a human
+ * reset, because resetJobFields deletes the notice outright, so `prior` is
+ * `undefined` and this falls to the same `now` default.
+ */
+function buildReviewNotice({ job, report, epicId, now, prior } = {}) {
+  const cause = `${job?.verifierVerdict || 'unknown'}${job?.integrationFailureKind ? `:${job.integrationFailureKind}` : ''}`;
+  const filed = Boolean(report && report.filed);
+  const summary = filed ? report.summary : `${job?.slug ?? 'unknown job'} stopped (${cause})`;
+  const reportPath = filed ? (report.path ?? null) : null;
+  const firstParkedAt = prior && !prior.sentAt && prior.firstParkedAt ? prior.firstParkedAt : now;
+  return {
+    summary,
+    reportPath,
+    cause,
+    epicId: epicId ?? null,
+    firstParkedAt,
+    sentAt: null,
+  };
+}
+
+// A not-yet-due row only joins a due group ("sweeps in") once it has sat
+// `needs_review` for at least this long. Why: the self-heal ladder
+// (scheduler-operations.md §4) needs about 30 minutes to work through its
+// early rungs, so sweeping in a row seconds after it parked would announce
+// it before the ladder ever got a chance to self-heal it. A row that is due
+// ON ITS OWN (its own hold expired, or a skipped auto-resolve) is never held
+// back by this rule — see isDue below.
+const SWEEP_MIN_AGE_MINUTES = 30;
+
+// Milliseconds since reviewNotice.firstParkedAt, or 0 for a missing/
+// unparsable timestamp (fail young — never treat a bad timestamp as old
+// enough to sweep in early).
+function parkedAgeMs(j, now) {
+  const firstParkedAt = j.reviewNotice && j.reviewNotice.firstParkedAt;
+  if (!firstParkedAt) return 0;
+  const parkedMs = Date.parse(firstParkedAt);
+  return Number.isFinite(parkedMs) ? now - parkedMs : 0;
+}
+
+/**
+ * selectDueReviewNotices(jobs, { now, holdMs }) → [{ cwd, epicId, cause, jobs }]
+ *
+ * A row is a candidate when it carries an unsent `reviewNotice` and is
+ * either `skipped` with `needsReviewAutoResolvedSkip` (the ladder gave up),
+ * or still `needs_review` with its notice's `firstParkedAt` at least
+ * `holdMs` in the past. completed/pending/running rows, and rows whose
+ * notice is already sent, are never candidates.
+ *
+ * Grouping key is (cwd, reviewNotice.epicId, reviewNotice.cause) — one
+ * message per distinct cause per Epic, not one per PRD. Once any row in a
+ * key is due, every other unsent candidate sharing that same key is swept
+ * into the SAME group even if it individually hasn't reached its own due
+ * condition yet, so a cause that affects several PRDs is reported once —
+ * except a swept-in `needs_review` row must itself be at least
+ * SWEEP_MIN_AGE_MINUTES old (parkedAgeMs); a row due on its own skips that
+ * check entirely.
+ */
+function selectDueReviewNotices(jobs = [], { now = Date.now(), holdMs = DEFAULT_HOLD_MINUTES * 60000 } = {}) {
+  const isCandidate = (j) => Boolean(
+    j
+    && j.reviewNotice
+    && !j.reviewNotice.sentAt
+    && (j.status === 'needs_review' || (j.status === 'skipped' && j.needsReviewAutoResolvedSkip)),
+  );
+  const isDue = (j) => {
+    if (j.status === 'skipped' && j.needsReviewAutoResolvedSkip) return true;
+    if (j.status !== 'needs_review') return false;
+    const firstParkedAt = j.reviewNotice.firstParkedAt;
+    if (!firstParkedAt) return false;
+    const parkedMs = Date.parse(firstParkedAt);
+    if (!Number.isFinite(parkedMs)) return false;
+    return now - parkedMs >= holdMs;
+  };
+  const keyOf = (j) => `${j.cwd ?? ''}\u0000${j.reviewNotice.epicId ?? ''}\u0000${j.reviewNotice.cause ?? ''}`;
+
+  const list = Array.isArray(jobs) ? jobs : [];
+  const dueKeys = new Set();
+  for (const j of list) {
+    if (isCandidate(j) && isDue(j)) dueKeys.add(keyOf(j));
+  }
+  if (dueKeys.size === 0) return [];
+
+  const sweepMinAgeMs = SWEEP_MIN_AGE_MINUTES * 60000;
+  const groupsByKey = new Map();
+  for (const j of list) {
+    if (!isCandidate(j)) continue;
+    const key = keyOf(j);
+    if (!dueKeys.has(key)) continue;
+    // Not due on its own, and too young to sweep in — leave it for a later
+    // pass, once either its own hold expires or it ages past the sweep gate.
+    if (!isDue(j) && parkedAgeMs(j, now) < sweepMinAgeMs) continue;
+    if (!groupsByKey.has(key)) {
+      groupsByKey.set(key, { cwd: j.cwd ?? null, epicId: j.reviewNotice.epicId ?? null, cause: j.reviewNotice.cause ?? null, jobs: [] });
+    }
+    groupsByKey.get(key).jobs.push(j);
+  }
+  return Array.from(groupsByKey.values());
+}
+
+// Plain-language stand-in for the raw verifier/integration cause string.
+// Only causes worth explaining in human terms get an entry — formatReviewNotice
+// falls back to the raw cause for anything not listed here.
+const HUMAN_CAUSE = {
+  'worktree_integration_failed:stray_checkout': 'the main checkout was on a different branch, so the work could not be merged',
+  transcript_errors: "the run's transcript showed error lines, so its pass could not be trusted",
+  no_verdict_sentinel: 'the run finished without leaving a clear pass or fail signal',
+  abandoned_background_task: 'the run started a background task and then stopped watching it',
+  silent_no_op: 'the run finished clean but made no changes, so there is no evidence it did the work',
+  pass_no_commit: 'the run reported success but did not commit anything',
+};
+
+function humanCauseFor(cause) {
+  return HUMAN_CAUSE[cause] ?? cause;
+}
+
+// One phrase per ladder rung, in the fixed order the ladder itself runs
+// (scheduler-operations.md §4). Checked across every row in the group — the
+// summary is the union of what was tried for ANY of the grouped PRDs, not
+// just one.
+function ladderSummaryFor(jobs) {
+  const some = (pred) => jobs.some(pred);
+  const phrases = [];
+  if (some((j) => j.mechanicalRecoveryAttempted)) phrases.push('re-merged the branch');
+  if (some((j) => j.resumeRecoveryAttempted)) phrases.push('resumed the session');
+  if (some((j) => (j.quarantineResolveAttempts ?? 0) > 0)) phrases.push('set aside stray files');
+  if (some((j) => j.autoFixAttempted)) phrases.push('ran an auto-fix job');
+  if (some((j) => j.gateShadow)) phrases.push('re-ran the gate');
+  if (some((j) => (j.exhaustedResolveAttempts ?? 0) > 0)) phrases.push('re-queued the job');
+  if (some((j) => j.needsReviewAutoResolvedSkip)) phrases.push('gave up and skipped the job');
+  return phrases.length ? phrases.join(', ') : 'nothing yet';
+}
+
+// The pending rows (from the FULL job list, not just this group) that a
+// still-`needs_review` row in the group blocks. A dep slug "names" a group
+// row when it matches that row's slug exactly, or by bare name (same rule as
+// findBlockingDep). Only rows in the group's own cwd are considered — a
+// dependsOn chain never crosses projects. Returns a sorted, de-duplicated
+// list of the blocked rows' slugs.
+function blockedDependents(group, jobs) {
+  const blockingSlugs = (group.jobs ?? [])
+    .filter((j) => j.status === 'needs_review')
+    .map((j) => j.slug)
+    .filter(Boolean);
+  if (!blockingSlugs.length) return [];
+  const namesABlockingSlug = (depSlug) => blockingSlugs.some(
+    (slug) => depSlug === slug || bareSlug(depSlug) === bareSlug(slug),
+  );
+  const blocked = new Set();
+  for (const p of jobs ?? []) {
+    if (p.status !== 'pending' || p.cwd !== group.cwd) continue;
+    if ((p.dependsOn ?? []).some(namesABlockingSlug)) blocked.add(p.slug);
+  }
+  return [...blocked].sort();
+}
+
+/**
+ * formatReviewNotice(group, { jobs }) → plain-text message body for the
+ * authoring Epic's event chain. `group` is one entry from
+ * selectDueReviewNotices(). `jobs` is the FULL live job list (every status,
+ * every project) — needed to find any `pending` row this group still blocks;
+ * omit it (or pass `[]`) to always get the "nothing is waiting" wording,
+ * e.g. from a caller that only has the group itself.
+ */
+function formatReviewNotice(group, { jobs = [] } = {}) {
+  const groupJobs = group.jobs ?? [];
+  const slugs = groupJobs.map((j) => j.slug).filter(Boolean);
+  const reportPaths = groupJobs.map((j) => j.reviewNotice?.reportPath).filter(Boolean);
+  const blocked = blockedDependents(group, jobs);
+  const waitingLine = blocked.length
+    ? `These PRDs block ${blocked.length} other PRD(s) until they are fixed, reset or archived: ${blocked.join(', ')}.`
+    : 'The rest of the plan keeps running. Nothing is waiting on you unless you want to act.';
+  const lines = [
+    `${groupJobs.length} PRD(s) stopped for the same reason: ${humanCauseFor(group.cause)}.`,
+    `The scheduler already tried to fix this on its own: ${ladderSummaryFor(groupJobs)}.`,
+    waitingLine,
+    `PRDs: ${slugs.join(', ')}`,
+  ];
+  if (reportPaths.length) lines.push(`Reports: ${reportPaths.join(', ')}`);
+  return lines.join('\n');
+}
+
+/**
+ * holdMsFromEnv(env) → milliseconds a needs_review park waits, with no
+ * ladder resolution, before it gets a grouped notice on its own (case b in
+ * selectDueReviewNotices). SM_REVIEW_NOTICE_HOLD_MINUTES must be a positive
+ * number; anything else (unset, zero, negative, NaN) falls back to the
+ * DEFAULT_HOLD_MINUTES default.
+ */
+function holdMsFromEnv(env = process.env) {
+  const raw = Number(env.SM_REVIEW_NOTICE_HOLD_MINUTES);
+  const minutes = Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_HOLD_MINUTES;
+  return minutes * 60000;
+}
+
+module.exports = {
+  DEFAULT_HOLD_MINUTES,
+  buildReviewNotice,
+  selectDueReviewNotices,
+  formatReviewNotice,
+  holdMsFromEnv,
+};

package/src/main/lib/runClaudeP.cjs

@@ -16,12 +16,14 @@
 
 const { spawn } = require('node:child_process');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
+const { headlessPermissionArgs, ensureCliCapsProbed } = require('./claudeCliCaps.cjs');
 const { withProcRole } = require('./cleanEnv.cjs');
 
 const MAX_OUT_BYTES = 8 * 1024 * 1024;
 
 /** Spawn `claude -p`, capture stdout. Resolves {ok, out, error} — never throws. */
-function runClaudeP(prompt, { model = 'sonnet', timeoutMs = 180_000, systemPrompt = null } = {}) {
+async function runClaudeP(prompt, { model = 'sonnet', timeoutMs = 180_000, systemPrompt = null } = {}) {
+  await ensureCliCapsProbed();
   return new Promise((resolve) => {
     let bin;
     try { bin = resolveClaudeBin(); } catch (e) { resolve({ ok: false, error: `claude not found: ${e?.message}` }); return; }
@@ -29,6 +31,7 @@ function runClaudeP(prompt, { model = 'sonnet', timeoutMs = 180_000, systemPromp
       '-p', prompt,
       '--model', model,
       '--dangerously-skip-permissions',
+      ...headlessPermissionArgs(),
       '--output-format', 'text',
     ];
     if (systemPrompt) args.push('--append-system-prompt', systemPrompt);

package/src/main/lib/schedulerPaths.cjs

@@ -23,8 +23,28 @@ const os = require('node:os');
 const path = require('node:path');
 
 function isUnder(child, parent) {
-  const rel = path.relative(path.resolve(parent), path.resolve(child));
-  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  const within = (c, p) => {
+    const rel = path.relative(p, c);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  };
+  const c = path.resolve(child);
+  const p = path.resolve(parent);
+  if (within(c, p)) return true;
+  // Symlinked roots (macOS os.tmpdir() /var -> /private/var): also compare canonical spellings.
+  return within(realpathDeepest(c), realpathDeepest(p));
+}
+
+/** realpath of the deepest existing ancestor + the not-yet-existing tail. Never throws. */
+function realpathDeepest(abs) {
+  let head = abs;
+  const tail = [];
+  for (;;) {
+    try { return path.join(fs.realpathSync(head), ...tail.reverse()); } catch { /* walk up */ }
+    const up = path.dirname(head);
+    if (up === head) return abs;
+    tail.push(path.basename(head));
+    head = up;
+  }
 }
 
 /**