claude-code-session-manager 0.86.0 → 0.87.0

package/src/main/lib/scheduleJobTransitions.cjs

@@ -32,6 +32,8 @@
 
 const { appendAuditEvent } = require('./auditLog.cjs');
 const telemetryCounters = require('./telemetryCounters.cjs');
+const queueHistory = require('./queueHistory.cjs');
+const { buildNeedsReviewEntryLine, buildNeedsReviewResolutionLine } = require('./needsReviewLedger.cjs');
 
 // A run genuinely finished when it leaves 'running' for one of these —
 // distinct from every other legal edge in LEGAL_TRANSITIONS (retries,
@@ -195,6 +197,37 @@ function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } =
     telemetryCounters.trackSchedulerJobFinish({ status: toStatus });
   }
 
+  // needs_review ledger (PRD: needs_review durability). This IS the single
+  // funnel every needs_review transition — entry or resolution — passes
+  // through (see this file's own header comment: transitionJob is the ONE
+  // place `status` is assigned), so hooking here, rather than any one of
+  // needs_review's several distinct entry call sites in scheduler.cjs,
+  // guarantees no path can bypass it.
+  //
+  // Fire-and-forget, exactly like every other best-effort side-channel write
+  // in this codebase (rcaReport.cjs, auditLog.cjs's own posture) — a ledger
+  // write failure must never fail or delay the transition it's recording.
+  if (toStatus === 'needs_review' && from !== 'needs_review') {
+    // ENTRY: stamp the episode's runId/enteredAt on the job itself so the
+    // RESOLUTION line (below) can reference the SAME runId even if the job's
+    // own `runId` is reassigned in between (e.g. a resume-recovery
+    // re-dispatch mints a fresh one before this episode resolves).
+    job.needsReviewEntryRunId = job.runId ?? null;
+    job.needsReviewEnteredAt = entry.at;
+    queueHistory.appendHistory([buildNeedsReviewEntryLine(job, entry)]).catch((e) => {
+      console.error('[scheduleJobTransitions] failed to append needs_review entry', e?.message ?? String(e));
+    });
+  } else if (from === 'needs_review' && toStatus !== 'needs_review') {
+    // RESOLUTION: read the episode stamped at entry, then clear it — the
+    // episode is over regardless of what this resolution line looks like.
+    const episode = { runId: job.needsReviewEntryRunId ?? null, enteredAt: job.needsReviewEnteredAt ?? null };
+    delete job.needsReviewEntryRunId;
+    delete job.needsReviewEnteredAt;
+    queueHistory.appendHistory([buildNeedsReviewResolutionLine(job, entry, episode)]).catch((e) => {
+      console.error('[scheduleJobTransitions] failed to append needs_review resolution', e?.message ?? String(e));
+    });
+  }
+
   return true;
 }
 

package/src/main/lib/schedulerConfig.cjs

@@ -56,6 +56,16 @@ module.exports = {
   // (pause/resume, job start/finish/reap/reset) bypass this via
   // broadcast({ flush: true }).
   BROADCAST_COALESCE_MS: 200,
+  // reconcile() pass duration above which a single warn-level breakdown is
+  // logged (per-phase ms, PRD file count, resolved dir count) — the only
+  // evidence trail for a slow pass otherwise requires hand-timing the scan
+  // from a throwaway script. Baseline measured 2026-09-13 on a machine with
+  // ~160 PRD dirs: allProjectCwds() ~270ms x5/pass, resolvePrdsDirs()
+  // ~430ms, historyTerminalBySlug() ~418ms over 784 entries — a healthy pass
+  // today is comfortably under 2s; this should trip well before a
+  // regression back toward those numbers compounds into the reported
+  // "schedule.state timed out after 5000ms" toast.
+  RECONCILE_SLOW_PASS_MS: 2_000,
   // Terminal (completed/failed) jobs older than this move from queue.json's
   // hot jobs[] into the append-only history.jsonl sidecar. See
   // src/main/lib/queueHistory.cjs.
@@ -109,6 +119,20 @@ module.exports = {
   // SM_JOB_OVERRUN_FLOOR_MINUTES.
   JOB_OVERRUN_FLOOR_MS: 45 * 60_000,
 
+  // Wall-clock KILL budget (distinct from JOB_OVERRUN_FACTOR/JOB_OVERRUN_FLOOR_MS
+  // above, which only ever ESCALATE — log + audit, deliberately never kill).
+  // This one ACTS: a RUNNING job past `budgetMs = clamp(estimateMinutes *
+  // JOB_BUDGET_FACTOR, JOB_BUDGET_FLOOR_MS, JOB_BUDGET_CEILING_MS)` is
+  // SIGTERMed and parked needs_review. Calibrated against 606 run-meta
+  // records since 2026-08-25: p50=13m, p90=60m, max=240m, against a
+  // concurrencyCap of 4 — two 4h outliers hold half the machine's dispatch
+  // capacity for an afternoon with nothing noticing or acting on it. Override
+  // with SM_JOB_BUDGET_FACTOR / SM_JOB_BUDGET_FLOOR_MINUTES /
+  // SM_JOB_BUDGET_CEILING_MINUTES.
+  JOB_BUDGET_FACTOR: 3,
+  JOB_BUDGET_FLOOR_MS: 45 * 60_000,
+  JOB_BUDGET_CEILING_MS: 180 * 60_000,
+
   // A 'running' row with no runtime.pid recorded (spawnJob's status:running
   // mutate at scheduler.cjs:~3524 landed, but the pid-bearing runtime={}
   // mutate that follows executeJob's spawn callback never did — the spawn

package/src/main/lib/usageCircuit.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * usageCircuit.cjs — a breaker over the /api/oauth/usage meter (PRD ss-02).
+ * Degraded mode is explicit, never a silent 0: repeated failures open the
+ * circuit with jittered backoff; degradedBudget() carries forward the last
+ * known-good BINDING window's utilization (never 0), pinning to 100 on a
+ * fresh executor-observed 429 and capping concurrency at 2. Pure Node.
+ */
+
+const FLOOR_MS = 30_000;
+const CAP_MS = 8 * 60 * 1000;
+
+/** Doubles from FLOOR_MS, capped at CAP_MS. 0/falsy prevMs starts at the floor. */
+function doubledBase(prevMs) {
+  return prevMs > 0 ? Math.min(prevMs * 2, CAP_MS) : FLOOR_MS;
+}
+
+/**
+ * Next backoff interval: doubles `prevMs` (floor FLOOR_MS, cap CAP_MS), then
+ * jitters by 0.5 + rand()*0.5 so concurrent instances don't retry in lockstep.
+ */
+function backoffWithJitter(prevMs) {
+  const base = doubledBase(prevMs);
+  return base * (0.5 + Math.random() * 0.5);
+}
+
+/**
+ * A cached reset timestamp is fresh only if it's strictly in the future
+ * relative to `now` — null/unparseable/at-or-before-now all read as stale,
+ * since a passed reset no longer describes a live window.
+ */
+function isResetFresh(iso, now) {
+  if (!iso) return false;
+  const resetMs = Date.parse(iso);
+  if (!Number.isFinite(resetMs)) return false;
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) return false;
+  return resetMs > nowMs;
+}
+
+/**
+ * Which window is actually binding dispatch. Prefers `payload.limits[]`'s
+ * `is_active` entry (the richer per-window shape); falls back to the flat
+ * `five_hour` field when `limits[]` is absent, matching usage.cjs's shape.
+ */
+function bindingWindow(payload) {
+  if (payload && Array.isArray(payload.limits) && payload.limits.length) {
+    const active = payload.limits.find((l) => l && l.is_active);
+    if (active) {
+      return {
+        name: active.type || active.name || 'unknown',
+        utilization: active.utilization,
+        resets_at: active.resets_at ?? null,
+      };
+    }
+  }
+  const fh = payload && payload.five_hour;
+  return {
+    name: 'five_hour',
+    utilization: fh ? fh.utilization : undefined,
+    resets_at: fh ? fh.resets_at : null,
+  };
+}
+
+/**
+ * Conservative budget to run on while the meter is down. utilization is
+ * carried forward from the last known-good BINDING window — never 0, which
+ * would read as "plenty of headroom" instead of "we don't know." A fresh
+ * executor-observed 429 (its own window not yet passed) pins utilization to
+ * 100 regardless of the stale cached value. concurrencyCap never exceeds 2.
+ */
+function degradedBudget(lastGoodPayload, executorEvidence = {}) {
+  const window = bindingWindow(lastGoodPayload);
+  let utilization = Number.isFinite(window.utilization) && window.utilization > 0
+    ? window.utilization
+    : 100;
+
+  const configuredCap = Number.isFinite(executorEvidence.configuredCap)
+    ? executorEvidence.configuredCap
+    : 2;
+  const concurrencyCap = Math.min(configuredCap, 2);
+
+  if (executorEvidence.observed429 && isResetFresh(executorEvidence.resetsAt, executorEvidence.now)) {
+    utilization = 100;
+  }
+
+  return { utilization, concurrencyCap };
+}
+
+/** Wraps `fn` so concurrent callers awaiting an in-flight call share one promise. */
+function singleFlight(fn) {
+  let inFlight = null;
+  return function singleFlightWrapped(...args) {
+    if (inFlight) return inFlight;
+    inFlight = Promise.resolve(fn(...args)).finally(() => { inFlight = null; });
+    return inFlight;
+  };
+}
+
+/**
+ * Breaker state machine over the meter: closed -> open after 3 consecutive
+ * failures; open allows exactly one probe per backoff interval (half_open);
+ * a successful probe closes the circuit and resets backoff, a failed probe
+ * reopens it with backoff doubled.
+ */
+function createUsageCircuit({ now = () => Date.now() } = {}) {
+  let consecutiveFailures = 0;
+  let currentState = 'closed';
+  let backoffBaseMs = 0;
+  let nextProbeAtMs = 0;
+  let probeInFlight = false;
+
+  function scheduleNextProbe() {
+    const intervalMs = backoffWithJitter(backoffBaseMs);
+    backoffBaseMs = doubledBase(backoffBaseMs);
+    nextProbeAtMs = now() + intervalMs;
+  }
+
+  function state() {
+    if (currentState === 'open' && !probeInFlight && now() >= nextProbeAtMs) {
+      currentState = 'half_open';
+      probeInFlight = true;
+    }
+    return currentState;
+  }
+
+  function recordFailure(kind) { // eslint-disable-line no-unused-vars
+    consecutiveFailures += 1;
+    if (currentState === 'half_open') {
+      probeInFlight = false;
+      currentState = 'open';
+      scheduleNextProbe();
+      return;
+    }
+    if (currentState === 'closed' && consecutiveFailures >= 3) {
+      currentState = 'open';
+      scheduleNextProbe();
+    }
+  }
+
+  function recordSuccess(payload) { // eslint-disable-line no-unused-vars
+    consecutiveFailures = 0;
+    probeInFlight = false;
+    backoffBaseMs = 0;
+    currentState = 'closed';
+  }
+
+  return { recordSuccess, recordFailure, state };
+}
+
+module.exports = {
+  createUsageCircuit,
+  backoffWithJitter,
+  isResetFresh,
+  bindingWindow,
+  degradedBudget,
+  singleFlight,
+};

package/{scripts → src/main}/lib/watchdogHelpers.cjs

@@ -362,7 +362,7 @@ function releaseLock(lockPath) {
  *  dependency fails inside maybeFinalizeHistory's try/catch, not at require
  *  time for the whole watchdog script. */
 function defaultFinalizeClosedDays(opts) {
-  const { finalizeClosedDays } = require('../../src/main/historyAggregator.cjs');
+  const { finalizeClosedDays } = require('../historyAggregator.cjs');
   return finalizeClosedDays(opts);
 }
 

package/src/main/scheduler/prdParser.cjs

@@ -119,10 +119,23 @@ async function parsePrdRaw(filePath) {
     // dependent follow-up PRD (scheduler-launch-as-persona) resolves this
     // into a launch decision, which this module does not do.
     agentType: fm.agentType || null,
+    // Wave-authoring decision (scheduler wave-disposition PRD): 'append' or
+    // 'new-head', set only when createPrd() actually had a disposition to
+    // record — see prdCreate.cjs/prdDisposition.cjs. Absent on every PRD
+    // authored before this field existed, and on any PRD that never needed
+    // the decision (first-ever PRD in its Epic, or one with its own explicit
+    // dependsOn).
+    disposition: (fm.disposition === 'append' || fm.disposition === 'new-head') ? fm.disposition : null,
     // Opt-in exclusive-lease flag (PRD 1107, quietMachineLease.cjs +
     // schedulerBatch.cjs's pickNextBatch). Only a literal `true` opts in —
     // matches prdFrontmatter.cjs's applyKey semantics for this field.
     quietMachine: fm.quietMachine === 'true',
+    // Explicit opt-out of the wall-clock budget kill (scheduler.cjs's budget
+    // watchdog) — only a literal `true` opts out, matching quietMachine's
+    // parse semantics above. quietMachine jobs are exempt regardless of this
+    // field; this is for a job that isn't quiet-machine-eligible but still
+    // needs no wall-clock kill ceiling.
+    budgetExempt: fm.budgetExempt === 'true',
     body: body.trim(),
   };
 }