claude-code-session-manager 0.85.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/schedulerBatch.cjs

@@ -102,9 +102,20 @@ function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
     }
     return satisfiedBareSlugs.has(bareSlug(slug));
   };
+  // A dep row is blocking unless it's 'completed', OR it's a 'skipped' row
+  // stamped `needsReviewAutoResolvedSkip` — the bounded needs_review
+  // auto-resolve terminal decision (scheduler.cjs's
+  // applyNeedsReviewAutoResolve). That skip is deliberately NOT the
+  // "PRD source vanished, a human must author a fresh PRD" skip the
+  // heldBySkippedDep messaging above describes — it already got every
+  // bounded chance to resolve itself, so treating it as a permanent
+  // dependsOn block would defeat the whole point of that auto-resolve pass
+  // (a chain that never drains without an operator).
+  const isSatisfiedRow = (dep) => dep.status === 'completed'
+    || (dep.status === 'skipped' && dep.needsReviewAutoResolvedSkip === true);
   return (job.dependsOn ?? []).find((slug) => {
     const rows = rowsForDep(slug);
-    if (rows.length > 0) return rows.some((dep) => dep.status !== 'completed');
+    if (rows.length > 0) return rows.some((dep) => !isSatisfiedRow(dep));
     return !isKnownSatisfied(slug);
   });
 }

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.
@@ -81,6 +91,19 @@ module.exports = {
   // 1086). Escalation only — warn + audit, never dispatch.
   STARVATION_ESCALATE_MS: 45 * 60_000,
 
+  // A project still meeting findStarvedProjects' STARVED verdict past THIS
+  // (later) threshold gets a bounded, automated consequence beyond the
+  // repeating project_starved WARN above: a one-shot 'project_starve_escalated'
+  // audit event + a user-facing toast naming the project and the last tick's
+  // hold reason (scheduler.cjs's `lastTick`). Escalation only — never
+  // auto-resets, auto-cancels, or bypasses a gate; the queue's own state is
+  // untouched. The 2026-09-12 audit log showed /home/bilko/Projects/Bilko
+  // emit project_starved for 19h straight (ageMs 60.5M → 68.9M) with zero
+  // consequence and no toast — this is the fix. Latched per-cwd so the SAME
+  // starve stretch escalates exactly once; the latch resets the moment that
+  // cwd stops appearing in findStarvedProjects.
+  STARVE_ESCALATION_MS: 60 * 60_000,
+
   // A RUNNING job that has overrun its own PRD's `estimateMinutes` by this
   // factor is escalated. Distinct from MAX_JOB_DURATION_MS (4h), which is a
   // deadman kill: a 20-minute PRD still running at 3h is 9x over estimate but
@@ -96,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/telemetryBoot.cjs

@@ -38,8 +38,10 @@ function resolveDeps(deps = {}) {
  *     signal that also gates the machine-profile heartbeat below).
  *  3. install upsert — sent once via telemetryClient.reportInstall(profile)
  *     when telemetrySettings.isMachineReportDue() is true (a version bump, OR
- *     the 30-day liveness heartbeat), then lastMachineReportAt/Version are
- *     persisted so a same-version reboot within the window sends nothing.
+ *     the 30-day liveness heartbeat). lastMachineReportAt/Version are only
+ *     persisted when reportInstall() reports success — a failed/dropped
+ *     upsert stays due so the next boot retries, rather than being marked
+ *     done regardless of outcome.
  *     This lands in bilko.run's app_installs table (the sole source for
  *     every install-shaped number on the site). It replaces the former
  *     track('install.machine', profile) call, which duplicated the same
@@ -62,12 +64,13 @@ async function bootSequence({ now = Date.now(), appVersion, installChannel, deps
 
   if (telemetrySettings.isMachineReportDue(settings, { now, appVersion })) {
     const profile = await buildMachineProfile();
-    await telemetryClient.reportInstall(profile);
-    await telemetrySettings.save({
-      ...settings,
-      lastMachineReportAt: new Date(now).toISOString(),
-      lastMachineReportVersion: appVersion,
-    });
+    const reportResult = await telemetryClient.reportInstall(profile);
+    if (reportResult && reportResult.accepted) {
+      await telemetrySettings.save({
+        lastMachineReportAt: new Date(now).toISOString(),
+        lastMachineReportVersion: appVersion,
+      });
+    }
   }
 
   telemetryCounters.trackAppLaunch({ installChannel, appVersion });

package/src/main/lib/telemetryClient.cjs

@@ -91,8 +91,24 @@ const S = {
   lastError: null,
   lastFlushAt: null,
   lastFlushReason: null,
+  logger: null,
 };
 
+/**
+ * Best-effort warn logger for failures this module would otherwise swallow
+ * (e.g. reportInstall()'s bare catch). Lazily requires logs.cjs — which
+ * requires('electron') at module scope — so this stays a no-op under plain
+ * vitest with no Electron runtime, exactly like machineProfile.cjs's
+ * resolveElectronApp(). Injectable via _setLogger so tests can observe it
+ * without an Electron runtime.
+ */
+function logWarn(message, meta) {
+  try {
+    const fn = S.logger || require('../logs.cjs').writeLine;
+    fn({ scope: 'telemetry', level: 'warn', message, meta });
+  } catch { /* logs unavailable outside an Electron runtime */ }
+}
+
 /**
  * SM_TELEMETRY_SPOOL, when set, overrides the spool directory in place of
  * `~/.config/session-manager` — the explicit opt-in a test that genuinely
@@ -130,6 +146,18 @@ function getBeaconToken() {
   return process.env.SM_BEACON_KEY || FALLBACK_BEACON_KEY;
 }
 
+/**
+ * The wire-level `env` discriminator for the currently-running process,
+ * resolved from real signals (never from an appVersion string — see
+ * machineProfile.cjs's resolveEnv header comment for why that matters).
+ */
+function currentEnv() {
+  return machineProfile.resolveEnv({
+    isTestRunner: isTestEnvironment(),
+    installChannel: S.profile && S.profile.installChannel,
+  });
+}
+
 // ─── safe coercion helpers (never throw, regardless of input shape) ───────
 
 function safeObj(v) {
@@ -436,6 +464,7 @@ async function track(name, props) {
       props: meta,
       session_id: S.sessionId,
       visitor_id: S.settings.installId,
+      env: currentEnv(),
     };
     return await appendRecord('event', wire, recordId);
   } catch {
@@ -465,6 +494,7 @@ async function logLine(opts) {
       session_id: S.sessionId,
       fields: meta,
       ts: Date.now(),
+      env: currentEnv(),
     };
     return await appendRecord('log', wire, recordId);
   } catch {
@@ -501,6 +531,7 @@ async function reportError(opts) {
       session_id: S.sessionId,
       context: meta,
       ts: Date.now(),
+      env: currentEnv(),
     };
     return await appendRecord('error', wire, recordId);
   } catch {
@@ -527,6 +558,11 @@ function buildInstallWire(profile, installId) {
     // the numeric UTC offset (see machineProfile.cjs) — so that is what maps
     // onto the server's `timezone` column.
     timezone: safeStr(p.timezoneOffsetMinutes, 20),
+    // Resolved from this passed-in profile's own installChannel (never
+    // S.profile — reportInstall() is always given a freshly-built profile,
+    // not the module-singleton one) plus the current process's test-runner
+    // signal, same three-value contract as the other three channels.
+    env: machineProfile.resolveEnv({ isTestRunner: isTestEnvironment(), installChannel: p.installChannel }),
   };
 }
 
@@ -544,7 +580,8 @@ async function reportInstall(profile) {
     const recordId = crypto.randomUUID();
     const wire = buildInstallWire(profile, S.settings.installId);
     return await appendRecord('install', wire, recordId);
-  } catch {
+  } catch (e) {
+    logWarn('reportInstall failed', { error: e && e.message ? e.message : String(e) });
     return { accepted: false, reason: 'error' };
   }
 }
@@ -684,7 +721,7 @@ async function flushImpl(reason) {
     await persistSent();
 
     if (safeReason === 'daily' && result.failed.length === 0) {
-      S.settings = await telemetrySettings.save({ ...S.settings, lastDailyFlushAt: new Date().toISOString() });
+      S.settings = await telemetrySettings.save({ lastDailyFlushAt: new Date().toISOString() });
     }
   } catch { /* fail-inert */ }
   S.lastFlushAt = Date.now();
@@ -749,6 +786,10 @@ function _setMachineProfileBuilder(fn) {
   S.profileBuilder = typeof fn === 'function' ? fn : machineProfile.buildMachineProfile;
 }
 
+function _setLogger(fn) {
+  S.logger = typeof fn === 'function' ? fn : null;
+}
+
 module.exports = {
   track,
   logLine,
@@ -764,4 +805,5 @@ module.exports = {
   sentPath,
   _setFetchImpl,
   _setMachineProfileBuilder,
+  _setLogger,
 };

package/src/main/lib/telemetrySettings.cjs

@@ -78,11 +78,28 @@ function normalize(cfg) {
   };
 }
 
+/**
+ * Persists `patch` merged onto a FRESHLY-READ copy of the on-disk config —
+ * never onto a caller-held snapshot. Two independent modules (telemetryBoot's
+ * install-report stamp, telemetryClient's own daily-flush stamp) each keep
+ * their own in-memory copy of settings loaded at different times; if save()
+ * blindly wrote a caller's full snapshot, whichever call landed last would
+ * silently revert every field the OTHER caller had just written (a lost
+ * update — the root cause behind lastMachineReportAt never sticking). Calls
+ * are still serialized through the existing writeQueue chain, so the fresh
+ * read for call N+1 always observes call N's write.
+ */
 let writeQueue = Promise.resolve();
-async function save(cfg) {
-  if (!isValid(cfg)) throw new Error('Invalid telemetry config');
-  const next = normalize(cfg);
+async function save(patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('Invalid telemetry config');
+  for (const k of Object.keys(patch)) {
+    if (!KNOWN_KEYS.has(k)) throw new Error('Invalid telemetry config');
+  }
   const run = async () => {
+    const current = await readRaw();
+    const merged = { ...current, ...patch };
+    if (!isValid(merged)) throw new Error('Invalid telemetry config');
+    const next = normalize(merged);
     await config.writeTextAtomic(storePath(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
     return next;
   };

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/pty.cjs

@@ -109,6 +109,15 @@ class PtyManager {
     // renderer will re-register its data/exit listeners on the same IPC
     // channels. The data stream is live; pre-reattach output is lost, which
     // is acceptable for a dev reload.
+    //
+    // Telemetry: this branch deliberately does NOT call
+    // telemetryCounters.trackSessionOpen() (see below, after the real spawn).
+    // Tab = claudeSessionId is a 1:1 mapping (CLAUDE.md domain model) — a
+    // reattach is the SAME session process still running, not a new one, so
+    // counting it here would double-count every renderer reload and every
+    // switch back to an already-open Epic's Terminal pane within the same
+    // Electron process. `session.open` counts fresh PTY spawns only; see
+    // telemetry.md for the full rationale and its trade-off.
     const existing = this.sessions.get(tabId);
     if (existing) {
       console.log('[pty] reattach to existing session tabId=', tabId, 'pid=', existing.proc.pid);

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(),
   };
 }