claude-code-session-manager 0.95.0 → 0.97.0

package/src/main/scheduler.cjs

@@ -80,6 +80,8 @@ const sessionsStore = require('./sessionsStore.cjs');
 const { enqueueExternalPrompt } = require('./chatRunner.cjs');
 const { appendResponseEventIfKnown } = require('./promptSessionEvents.cjs');
 const { maybeEnqueueValidationPrompt } = require('./lib/epicValidationHook.cjs');
+const { parseValidationSentinels } = require('./lib/validationSentinels.cjs');
+const { hasDownstreamValidator } = require('./lib/planValidator.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { verifyRun, parseLog, scanSentinel, scanForeignWipPathsClaim } = require('./runVerify.cjs');
 const { latestTerminalOutcomeForSlug, COMPLETED_EQUIVALENT_VERDICTS } = require('./lib/terminalRunOutcome.cjs');
@@ -274,7 +276,17 @@ const BASH_MAX_TIMEOUT_MS = 900_000; // 15 min — must stay below IDLE_OUTPUT_K
 // centrally here (not per-PRD) so it applies to every current and future PRD.
 // The commit step is also backstopped by the post-run commit guard below: a
 // clean exit that leaves uncommitted changes is downgraded to needs_review.
-const FINISH_PROTOCOL = `
+//
+// PRD 1408: a plan that ends in its own trailing `validator` job (PRD
+// 1405/1407) already re-reviews every work-item's diff once, so asking EVERY
+// work-item to also run /code-review + /security-review inline is duplicate
+// review work — and the dominant cost tail on multi-file PRDs. buildFinishProtocol
+// derives a `reviewInRun: false` variant that collapses those two steps into
+// one deferral note and renumbers the rest, sharing every other word
+// byte-for-byte with the default (`reviewInRun: true`, which is exactly
+// FINISH_PROTOCOL) via the head/review-steps/tail pieces below.
+function buildFinishHead(verifyStepNum) {
+  return `
 
 ---
 # SCHEDULER FINISH PROTOCOL (mandatory — runs AFTER the work above)
@@ -283,7 +295,7 @@ Once every acceptance-criteria line above is satisfied, finish in this EXACT
 sequence. Do not stop before the commit lands; committing is part of the job.
 
 RUN VERIFICATION IN THE FOREGROUND — this applies to the whole run, not just
-step 3 below: every test/typecheck/lint/build command you run, whether while
+step ${verifyStepNum} below: every test/typecheck/lint/build command you run, whether while
 implementing the AC or during VERIFY, must run SYNCHRONOUSLY and you must wait
 for it to return. Never start a verification command as a background task
 (no background Bash) and then call Monitor, TaskOutput, or ScheduleWakeup to
@@ -296,17 +308,26 @@ to fit inside that ceiling; if a gate command still cannot finish inside
 budget, stop and emit SCHEDULER_VERDICT: FAIL with the reason instead of
 deferring it.
 
-1. CODE REVIEW — run \`/code-review --fix\` on your changes and apply the fixes it
+`;
+}
+
+const FINISH_REVIEW_STEPS_IN_RUN = `1. CODE REVIEW — run \`/code-review --fix\` on your changes and apply the fixes it
    surfaces (correctness first). For any finding you judge a false positive, say
    why in your result; do not silently skip it. If \`/code-review\` is not
    available in this environment, do an equivalent careful self-review instead.
 2. SECURITY REVIEW — run \`/security-review\` and address every finding (or
    justify it). If unavailable, self-review the diff for injection, secrets,
    path traversal, and unsafe input handling.
-3. VERIFY — run the project's OWN check commands (typecheck / lint / tests — the
+`;
+
+const FINISH_REVIEW_STEP_DEFERRED = `1. REVIEW — code and security review for this plan run once, in its trailing validator job. Do NOT run /code-review or /security-review here.
+`;
+
+function buildFinishTail({ verifyStepNum, commitStepNum, verdictStepNum }) {
+  return `${verifyStepNum}. VERIFY — run the project's OWN check commands (typecheck / lint / tests — the
    project's CLAUDE.md names them; infer from the repo if not) and make them
    pass. Do not assume npm; use whatever the target project uses.
-4. COMMIT — the queue can run several jobs against this SAME working tree at
+${commitStepNum}. COMMIT — the queue can run several jobs against this SAME working tree at
    once. Do NOT stage the whole working tree in one blanket/wildcard git-add
    sweep — that captures whatever a concurrent sibling job is mid-writing and
    mis-attributes its work to this commit, corrupting both jobs' verdicts.
@@ -314,12 +335,12 @@ deferring it.
    commit: \`git add <path> [<path>...] && git commit -m "<type>(<scope>): <summary>"\`.
    Your own work must still never be left uncommitted — this only changes
    which paths get staged, never whether you commit.
-5. VERDICT SENTINEL — as the LAST LINE of your final result text, emit exactly
+${verdictStepNum}. VERDICT SENTINEL — as the LAST LINE of your final result text, emit exactly
    one of these lines (no trailing text after it):
      SCHEDULER_VERDICT: PASS
      SCHEDULER_VERDICT: FAIL <one-line reason>
      SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP
-   Print PASS only when the AC gate is green AND the commit from step 4 landed.
+   Print PASS only when the AC gate is green AND the commit from step ${commitStepNum} landed.
    Print FAIL (and exit 1) if the AC gate was red or the commit could not land.
    NEVER print PASS on a red AC gate — a lying PASS turns the verifier from a
    false-failure catcher into a silent-failure shipper. A truthful PASS + a
@@ -348,6 +369,30 @@ for review. Do NOT add work beyond the acceptance criteria — this protocol is
 only post-AC work. If a review finding can't be fixed within scope, commit what
 you have, describe the finding in the commit body, and note the follow-up in your
 final result.`;
+}
+
+/**
+ * buildFinishProtocol({ reviewInRun }) → string
+ *
+ * `reviewInRun: true` (default) is byte-for-byte FINISH_PROTOCOL: steps 1-5
+ * are CODE REVIEW, SECURITY REVIEW, VERIFY, COMMIT, VERDICT SENTINEL.
+ * `reviewInRun: false` collapses the two review steps into one deferral note
+ * (step 1) and renumbers VERIFY/COMMIT/VERDICT SENTINEL to 2-4 — used when
+ * `hasDownstreamValidator` (lib/planValidator.cjs) finds this job's diff will
+ * be re-reviewed once by the plan's own trailing validator job, so asking
+ * every work-item to also run /code-review + /security-review inline is
+ * redundant review work.
+ */
+function buildFinishProtocol({ reviewInRun = true } = {}) {
+  if (reviewInRun) {
+    return buildFinishHead(3) + FINISH_REVIEW_STEPS_IN_RUN
+      + buildFinishTail({ verifyStepNum: 3, commitStepNum: 4, verdictStepNum: 5 });
+  }
+  return buildFinishHead(2) + FINISH_REVIEW_STEP_DEFERRED
+    + buildFinishTail({ verifyStepNum: 2, commitStepNum: 3, verdictStepNum: 4 });
+}
+
+const FINISH_PROTOCOL = buildFinishProtocol({ reviewInRun: true });
 
 // Unquote a single git porcelain v1 path token. Defined once in
 // gitWorktree.cjs (which this file already requires — the reverse would be
@@ -1513,9 +1558,19 @@ function loadSchedulerState() {
     if (typeof s.failureStreakWarnedAt === 'number') failureStreakWarnedAt = s.failureStreakWarnedAt;
     failureStreakWarnedAt = restoreFailureStreakWarnedAt(failureStreakWarned, failureStreakWarnedAt, Date.now());
     if (typeof s.lastEscalationAt === 'number') lastEscalationAtMs = s.lastEscalationAt;
+    if (typeof s.lastPollOk === 'boolean') lastPollOk = s.lastPollOk;
+    if (typeof s.lastFailureKind === 'string' || s.lastFailureKind === null) lastFailureKind = s.lastFailureKind;
+    if (typeof s.backoffNextAt === 'number' || s.backoffNextAt === null) backoffNextAt = s.backoffNextAt;
+    if (typeof s.cachedUtilization === 'number' || s.cachedUtilization === null) cachedUtilization = s.cachedUtilization;
+    if (typeof s.cachedBindingWindowName === 'string' || s.cachedBindingWindowName === null) cachedBindingWindowName = s.cachedBindingWindowName;
   } catch { /* first boot or corrupt — start fresh */ }
 }
 
+/** Test-only seam: the module-level fields loadSchedulerState() restores that have no other exported reader. */
+function getSchedulerStateSnapshot() {
+  return { lastPollOk, lastFailureKind, backoffNextAt, cachedUtilization, cachedBindingWindowName };
+}
+
 function persistSchedulerState() {
   // Sync write: called from many sync hot paths (clearPause, pollLoop catch
   // block) and the sidecar is tiny (<1 KB). Converting to async here would
@@ -1544,6 +1599,14 @@ function persistSchedulerState() {
       // THESE persisted values, since it never holds the in-memory circuit.
       usageCircuitState: billing.usageCircuit.state(),
       usageCircuitOpenedAt: billing.usageCircuit.openedAt(),
+      // Footer/KPI display fields — previously memory-only, so a restart showed
+      // misleading placeholders (poll-failed, no rate-limit banner, "—" utilization)
+      // until the next post-boot billing poll overwrote them.
+      lastPollOk,
+      lastFailureKind,
+      backoffNextAt,
+      cachedUtilization,
+      cachedBindingWindowName,
     });
   } catch (e) {
     console.warn('[scheduler] failed to persist scheduler state', e?.message);
@@ -4280,6 +4343,11 @@ async function notifyOriginatingTab(job, {
   appendTranscriptTurn = promptSessionTranscript.appendTurn,
   readResultFromLog = extractResultTextFromLog,
   enqueueValidation = maybeEnqueueValidationPrompt,
+  // PRD 1408: same queue rows spawnJob/tickQueue already use — read fresh
+  // here (not threaded through the terminal-transition snapshot) since this
+  // fires well after dispatch, when the plan may have gained/dropped a
+  // trailing validator row since this job was spawned.
+  loadJobs = async () => (await readQueue()).jobs || [],
 } = {}) {
   try {
     const prd = await resolveNotifyPrd(job, parsePrdRaw);
@@ -4311,10 +4379,25 @@ async function notifyOriginatingTab(job, {
     // fallback). 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 || job.epicId || null;
-    if (epicIdForTranscript && job.cwd) {
+    // Read the job's raw result text once, up front, so both the transcript
+    // append below and the validator-sentinel parsing further down (PRD
+    // 1407) reuse the same read instead of hitting the run log twice. Only
+    // read when at least one consumer needs it — an ordinary job with no
+    // resolvable transcript target and no validator sentinels to parse must
+    // not pay for a log-tail read it will throw away.
+    const needsResultText = (epicIdForTranscript && job.cwd)
+      || (job.agentType === 'validator' && job.status === 'completed');
+    let resultText = null;
+    if (needsResultText) {
       try {
         const logPath = job.runId ? path.join(schedulerPaths.runsDir(), job.runId, `${job.slug}.log`) : null;
-        const resultText = readResultFromLog(logPath);
+        resultText = readResultFromLog(logPath);
+      } catch (e) {
+        console.error('[scheduler] notifyOriginatingTab readResultFromLog error', job?.slug, e);
+      }
+    }
+    if (epicIdForTranscript && job.cwd) {
+      try {
         await appendTranscriptTurn(job.cwd, epicIdForTranscript, {
           role: 'assistant',
           text: resultText || message,
@@ -4325,7 +4408,43 @@ async function notifyOriginatingTab(job, {
       }
     }
 
+    // PRD 1407: a plan-level validator job ends its run with one
+    // `VALIDATION: <slug> VERIFIED`/`REFUTED` line per PRD it checked.
+    // Parsed only for a completed validator job; every ordinary work-item
+    // job gets an empty array here and behaves exactly as before.
+    const verdicts = (job.agentType === 'validator' && job.status === 'completed')
+      ? parseValidationSentinels(resultText)
+      : [];
+
+    if (!epicId && verdicts.length > 0) {
+      // No Epic to attach these to (unresolved sourcePromptId/epicId, same
+      // rare case the check-in message below falls back on) — unlike the
+      // check-in message, a verdict has no chat-notification fallback, so
+      // without this log the parsed evidence vanishes with no trace at all.
+      console.error(
+        `[scheduler] notifyOriginatingTab: ${verdicts.length} validator verdict(s) parsed for ${job.slug} but no epicId to attach them to — dropped`,
+      );
+    }
+
     if (epicId) {
+      // PRD 1407: append one response event per parsed verdict, BEFORE the
+      // validator job's own check-in append below — each verdict stamps
+      // `validation: 'verified' | 'refuted'` onto the authoring Epic's
+      // event chain, which epicDerive.ts/epicTimeline.ts already render as
+      // the Epic traffic light and which epicValidationHook.cjs's loop
+      // guard already ignores (only 'unvalidated' can trigger a prompt).
+      for (const v of verdicts) {
+        try {
+          await appendResponseEvent(
+            job.cwd || null,
+            epicId,
+            `Validation ${v.verdict.toUpperCase()}: ${v.slug}${v.reason ? ` — ${v.reason}` : ''}`,
+            { prdSlug: v.slug, outcome: 'completed', validation: v.verdict },
+          );
+        } catch (e) {
+          console.error('[scheduler] notifyOriginatingTab verdict appendResponseEvent error', job?.slug, v.slug, e);
+        }
+      }
       // PRD 986: the check-in event is born validation:'unvalidated' — never
       // 'verified' — regardless of the job's self-reported outcome. The
       // check-in is a request to validate, not an assertion of done.
@@ -4348,20 +4467,40 @@ async function notifyOriginatingTab(job, {
         // happened above). All gating (kill-switch SM_EPIC_VALIDATION_DISABLE,
         // active-Epic check, once-per-(epicId, prdSlug), loop guard, slot-pool
         // routing) lives in lib/epicValidationHook.cjs.
-        try {
-          enqueueValidation(
-            {
-              cwd: job.cwd || null,
-              epicId,
-              prdSlug: job.slug,
-              prdPath: prd?.path || archivedPrdPathForJob(job) || null,
-              outcome: job.status,
-              eventValidation: 'unvalidated',
-            },
-            { sendPrompt },
-          );
-        } catch (e) {
-          console.error('[scheduler] notifyOriginatingTab enqueueValidation error', job?.slug, e);
+        //
+        // PRD 1407: a validator job's own check-in never enqueues a
+        // validation prompt for itself — it IS the plan's validation pass,
+        // not a work-item awaiting one.
+        //
+        // PRD 1408: nor does an ordinary work-item whose plan already ends in
+        // a trailing validator job depending on it — that validator's own
+        // check-in (above) is the single validation pass for the whole plan,
+        // so a per-PRD prompt here would be a second, redundant ask into the
+        // same (Opus/Fable-tier) authoring session.
+        if (job.agentType !== 'validator') {
+          let skipForDownstreamValidator = false;
+          try {
+            skipForDownstreamValidator = hasDownstreamValidator(job, await loadJobs());
+          } catch (e) {
+            console.error('[scheduler] notifyOriginatingTab loadJobs error', job?.slug, e);
+          }
+          if (!skipForDownstreamValidator) {
+            try {
+              enqueueValidation(
+                {
+                  cwd: job.cwd || null,
+                  epicId,
+                  prdSlug: job.slug,
+                  prdPath: prd?.path || archivedPrdPathForJob(job) || null,
+                  outcome: job.status,
+                  eventValidation: 'unvalidated',
+                },
+                { sendPrompt },
+              );
+            } catch (e) {
+              console.error('[scheduler] notifyOriginatingTab enqueueValidation error', job?.slug, e);
+            }
+          }
         }
         return;
       }
@@ -5337,7 +5476,7 @@ function pickRunDir() {
  * Watchdogs are declared as an array; the result-tailer's exit-code mapping
  * (success+killedBySignal → 0) is scheduler-specific and lives in onExit.
  */
-async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget = null, foreignWip = null, launchEnv = null, onPhase = null) {
+async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget = null, foreignWip = null, launchEnv = null, onPhase = null, reviewInRun = true) {
   // First statement — stamps the 'exec-entered' dispatch-phase breadcrumb
   // before openLog below, so a hang inside openLog/spawn itself still shows
   // execution reached this function (see spawnJob's dispatchPhase comment).
@@ -5523,7 +5662,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
   // Always route through composeExecutorPrompt (even with an empty digest)
   // so the finish protocol is appended in the prompt's tail exactly once,
   // after any digest fence rather than concatenated ahead of it.
-  prompt = composeExecutorPrompt({ prdBody: prompt, digestText, finishProtocol: FINISH_PROTOCOL });
+  prompt = composeExecutorPrompt({ prdBody: prompt, digestText, finishProtocol: buildFinishProtocol({ reviewInRun }) });
 
   // Foreign-WIP manifest (starry-night-ships PRD 148 postmortem): the
   // scheduler already knows, at spawn time, which dirty paths this job did
@@ -6744,7 +6883,15 @@ function guardedTick(fn, label) {
   }
 }
 
-async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
+async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, siblingJobs = null) {
+  // PRD 1408: the queue rows in scope at dispatch (tickQueue's own
+  // state.jobs, threaded straight down — never re-read here or inside
+  // executeJob) decide whether this job's own finish protocol still needs to
+  // run /code-review + /security-review inline, or can defer to a downstream
+  // `validator` job that will re-review this diff once the plan finishes.
+  // A caller with no rows in scope (spawnResumeRecovery) reads them itself,
+  // once, before delegating to spawnJob — still never inside executeJob.
+  const reviewInRun = !hasDownstreamValidator(job, siblingJobs || []);
   // Session-Manager owns the machine-wide `claude -p` pool (sessionSlots.cjs)
   // — the scheduler REQUESTS capacity, it doesn't own a private cap. A miss
   // leaves the job pending; the next tick retries when a slot frees up.
@@ -7116,7 +7263,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
             s.jobs[idx].dispatchPhaseAt = new Date().toISOString();
           }
         });
-      });
+      }, reviewInRun);
     } finally {
       if (worktree.ok) {
         ({ worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths } =
@@ -7506,10 +7653,17 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     let mechanicalRecoveryTarget = null;
     let terminalNotifySnapshot = null;
     const newlyCompletedPrds = [];
+    // PRD 1408: captured inside the mutate() below (the one in-memory read of
+    // `s.jobs` this finalize pass already does) so notifyOriginatingTab's own
+    // hasDownstreamValidator check can reuse it instead of a second, redundant
+    // readQueue() — that call federates queue.json shards across every known
+    // project cwd on the machine, not just this job's own project.
+    let jobsSnapshotForNotify = null;
     // Base HEAD for the mechanical-recovery futility check — read here, never inside mutate() (no I/O).
     const finalizeHeadSha = worktreeIntegrationDetail && worktreeIntegrationDetail.failureKind === 'content_conflict'
       ? await gitHead(guardCwd) : null;
     await mutate((s) => {
+      jobsSnapshotForNotify = s.jobs.slice();
       const i2 = s.jobs.findIndex((x) => x.slug === job.slug);
       // A job already moved off 'running' by someone else (namely
       // remote.cancelJob, PRD 1024 — it SIGTERMs the process then finalizes
@@ -7923,7 +8077,9 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     });
 
     if (terminalNotifySnapshot) {
-      notifyOriginatingTab(terminalNotifySnapshot).catch((e) => {
+      notifyOriginatingTab(terminalNotifySnapshot, {
+        loadJobs: async () => jobsSnapshotForNotify || [],
+      }).catch((e) => {
         console.error('[scheduler] notifyOriginatingTab error', job.slug, e);
       });
     }
@@ -8151,7 +8307,11 @@ async function reclaimTerminalJobOrphansThrottled(state) {
  */
 async function spawnResumeRecovery(job, resumeTarget) {
   const { runId, dir: runDir } = pickRunDir();
-  await spawnJob(job, runId, runDir, job.cwd || DEFAULT_PROJECT_CWD, resumeTarget);
+  // No queue rows in scope here (unlike tickQueue's own dispatch loop) — read
+  // once, before delegating to spawnJob, so hasDownstreamValidator still
+  // never runs inside executeJob itself.
+  const siblingJobs = (await readQueue().catch(() => ({ jobs: [] }))).jobs || [];
+  await spawnJob(job, runId, runDir, job.cwd || DEFAULT_PROJECT_CWD, resumeTarget, siblingJobs);
 }
 
 // Serialized ticker: prevents two concurrent tickQueue() calls from racing
@@ -8411,7 +8571,10 @@ async function tickBody(gen, { bypassLoadGate }) {
     for (const job of gatedBatch) {
       if (cancelToken.cancelled || stale()) break;
       // spawnJob is fire-and-forget; it calls tickQueue() on completion.
-      spawnJob(job, runId, runDir, state.config.defaultCwd).catch((e) => reportSchedulerError('spawnJob dispatch rejected', job.slug, e));
+      // state.jobs is the queue's rows in scope at THIS dispatch (PRD 1408) —
+      // threaded straight through so spawnJob's hasDownstreamValidator check
+      // never re-reads the queue itself.
+      spawnJob(job, runId, runDir, state.config.defaultCwd, null, state.jobs).catch((e) => reportSchedulerError('spawnJob dispatch rejected', job.slug, e));
     }
     return recordTick({ fired: true, count: gatedBatch.length, group: gatedBatch[0]?.parallelGroup }, { holds });
   }
@@ -8854,7 +9017,24 @@ async function runQueueStarvationWatchdog(state, {
   // A forced tick is machine-wide by construction (the picker considers
   // every project's rows) — one call here services every starved cwd found
   // this pass, not one call per cwd.
-  await tickQueue({ bypassLoadGate: false }).catch((e) => console.error('[scheduler] starvation tick error', e));
+  //
+  // bypassLoadGate: TRUE. The watchdog only reaches here on a 'starved'
+  // verdict: pending + dispatchable rows, ZERO running, idle >= 10 min. That
+  // is exactly the state where the CPU load gate (scheduler.cjs's INNERMOST
+  // launch predicate) is a false positive — a box whose loadavg is high while
+  // *this* scheduler runs nothing is being loaded by something else, and the
+  // load gate would then hold the last-resort tick behind the very saturation
+  // it can't influence, freezing the queue for hours (observed 2026-09-23:
+  // 3 dispatchable, 0 running, lastTickReason 'load-deferred' unbroken from
+  // 07:00→13:06). The gate is advisory headroom ("leave one core free"), not
+  // a resource guard; starting ONE batch cannot OOM the host. The slot pool
+  // and memory gate — which DO guard real exhaustion — are unaffected by this
+  // flag and still bound the batch. The watchdog is the automated equivalent
+  // of a human Run-now, the other caller that legitimately bypasses load
+  // (§2/§3, scheduler-operations.md). Latched to one forced tick per
+  // QUEUE_STARVATION_MS per cwd, so this cannot thrash. Routed via
+  // module.exports so tests can assert the bypass without driving real load.
+  await module.exports.tickQueue({ bypassLoadGate: true }).catch((e) => console.error('[scheduler] starvation tick error', e));
   return primary;
 }
 
@@ -12690,6 +12870,9 @@ module.exports = {
   shouldEscalateFailureStreak,
   restoreFailureStreakWarnedAt,
   persistedStreakMinutes,
+  loadSchedulerState,
+  persistSchedulerState,
+  getSchedulerStateSnapshot,
   computeDegradedBudget,
   healRefusalReason,
   writeQueue,
@@ -12701,6 +12884,7 @@ module.exports = {
   parsePorcelain,
   parsePorcelainEntries,
   FINISH_PROTOCOL,
+  buildFinishProtocol,
   IDLE_OUTPUT_KILL_MS,
   BASH_DEFAULT_TIMEOUT_MS,
   BASH_MAX_TIMEOUT_MS,

package/src/main/seedAgentPersonas.cjs

@@ -39,7 +39,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { writeJsonSync } = require('./config.cjs');
 
-const PERSONAS = ['architect', 'dev-lead', 'project-home-builder'];
+const PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator'];
 // What `{ done: true }` (the pre-seeded-set marker format) meant: only these two personas existed
 // in PERSONAS at the time. Fixed, not derived from the current PERSONAS array above — otherwise
 // every future persona added to PERSONAS would retroactively count as already delivered to a

package/src/main/sessionsStore.cjs

@@ -2,7 +2,7 @@
  * SessionsStore — persists the renderer's tab list to disk so the app can
  * restore tabs + resume claude sessions after an electron restart.
  *
- * Storage: ~/.config/session-manager/tabs.json
+ * Storage: ~/.claude/session-manager/tabs.json
  * Shape: { tabs: PersistedTab[], activeTabId: string | null, savedAt: number }
  *
  * Only serializable, durable fields are persisted: id, sessionId, cwd,
@@ -17,8 +17,14 @@ const os = require('node:os');
 const { ipcMain } = require('electron');
 const config = require('./config.cjs');
 
+let migrated = false;
 function storePath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'tabs.json');
+  const p = path.join(os.homedir(), '.claude', 'session-manager', 'tabs.json');
+  if (!migrated) {
+    migrated = true;
+    config.migrateLegacyHomeFile(path.join(os.homedir(), '.config', 'session-manager', 'tabs.json'), p);
+  }
+  return p;
 }
 
 async function load() {

package/src/main/supervisor.cjs

@@ -18,11 +18,11 @@ const { spawn, execFileSync } = require('node:child_process');
 const { ipcMain } = require('electron');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
 const { withProcRole } = require('./lib/cleanEnv.cjs');
+const schedulerPaths = require('./lib/schedulerPaths.cjs');
 
 const HOME = os.homedir();
 const SUPERVISOR_LOG_PATH = path.join(HOME, '.claude', 'session-manager', 'supervisor.log');
 const SUPERVISOR_LOG_MAX_BYTES = 1024 * 1024;
-const RUNS_DIR = path.join(HOME, '.claude', 'session-manager', 'scheduled-plans', 'runs');
 
 // In-flight probe slugs — prevents duplicate probes across ticks.
 const inFlightProbes = new Set();
@@ -371,7 +371,7 @@ async function probeJob(job, lastActivityAge) {
     const startedAt = job.startedAt || new Date().toISOString();
     const ageMinutes = Math.floor((Date.now() - Date.parse(startedAt)) / 60_000);
     const runId = job.runtime?.runId;
-    const logPath = runId ? path.join(RUNS_DIR, runId, `${slug}.log`) : null;
+    const logPath = runId ? path.join(schedulerPaths.runsDir(), runId, `${slug}.log`) : null;
 
     const pstreeOutput = getPstree(jobPid);
     const childBashCmdlines = getChildBashCmdlines(jobPid);
@@ -426,7 +426,7 @@ async function supervisorTick() {
   for (const job of runningJobs) {
     if (inFlightProbes.has(job.slug)) continue;
     const runId = job.runtime?.runId;
-    const logPath = runId ? path.join(RUNS_DIR, runId, `${job.slug}.log`) : null;
+    const logPath = runId ? path.join(schedulerPaths.runsDir(), runId, `${job.slug}.log`) : null;
     if (!logPath) continue;
     const lastActivity = getLastActivityTs(logPath);
     const ageMs = Date.now() - lastActivity;

package/src/main/templates/PRD_AUTHORING.md

@@ -1,4 +1,4 @@
-<!-- PRD_AUTHORING.md v2 -->
+<!-- PRD_AUTHORING.md v3 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 This guide codifies lessons from two stuck-job incidents (fizzpop poll-hang, etch-engine post-AC overrun) into enforceable rules every PRD MUST follow. Violating these rules costs real money and wastes hours waiting at a terminal.
@@ -122,14 +122,14 @@ curl -sf https://bilko.run/projects/<slug>/ > /dev/null || { echo "SMOKE TEST FA
 
 ## §6 Frontmatter rules
 
-**Summary:** Required keys are `title`, `cwd` (absolute path), `estimateMinutes`. Default to letting the filename `NN-` prefix drive grouping; include `parallelGroup` ONLY when you are deliberately interleaving across project streams.
+**Summary:** Required keys are `title`, `cwd` (absolute path), `estimateMinutes`. Default to letting the filename `NN-` prefix drive grouping.
 
 **Required frontmatter:**
 ```yaml
 ---
 title: <one line, plain English>
 cwd: ~/Projects/<target-repo>
-estimateMinutes: 60
+estimateMinutes: 10
 ---
 ```
 
@@ -139,7 +139,7 @@ estimateMinutes: 60
 - `cwd` MUST point to the target project. Prefer `~/...` for portability; only use an absolute path if you have a specific reason to pin to one machine.
 - **`cwd` MUST already exist on disk at queue time.** The scheduler runs a dead-cwd guard (`fs.accessSync(cwd, fs.constants.X_OK)` in `src/main/scheduler.cjs:669-680`) *before* spawning the child, so a PRD whose `cwd` references a not-yet-created directory will exit with `-1: cwd no longer exists` and the body will never run — even if the first step of the body would have created the directory. If the PRD's purpose is to create a brand-new sibling project at `~/Projects/<new-slug>/`, point `cwd` at the parent (`~/Projects`) and make the first executable step `mkdir -p ~/Projects/<new-slug> && cd ~/Projects/<new-slug>`.
 - `estimateMinutes` is used for ETA display; include a realistic estimate (note: empirical median is ~10 min, p90 ~20 min — avoid wildly inflated estimates that hide real outliers).
-- `parallelGroup` in frontmatter, when present, IS honored by the scheduler (`pickNextBatch` reads `parallelGroup ?? 99` and overrides the filename NN). Use this only for cross-stream interleaving — e.g., the cellar series `122-`, `123-`, `124-` overrides to groups `113`, `114`, `115` so cellar steps fire alongside the parallel etch steps. Do NOT use it to reorder within a single stream; rename the file instead.
+- `parallelGroup` is DEPRECATED and ignored (PRD 832) — `dependsOn: [<slug>, …]` is the only ordering primitive; numbers are unique per project.
 
 ### `planId` (API-owned — never pass it)
 
@@ -168,11 +168,11 @@ Incident: sigma PRD `816-prepare-157-copy-citation-extras-patch` (2026-09-20) wr
 
 ---
 
-## §8 Scope sizing — target ~15 min, ceiling 30 (data-driven, 2026-06)
+## §8 Scope sizing — target ≤10 min, ceiling 15 (data-driven, 2026-09)
 
-**Summary:** One PRD ≈ **~15 wall-clock minutes** of work. Empirically (400+ runs) median real run = **~7 min**, p90 = **21 min**; authored estimates ran 5–8× too high. **If you project >30 min, SPLIT.**
+**Summary:** One PRD ≈ **≤10 wall-clock minutes** of work. Empirically (2026-09 calibration) wall p50 = **7.8 min**, 60% of runs ≤ 10 min; authored estimates ran 4× too high. **If you project >15 min, SPLIT.**
 
-**Rule:** Split larger work into sequential PRDs; reference the dependency in `# Implementation notes`. PRDs in the same `NN-` group run in parallel — don't put dependent work in the same group. e2e/publish work is the failure tail: **shard test suites to one spec per PRD; never run a full suite or an endpoint-polling publish in a single PRD** (§1/§5).
+**Rule:** Split larger work into sequential PRDs; reference the dependency in `# Implementation notes`. e2e/publish work is the failure tail: **shard test suites to one spec per PRD; never run a full suite or an endpoint-polling publish in a single PRD** (§1/§5).
 
 ---
 
@@ -202,9 +202,9 @@ Before queueing a new PRD, verify each of these:
 - [ ] **§3 Smoke tests + verify-before-done:** Every deploy/migration step is followed by a test command that exits 1 on failure. Run the AC test command once before declaring done; never end the run on a red test.
 - [ ] **§4 Bounded generators:** Any search/seed loop has an explicit `MAX_ATTEMPTS` constant and surfaces failure on exhaustion.
 - [ ] **§5 Render deploys:** Deploy waits use a live URL check, not uptime/restart signals.
-- [ ] **§6 Frontmatter:** `title`, `cwd` (`~/Projects/<name>` preferred; path MUST exist on this machine), `estimateMinutes` present. `parallelGroup` only if intentionally interleaving cross-stream.
+- [ ] **§6 Frontmatter:** `title`, `cwd` (`~/Projects/<name>` preferred; path MUST exist on this machine), `estimateMinutes` present. `parallelGroup` is deprecated — use `dependsOn` for ordering.
 - [ ] **§7 Self-contained:** No references to "the conversation" or external context. Paths and identifiers are inline. Body is clean UTF-8 — **no NUL/control bytes** (paste-from-PDF crashes the spawn). Quick check: `grep -qP '\x00' file && echo BAD`.
-- [ ] **§8 Scope:** Targets ~15 min, ceiling 30. If projected larger, split. e2e/publish sharded to one spec per PRD.
+- [ ] **§8 Scope:** Targets ≤10 min, ceiling 15. If projected larger, split. e2e/publish sharded to one spec per PRD.
 - [ ] **§9 Failure surfacing:** Errors exit 1 with a diagnostic line. No silent `|| true` swallows. (`rateLimited` exit-1 is benign auto-pause, not a failure.)
 - [ ] **§11 Negative-assertion checks:** Any "this should produce NO output / NO match" check (a `grep` that should find nothing, a "no leftover X" guard) is written as an inverted conditional that exits 0 on the clean case. A bare `grep` whose success is "no match" exits 1 and trips the verifier `transcript_errors` downgrade even when the run is perfect.
 - [ ] **§12 End green:** The acceptance/test gate is the LAST thing the run does; any intentionally-failing step (TDD red test, expected-nonzero probe) runs EARLY, never after the gate, and is captured (`2>&1 | tail` inside a conditional) so it doesn't surface as a bare `is_error`/`Traceback` in the final portion of the transcript.

package/src/main/voiceSettings.cjs

@@ -1,7 +1,7 @@
 /**
  * VoiceSettings — persists voice hotkey configuration to disk.
  *
- * Storage: ~/.config/session-manager/voice.json
+ * Storage: ~/.claude/session-manager/voice.json
  * Shape: {
  *   accelerator: string, mode: 'hold'|'toggle', global: boolean, schemaVersion: 1,
  *   // F5 device picker (optional, additive):
@@ -44,8 +44,14 @@ function defaultsForPlatform() {
   return { accelerator: 'Ctrl+Shift+Space', mode: 'hold', global: false, schemaVersion: SCHEMA_VERSION };
 }
 
+let migrated = false;
 function storePath() {
-  return path.join(os.homedir(), '.config', 'session-manager', 'voice.json');
+  const p = path.join(os.homedir(), '.claude', 'session-manager', 'voice.json');
+  if (!migrated) {
+    migrated = true;
+    config.migrateLegacyHomeFile(path.join(os.homedir(), '.config', 'session-manager', 'voice.json'), p);
+  }
+  return p;
 }
 
 // PRD F1 v2 §Chord schema. Anchored, requires ≥1 modifier so a bare

package/src/preload/api.d.ts

@@ -66,7 +66,7 @@ export interface ImportRef {
 /** Declared owner ids for the single-writer law over a project's
  *  session-manager-operations/ root. Mirrors OWNERS in
  *  src/main/lib/opsOwnership.cjs — one writer per namespace; everyone reads. */
-export type OpsWriter = 'epics' | 'scheduler' | 'project-home';
+export type OpsWriter = 'epics' | 'scheduler' | 'project-home' | 'ui-prefs';
 
 export interface WriteResult {
   ok: boolean;
@@ -340,7 +340,7 @@ export interface VoiceMarkWizardCompleteResult {
 /**
  * F8 — semantic turn-detection settings. MVP shape only; the actual
  * smart-turn-v3 ONNX model is not loaded in v1. Persisted at
- * ~/.config/session-manager/voice.json under `turnDetector`. See PRD F8 v2.
+ * ~/.claude/session-manager/voice.json under `turnDetector`. See PRD F8 v2.
  */
 export interface VoiceTurnDetectorState {
   enabled: boolean;
@@ -1944,7 +1944,7 @@ export interface SessionManagerAPI {
     /** Create a new memory entry with starter frontmatter + body. */
     create: (name: string, description?: string, workspace?: string) => Promise<MemoryMutationResult>;
     /** Aggregate workspace memories into semantic clusters. `refresh:true` fires a cost-gated `claude -p` pass; otherwise returns the cache only. */
-    aggregate: (workspace: string, refresh?: boolean) => Promise<MemoryAggregateResult>;
+    aggregate: (workspace: string, refresh?: boolean, cwd?: string) => Promise<MemoryAggregateResult>;
     /** Deterministic, zero-LLM-cost staleness report. `cwd` (optional) scopes the dead-repo-ref check. */
     stale: (workspace?: string, cwd?: string) => Promise<MemoryStaleResult>;
   };

package/src/preload/index.cjs

@@ -158,13 +158,13 @@ contextBridge.exposeInMainWorld('api', {
     getHotkeyConfig: () => ipcRenderer.invoke('voice:get-hotkey-config'),
     setHotkeyConfig: (cfg) => ipcRenderer.invoke('voice:set-hotkey', cfg),
     setRecording: (recording) => ipcRenderer.send('voice:set-recording', !!recording),
-    // F5 device picker prefs (~/.config/session-manager/voice.json `device` key).
+    // F5 device picker prefs (~/.claude/session-manager/voice.json `device` key).
     getDevicePref: () => ipcRenderer.invoke('voice:get-device-pref'),
     setDevicePref: (pref) => ipcRenderer.invoke('voice:set-device-pref', pref),
-    // F7 first-run wizard state (~/.config/session-manager/voice.json `wizard` key).
+    // F7 first-run wizard state (~/.claude/session-manager/voice.json `wizard` key).
     getWizardState: () => ipcRenderer.invoke('voice:wizard-state'),
     markWizardComplete: () => ipcRenderer.invoke('voice:wizard-complete'),
-    // F8 turn-detector settings (~/.config/session-manager/voice.json `turnDetector` key).
+    // F8 turn-detector settings (~/.claude/session-manager/voice.json `turnDetector` key).
     // MVP: settings persistence + kill switch only; no model is actually loaded in v1.
     getTurnDetector: () => ipcRenderer.invoke('voice:get-turn-detector'),
     setTurnDetector: (state) => ipcRenderer.invoke('voice:set-turn-detector', state),
@@ -315,8 +315,8 @@ contextBridge.exposeInMainWorld('api', {
       if (workspace) payload.workspace = workspace;
       return ipcRenderer.invoke('memory:create', payload);
     },
-    aggregate: (workspace, refresh) =>
-      ipcRenderer.invoke('memory:aggregate', refresh ? { workspace, refresh: true } : { workspace }),
+    aggregate: (workspace, refresh, cwd) =>
+      ipcRenderer.invoke('memory:aggregate', { workspace, ...(refresh ? { refresh: true } : {}), ...(cwd ? { cwd } : {}) }),
     stale: (workspace, cwd) =>
       ipcRenderer.invoke('memory:stale', { ...(workspace ? { workspace } : {}), ...(cwd ? { cwd } : {}) }),
   },