claude-code-session-manager 0.85.0 → 0.87.0

package/src/main/lib/__tests__/prdDisposition.test.cjs

@@ -0,0 +1,224 @@
+/**
+ * prdDisposition.test.cjs — pure logic behind the scheduler wave-disposition
+ * PRD: does a new PRD wave extend an Epic's existing dependsOn chain
+ * ('append', gaining a dependsOn on the chain's current terminal PRD(s)) or
+ * start an independent, parallel-eligible root ('new-head')? And, after the
+ * fact, can a human safely rewrite that choice from the Scheduler UI?
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/prdDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+
+const {
+  isIncomplete,
+  resolveChainTerminals,
+  wouldCreateCycle,
+  computeDispositionRewrite,
+} = require('../prdDisposition.cjs');
+
+function row(overrides) {
+  return { slug: 'x', status: 'pending', dependsOn: [], ...overrides };
+}
+
+// ─────────────────────────────────────────── isIncomplete
+
+test('isIncomplete: completed is the only complete status', () => {
+  expect(isIncomplete('completed')).toBe(false);
+  for (const status of [null, undefined, 'pending', 'running', 'needs_review', 'failed', 'quarantined']) {
+    expect(isIncomplete(status)).toBe(true);
+  }
+});
+
+// ─────────────────────────────────────────── resolveChainTerminals
+
+test('resolveChainTerminals: a lone root is its own terminal', () => {
+  const rows = [row({ slug: 'a' })];
+  expect(resolveChainTerminals(rows)).toEqual(['a']);
+});
+
+test('resolveChainTerminals: a linear chain terminates at its tail', () => {
+  const rows = [
+    row({ slug: 'a' }),
+    row({ slug: 'b', dependsOn: ['a'] }),
+    row({ slug: 'c', dependsOn: ['b'] }),
+  ];
+  expect(resolveChainTerminals(rows)).toEqual(['c']);
+});
+
+test('resolveChainTerminals: a fork yields both leaves', () => {
+  const rows = [
+    row({ slug: 'a' }),
+    row({ slug: 'b', dependsOn: ['a'] }),
+    row({ slug: 'c', dependsOn: ['a'] }),
+  ];
+  expect(resolveChainTerminals(rows).sort()).toEqual(['b', 'c']);
+});
+
+test('resolveChainTerminals: two independent roots are both terminals (existing multi-head Epic)', () => {
+  const rows = [row({ slug: 'a' }), row({ slug: 'z' })];
+  expect(resolveChainTerminals(rows).sort()).toEqual(['a', 'z']);
+});
+
+test('resolveChainTerminals: a dependsOn cycle contributes no terminal', () => {
+  const rows = [
+    row({ slug: 'a', dependsOn: ['b'] }),
+    row({ slug: 'b', dependsOn: ['a'] }),
+  ];
+  expect(resolveChainTerminals(rows)).toEqual([]);
+});
+
+test('resolveChainTerminals: empty input yields no terminals', () => {
+  expect(resolveChainTerminals([])).toEqual([]);
+});
+
+// ─────────────────────────────────────────── wouldCreateCycle
+
+test('wouldCreateCycle: false for a fresh, unrelated edge', () => {
+  const rows = [row({ slug: 'a' }), row({ slug: 'b' })];
+  expect(wouldCreateCycle(rows, 'b', ['a'])).toBe(false);
+});
+
+test('wouldCreateCycle: true when the target already (transitively) depends on the source', () => {
+  // a depends on b; proposing b depends on a closes the loop.
+  const rows = [
+    row({ slug: 'a', dependsOn: ['b'] }),
+    row({ slug: 'b' }),
+  ];
+  expect(wouldCreateCycle(rows, 'b', ['a'])).toBe(true);
+});
+
+test('wouldCreateCycle: true for a direct self-reference', () => {
+  const rows = [row({ slug: 'a' })];
+  expect(wouldCreateCycle(rows, 'a', ['a'])).toBe(true);
+});
+
+test('wouldCreateCycle: false through an unrelated third row', () => {
+  const rows = [
+    row({ slug: 'a' }),
+    row({ slug: 'b', dependsOn: ['a'] }),
+    row({ slug: 'c' }),
+  ];
+  expect(wouldCreateCycle(rows, 'c', ['b'])).toBe(false);
+});
+
+// ─────────────────────────────────────────── computeDispositionRewrite
+
+test('append sets the expected edges', () => {
+  const rows = [
+    row({ slug: 'wave1-tail' }),
+    row({ slug: 'wave2-root' }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'wave2-root',
+    disposition: 'append',
+    dependsOn: ['wave1-tail'],
+    rows,
+  });
+  expect(result).toEqual({ ok: true, dependsOn: ['wave1-tail'] });
+});
+
+test('new-head sets none', () => {
+  const rows = [
+    row({ slug: 'wave1-tail' }),
+    row({ slug: 'wave2-root', dependsOn: ['wave1-tail'] }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'wave2-root',
+    disposition: 'new-head',
+    dependsOn: [],
+    rows,
+  });
+  expect(result).toEqual({ ok: true, dependsOn: [] });
+});
+
+test('promoting a wave to a head removes exactly its root edges', () => {
+  const rows = [
+    row({ slug: 'wave1-tail' }),
+    row({ slug: 'other-head' }),
+    row({ slug: 'wave2-root', dependsOn: ['wave1-tail'] }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'wave2-root',
+    disposition: 'new-head',
+    dependsOn: [],
+    rows,
+  });
+  expect(result.ok).toBe(true);
+  expect(result.dependsOn).toEqual([]);
+  // The unrelated head's own row is untouched — this function only ever
+  // returns the target row's new dependsOn, never mutates `rows`.
+  expect(rows.find((r) => r.slug === 'other-head').dependsOn).toEqual([]);
+});
+
+test('a change that would create a cycle is rejected', () => {
+  const rows = [
+    row({ slug: 'a', dependsOn: ['b'] }),
+    row({ slug: 'b' }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'b',
+    disposition: 'append',
+    dependsOn: ['a'],
+    rows,
+  });
+  expect(result.ok).toBe(false);
+  expect(result.error).toMatch(/cycle/i);
+});
+
+test('running rows are untouched', () => {
+  const rows = [
+    row({ slug: 'wave1-tail' }),
+    row({ slug: 'wave2-root', status: 'running', dependsOn: ['wave1-tail'] }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'wave2-root',
+    disposition: 'new-head',
+    dependsOn: [],
+    rows,
+  });
+  expect(result.ok).toBe(false);
+  expect(result.error).toMatch(/running/i);
+});
+
+test('completed rows are untouched', () => {
+  const rows = [
+    row({ slug: 'wave1-tail' }),
+    row({ slug: 'wave2-root', status: 'completed', dependsOn: ['wave1-tail'] }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'wave2-root',
+    disposition: 'append',
+    dependsOn: ['wave1-tail'],
+    rows,
+  });
+  expect(result.ok).toBe(false);
+  expect(result.error).toMatch(/completed/i);
+});
+
+test('refuses to rewrite a row whose existing blocker has already completed', () => {
+  const rows = [
+    row({ slug: 'blocker', status: 'completed' }),
+    row({ slug: 'dependent', status: 'pending', dependsOn: ['blocker'] }),
+  ];
+  const result = computeDispositionRewrite({
+    slug: 'dependent',
+    disposition: 'new-head',
+    dependsOn: [],
+    rows,
+  });
+  expect(result.ok).toBe(false);
+  expect(result.error).toMatch(/already completed|satisfied/i);
+});
+
+test('unknown slug is refused, not silently ignored', () => {
+  const result = computeDispositionRewrite({
+    slug: 'ghost',
+    disposition: 'new-head',
+    dependsOn: [],
+    rows: [row({ slug: 'a' })],
+  });
+  expect(result.ok).toBe(false);
+});

package/src/main/lib/__tests__/reaperHelpers.test.cjs

@@ -23,7 +23,8 @@ const { spawn } = require('node:child_process');
 const {
   selectReapableJobs, mapOutcomeToGateOutcome, classifyRunOutcome,
   findLiveProcessForJob, logHasOutput, resolvePidlessGateOutcome,
-  isAlreadySatisfiedOnMain,
+  isAlreadySatisfiedOnMain, resolvePidlessFailureOverride,
+  readSpawnedPidFromLog, isLogFresh,
 } = require('../reaperHelpers.cjs');
 const { detectRateLimitInLog } = require('../rateLimitDetect.cjs');
 
@@ -339,6 +340,28 @@ test('findLiveProcessForJob: no live process anywhere → null', () => {
   assert.strictEqual(pid, null);
 });
 
+// findLiveProcessForJob: runCwd — the 2026-09-13 in-place/shared-tree fix.
+// A run with no dedicated worktree (no worktreeDir) and no slug in argv
+// (dispatch never puts it there) is invisible to both existing matches; the
+// runCwd+cmdline-claude combo match exists for exactly this shape. `sleep`
+// is used as the /proc-visible process here (not a real `claude` binary), so
+// this exercises the cwd-plus-cmdline-substring code path directly rather
+// than depending on a real claude binary being installed.
+test('findLiveProcessForJob: runCwd match requires BOTH cwd AND a claude-looking cmdline — bare cwd match is never sufficient', async () => {
+  if (process.platform !== 'linux' || !fs.existsSync('/proc')) return;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reaper-runcwd-'));
+  // Runs in `dir` but its cmdline has no "claude" in it — must NOT match.
+  const child = spawn('sleep', ['5'], { cwd: dir, stdio: 'ignore' });
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    const pid = findLiveProcessForJob({ slug: 'unrelated-slug' }, { runCwd: dir });
+    assert.strictEqual(pid, null, 'a bare cwd match without a claude-looking cmdline must never match — shared-tree cross-match hazard');
+  } finally {
+    child.kill('SIGKILL');
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 // logHasOutput — the literal "did the run dir produce any log output" check
 // that gates whether a pidless reap may assert gateOutcome: 'never_ran'.
 
@@ -397,3 +420,158 @@ test('isAlreadySatisfiedOnMain: no satisfying commits → null — the gate must
   assert.strictEqual(isAlreadySatisfiedOnMain(null), null);
   assert.strictEqual(isAlreadySatisfiedOnMain(undefined), null);
 });
+
+// resolvePidlessFailureOverride — PRD 1173. A pidless reap must never stamp
+// 'failed' on a row that already carries proof (landedCommit) that its work
+// shipped, purely because reproting bookkeeping (runtime.pid) was lost.
+
+test('resolvePidlessFailureOverride: row with a landedCommit → override naming the recorded commit sha', () => {
+  const override = resolvePidlessFailureOverride({ slug: 'shipped-but-pidless', landedCommit: 'f3e35a7f9e49f13a9eb8c338b0d086160e32a87f' });
+  assert.ok(override, 'a row with landedCommit must produce a failure override');
+  assert.strictEqual(override.verdict, 'pidless_reap_with_landed_commit');
+  assert.strictEqual(override.landedCommit, 'f3e35a7f9e49f13a9eb8c338b0d086160e32a87f');
+  assert.match(override.reason, /f3e35a7f9e49f13a9eb8c338b0d086160e32a87f/, 'the reason string must name the recorded commit sha so a human can go straight to `git show <sha>`');
+});
+
+test('resolvePidlessFailureOverride: row with no landedCommit → null, existing failed transition untouched', () => {
+  assert.strictEqual(resolvePidlessFailureOverride({ slug: 'genuinely-never-ran' }), null);
+  assert.strictEqual(resolvePidlessFailureOverride({ slug: 'genuinely-never-ran', landedCommit: null }), null);
+  assert.strictEqual(resolvePidlessFailureOverride({ slug: 'genuinely-never-ran', landedCommit: '' }), null);
+});
+
+// readSpawnedPidFromLog — recovers the pid a pidless row's spawn actually
+// produced from the run's own log (2026-09-13 incident: runId
+// 2026-09-13T16-15-56-818Z spawned pid=3138458, logged it, but the
+// runtime.pid persistence mutate failed silently and the pidless-grace
+// reaper terminalized a live job it could have found here).
+
+test('readSpawnedPidFromLog: parses the scheduler\'s own spawned-pid line', () => {
+  const p = writeTmpLog('some preamble\n[scheduler] spawned pid=3138458 sessionId=345ca5b1-c7a7-4167-9b55-f4905e3afe01 (process group)\n\nmore output\n');
+  assert.strictEqual(readSpawnedPidFromLog(p), 3138458);
+});
+
+test('readSpawnedPidFromLog: missing file → null', () => {
+  assert.strictEqual(readSpawnedPidFromLog('/nonexistent/path/does-not-exist.log'), null);
+});
+
+test('readSpawnedPidFromLog: empty file → null', () => {
+  const p = writeTmpLog('');
+  assert.strictEqual(readSpawnedPidFromLog(p), null);
+});
+
+test('readSpawnedPidFromLog: log with no spawned-pid line → null', () => {
+  const p = writeTmpLog('{"type":"result","subtype":"success","is_error":false,"result":"done"}\n');
+  assert.strictEqual(readSpawnedPidFromLog(p), null);
+});
+
+test('readSpawnedPidFromLog: null path → null', () => {
+  assert.strictEqual(readSpawnedPidFromLog(null), null);
+});
+
+// isLogFresh — pure predicate: a log modified within the window is positive
+// proof of life, independent of runtime.pid bookkeeping.
+
+test('isLogFresh: mtime within window → true', () => {
+  assert.strictEqual(isLogFresh(NOW - 60_000, NOW, 20 * 60_000), true);
+});
+
+test('isLogFresh: mtime outside window → false', () => {
+  assert.strictEqual(isLogFresh(NOW - 30 * 60_000, NOW, 20 * 60_000), false);
+});
+
+test('isLogFresh: missing/invalid mtime or window → false', () => {
+  assert.strictEqual(isLogFresh(null, NOW, 20 * 60_000), false);
+  assert.strictEqual(isLogFresh(NaN, NOW, 20 * 60_000), false);
+  assert.strictEqual(isLogFresh(NOW - 60_000, NOW, null), false);
+});
+
+// selectReapableJobs — Part B wiring: a pidless row past grace now consults
+// the run log for a pid, and a fresh log skips the row entirely, BEFORE
+// falling back to findLiveProcess or the existing terminal reap.
+
+test('selectReapableJobs: pidless + past grace + log yields a LIVE pid → recovered, never reapable, row stays running', () => {
+  const jobs = [{ slug: 'zombie-log-alive', status: 'running', startedAt: agoMin(464) }];
+  const pidAlive = (pid) => pid === 3138458;
+  const getLogPid = () => 3138458;
+  const { reapable, recovered, warnings } = selectReapableJobs(jobs, NOW, {
+    pidAlive, grace: GRACE, getLogPid,
+  });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(warnings, []);
+  assert.strictEqual(recovered.length, 1);
+  assert.strictEqual(recovered[0].slug, 'zombie-log-alive');
+  assert.strictEqual(recovered[0].pid, 3138458);
+});
+
+test('selectReapableJobs: pidless + past grace + log yields a DEAD pid → still reaps (no regression)', () => {
+  const jobs = [{ slug: 'zombie-log-dead', status: 'running', startedAt: agoMin(464) }];
+  const getLogPid = () => 3138458;
+  const { reapable, recovered } = selectReapableJobs(jobs, NOW, {
+    pidAlive: alwaysDead, grace: GRACE, getLogPid,
+  });
+  assert.deepStrictEqual(recovered, []);
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].pidless, true);
+});
+
+test('selectReapableJobs: pidless + past grace + FRESH log mtime → skipped entirely (neither reapable nor recovered)', () => {
+  const jobs = [{ slug: 'chatty-pidless', status: 'running', startedAt: agoMin(464) }];
+  const getLogMtimeMs = () => NOW - 60_000; // modified 1 minute ago
+  const { reapable, recovered, warnings } = selectReapableJobs(jobs, NOW, {
+    pidAlive: alwaysAlive, grace: GRACE, getLogMtimeMs, logFreshWindowMs: 20 * 60_000,
+  });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(recovered, []);
+  assert.strictEqual(warnings.length, 1);
+  assert.strictEqual(warnings[0].slug, 'chatty-pidless');
+  assert.match(warnings[0].reason, /log evidence/);
+});
+
+test('selectReapableJobs: pidless + past grace + STALE log mtime + no recoverable pid → reaps with the existing reason string, byte-identical', () => {
+  const jobs = [{ slug: 'zombie', status: 'running', startedAt: agoMin(464) }];
+  const getLogMtimeMs = () => NOW - 25 * 60_000; // stale relative to a 20m window
+  const { reapable } = selectReapableJobs(jobs, NOW, {
+    pidAlive: alwaysAlive, grace: GRACE, getLogMtimeMs, logFreshWindowMs: 20 * 60_000,
+  });
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].reason, 'reaped: no runtime.pid recorded after 10m — spawn never completed');
+});
+
+test('selectReapableJobs: a row WITH a live runtime.pid is untouched by every new code path', () => {
+  const jobs = [{ slug: 'live', status: 'running', runtime: { pid: 1 }, startedAt: agoMin(500) }];
+  const getLogPid = () => { throw new Error('must never be called for a live-pid row'); };
+  const getLogMtimeMs = () => { throw new Error('must never be called for a live-pid row'); };
+  const { reapable, recovered, warnings } = selectReapableJobs(jobs, NOW, {
+    pidAlive: alwaysAlive, grace: GRACE, getLogPid, getLogMtimeMs, logFreshWindowMs: 20 * 60_000,
+  });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(recovered, []);
+  assert.deepStrictEqual(warnings, []);
+});
+
+test('selectReapableJobs: pidless + past grace + landedCommit on the row → reapable entry carries a failureOverride', () => {
+  const jobs = [{
+    slug: 'shipped-but-pidless',
+    status: 'running',
+    startedAt: agoMin(464),
+    landedCommit: 'f3e35a7f9e49f13a9eb8c338b0d086160e32a87f',
+  }];
+  const { reapable } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].pidless, true);
+  assert.ok(reapable[0].failureOverride, 'the reapable entry must carry the evidence-based override');
+  assert.strictEqual(reapable[0].failureOverride.landedCommit, 'f3e35a7f9e49f13a9eb8c338b0d086160e32a87f');
+  // The existing byte-for-byte reason string is untouched by this PRD — the
+  // override is carried as a separate field, not folded into `reason`.
+  assert.strictEqual(
+    reapable[0].reason,
+    'reaped: no runtime.pid recorded after 10m — spawn never completed',
+  );
+});
+
+test('selectReapableJobs: pidless + past grace + NO landedCommit on the row → failureOverride is null, unchanged from today', () => {
+  const jobs = [{ slug: 'genuinely-never-ran', status: 'running', startedAt: agoMin(464) }];
+  const { reapable } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].failureOverride, null);
+});

package/src/main/lib/__tests__/telemetryBoot.test.cjs

@@ -113,6 +113,17 @@ test('with no version change, flush("version-change") does NOT run', async () =>
   expect(flushCalls).toEqual(['boot']);
 });
 
+test('a rejected reportInstall leaves lastMachineReportAt unset so the next boot retries', async () => {
+  const now = Date.now();
+  const { deps, state } = fakeDeps({ settings: { lastMachineReportVersion: '', lastMachineReportAt: null } });
+  deps.telemetryClient.reportInstall = async () => ({ accepted: false, reason: 'error' });
+
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+
+  expect(state().lastMachineReportAt).toBe(null);
+  expect(state().lastMachineReportVersion).toBe('');
+});
+
 test('fires app.launch via telemetryCounters with installChannel + appVersion', async () => {
   const now = Date.now();
   const { deps } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });

package/src/main/lib/__tests__/usageCircuit.test.cjs

@@ -0,0 +1,224 @@
+/**
+ * usageCircuit.test.cjs — breaker transitions, jitter bounds, bindingWindow
+ * fallback, reset freshness, degraded-budget floor/cap, singleFlight dedup.
+ *
+ * Run: timeout 300 npx vitest run src/main/lib/__tests__/usageCircuit.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const {
+  createUsageCircuit,
+  backoffWithJitter,
+  isResetFresh,
+  bindingWindow,
+  degradedBudget,
+  singleFlight,
+} = require('../usageCircuit.cjs');
+
+test('state machine: closed -> open after 3 consecutive failures', () => {
+  let nowMs = 0;
+  const circuit = createUsageCircuit({ now: () => nowMs });
+  assert.strictEqual(circuit.state(), 'closed');
+  circuit.recordFailure('meter_rate_limited');
+  assert.strictEqual(circuit.state(), 'closed');
+  circuit.recordFailure('meter_rate_limited');
+  assert.strictEqual(circuit.state(), 'closed');
+  circuit.recordFailure('meter_rate_limited');
+  assert.strictEqual(circuit.state(), 'open');
+});
+
+test('open -> half_open after the backoff interval elapses, exactly one probe granted', () => {
+  let nowMs = 0;
+  const circuit = createUsageCircuit({ now: () => nowMs });
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  assert.strictEqual(circuit.state(), 'open');
+
+  nowMs += 10_000; // still inside the (>=15s) minimum backoff window
+  assert.strictEqual(circuit.state(), 'open');
+
+  nowMs += 60 * 60 * 1000; // well past any possible backoff interval
+  assert.strictEqual(circuit.state(), 'half_open');
+  // Re-querying before the probe's result is recorded must not grant a second probe.
+  assert.strictEqual(circuit.state(), 'half_open');
+});
+
+test('half_open -> closed on a successful probe, resetting backoff', () => {
+  let nowMs = 0;
+  const circuit = createUsageCircuit({ now: () => nowMs });
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  nowMs += 60 * 60 * 1000;
+  assert.strictEqual(circuit.state(), 'half_open');
+  circuit.recordSuccess({ five_hour: { utilization: 10, resets_at: null } });
+  assert.strictEqual(circuit.state(), 'closed');
+});
+
+test('half_open -> open on a failed probe, with backoff doubled (probe takes longer to reopen)', () => {
+  let nowMs = 0;
+  const circuit = createUsageCircuit({ now: () => nowMs });
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  nowMs += 60 * 60 * 1000;
+  assert.strictEqual(circuit.state(), 'half_open');
+  circuit.recordFailure('a');
+  assert.strictEqual(circuit.state(), 'open');
+  nowMs += 25_000; // below the doubled 2nd-stage backoff's own 30s floor
+  assert.strictEqual(circuit.state(), 'open');
+  nowMs += 60 * 60 * 1000;
+  assert.strictEqual(circuit.state(), 'half_open');
+});
+
+test('backoffWithJitter: 1000 samples stay within [0.5x, 1.0x] of the doubled base, floor 30s / cap 8min', () => {
+  for (let i = 0; i < 1000; i++) {
+    const first = backoffWithJitter(0);
+    assert.ok(first >= 15_000 && first <= 30_000, `first=${first}`);
+
+    const second = backoffWithJitter(30_000);
+    assert.ok(second >= 30_000 && second <= 60_000, `second=${second}`);
+
+    const atCap = backoffWithJitter(8 * 60 * 1000);
+    assert.ok(atCap >= 4 * 60 * 1000 && atCap <= 8 * 60 * 1000, `atCap=${atCap}`);
+
+    const beyondCap = backoffWithJitter(20 * 60 * 1000); // doubling would exceed the 8min cap
+    assert.ok(beyondCap >= 4 * 60 * 1000 && beyondCap <= 8 * 60 * 1000, `beyondCap=${beyondCap}`);
+  }
+});
+
+test('isResetFresh: past -> false, future -> true, null -> false', () => {
+  const now = Date.parse('2026-09-13T12:00:00Z');
+  assert.strictEqual(isResetFresh('2026-09-13T11:59:59Z', now), false); // past
+  assert.strictEqual(isResetFresh('2026-09-13T12:00:00Z', now), false); // at now
+  assert.strictEqual(isResetFresh('2026-09-13T12:00:01Z', now), true); // future
+  assert.strictEqual(isResetFresh(null, now), false);
+  assert.strictEqual(isResetFresh(undefined, now), false);
+  assert.strictEqual(isResetFresh('not-a-date', now), false);
+});
+
+test('bindingWindow: limits[] with weekly_all is_active wins over five_hour', () => {
+  const payload = {
+    five_hour: { utilization: 5, resets_at: '2026-09-13T15:00:00Z' },
+    limits: [
+      { type: 'five_hour', is_active: false, utilization: 5, resets_at: '2026-09-13T15:00:00Z' },
+      { type: 'weekly_all', is_active: true, utilization: 81, resets_at: '2026-09-19T00:00:00Z' },
+    ],
+  };
+  const win = bindingWindow(payload);
+  assert.strictEqual(win.name, 'weekly_all');
+  assert.strictEqual(win.utilization, 81);
+  assert.strictEqual(win.resets_at, '2026-09-19T00:00:00Z');
+});
+
+test('bindingWindow: limits[] absent falls back to five_hour', () => {
+  const payload = { five_hour: { utilization: 42, resets_at: '2026-09-13T15:00:00Z' } };
+  const win = bindingWindow(payload);
+  assert.strictEqual(win.name, 'five_hour');
+  assert.strictEqual(win.utilization, 42);
+});
+
+test('bindingWindow: limits[] present but nothing is_active also falls back to five_hour', () => {
+  const payload = {
+    five_hour: { utilization: 12, resets_at: null },
+    limits: [
+      { type: 'five_hour', is_active: false, utilization: 12, resets_at: null },
+      { type: 'weekly_all', is_active: false, utilization: 81, resets_at: null },
+    ],
+  };
+  const win = bindingWindow(payload);
+  assert.strictEqual(win.name, 'five_hour');
+  assert.strictEqual(win.utilization, 12);
+});
+
+test('degradedBudget: never yields 0 utilization, even when the last good binding window read 0', () => {
+  const payload = { five_hour: { utilization: 0, resets_at: null } };
+  const { utilization } = degradedBudget(payload, {});
+  assert.notStrictEqual(utilization, 0);
+  assert.strictEqual(utilization, 100); // no real signal -> conservative default
+});
+
+test('degradedBudget: carries forward the real last-good BINDING (weekly_all) utilization, e.g. 81%, never 0', () => {
+  const payload = {
+    five_hour: { utilization: 0, resets_at: null },
+    limits: [
+      { type: 'five_hour', is_active: false, utilization: 0, resets_at: null },
+      { type: 'weekly_all', is_active: true, utilization: 81, resets_at: '2026-09-19T00:00:00Z' },
+    ],
+  };
+  const { utilization } = degradedBudget(payload, {});
+  assert.strictEqual(utilization, 81);
+});
+
+test('degradedBudget: caps concurrency at 2 regardless of a higher configured cap', () => {
+  const payload = { five_hour: { utilization: 30, resets_at: null } };
+  const { concurrencyCap } = degradedBudget(payload, { configuredCap: 5 });
+  assert.strictEqual(concurrencyCap, 2);
+});
+
+test('degradedBudget: respects a configured cap below 2', () => {
+  const payload = { five_hour: { utilization: 30, resets_at: null } };
+  const { concurrencyCap } = degradedBudget(payload, { configuredCap: 1 });
+  assert.strictEqual(concurrencyCap, 1);
+});
+
+test('degradedBudget: an executor-observed 429 whose window has not passed pins utilization to 100', () => {
+  const payload = { five_hour: { utilization: 5, resets_at: null } };
+  const now = Date.parse('2026-09-13T12:00:00Z');
+  const { utilization } = degradedBudget(payload, {
+    observed429: true,
+    resetsAt: '2026-09-13T13:00:00Z', // still in the future
+    now,
+  });
+  assert.strictEqual(utilization, 100);
+});
+
+test('degradedBudget: once the 429 window passes, it stops pinning to 100 and falls back to real utilization', () => {
+  const payload = { five_hour: { utilization: 5, resets_at: null } };
+  const now = Date.parse('2026-09-13T12:00:00Z');
+  const { utilization } = degradedBudget(payload, {
+    observed429: true,
+    resetsAt: '2026-09-13T11:00:00Z', // already passed
+    now,
+  });
+  assert.strictEqual(utilization, 5);
+});
+
+test('singleFlight: concurrent callers share the same in-flight promise, fn invoked once', async () => {
+  let calls = 0;
+  let resolveFn;
+  const fn = () => new Promise((resolve) => { resolveFn = resolve; calls += 1; });
+  const wrapped = singleFlight(fn);
+
+  const p1 = wrapped();
+  const p2 = wrapped();
+  assert.strictEqual(p1, p2);
+  assert.strictEqual(calls, 1);
+  resolveFn('done');
+  assert.strictEqual(await p1, 'done');
+
+  const p3 = wrapped();
+  assert.notStrictEqual(p3, p1);
+  assert.strictEqual(calls, 2);
+  resolveFn('done2');
+  await p3;
+});
+
+test('singleFlight: de-dupes even when fn rejects, next call gets a fresh attempt', async () => {
+  let calls = 0;
+  const fn = () => (calls++ === 0 ? Promise.reject(new Error('boom')) : Promise.resolve('ok'));
+  const wrapped = singleFlight(fn);
+
+  const p1 = wrapped();
+  const p2 = wrapped();
+  assert.strictEqual(p1, p2);
+  await assert.rejects(p1, /boom/);
+
+  const p3 = wrapped();
+  assert.strictEqual(await p3, 'ok');
+  assert.strictEqual(calls, 2);
+});