claude-code-session-manager 0.120.0 → 0.122.0

package/src/main/lib/scheduler/queueHistory.cjs

@@ -11,7 +11,8 @@
 // disk. appendHistory/readHistory own the actual fs I/O.
 
 const path = require('path');
-const fsp = require('fs').promises;
+const fs = require('fs');
+const fsp = fs.promises;
 const { HISTORY_RETENTION_MS } = require('./schedulerConfig.cjs');
 const { projectHistoryPath, stateCwds } = require('./queueStore.cjs');
 const { queueHistoryPath } = require('./schedulerPaths.cjs');
@@ -288,6 +289,47 @@ async function readHistoryFile(target, cap) {
   }
 }
 
+/**
+ * Sync bounded tail read of one history file: newest-first parsed rows, at
+ * most `maxRows` (clamped [1,500]) drawn from at most the last `maxBytes`
+ * bytes (default 1 MB). Missing/unreadable file -> []. Never throws.
+ */
+function readHistoryFileTailSync(target, { maxRows = 500, maxBytes = 1024 * 1024 } = {}) {
+  const cap = Math.max(1, Math.min(500, Math.floor(maxRows) || 500));
+  let fd;
+  try {
+    fd = fs.openSync(target, 'r');
+    const { size } = fs.fstatSync(fd);
+    if (size === 0) return [];
+    const length = Math.min(Math.max(1, maxBytes), size);
+    const start = size - length;
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, start);
+    let text = buf.toString('utf8');
+    if (start > 0) {
+      // Chunk may begin mid-line; drop the partial first fragment.
+      const firstNl = text.indexOf('\n');
+      text = firstNl === -1 ? '' : text.slice(firstNl + 1);
+    }
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean).slice(-cap);
+    const parsed = [];
+    for (const line of lines) {
+      try {
+        parsed.push(JSON.parse(line));
+      } catch {
+        // corrupt/partial line — skip
+      }
+    }
+    return parsed.reverse();
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+  }
+}
+
 // mtime-gated cache, same convention as scheduler/prdParser.cjs's dirCache —
 // repeated reconcile() calls between appends hit the cache instead of
 // re-reading/re-parsing a JSONL file that only grows over time.
@@ -467,6 +509,7 @@ module.exports = {
   appendHistory,
   slimHistoryRow,
   readHistory,
+  readHistoryFileTailSync,
   historyTerminalBySlug,
   completedSlugsForCwd,
 };

package/src/main/lib/scheduler/queueStore.cjs

@@ -11,7 +11,7 @@
  *   - Per-project history:    `<cwd>/session-manager-operations/scheduler/state/history.jsonl`
  *     (owned by queueHistory.cjs, path resolved here)
  *   - Machine runtime state:  `~/.claude/session-manager/scheduler-machine.json`
- *     (config, paused/rate-limit, scheduledFor, lastRunAt — these are
+ *     (config, paused/rate-limit, lastRunAt — these are
  *     Session-Manager runtime concerns, like the sessionSlots pool, not any
  *     one project's data. Run logs under scheduled-plans/runs/ stay
  *     machine-local for the same reason: they're execution artifacts of this
@@ -230,7 +230,6 @@ function bustCwdCache() {
 function shapeMachine(data) {
   return {
     config: data.config || {},
-    scheduledFor: data.scheduledFor ?? null,
     lastRunAt: data.lastRunAt ?? null,
     // Distinct from lastRunAt (stamped only when tickQueue actually launches a
     // job): this is stamped every time tickQueue gets far enough to evaluate
@@ -451,7 +450,7 @@ function shapeJobs(raw, file) {
 }
 
 /**
- * readMergedSync(opts?) → { config, jobs, scheduledFor, lastRunAt, paused,
+ * readMergedSync(opts?) → { config, jobs, lastRunAt, paused,
  * unreadable?, unreadablePath?, unreadableCwds, sourceCwds }.
  *
  * `unreadable` is reserved for the machine-runtime file alone (a machine-wide
@@ -462,7 +461,7 @@ function shapeJobs(raw, file) {
  * writeSplit can persist "this project now has zero jobs".
  */
 function readMergedSync(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
+  const out = { config: {}, jobs: [], lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
   const sourceCwds = [];
   const machine = loadMachineStateSync();
   if (machine.shaped) {
@@ -496,7 +495,7 @@ function readMergedSync(opts) {
 
 /** Async twin of readMergedSync for IPC hot paths. */
 async function readMerged(opts) {
-  const out = { config: {}, jobs: [], scheduledFor: null, lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
+  const out = { config: {}, jobs: [], lastRunAt: null, lastDispatchAttemptAt: null, paused: null, drain: null, launchBlocks: {}, launchMitigations: {}, invalidJobs: [], unreadableCwds: [] };
   const sourceCwds = [];
   const machine = await loadMachineState();
   if (machine.shaped) {
@@ -547,7 +546,6 @@ function defineSources(state, sourceCwds) {
 async function writeSplit(state, defaultCwd) {
   await writeJsonAtomic(schedulerPaths.machineStatePath(), {
     config: state.config,
-    scheduledFor: state.scheduledFor ?? null,
     lastRunAt: state.lastRunAt ?? null,
     lastDispatchAttemptAt: state.lastDispatchAttemptAt ?? null,
     paused: state.paused ?? null,
@@ -581,70 +579,6 @@ async function writeSplit(state, defaultCwd) {
   bustCwdCache();
 }
 
-// ---------- legacy migration ----------
-
-/**
- * migrateLegacyGlobalQueue(defaultCwd) — one-time boot split of the retired
- * global queue.json into per-project shards. Shard rows win over legacy rows
- * with the same slug (the shard is newer by construction). The legacy file is
- * renamed to `queue.json.retired-<epoch>` so a rollback can recover it but no
- * reader ever consults it again. Machine fields (config/paused/...) migrate
- * only when no machine file exists yet. Idempotent: no legacy file → no-op.
- */
-async function migrateLegacyGlobalQueue(defaultCwd) {
-  let raw;
-  try {
-    raw = await fsp.readFile(schedulerPaths.legacyQueuePath(), 'utf8');
-  } catch {
-    return { migrated: false };
-  }
-  let legacy;
-  try {
-    legacy = JSON.parse(raw);
-  } catch (e) {
-    console.error(`[queueStore] legacy queue.json unparseable — leaving in place: ${e?.message}`);
-    return { migrated: false, error: e?.message };
-  }
-
-  if (!fs.existsSync(schedulerPaths.machineStatePath())) {
-    await writeJsonAtomic(schedulerPaths.machineStatePath(), {
-      config: legacy.config || {},
-      scheduledFor: legacy.scheduledFor ?? null,
-      lastRunAt: legacy.lastRunAt ?? null,
-      paused: legacy.paused ?? null,
-    });
-  }
-
-  const legacyJobs = Array.isArray(legacy.jobs) ? legacy.jobs : [];
-  const byCwd = new Map();
-  for (const job of legacyJobs) {
-    const cwd = job.cwd || defaultCwd;
-    if (!cwd) continue;
-    if (!byCwd.has(cwd)) byCwd.set(cwd, []);
-    byCwd.get(cwd).push(job);
-  }
-  let moved = 0;
-  for (const [cwd, jobs] of byCwd) {
-    const file = queuePathOrSkip(cwd, 'legacy split');
-    if (!file) continue;
-    let existing = [];
-    try { existing = shapeJobs(await fsp.readFile(file, 'utf8'), file).jobs; } catch { /* fresh shard */ }
-    const have = new Set(existing.map((j) => j.slug));
-    const merged = [...existing, ...jobs.filter((j) => !have.has(j.slug))];
-    try {
-      await writeJsonAtomic(file, { jobs: merged });
-      moved += merged.length - existing.length;
-    } catch (e) {
-      console.error(`[queueStore] legacy split: failed to write ${file}: ${e?.message}`);
-      return { migrated: false, error: e?.message };
-    }
-  }
-
-  await fsp.rename(schedulerPaths.legacyQueuePath(), `${schedulerPaths.legacyQueuePath()}.retired-${Date.now()}`);
-  bustCwdCache();
-  return { migrated: true, moved, projects: byCwd.size };
-}
-
 module.exports = {
   STATE_SUBPATH,
   projectStateDir,
@@ -656,7 +590,6 @@ module.exports = {
   readMerged,
   readMergedSync,
   writeSplit,
-  migrateLegacyGlobalQueue,
   writeJsonAtomic,
   writeJsonAtomicSync,
   findLongestValidJsonPrefix,
@@ -664,4 +597,3 @@ module.exports = {
 
 // Lazy path getters (SM_SCHEDULER_HOME resolved at read, never at require).
 Object.defineProperty(module.exports, 'MACHINE_STATE_PATH', { get: schedulerPaths.machineStatePath, enumerable: true });
-Object.defineProperty(module.exports, 'LEGACY_QUEUE_PATH', { get: schedulerPaths.legacyQueuePath, enumerable: true });

package/src/main/lib/scheduler/rcaReport.cjs

@@ -12,7 +12,7 @@
  * It used to file a `proposed` Epic per parked job; Epics are now created in
  * exactly one place — the human pressing New Epic (see epicMint.cjs's
  * SINGLE-CREATOR LAW). Surfacing the parked job back to a human is the
- * scheduler's job (notifyNeedsReview → appendResponseEventIfKnown), which
+ * scheduler's job (flushDueReviewNotices → appendResponseEventIfKnown), which
  * routes it into the Epic that AUTHORED the PRD rather than opening a
  * sibling Epic about it.
  *

package/src/main/lib/scheduler/refireCap.cjs

@@ -0,0 +1,40 @@
+/**
+ * refireCap.cjs — pure decision for a job the post-run verifier downgraded
+ * back to `pending` (verdict `halt` / `deps_unmet`).
+ *
+ * Why: scheduler.cjs re-fired such jobs with no counter, so any verifier
+ * disagreement re-ran a billed `claude -p` forever (Bilko-Launch-Kit,
+ * 2026-10-11: 125 runs, 846 turns, $28 in 3.5 hours). This helper decides,
+ * from the job's consecutive-downgrade count, whether to re-fire or park.
+ *
+ * Pure: no I/O, no mutation of inputs. Complexity O(1).
+ */
+
+'use strict';
+
+/** Max consecutive post-run downgrades that are still re-fired. */
+const MAX_CONSECUTIVE_VERIFY_REFIRES = 2;
+
+/**
+ * @param {{ verifyRefireCount?: unknown }} job
+ * @param {{ verdict?: string, reason?: string }} verifyResult
+ * @param {{ cap?: number }} [opts]
+ * @returns {{ action: 'refire', nextCount: number }
+ *   | { action: 'park', nextCount: number, verdict: 'refire_capped', reason: string }}
+ */
+function decideVerifyDowngrade(job, verifyResult, { cap = MAX_CONSECUTIVE_VERIFY_REFIRES } = {}) {
+  const raw = job && job.verifyRefireCount;
+  const count = Number.isInteger(raw) && raw > 0 ? raw : 0;
+  const nextCount = count + 1;
+  const effectiveCap = Math.max(0, cap);
+  if (nextCount <= effectiveCap) return { action: 'refire', nextCount };
+  const vr = verifyResult || {};
+  return {
+    action: 'park',
+    nextCount,
+    verdict: 'refire_capped',
+    reason: `re-fire cap: ${nextCount} consecutive post-run downgrades (${vr.verdict}: ${vr.reason})`,
+  };
+}
+
+module.exports = { MAX_CONSECUTIVE_VERIFY_REFIRES, decideVerifyDowngrade };

package/src/main/lib/scheduler/reviewNotice.cjs

@@ -5,7 +5,7 @@
  * 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
+ * immediately at park time, 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.

package/src/main/lib/scheduler/schedulerConfig.cjs

@@ -78,8 +78,7 @@ module.exports = {
   // this age is escalated: warn-logged naming project + slug + age, and
   // surfaced distinctly on Home (see homeNeedsYou.ts's matching constant)
   // so it cannot be stranded indefinitely with nothing looking at it — see
-  // findStaleQuarantinedJobs in scheduler.cjs. Overridable via
-  // SM_QUARANTINE_ESCALATE_HOURS for testing/tuning.
+  // findStaleQuarantinedJobs in scheduler.cjs.
   QUARANTINE_ESCALATE_MS: 24 * 60 * 60_000,
 
   // A project with pending work, nothing of its own running, and an oldest

package/src/main/lib/scheduler/schedulerPaths.cjs

@@ -104,7 +104,6 @@ function scheduledPlansRoot() { return assertNotLiveRoot(path.join(schedulerHome
 function runsDir() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'runs'), 'runsDir'); }
 function prdsRoot() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'prds'), 'prdsRoot'); }
 function machineStatePath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-machine.json'), 'machineStatePath'); }
-function legacyQueuePath() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'queue.json'), 'legacyQueuePath'); }
 function schedulerStatePath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-state.json'), 'schedulerStatePath'); }
 function heartbeatPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-heartbeat.log'), 'heartbeatPath'); }
 function sessionSlotsConfigPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'session-slots-config.json'), 'sessionSlotsConfigPath'); }
@@ -193,7 +192,6 @@ module.exports = {
   runsDir,
   prdsRoot,
   machineStatePath,
-  legacyQueuePath,
   schedulerStatePath,
   heartbeatPath,
   sessionSlotsConfigPath,

package/src/main/lib/scheduler/sessionSlots.cjs

@@ -32,7 +32,7 @@ const atomicFs = require('../util/atomicFs.cjs');
 const { isProvablyDead, DEFAULT_GRACE_MS } = require('./reservationExpiry.cjs');
 
 const MIN_SLOTS = 0;
-const MAX_SLOTS = 10;
+const MAX_SLOTS = 32;
 const DEFAULT_SLOTS = 5;
 
 

package/src/main/lib/telemetry/auditLog.cjs

@@ -7,8 +7,8 @@
  * state a project's single-writer law needs to arbitrate, and it must
  * survive even if the project's ops root doesn't exist yet.
  *
- * Rotation: on the first append in a new calendar month (UTC) the live file is
- * gzipped to audit-log-<YYYY-MM>.jsonl.gz beside it (YYYY-MM = the month of the
+ * Rotation: on the first append in a new calendar month (UTC), or once the live file passes
+ * 32 MB, the live file is renamed synchronously and then stream-gzipped (async) to audit-log-<YYYY-MM>.jsonl.gz beside it (YYYY-MM = the month of the
  * file's last write) and a fresh live file starts; the newest `auditLogMonths` rolled
  * files are kept. The live file stays plain JSONL, so readers are unaffected.
  *
@@ -23,6 +23,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const zlib = require('node:zlib');
+const { pipeline } = require('node:stream/promises');
 
 const { auditLogPath } = require('../scheduler/schedulerPaths.cjs');
 
@@ -55,23 +56,73 @@ const ROLLED_RE = /^audit-log-\d{4}-\d{2}\.jsonl\.gz$/;
 
 function monthKey(d) { return d.toISOString().slice(0, 7); }
 
-/** Roll the live file if its last write was in an earlier month than `now`; prune old rolls. */
-function rotateIfNewMonth(target, now) {
+const MAX_LIVE_BYTES = 32 * 1024 * 1024;
+let rollSeq = 0;
+const inflight = new Set(); // renamed files currently being compressed
+let chain = Promise.resolve();
+const settling = new Set(); // promises of in-progress compressions
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function pruneRolled(dir) {
+  const rolls = fs.readdirSync(dir).filter((f) => ROLLED_RE.test(f)).sort();
+  for (const f of rolls.slice(0, Math.max(0, rolls.length - maxRolled()))) {
+    try { fs.unlinkSync(path.join(dir, f)); } catch { /* best-effort */ }
+  }
+}
+
+/** Stream-gzip `pending` onto the month archive (append: members concatenate), then unlink it. */
+async function compressPending(pending, rolled, dir) {
+  let before = 0;
+  try { before = fs.statSync(rolled).size; } catch { /* new archive */ }
+  try {
+    await pipeline(fs.createReadStream(pending), zlib.createGzip(), fs.createWriteStream(rolled, { flags: 'a' }));
+  } catch (e) {
+    // Drop any partial gzip member so the archive stays valid; the pending file is kept for retry.
+    try { if (fs.existsSync(rolled)) fs.truncateSync(rolled, before); } catch { /* best-effort */ }
+    throw e;
+  }
+  fs.unlinkSync(pending);
+  try { pruneRolled(dir); } catch { /* best-effort */ }
+}
+
+function startCompress(pending, rolled, dir) {
+  if (inflight.has(pending)) return;
+  inflight.add(pending);
+  // Serialized: two members appended to one archive concurrently would interleave.
+  const p = chain.then(() => compressPending(pending, rolled, dir))
+    .catch((e) => { console.error('[auditLog] roll compress failed; will retry', e?.message ?? String(e)); })
+    .finally(() => { inflight.delete(pending); settling.delete(p); });
+  chain = p;
+  settling.add(p);
+}
+
+/** Resolves once every in-flight roll compression has finished (success or failure). Test seam. */
+async function settleRolls() {
+  while (settling.size) await Promise.all([...settling]);
+}
+
+/**
+ * Roll the live file if its last write was in an earlier month than `now`, or it
+ * exceeds `maxBytes`. The rename is synchronous; compression is async. Leftover
+ * renamed files from a failed compress are retried here.
+ */
+function rotateIfNeeded(target, now, maxBytes) {
   let st;
   try { st = fs.statSync(target); } catch { return; }
   if (!st.isFile() || st.size === 0) return;
   const oldMonth = monthKey(st.mtime);
-  if (oldMonth === monthKey(now)) return;
+  if (oldMonth === monthKey(now) && st.size <= maxBytes) return;
   const dir = path.dirname(target);
   const base = path.basename(target, path.extname(target));
-  const rolled = path.join(dir, `${base}-${oldMonth}.jsonl.gz`);
-  // appendFileSync: gzip members concatenate, so a pre-existing roll for that month is extended.
-  fs.appendFileSync(rolled, zlib.gzipSync(fs.readFileSync(target)));
-  fs.unlinkSync(target);
-  const rolls = fs.readdirSync(dir).filter((f) => ROLLED_RE.test(f)).sort();
-  for (const f of rolls.slice(0, Math.max(0, rolls.length - maxRolled()))) {
-    try { fs.unlinkSync(path.join(dir, f)); } catch { /* best-effort */ }
+  const pending = path.join(dir, `${base}-${oldMonth}.jsonl.rolling-${Date.now().toString(36)}${(rollSeq++).toString(36)}`);
+  fs.renameSync(target, pending);
+  const pendingRe = new RegExp(`^${escapeRe(base)}-(\\d{4}-\\d{2})\\.jsonl\\.rolling-[a-z0-9]+$`);
+  for (const f of fs.readdirSync(dir)) {
+    const m = pendingRe.exec(f);
+    if (m) startCompress(path.join(dir, f), path.join(dir, `${base}-${m[1]}.jsonl.gz`), dir);
   }
+  try { pruneRolled(dir); } catch { /* best-effort */ }
 }
 
 /**
@@ -92,7 +143,7 @@ function appendAuditEvent(kind, fields = {}, opts = {}) {
     const target = opts.target ?? auditLogPath();
     fs.mkdirSync(path.dirname(target), { recursive: true });
     try {
-      rotateIfNewMonth(target, now);
+      rotateIfNeeded(target, now, opts.maxBytes ?? MAX_LIVE_BYTES);
     } catch (e) {
       console.error('[auditLog] rotation failed', e?.message ?? String(e));
     }
@@ -127,4 +178,4 @@ function readTail(maxBytes, target = auditLogPath()) {
   }
 }
 
-module.exports = { appendAuditEvent, auditLogPath, readTail };
+module.exports = { appendAuditEvent, settleRolls, MAX_LIVE_BYTES, auditLogPath, readTail };

package/src/main/loopEfficiencyHandlers.cjs

@@ -0,0 +1,160 @@
+/**
+ * loopEfficiencyHandlers.cjs — `history:loop-efficiency` IPC. Gathers this
+ * usage week's run records + validator verdicts from the runs dir and feeds
+ * the pure calculator in lib/scheduler/loopEfficiency.cjs.
+ *
+ * Complexity O(runs in window); run logs are immutable after finalize, so
+ * validator verdicts are memoized per log path.
+ */
+
+'use strict';
+
+const fsp = require('fs/promises');
+const path = require('path');
+const { ipcMain } = require('electron');
+const { computeLoopEfficiency } = require('./lib/scheduler/loopEfficiency.cjs');
+const { parseValidationSentinels } = require('./lib/scheduler/validationSentinels.cjs');
+
+const WEEK_MS = 7 * 24 * 3600 * 1000;
+const LOG_TAIL_BYTES = 1024 * 1024;
+const USAGE_TIMEOUT_MS = 5000;
+const VALIDATOR_SLUG_RE = /(^|-)validate-/;
+
+/** @type {Map<string, Array<{ slug: string, verdict: string, reason: string }>>} */
+const validationMemo = new Map();
+
+/** `2026-10-23T01-26-37-026Z` -> epoch ms (NaN if not a run dir name). */
+function runIdToMs(runId) {
+  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/.exec(runId);
+  return m ? Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`) : NaN;
+}
+
+async function readJson(p) {
+  try { return JSON.parse(await fsp.readFile(p, 'utf8')); } catch { return null; }
+}
+
+/** Last 1 MB of a file as text ('' on failure). */
+async function readTail(p) {
+  let fh;
+  try {
+    fh = await fsp.open(p, 'r');
+    const { size } = await fh.stat();
+    const len = Math.min(size, LOG_TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    await fh.read(buf, 0, len, size - len);
+    return buf.toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fh) await fh.close().catch(() => {});
+  }
+}
+
+async function validationsForLog(logPath) {
+  const hit = validationMemo.get(logPath);
+  if (hit) return hit;
+  let out = [];
+  const tail = await readTail(logPath);
+  const lines = tail.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].includes('"type":"result"')) continue;
+    try {
+      const obj = JSON.parse(lines[i]);
+      if (typeof obj.result === 'string') out = parseValidationSentinels(obj.result);
+    } catch { /* torn line — treat as no verdicts */ }
+    break;
+  }
+  validationMemo.set(logPath, out);
+  return out;
+}
+
+/** Never throws; resolves null on any failure or after 5 s. */
+async function defaultUsage(fetchUsage) {
+  let timer;
+  try {
+    const fetchFn = fetchUsage || require('./usage.cjs').fetchUsage;
+    const r = await Promise.race([
+      fetchFn(),
+      new Promise((resolve) => { timer = setTimeout(() => resolve(null), USAGE_TIMEOUT_MS); }),
+    ]);
+    if (!r) return null;
+    // 'ok-stale' = last cached payload served while the API fails / rate-limits.
+    if (r.kind === 'ok' || r.kind === 'ok-stale') return r.data && r.data.usage ? r.data.usage : null;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * @param {{ runsRoot?: string, nowMs?: number, usage?: any }} [opts]
+ *   `usage` is the usage payload (`{ seven_day: { utilization, resets_at } }`) or null.
+ */
+async function gatherLoopEfficiency({ runsRoot, nowMs, usage } = {}) {
+  const root = runsRoot || require('./lib/scheduler/schedulerPaths.cjs').runsDir();
+  const now = typeof nowMs === 'number' ? nowMs : Date.now();
+
+  let fromMs = now - WEEK_MS;
+  let weeklyUtilizationPct = null;
+  const sd = usage && usage.seven_day;
+  if (sd && sd.resets_at && typeof sd.utilization === 'number') {
+    const reset = typeof sd.resets_at === 'number' ? sd.resets_at : Date.parse(sd.resets_at);
+    if (Number.isFinite(reset)) {
+      fromMs = reset - WEEK_MS;
+      weeklyUtilizationPct = sd.utilization;
+    }
+  }
+
+  const runs = [];
+  const validations = [];
+  let dirs = [];
+  try { dirs = await fsp.readdir(root); } catch { /* no runs dir */ }
+
+  for (const runId of dirs) {
+    const t = runIdToMs(runId);
+    if (!Number.isFinite(t) || t < fromMs) continue;
+    const runDir = path.join(root, runId);
+    let files;
+    try { files = await fsp.readdir(runDir); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.meta.json')) continue;
+      const meta = await readJson(path.join(runDir, f));
+      if (!meta || typeof meta !== 'object') continue;
+      // Slug comes from the filename, never meta content (no path traversal via meta.slug).
+      const slug = f.slice(0, -'.meta.json'.length);
+      const vd = await readJson(path.join(runDir, `${slug}.verdicts.json`));
+      const startedAtMs = typeof meta.startedAt === 'number' ? meta.startedAt : t;
+      const cwd = String(meta.cwd == null ? '' : meta.cwd);
+      runs.push({
+        cwd,
+        slug,
+        startedAtMs,
+        costUsd: meta.totalCostUsd,
+        verdict: vd && typeof vd.verdict === 'string' ? vd.verdict : null,
+      });
+      if (VALIDATOR_SLUG_RE.test(slug)) {
+        for (const v of await validationsForLog(path.join(runDir, `${slug}.log`))) {
+          validations.push({
+            cwd,
+            slug: v.slug,
+            verdict: v.verdict === 'verified' ? 'VERIFIED' : 'REFUTED',
+            atMs: startedAtMs,
+          });
+        }
+      }
+    }
+  }
+
+  return computeLoopEfficiency({ runs, validations, fromMs, toMs: now, weeklyUtilizationPct });
+}
+
+function registerLoopEfficiencyHandlers() {
+  ipcMain.handle('history:loop-efficiency', async () => {
+    const usage = await defaultUsage();
+    return gatherLoopEfficiency({ nowMs: Date.now(), usage });
+  });
+}
+
+module.exports = { gatherLoopEfficiency, registerLoopEfficiencyHandlers, defaultUsage };

package/src/main/queueOps.cjs

@@ -18,7 +18,8 @@
  *   - `^until ` at the start of a logical line  → fizzpop-style poll hang
  *   - `^while true` (case insensitive)          → unbounded while loop
  *   - `for .* in $(seq 1 [5-9][0-9][0-9]+)`     → unbounded large seq
- *   - missing frontmatter title / cwd / estimateMinutes
+ *   - missing frontmatter title / cwd (estimateMinutes is optional; if present
+ *     it must be a positive integer)
  *   - cwd doesn't exist on disk (fs.accessSync)
  *   - `--no-verify` or `--no-gpg-sign`          → hook-skip flags
  *
@@ -200,14 +201,8 @@ function lintParsed(slug, raw) {
       }
     }
   }
-  if (fm.estimateMinutes === undefined || !String(fm.estimateMinutes).trim()) {
-    findings.push({
-      rule: 'missing-estimate',
-      line: 1,
-      snippet: 'frontmatter "estimateMinutes" is required',
-      severity: 'warn',
-    });
-  } else {
+  // estimateMinutes is optional (budget.cjs floors a missing one); validate only when present.
+  if (fm.estimateMinutes !== undefined && String(fm.estimateMinutes).trim()) {
     const v = Number(fm.estimateMinutes);
     if (!Number.isInteger(v) || v <= 0) {
       findings.push({