claude-code-session-manager 0.94.0 → 0.96.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
@@ -955,7 +1000,11 @@ const DEFAULT_CONFIG = {
   // 'on-reset'        = fire offsetMinutes after the next 5h reset (legacy).
   // 'manual'          = only fire on explicit Run now click.
   firePolicy: 'when-available',
-  // For 'when-available'. Fire only when five_hour utilization < this percent.
+  // For 'when-available'. Fire only when BINDING-window utilization < this
+  // percent. Binding = the most-consumed unscoped window (five_hour OR weekly):
+  // dispatching into an exhausted weekly window would just produce 429s, so the
+  // gate holds on it — a hold that can last days, which is why it is surfaced
+  // loudly (utilizationHold snapshot field, heartbeat window name, health).
   utilizationThreshold: 90,
   schemaVersion: 1,
   supervisor: {
@@ -1509,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
@@ -1540,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);
@@ -1804,6 +1871,9 @@ function heartbeatTick(deps = {}) {
         quarantinedCwds: (s.unreadableCwds ?? []).map((u) => u.cwd),
         nextReset: cachedNextReset,
         utilization: cachedUtilization,
+        // Which window `utilization` (and nextReset) refer to — a reader of
+        // this log can't otherwise tell a 5h hold from a weekly one.
+        utilizationWindow: cachedBindingWindowName,
         consecutiveFailures,
         // State/consecutiveFailures/degraded-budget snapshot of the shared
         // usage-meter breaker, so a human reading only the heartbeat log can
@@ -3226,6 +3296,10 @@ async function reconcile(state) {
 
 let cachedNextReset = null; // bare ISO string or null
 let cachedUtilization = null; // binding-window utilization %, 0–100, or null if unknown
+let cachedBindingWindowName = null; // name/kind of the window cachedUtilization reads (e.g. 'five_hour', 'weekly_all')
+// Non-null while maybeLaunchWhenAvailable is holding the queue on the
+// utilization gate: { window, percent, threshold, resetsAt }. Snapshot-level.
+let utilizationHold = null;
 // ms timestamp of the last FRESH reset observation (see recordObservedReset)
 // — distinct from Date.now(), so persistSchedulerState never re-stamps a
 // stale cachedNextReset as "just observed" on every poll cycle.
@@ -3281,6 +3355,7 @@ function computeDegradedBudget() {
 function applyDegradedBudget() {
   const budget = computeDegradedBudget();
   cachedUtilization = budget.utilization;
+  cachedBindingWindowName = bindingWindow(lastGoodUsagePayload).name;
   degradedConcurrencyCapValue = budget.concurrencyCap;
   return budget;
 }
@@ -3290,8 +3365,15 @@ async function refreshNextReset() {
   const r = await billing.fetchUsage();
   if (r.kind !== 'ok') throw new Error(`usage fetch failed (${r.kind}): ${r.message ?? ''}`);
   const window = bindingWindow(r.data?.usage);
+  if (!Number.isFinite(window.utilization)) {
+    // Successful fetch with no readable percent = meter/contract problem, not a reading.
+    billing.usageCircuit.recordFailure('no_utilization');
+    throw new Error('usage fetch ok but payload yielded no finite utilization');
+  }
   recordObservedReset(window.resets_at ?? null);
-  cachedUtilization = Number.isFinite(window.utilization) ? window.utilization : cachedUtilization;
+  cachedUtilization = window.utilization;
+  cachedBindingWindowName = window.name;
+  lastGoodUsagePayload = r.data?.usage ?? lastGoodUsagePayload;
   return cachedNextReset;
 }
 
@@ -3606,6 +3688,8 @@ function buildScheduleStatePayload(state) {
     launchBlocks: state.launchBlocks ?? {},
     launchMitigations: state.launchMitigations ?? {},
     utilization: cachedUtilization,
+    utilizationWindow: cachedBindingWindowName,
+    utilizationHold,
     pollHealth: {
       lastPollAt,
       lastPollOk,
@@ -4259,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);
@@ -4290,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,
@@ -4304,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.
@@ -4327,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;
       }
@@ -5316,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).
@@ -5502,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
@@ -6723,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.
@@ -7095,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 } =
@@ -7485,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
@@ -7902,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);
       });
     }
@@ -8130,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
@@ -8390,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 });
   }
@@ -8449,12 +8633,20 @@ async function runDueJobs({ bypassLoadGate = false } = {}) {
 // ---------- when-available launch logic ----------
 
 async function maybeLaunchWhenAvailable(state) {
+  utilizationHold = null;
   if (state.config.firePolicy !== 'when-available') return;
   if (state.paused) return;
   const pending = state.jobs.filter((j) => j.status === 'pending' && !runningSet.has(j.slug));
   if (pending.length === 0) return;
   if (cachedUtilization === null || cachedUtilization === undefined) return;
   if (cachedUtilization >= state.config.utilizationThreshold) {
+    utilizationHold = {
+      window: cachedBindingWindowName,
+      percent: cachedUtilization,
+      threshold: state.config.utilizationThreshold,
+      resetsAt: cachedNextReset,
+    };
+    console.log(`[scheduler] when-available: utilization-held — ${cachedBindingWindowName ?? 'unknown'} window at ${cachedUtilization}% ≥ ${state.config.utilizationThreshold}%, resets ${cachedNextReset ?? 'unknown'}, ${pending.length} pending — holding, not ticking`);
     await broadcast();
     return;
   }
@@ -8825,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;
 }
 
@@ -9520,10 +9729,26 @@ async function pollLoop() {
 
     const r = await billing.fetchUsage();
 
+    if (r.kind === 'ok' && !Number.isFinite(bindingWindow(r.data?.usage).utilization)) {
+      // Successful fetch but no finite percent: a meter/contract problem, not a
+      // reading. Report it truthfully instead of leaving a stale number that
+      // looks live; carry the conservative degraded budget forward.
+      billing.usageCircuit.recordFailure('no_utilization');
+      applyDegradedBudget();
+      lastPollAt = Date.now();
+      lastPollOk = false;
+      persistSchedulerState();
+      const cur = await readQueue();
+      await maybeLaunchWhenAvailable(cur);
+      await broadcast();
+      return;
+    }
+
     if (r.kind === 'ok') {
       const window = bindingWindow(r.data?.usage);
       recordObservedReset(window.resets_at ?? null);
-      cachedUtilization = Number.isFinite(window.utilization) ? window.utilization : cachedUtilization;
+      cachedUtilization = window.utilization;
+      cachedBindingWindowName = window.name;
       lastGoodUsagePayload = r.data?.usage ?? lastGoodUsagePayload;
       degradedConcurrencyCapValue = null;
       consecutiveFailures = 0;
@@ -12645,6 +12870,9 @@ module.exports = {
   shouldEscalateFailureStreak,
   restoreFailureStreakWarnedAt,
   persistedStreakMinutes,
+  loadSchedulerState,
+  persistSchedulerState,
+  getSchedulerStateSnapshot,
   computeDegradedBudget,
   healRefusalReason,
   writeQueue,
@@ -12656,6 +12884,7 @@ module.exports = {
   parsePorcelain,
   parsePorcelainEntries,
   FINISH_PROTOCOL,
+  buildFinishProtocol,
   IDLE_OUTPUT_KILL_MS,
   BASH_DEFAULT_TIMEOUT_MS,
   BASH_MAX_TIMEOUT_MS,
@@ -12743,6 +12972,7 @@ module.exports = {
   FOREIGN_WIP_END_DELIMITER,
   TRANSIENT_RETRY_CAP,
   buildScheduleStatePayload,
+  refreshNextReset,
   partitionBootOrphans,
   applyOrphanOutcome,
   registerAdminRoutes,

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;