claude-code-session-manager 0.80.0 → 0.82.0

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

@@ -19,7 +19,12 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { selectReapableJobs, mapOutcomeToGateOutcome, classifyRunOutcome } = require('../reaperHelpers.cjs');
+const { spawn } = require('node:child_process');
+const {
+  selectReapableJobs, mapOutcomeToGateOutcome, classifyRunOutcome,
+  findLiveProcessForJob, logHasOutput, resolvePidlessGateOutcome,
+  isAlreadySatisfiedOnMain,
+} = require('../reaperHelpers.cjs');
 const { detectRateLimitInLog } = require('../rateLimitDetect.cjs');
 
 const NOW = Date.parse('2026-09-01T12:00:00.000Z');
@@ -101,6 +106,33 @@ test('non-running rows are never considered, pidless or not', () => {
   assert.deepStrictEqual(warnings, []);
 });
 
+test('pidless + past grace + findLiveProcess finds a pid → recovered, never reaped', () => {
+  const jobs = [{ slug: 'zombie-alive', status: 'running', startedAt: agoMin(464) }];
+  const findLiveProcess = () => 2174739;
+  const { reapable, recovered, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE, findLiveProcess });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(warnings, []);
+  assert.strictEqual(recovered.length, 1);
+  assert.strictEqual(recovered[0].slug, 'zombie-alive');
+  assert.strictEqual(recovered[0].pid, 2174739);
+});
+
+test('pidless + past grace + findLiveProcess finds nothing → reaped exactly as today', () => {
+  const jobs = [{ slug: 'zombie-dead', status: 'running', startedAt: agoMin(464) }];
+  const findLiveProcess = () => null;
+  const { reapable, recovered } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE, findLiveProcess });
+  assert.deepStrictEqual(recovered, []);
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].pidless, true);
+});
+
+test('pidless + past grace + no findLiveProcess supplied → reaped exactly as before this PRD', () => {
+  const jobs = [{ slug: 'zombie', status: 'running', startedAt: agoMin(464) }];
+  const { reapable, recovered } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.strictEqual(reapable.length, 1);
+  assert.deepStrictEqual(recovered, []);
+});
+
 test('mixed batch: each row classified independently', () => {
   const jobs = [
     { slug: 'zombie', status: 'running', startedAt: agoMin(464) },
@@ -220,3 +252,90 @@ test('classifyRunOutcome: a clean success log still classifies as success', () =
   const p = writeTmpLog('{"type":"result","subtype":"success","is_error":false,"result":"done"}\n');
   assert.strictEqual(classifyRunOutcome(p), 'success');
 });
+
+// findLiveProcessForJob — the /proc positive liveness scan behind the
+// 2026-09-06 stranded-branch incident (234-uranus-eight-tails-ox: marked
+// failed/never_ran while its process was alive and still writing to its
+// worktree). Linux-only, and a safe no-op everywhere else per its own header.
+
+test('findLiveProcessForJob: finds a live process via /proc/<pid>/cwd match', async () => {
+  if (process.platform !== 'linux' || !fs.existsSync('/proc')) return;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reaper-liveness-'));
+  const child = spawn('sleep', ['5'], { cwd: dir, stdio: 'ignore' });
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    const pid = findLiveProcessForJob({ slug: 'irrelevant-slug' }, { worktreeDir: dir });
+    assert.strictEqual(pid, child.pid);
+  } finally {
+    child.kill('SIGKILL');
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('findLiveProcessForJob: no live process anywhere → null', () => {
+  if (process.platform !== 'linux' || !fs.existsSync('/proc')) return;
+  const pid = findLiveProcessForJob(
+    { slug: 'definitely-not-a-real-running-slug-xyz123' },
+    { worktreeDir: '/nonexistent/worktree/dir/xyz123' },
+  );
+  assert.strictEqual(pid, null);
+});
+
+// logHasOutput — the literal "did the run dir produce any log output" check
+// that gates whether a pidless reap may assert gateOutcome: 'never_ran'.
+
+test('logHasOutput: missing file → false', () => {
+  assert.strictEqual(logHasOutput('/nonexistent/path/does-not-exist.log'), false);
+});
+
+test('logHasOutput: empty file → false', () => {
+  const p = writeTmpLog('');
+  assert.strictEqual(logHasOutput(p), false);
+});
+
+test('logHasOutput: file with content → true', () => {
+  const p = writeTmpLog('some real log output\n');
+  assert.strictEqual(logHasOutput(p), true);
+});
+
+test('logHasOutput: null path → false', () => {
+  assert.strictEqual(logHasOutput(null), false);
+});
+
+// resolvePidlessGateOutcome — never_ran is asserted ONLY when the run dir has
+// no log output; a run dir WITH output must not claim never_ran even if no
+// clean result event was found in it.
+
+test('resolvePidlessGateOutcome: no output → never_ran, regardless of raw outcome (terminalizes as today)', () => {
+  assert.strictEqual(resolvePidlessGateOutcome('no_result', false), 'never_ran');
+  assert.strictEqual(resolvePidlessGateOutcome('success', false), 'never_ran');
+});
+
+test('resolvePidlessGateOutcome: output present + no_result → failed, never never_ran', () => {
+  assert.strictEqual(resolvePidlessGateOutcome('no_result', true), 'failed');
+});
+
+test('resolvePidlessGateOutcome: output present + success → passed', () => {
+  assert.strictEqual(resolvePidlessGateOutcome('success', true), 'passed');
+});
+
+test('resolvePidlessGateOutcome: output present + failed → failed', () => {
+  assert.strictEqual(resolvePidlessGateOutcome('failed', true), 'failed');
+});
+
+// isAlreadySatisfiedOnMain — PRD 1136. Pure decision layer: given the
+// already-git-queried list of satisfying commits, decide whether the
+// commit-guard's 'silent_no_op' verdict should be overridden to 'completed'.
+
+test('isAlreadySatisfiedOnMain: a satisfying commit → completed-shaped verdict naming the sha', () => {
+  const verdict = isAlreadySatisfiedOnMain(['5de4134abc123', 'a96de98def456']);
+  assert.strictEqual(verdict.sha, '5de4134abc123');
+  assert.strictEqual(verdict.verdict, 'already_satisfied_on_main');
+  assert.match(verdict.reason, /5de4134abc123/);
+});
+
+test('isAlreadySatisfiedOnMain: no satisfying commits → null — the gate must not be weakened into always-passing', () => {
+  assert.strictEqual(isAlreadySatisfiedOnMain([]), null);
+  assert.strictEqual(isAlreadySatisfiedOnMain(null), null);
+  assert.strictEqual(isAlreadySatisfiedOnMain(undefined), null);
+});

package/src/main/lib/branchSweep.cjs

@@ -0,0 +1,127 @@
+/**
+ * branchSweep.cjs — periodic recovery for `sm-job/<slug>` branches whose
+ * owning job row was terminalized (or lost entirely) without the branch ever
+ * being merged back into its project's HEAD (PRD 1135).
+ *
+ * The reaper's own liveness check (reaperHelpers.cjs findLiveProcessForJob)
+ * stops NEW stranding at the source; this module recovers anything already
+ * stranded before that fix landed, or by a crash the liveness check can't
+ * cover (app killed between a job's commit and its own integrateJobBranch
+ * call). Two halves of one invariant — see the PRD body.
+ *
+ * Deliberately never deletes a branch (`git branch -D` or otherwise) —
+ * reclaiming disk is out of scope; this module only ever merges forward.
+ *
+ * Kept free of scheduler.cjs / electron / queueStore coupling (same reason
+ * reaperHelpers.cjs is separate — importable and unit-testable without
+ * requiring electron) — callers own persisting a `conflict` result onto a
+ * job row.
+ */
+'use strict';
+
+const { execFile } = require('node:child_process');
+const gitWorktree = require('./gitWorktree.cjs');
+
+function execGit(cwd, args, timeout = 20_000) {
+  return new Promise((resolve, reject) => {
+    execFile('git', ['-C', cwd, ...args], { timeout, windowsHide: true, encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        err.stderrText = stderr;
+        reject(err);
+        return;
+      }
+      resolve(stdout || '');
+    });
+  });
+}
+
+/** List every local branch under `refs/heads/sm-job/*`. Never throws. */
+async function listSmJobBranches(cwd) {
+  try {
+    const out = await execGit(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/sm-job/*']);
+    return out.split('\n').map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** Branch names currently checked out in any linked worktree (incl. main). Never throws. */
+async function listCheckedOutBranches(cwd) {
+  try {
+    const out = await execGit(cwd, ['worktree', 'list', '--porcelain']);
+    return gitWorktree.parseWorktreeListPorcelain(out)
+      .map((e) => e.branch)
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+const TERMINAL_JOB_STATUSES = new Set(['completed', 'failed', 'skipped']);
+
+/**
+ * sweepStrandedJobBranches({ cwd, jobs, attemptedBranches }) → { results }
+ *
+ * `jobs` is the full in-memory queue snapshot (any project's rows may be
+ * present; matched by slug only, since a slug is globally unique). `attemptedBranches`
+ * is a caller-owned `Set` of `"<cwd>::<branch>"` keys — persisted across calls
+ * (in-memory is enough: the goal is "not retried every cycle forever" while
+ * the process is up, not durability across a restart) so a branch that
+ * conflicts once is never retried again in the same process lifetime.
+ *
+ * Each result is `{ branch, slug, action }` where action is one of:
+ *   'skip-checked-out'   — branch is checked out in a live worktree, left alone
+ *   'no-op-merged'       — branch has no commits beyond HEAD, nothing to do
+ *   'skip-active-row'    — job row exists and is NOT terminal, left alone
+ *   'skip-already-attempted' — a prior sweep already tried and failed this branch
+ *   'integrated'         — merged into HEAD this pass (`integration` attached)
+ *   'conflict'           — one bounded integrateBranch attempt failed (`integration` attached)
+ *
+ * SM_BRANCH_SWEEP_DISABLE=1 restores today's behaviour exactly (no-op),
+ * mirroring SM_RESUME_RECOVERY_DISABLE.
+ */
+async function sweepStrandedJobBranches({ cwd, jobs, attemptedBranches }) {
+  if (process.env.SM_BRANCH_SWEEP_DISABLE === '1') return { results: [] };
+  if (!cwd || !(await gitWorktree.isGitRepo(cwd))) return { results: [] };
+
+  const attempted = attemptedBranches instanceof Set ? attemptedBranches : new Set();
+  const branches = await listSmJobBranches(cwd);
+  if (!branches.length) return { results: [] };
+  const checkedOut = new Set(await listCheckedOutBranches(cwd));
+  const jobsBySlug = new Map((Array.isArray(jobs) ? jobs : []).map((j) => [j.slug, j]));
+
+  const results = [];
+  for (const branch of branches) {
+    const slug = gitWorktree.keyFromBranch('job', branch);
+    if (checkedOut.has(branch)) {
+      results.push({ branch, slug, action: 'skip-checked-out' });
+      continue;
+    }
+    const merged = await gitWorktree.isBranchMergedIntoHead(cwd, branch);
+    if (merged) {
+      results.push({ branch, slug, action: 'no-op-merged' });
+      continue;
+    }
+    const row = slug ? jobsBySlug.get(slug) : null;
+    const terminalOrMissing = !row || TERMINAL_JOB_STATUSES.has(row.status);
+    if (!terminalOrMissing) {
+      results.push({ branch, slug, action: 'skip-active-row' });
+      continue;
+    }
+    const attemptKey = `${cwd}::${branch}`;
+    if (attempted.has(attemptKey)) {
+      results.push({ branch, slug, action: 'skip-already-attempted' });
+      continue;
+    }
+    attempted.add(attemptKey);
+    const integration = await gitWorktree.integrateJobBranch({ cwd, branch, slug: slug || branch });
+    results.push({ branch, slug, action: integration.ok ? 'integrated' : 'conflict', integration });
+  }
+  return { results };
+}
+
+module.exports = {
+  listSmJobBranches,
+  listCheckedOutBranches,
+  sweepStrandedJobBranches,
+};

package/src/main/lib/gitWorktree.cjs

@@ -859,6 +859,25 @@ async function salvageDirtyDelta({ cwd, paths, outFile }) {
   }
 }
 
+/**
+ * True when every commit on `branch` is already an ancestor of (or equal to)
+ * `cwd`'s current HEAD — i.e. the branch holds no work that isn't already
+ * landed. Used by the stranded-branch sweep (branchSweep.cjs) to tell a
+ * genuinely stranded `sm-job/*` branch from one that's already a no-op.
+ * Never throws; a branch that doesn't exist, or any other git failure, is
+ * conservatively reported as NOT merged so a caller never treats an
+ * unreadable branch as safe to skip.
+ */
+async function isBranchMergedIntoHead(cwd, branch) {
+  try {
+    const branchHead = (await execGit(['rev-parse', '--verify', branch], { cwd, timeout: 10_000 })).trim();
+    const mergeBase = (await execGit(['merge-base', 'HEAD', branch], { cwd, timeout: 10_000 })).trim();
+    return mergeBase !== '' && mergeBase === branchHead;
+  } catch {
+    return false;
+  }
+}
+
 /** Parse `git worktree list --porcelain` into `[{ worktree, branch }]`. */
 function parseWorktreeListPorcelain(text) {
   const entries = [];
@@ -1003,6 +1022,7 @@ module.exports = {
   cleanupWorktree,
   salvageWorktreeDiff,
   salvageDirtyDelta,
+  isBranchMergedIntoHead,
   parseWorktreeListPorcelain,
   reconcileWorktreesOnBoot,
   sweepStaleWorktreeCheckouts,

package/src/main/lib/landedSinceRun.cjs

@@ -52,4 +52,44 @@ function landedSinceRun(cwd, sinceIso, paths, { timeoutMs = LANDED_SINCE_RUN_TIM
   });
 }
 
-module.exports = { landedSinceRun, LANDED_SINCE_RUN_TIMEOUT_MS };
+/**
+ * Commits reachable from `main` in `cwd` since `sinceIso` that touch any of
+ * `paths` — the evidence query behind PRD 1136's already-satisfied-on-main
+ * commit-guard exemption. Deliberately narrower than landedSinceRun in one
+ * axis (scoped to `main`, not `--all` — a commit on a stray branch is not
+ * "satisfied") and identical in the other (path-scoped, so an unrelated
+ * commit elsewhere in the repo is never credited to this job).
+ *
+ * Falls back from local `main` to `origin/main` when the local branch ref
+ * doesn't exist (a worktree/CI checkout that never checked main out
+ * locally) — never throws either way; git-unavailable, a non-repo cwd, an
+ * unresolvable ref, or an empty `paths` list all resolve to `[]`.
+ *
+ * @param {string} cwd
+ * @param {string} sinceIso
+ * @param {string[]} paths
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<string[]>} full commit SHAs, newest first
+ */
+function landedOnMainSince(cwd, sinceIso, paths, { timeoutMs = LANDED_SINCE_RUN_TIMEOUT_MS } = {}) {
+  const runLog = (ref) => new Promise((resolve) => {
+    execFile(
+      'git',
+      ['-C', cwd, 'log', ref, `--since=${sinceIso}`, '--format=%H', '--', ...paths],
+      { timeout: timeoutMs, windowsHide: true },
+      (err, stdout) => {
+        if (err) { resolve(null); return; }
+        resolve(String(stdout || '').trim().split('\n').filter(Boolean));
+      },
+    );
+  });
+  return (async () => {
+    if (!cwd || !sinceIso || !Array.isArray(paths) || paths.length === 0) return [];
+    const viaLocal = await runLog('main');
+    if (viaLocal !== null) return viaLocal;
+    const viaRemote = await runLog('origin/main');
+    return viaRemote ?? [];
+  })();
+}
+
+module.exports = { landedSinceRun, landedOnMainSince, LANDED_SINCE_RUN_TIMEOUT_MS };

package/src/main/lib/machineProfile.cjs

@@ -0,0 +1,144 @@
+/**
+ * machineProfile — builds the "once per machine" telemetry payload: which
+ * build (appVersion) this install id is running, plus basic hardware/OS specs.
+ *
+ * Deliberately anonymous: no hostname, no OS username, no homedir, no MAC
+ * address, no hardware serial, no absolute filesystem path, no IANA timezone
+ * name (offset only). machineDigest is a coarse hash of stable spec fields —
+ * a hardware-CLASS fingerprint, never a device id — so individual records
+ * can be joined back to a machine class without repeating the whole profile.
+ *
+ * Pure data plumbing: no network code, no call sites. Later PRDs consume it.
+ */
+'use strict';
+
+const os = require('node:os');
+const crypto = require('node:crypto');
+const path = require('node:path');
+const claudeBin = require('./claudeBin.cjs');
+
+function resolveElectronApp() {
+  try {
+    // eslint-disable-next-line global-require
+    const electron = require('electron');
+    if (electron && typeof electron === 'object' && typeof electron.app === 'object') {
+      return electron.app;
+    }
+  } catch { /* no electron runtime (plain vitest, or electron require resolved to a path string) */ }
+  return null;
+}
+
+function resolvePackageVersion() {
+  try {
+    // src/main/lib/machineProfile.cjs -> src/main/lib -> src/main -> src -> repo root
+    const pkg = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+    return (pkg && typeof pkg.version === 'string') ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 'npx' when the app path lives inside an npm/npx cache dir, 'dev' when
+ * SM_DEV is set, else 'unknown'. Injectable so tests never depend on real
+ * process state.
+ */
+function resolveInstallChannel({ appPath = null, devFlag = !!process.env.SM_DEV } = {}) {
+  if (devFlag) return 'dev';
+  if (typeof appPath === 'string' && /[\\/](\.npm|_npx|npm-cache|npx-cache)[\\/]/i.test(appPath)) {
+    return 'npx';
+  }
+  return 'unknown';
+}
+
+/** sha256 of the concatenated stable spec fields, truncated to 12 hex chars. */
+function computeMachineDigest(specs) {
+  const material = [
+    specs.platform,
+    specs.osRelease,
+    specs.arch,
+    specs.cpuModel || '',
+    String(specs.cpuCount),
+    String(specs.totalMemMb),
+  ].join('|');
+  return crypto.createHash('sha256').update(material).digest('hex').slice(0, 12);
+}
+
+/** Reads basic, non-identifying specs from node:os. Null-safe when os.cpus() is empty. */
+function readSpecs(osModule) {
+  const cpus = osModule.cpus() || [];
+  const cpu0 = cpus[0] || null;
+  return {
+    platform: osModule.platform(),
+    osRelease: osModule.release(),
+    arch: osModule.arch(),
+    cpuModel: cpu0 && typeof cpu0.model === 'string' ? cpu0.model.trim() : null,
+    cpuSpeedMhz: cpu0 && typeof cpu0.speed === 'number' ? cpu0.speed : null,
+    cpuCount: cpus.length,
+    totalMemMb: Math.round(osModule.totalmem() / 1048576),
+  };
+}
+
+/**
+ * Builds the machine profile. All external dependencies are injectable so
+ * this is fully testable under plain vitest with no Electron runtime and no
+ * real Claude CLI.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.osModule] - defaults to node:os
+ * @param {function} [opts.probeClaudeVersion] - defaults to claudeBin.probeClaudeVersion; must resolve to a string or null and never block startup
+ * @param {object|null} [opts.electronApp] - override for tests; when omitted, 'electron' is required lazily
+ * @param {string} [opts.firstSeenAt] - ISO timestamp; defaults to now (callers that track a persisted first-seen value should pass it)
+ */
+async function buildMachineProfile(opts = {}) {
+  const osModule = opts.osModule || os;
+  const probeClaudeVersion = opts.probeClaudeVersion || claudeBin.probeClaudeVersion;
+  const electronApp = Object.prototype.hasOwnProperty.call(opts, 'electronApp')
+    ? opts.electronApp
+    : resolveElectronApp();
+
+  let appVersion = null;
+  let appPath = null;
+  if (electronApp) {
+    try { appVersion = electronApp.getVersion(); } catch { /* not ready / not a real app object */ }
+    try { appPath = electronApp.getAppPath(); } catch { /* not ready / not a real app object */ }
+  }
+  if (!appVersion) appVersion = resolvePackageVersion();
+
+  const specs = readSpecs(osModule);
+  const machineDigest = computeMachineDigest(specs);
+
+  let claudeCliVersion = null;
+  try {
+    claudeCliVersion = await probeClaudeVersion();
+  } catch {
+    claudeCliVersion = null;
+  }
+
+  return {
+    appVersion,
+    installChannel: resolveInstallChannel({ appPath, devFlag: !!process.env.SM_DEV }),
+    machineDigest,
+    platform: specs.platform,
+    osRelease: specs.osRelease,
+    arch: specs.arch,
+    cpuModel: specs.cpuModel,
+    cpuCount: specs.cpuCount,
+    cpuSpeedMhz: specs.cpuSpeedMhz,
+    totalMemMb: specs.totalMemMb,
+    nodeVersion: process.versions.node || null,
+    electronVersion: process.versions.electron || null,
+    chromeVersion: process.versions.chrome || null,
+    v8Version: process.versions.v8 || null,
+    claudeCliVersion,
+    locale: Intl.DateTimeFormat().resolvedOptions().locale || null,
+    timezoneOffsetMinutes: new Date().getTimezoneOffset(),
+    firstSeenAt: opts.firstSeenAt || new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  buildMachineProfile,
+  computeMachineDigest,
+  resolveInstallChannel,
+};

package/src/main/lib/rateLimitWindow.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * rateLimitWindow.cjs — reads the BINDING rate-limit window's reset time
+ * straight off a run's own log, instead of trusting the billing usage
+ * endpoint's five_hour window (PRD 1118). A run can be 429'd by a
+ * different window than five_hour (seven_day, seven_day_overage_included)
+ * while five_hour utilization is still 0 — pausing against five_hour's
+ * reset in that case arms the resume timer against the wrong clock, and
+ * the billing endpoint can itself be 429'ing when this is needed most.
+ *
+ * Pure: log path in, reset value out. No electron import, so it is
+ * unit-testable without scheduler.cjs (mirrors reaperHelpers.cjs's split).
+ */
+
+const { readTail } = require('./fileTail.cjs');
+
+// Authoritative window block rides on the LAST rate_limit_event in the log
+// (often the one attached to the final result), so mirror classifyRunOutcome's
+// 64 KB tail rather than detectRateLimitInLog's smaller 16 KB one.
+const TAIL_BYTES = 64 * 1024;
+
+/**
+ * Scans a run log's tail for rate_limit_event entries and returns the
+ * UNIX-seconds resetsAt of the window that actually bound (utilization >= 1.0)
+ * in the LAST such event. When multiple windows bind in that event, the
+ * latest resetsAt wins. Returns null when no rate_limit_event is found, or
+ * none of its windows are at/above 1.0 utilization.
+ */
+function resolveBindingRateLimitReset(logPath) {
+  const text = readTail(logPath, TAIL_BYTES);
+  if (!text) return null;
+
+  let lastWindows = null;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed[0] !== '{') continue;
+    let event;
+    try {
+      event = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const windows = event?.rate_limit_info?.unifiedWindows;
+    if (event?.type === 'rate_limit_event' && windows && typeof windows === 'object') {
+      lastWindows = windows;
+    }
+  }
+  if (!lastWindows) return null;
+
+  let latestBoundReset = null;
+  for (const window of Object.values(lastWindows)) {
+    if (!window || typeof window.utilization !== 'number' || typeof window.resetsAt !== 'number') continue;
+    if (window.utilization < 1.0) continue;
+    if (latestBoundReset === null || window.resetsAt > latestBoundReset) {
+      latestBoundReset = window.resetsAt;
+    }
+  }
+  return latestBoundReset;
+}
+
+module.exports = { resolveBindingRateLimitReset };

package/src/main/lib/rcaReport.cjs

@@ -52,6 +52,7 @@ const VERDICT_LABELS = {
   pass_no_commit_already_shipped: 'PASS with no commit — deliverables already shipped',
   pass_no_commit_prior_run_verified: 'PASS with no commit — prior run of this slug already landed the work',
   silent_no_op: 'no commit, clean tree — no evidence of work',
+  blocked_by_foreign_wip_streak: 'blocked by a sibling job\'s foreign WIP 3x in a row',
 };
 
 function humanVerdict(verdict) {
@@ -69,14 +70,18 @@ const FAILURE_CLASSES = {
   UNCOMMITTED: 'uncommitted-changes',
   TRANSCRIPT_ERRORS: 'transcript-errors',
   ABANDONED_BACKGROUND_TASK: 'abandoned-background-task',
+  BLOCKED_BY_FOREIGN_WIP: 'blocked-by-foreign-wip',
   UNKNOWN: 'unknown',
 };
 
 // ─── Recovery actions — one per failure class, machine-readable ────────────
 // Closed set the scheduler routes on: 'archive' (stale re-run, do not
-// re-queue), 'resume-and-commit' (PRD 1111's --resume dispatch owns this),
-// 'verify-and-close' (the work likely landed, just missing its sentinel),
-// 'investigate' (the only class that still buys a fix-plan investigation).
+// re-queue — also the closest fit for BLOCKED_BY_FOREIGN_WIP: there is
+// nothing to investigate, and re-queuing is already owned by
+// reconcile()'s requeueForeignWipBlockedJobs, not this action), 'resume-and-commit'
+// (PRD 1111's --resume dispatch owns this), 'verify-and-close' (the work
+// likely landed, just missing its sentinel), 'investigate' (the only class
+// that still buys a fix-plan investigation).
 const RECOVERY_ACTIONS = {
   [FAILURE_CLASSES.ALREADY_SHIPPED]: 'archive',
   [FAILURE_CLASSES.SELF_QUEUE]: 'investigate',
@@ -96,6 +101,7 @@ const RECOVERY_ACTIONS = {
   // carries the "check for salvaged work, commit before re-implementing"
   // guidance into that cold-read investigation.
   [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]: 'investigate',
+  [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]: 'archive',
   [FAILURE_CLASSES.UNKNOWN]: 'investigate',
 };
 
@@ -121,6 +127,8 @@ const PREVENTION_HINTS = {
     'Recover or annotate every error within ~10 lines (e.g. `# expected/handled: <why>`) instead of leaving a bare Traceback near the end of the transcript.',
   [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]:
     'A headless run cannot receive a background-task completion notification — never let a long Bash command auto-background past its foreground timeout and then wait for it. Run long commands with an explicit bound (`timeout <N> <cmd>`) so they finish in the foreground, or poll their output file directly instead of waiting on Monitor/notification.',
+  [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]:
+    'This job correctly reported `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` against a sibling job\'s in-flight, uncommitted files three times in a row — auto-requeue is exhausted (reconcile() only clears this once the blocked paths go clean). This is not a defect in this PRD\'s own work: check on the sibling job/human that owns the still-dirty path(s) named on the job row, and either wait for them to commit or manually reset this job to `pending` once the tree is clear. Do not author a fix-plan PRD against it.',
   [FAILURE_CLASSES.UNKNOWN]:
     'Re-run the acceptance criteria gate locally against the failure log to pin down the specific break before re-queuing.',
 };
@@ -159,6 +167,13 @@ const POST_AC_OVERRUN_MIN_TAIL_FRACTION = 0.3;
 function classifyFailure({ verdict, logTail }) {
   const lines = (logTail || '').split('\n');
 
+  // Checked before every other rule: an unambiguous, materially-checked
+  // verdict (the scheduler itself validated the executor's claimed paths
+  // against the job's disclosed foreign-WIP manifest before ever landing
+  // this verdict — see validateForeignWipBlockClaim in scheduler.cjs) needs
+  // no log-tail heuristics to classify.
+  if (verdict === 'blocked_by_foreign_wip_streak') return FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP;
+
   // Checked first, before SELF_QUEUE/STUCK_LOOP: a correct executor that finds
   // its acceptance criteria already satisfied by a prior commit makes no
   // change and truthfully prints a PASS sentinel, so the run lands