claude-code-session-manager 0.75.3 → 0.76.0

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

@@ -0,0 +1,148 @@
+/**
+ * projectRootResolve.test.cjs — resolveProjectContext (PRD: worktree-cwd
+ * Epic-lookup hazard). Exercises the resolver purely in-process with injected
+ * deps (no Electron, no real git worktrees) — see prdCreate.test.cjs for the
+ * end-to-end fixture reproducing the live starry-night-ships shape.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/projectRootResolve.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, vi } from 'vitest';
+const { resolveProjectContext } = require('../projectRootResolve.cjs');
+
+function makeDeps({ projectRootOfImpl, allCwds = [], indexes = {}, ephemeral = [] } = {}) {
+  return {
+    projectRootOf: projectRootOfImpl || ((p) => p),
+    allProjectCwds: () => allCwds,
+    readActiveIndex: (cwd) => ({ sessions: indexes[cwd] || {}, events: {} }),
+    isEphemeralCwd: (cwd) => ephemeral.includes(cwd),
+    warn: vi.fn(),
+  };
+}
+
+test('a plain project root (no worktree, no ops-internal segment) is returned unchanged', () => {
+  const deps = makeDeps();
+  const result = resolveProjectContext({ cwd: '/home/bilko/Projects/some-app' }, deps);
+  expect(result).toEqual({ cwd: '/home/bilko/Projects/some-app', epicId: null, epicCwd: null, source: 'cwd' });
+});
+
+test('a worktree cwd normalizes to the main tree', () => {
+  const deps = makeDeps({
+    projectRootOfImpl: (p) => (p.startsWith('/tmp/worktree') ? '/home/bilko/Projects/starry-night-ships' : p),
+  });
+  const result = resolveProjectContext({ cwd: '/tmp/worktree/abc/epic-1' }, deps);
+  expect(result.cwd).toBe('/home/bilko/Projects/starry-night-ships');
+  expect(result.source).toBe('cwd');
+});
+
+test('an ops-internal cwd normalizes to the project root', () => {
+  const deps = makeDeps({
+    projectRootOfImpl: (p) => (p.includes('session-manager-operations') ? '/home/bilko/Projects/foo' : p),
+  });
+  const result = resolveProjectContext({ cwd: '/home/bilko/Projects/foo/session-manager-operations/scheduler/state' }, deps);
+  expect(result.cwd).toBe('/home/bilko/Projects/foo');
+});
+
+test('Epic found in the normalized cwd\'s own active-index — source epic-index', () => {
+  const deps = makeDeps({
+    indexes: {
+      '/home/bilko/Projects/foo': { 'epic-1': { id: 'epic-1', claudeSessionId: 'sess-1', status: 'active' } },
+    },
+  });
+  const result = resolveProjectContext({ cwd: '/home/bilko/Projects/foo', originClaudeSessionId: 'sess-1' }, deps);
+  expect(result).toEqual({ cwd: '/home/bilko/Projects/foo', epicId: 'epic-1', epicCwd: '/home/bilko/Projects/foo', source: 'epic-index' });
+});
+
+test('Epic found only via cross-project scan — epicCwd wins over the supplied cwd', () => {
+  const deps = makeDeps({
+    allCwds: ['/home/bilko/Projects/foo', '/home/bilko/Projects/bar'],
+    indexes: {
+      '/home/bilko/Projects/bar': { 'epic-2': { id: 'epic-2', claudeSessionId: 'sess-2', status: 'active' } },
+    },
+  });
+  const result = resolveProjectContext({ cwd: '/home/bilko/Projects/foo', originClaudeSessionId: 'sess-2' }, deps);
+  expect(result.epicId).toBe('epic-2');
+  expect(result.epicCwd).toBe('/home/bilko/Projects/bar');
+  expect(result.cwd).toBe('/home/bilko/Projects/bar');
+  expect(result.source).toBe('cross-project-scan');
+});
+
+test('no match anywhere → epicId null, cwd unchanged', () => {
+  const deps = makeDeps({ allCwds: ['/home/bilko/Projects/foo'] });
+  const result = resolveProjectContext({ cwd: '/home/bilko/Projects/foo', originClaudeSessionId: 'sess-unknown' }, deps);
+  expect(result).toEqual({ cwd: '/home/bilko/Projects/foo', epicId: null, epicCwd: null, source: 'cwd' });
+});
+
+test('explicit epicId (sourcePromptId) resolves cwd when no cwd was supplied at all', () => {
+  const deps = makeDeps({
+    allCwds: ['/home/bilko/Projects/foo'],
+    indexes: {
+      '/home/bilko/Projects/foo': { 'epic-3': { id: 'epic-3', claudeSessionId: 'sess-3', status: 'proposed' } },
+    },
+  });
+  const result = resolveProjectContext({ epicId: 'epic-3' }, deps);
+  expect(result.cwd).toBe('/home/bilko/Projects/foo');
+  expect(result.epicId).toBe('epic-3');
+});
+
+test('duplicate claudeSessionId across two projects: prefers the non-ephemeral, status=active row and warns naming both', () => {
+  const deps = makeDeps({
+    allCwds: ['/tmp/session-manager-epic-worktrees/abc/epic-1', '/home/bilko/Projects/starry-night-ships'],
+    indexes: {
+      '/tmp/session-manager-epic-worktrees/abc/epic-1': {
+        'epic-1': { id: 'epic-1', claudeSessionId: 'sess-dup', status: 'proposed' },
+      },
+      '/home/bilko/Projects/starry-night-ships': {
+        'epic-1': { id: 'epic-1', claudeSessionId: 'sess-dup', status: 'active' },
+      },
+    },
+    ephemeral: ['/tmp/session-manager-epic-worktrees/abc/epic-1'],
+  });
+  const result = resolveProjectContext({ originClaudeSessionId: 'sess-dup' }, deps);
+  expect(result.epicCwd).toBe('/home/bilko/Projects/starry-night-ships');
+  expect(result.source).toBe('cross-project-scan');
+  expect(deps.warn).toHaveBeenCalledTimes(1);
+  const warnMsg = deps.warn.mock.calls[0][0];
+  expect(warnMsg).toContain('/tmp/session-manager-epic-worktrees/abc/epic-1');
+  expect(warnMsg).toContain('/home/bilko/Projects/starry-night-ships');
+});
+
+test('an originProjectRoot hint outranks the supplied cwd, but a resolved Epic still outranks the hint', () => {
+  const deps = makeDeps({
+    indexes: {
+      '/home/bilko/Projects/hinted': { 'epic-4': { id: 'epic-4', claudeSessionId: 'sess-4', status: 'active' } },
+    },
+  });
+  const noEpic = resolveProjectContext({ cwd: '/home/bilko/Projects/guessed', originProjectRoot: '/home/bilko/Projects/hinted' }, deps);
+  expect(noEpic.cwd).toBe('/home/bilko/Projects/hinted');
+
+  const withEpic = resolveProjectContext(
+    { cwd: '/home/bilko/Projects/guessed', originProjectRoot: '/home/bilko/Projects/hinted', originClaudeSessionId: 'sess-4' },
+    deps,
+  );
+  expect(withEpic.cwd).toBe('/home/bilko/Projects/hinted');
+  expect(withEpic.epicId).toBe('epic-4');
+});
+
+test('never throws on missing cwd/originClaudeSessionId/epicId — returns an all-null result', () => {
+  const deps = makeDeps();
+  expect(resolveProjectContext({}, deps)).toEqual({ cwd: null, epicId: null, epicCwd: null, source: 'cwd' });
+  expect(resolveProjectContext(undefined, deps)).toEqual({ cwd: null, epicId: null, epicCwd: null, source: 'cwd' });
+});
+
+test('bounded: reads each candidate project\'s active-index exactly once per call', () => {
+  const readActiveIndex = vi.fn((cwd) => ({ sessions: {}, events: {} }));
+  const deps = {
+    projectRootOf: (p) => p,
+    allProjectCwds: () => ['/home/bilko/Projects/a', '/home/bilko/Projects/b', '/home/bilko/Projects/c'],
+    readActiveIndex,
+    isEphemeralCwd: () => false,
+    warn: vi.fn(),
+  };
+  resolveProjectContext({ cwd: '/home/bilko/Projects/a', originClaudeSessionId: 'sess-x' }, deps);
+  expect(readActiveIndex).toHaveBeenCalledTimes(3);
+  const calledCwds = readActiveIndex.mock.calls.map((c) => c[0]);
+  expect(new Set(calledCwds).size).toBe(3);
+});

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

@@ -0,0 +1,112 @@
+/**
+ * reaperHelpers.test.cjs — selectReapableJobs: the pure predicate behind
+ * reapDeadRunningJobs()'s pidless-zombie fix.
+ *
+ * Prior behaviour: a 'running' row with no runtime.pid was skipped forever,
+ * unconditionally ("spawn may be mid-flight; give it a cycle") — no age
+ * bound. Repro 2026-09-01: a row sat pidless for 464 minutes against a
+ * 24-minute estimate, empty run dir, no claude process anywhere — nothing
+ * pid-bound (deadman, idle watchdog, supervisor) could ever see it.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/reaperHelpers.test.cjs
+ */
+
+'use strict';
+
+// vitest, NOT node:test — this repo's suite is vitest-only (CLAUDE.md).
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const { selectReapableJobs } = require('../reaperHelpers.cjs');
+
+const NOW = Date.parse('2026-09-01T12:00:00.000Z');
+const agoMin = (m) => new Date(NOW - m * 60_000).toISOString();
+const GRACE = 10 * 60_000;
+const alwaysDead = () => false;
+const alwaysAlive = () => true;
+
+test('pidless + older than grace → reaped, with a named reason', () => {
+  const jobs = [{ slug: 'zombie', status: 'running', startedAt: agoMin(464) }];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.strictEqual(warnings.length, 0);
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].slug, 'zombie');
+  assert.strictEqual(reapable[0].pid, null);
+  assert.strictEqual(reapable[0].pidless, true);
+  assert.match(reapable[0].reason, /no runtime\.pid recorded after 10m/);
+});
+
+test('pidless + within grace → skipped (the genuine mid-flight-spawn case)', () => {
+  const jobs = [{ slug: 'fresh', status: 'running', startedAt: agoMin(2) }];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(warnings, []);
+});
+
+test('pidless + exactly at grace boundary → reaped (>= not >)', () => {
+  const jobs = [{ slug: 'boundary', status: 'running', startedAt: agoMin(10) }];
+  const { reapable } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.strictEqual(reapable.length, 1);
+});
+
+test('live pid → skipped regardless of age', () => {
+  const jobs = [{ slug: 'live', status: 'running', runtime: { pid: 4242 }, startedAt: agoMin(500) }];
+  const { reapable } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+});
+
+test('dead pid → reaped exactly as before (pidless: false, no reason string)', () => {
+  const jobs = [{ slug: 'dead', status: 'running', runtime: { pid: 4242 }, startedAt: agoMin(500) }];
+  const { reapable } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysDead, grace: GRACE });
+  assert.strictEqual(reapable.length, 1);
+  assert.strictEqual(reapable[0].slug, 'dead');
+  assert.strictEqual(reapable[0].pid, 4242);
+  assert.strictEqual(reapable[0].pidless, false);
+});
+
+test('pidless + missing startedAt → skipped and warned, not reaped', () => {
+  const jobs = [{ slug: 'no-started-at', status: 'running' }];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+  assert.strictEqual(warnings.length, 1);
+  assert.strictEqual(warnings[0].slug, 'no-started-at');
+});
+
+test('pidless + unparseable startedAt → skipped and warned, not reaped', () => {
+  const jobs = [{ slug: 'bad-started-at', status: 'running', startedAt: 'not-a-date' }];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+  assert.strictEqual(warnings.length, 1);
+  assert.strictEqual(warnings[0].slug, 'bad-started-at');
+});
+
+test('pidless + startedAt in the future (clock skew) → skipped, not reaped', () => {
+  const jobs = [{ slug: 'future', status: 'running', startedAt: agoMin(-60) }];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(warnings, []);
+});
+
+test('non-running rows are never considered, pidless or not', () => {
+  const jobs = [
+    { slug: 'a', status: 'pending', startedAt: agoMin(500) },
+    { slug: 'b', status: 'completed', startedAt: agoMin(500) },
+    { slug: 'c', status: 'failed', runtime: { pid: 1 }, startedAt: agoMin(500) },
+  ];
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive: alwaysDead, grace: GRACE });
+  assert.deepStrictEqual(reapable, []);
+  assert.deepStrictEqual(warnings, []);
+});
+
+test('mixed batch: each row classified independently', () => {
+  const jobs = [
+    { slug: 'zombie', status: 'running', startedAt: agoMin(464) },
+    { slug: 'fresh', status: 'running', startedAt: agoMin(2) },
+    { slug: 'live', status: 'running', runtime: { pid: 1 }, startedAt: agoMin(500) },
+    { slug: 'dead', status: 'running', runtime: { pid: 2 }, startedAt: agoMin(500) },
+    { slug: 'bad-started-at', status: 'running', startedAt: 'nope' },
+  ];
+  const pidAlive = (pid) => pid === 1;
+  const { reapable, warnings } = selectReapableJobs(jobs, NOW, { pidAlive, grace: GRACE });
+  assert.deepStrictEqual(reapable.map((r) => r.slug).sort(), ['dead', 'zombie']);
+  assert.deepStrictEqual(warnings.map((w) => w.slug), ['bad-started-at']);
+});

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

@@ -118,15 +118,25 @@ test('a SKIPPED (never-ran) bare-named dep holds the dependent and reports an ex
 // ---------------------------------------------------------------------------
 
 test('fires EVERY dependency-eligible job, not one per parallelGroup', () => {
-  const jobs = [
-    job('983-a', 'pending'),
-    job('984-b', 'pending'),
-    job('985-c', 'pending'),
-    job('986-d', 'pending'),
-  ];
-  const { batch } = pick(jobs, new Set(), 5);
-  // Pre-fix this returned exactly ['983-a'] — one singleton group.
-  assert.deepEqual(batch.map((j) => j.slug), ['983-a', '984-b', '985-c', '986-d']);
+  // This test predates the per-project job cap (PRD 1066, default 2) and
+  // asserts against the parallelGroup barrier specifically — raise the cap
+  // so it isn't incidentally exercising that unrelated limit.
+  const prevCap = process.env.SM_PROJECT_JOB_CAP;
+  process.env.SM_PROJECT_JOB_CAP = '10';
+  try {
+    const jobs = [
+      job('983-a', 'pending'),
+      job('984-b', 'pending'),
+      job('985-c', 'pending'),
+      job('986-d', 'pending'),
+    ];
+    const { batch } = pick(jobs, new Set(), 5);
+    // Pre-fix this returned exactly ['983-a'] — one singleton group.
+    assert.deepEqual(batch.map((j) => j.slug), ['983-a', '984-b', '985-c', '986-d']);
+  } finally {
+    if (prevCap === undefined) delete process.env.SM_PROJECT_JOB_CAP;
+    else process.env.SM_PROJECT_JOB_CAP = prevCap;
+  }
 });
 
 test('a higher-numbered job is NOT held behind an in-flight lower-numbered one', () => {

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

@@ -0,0 +1,213 @@
+'use strict';
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerBatchFairness.test.cjs
+//
+// PRDs 1086 + 1087 — cross-project fairness and starvation escalation.
+// pickNextBatch used to order projects by their lowest pending parallelGroup.
+// NN numbers are allocated PER PROJECT and only grow, so that compared
+// unrelated sequences: on 2026-09-01 social-signals-trader (8 pending, lowest
+// NN 3887) got zero starts for 3.5 h while starry-night-ships (lowest NN 158)
+// took every freed slot. These tests pin the replacement contract: fewest
+// running first, oldest pending as tiebreak, cwd last, and ROUND-ROBIN slot
+// hand-out — plus the escalation that makes any regression visible.
+const assert = require('node:assert/strict');
+const {
+  pickNextBatch, enqueueTimestamp, findStarvedProjects,
+} = require('../schedulerBatch.cjs');
+
+const A = '/home/user/Projects/starry-night-ships';
+const B = '/home/user/Projects/social-signals-trader';
+const C = '/home/user/Projects/burrow';
+const D = '/home/user/Projects/sigma';
+
+function job(slug, status, cwd, extra = {}) {
+  return {
+    slug,
+    status,
+    cwd,
+    parallelGroup: Number(String(slug).match(/^(\d+)-/)?.[1] ?? 99),
+    dependsOn: [],
+    ...extra,
+  };
+}
+const ORIGINAL_CAP_ENV = process.env.SM_PROJECT_JOB_CAP;
+afterEach(() => {
+  if (ORIGINAL_CAP_ENV === undefined) delete process.env.SM_PROJECT_JOB_CAP;
+  else process.env.SM_PROJECT_JOB_CAP = ORIGINAL_CAP_ENV;
+});
+
+// ─── the reported bug ───────────────────────────────────────────────────────
+
+test('a project with high NN numbers is never starved behind a project with low ones (freeSlots=1, repeated ticks)', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [];
+  for (let n = 158; n <= 172; n++) jobs.push(job(`${n}-a`, 'pending', A));
+  for (let n = 3887; n <= 3941; n++) jobs.push(job(`${n}-b`, 'pending', B));
+  const running = new Set();
+  const dispatched = [];
+  for (let tick = 0; tick < 2; tick++) {
+    const { batch } = pickNextBatch(jobs, running, 1);
+    assert.equal(batch.length, 1, `tick ${tick} should dispatch exactly one job`);
+    const picked = batch[0];
+    dispatched.push(picked);
+    // simulate the picked job going to running
+    const row = jobs.find((j) => j.slug === picked.slug);
+    row.status = 'running';
+    running.add(row.slug);
+  }
+  assert.ok(dispatched.some((j) => j.cwd === B), `B must get a start within 2 ticks, got ${dispatched.map((j) => j.slug)}`);
+  assert.ok(dispatched.some((j) => j.cwd === A), 'A still gets its start too');
+});
+
+// ─── round-robin ────────────────────────────────────────────────────────────
+
+test('round-robin: 4 projects x 3 eligible, freeSlots=4 -> exactly one job from each project', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [];
+  for (const [i, cwd] of [A, B, C, D].entries()) {
+    for (let k = 1; k <= 3; k++) jobs.push(job(`${(i + 1) * 100 + k}-${k}`, 'pending', cwd));
+  }
+  const { batch } = pickNextBatch(jobs, new Set(), 4);
+  assert.equal(batch.length, 4);
+  assert.deepEqual(new Set(batch.map((j) => j.cwd)), new Set([A, B, C, D]));
+});
+
+test('round-robin keeps cycling: 2 projects x 3 eligible, freeSlots=4, cap 2 -> 2 from each, not 3+1', () => {
+  process.env.SM_PROJECT_JOB_CAP = '2';
+  const jobs = [
+    job('101-a', 'pending', A), job('102-a', 'pending', A), job('103-a', 'pending', A),
+    job('201-b', 'pending', B), job('202-b', 'pending', B), job('203-b', 'pending', B),
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 4);
+  assert.equal(batch.length, 4);
+  assert.equal(batch.filter((j) => j.cwd === A).length, 2);
+  assert.equal(batch.filter((j) => j.cwd === B).length, 2);
+});
+
+test('the per-project cap holds ACROSS passes (a project already at cap is offered nothing more this tick)', () => {
+  process.env.SM_PROJECT_JOB_CAP = '2';
+  const jobs = [
+    job('101-a', 'pending', A), job('102-a', 'pending', A), job('103-a', 'pending', A), job('104-a', 'pending', A),
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['101-a', '102-a']);
+});
+
+test('within a project, parallelGroup ascending is still the priority hint', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [job('105-a', 'pending', A), job('101-a', 'pending', A)];
+  const { batch } = pickNextBatch(jobs, new Set(), 1);
+  assert.equal(batch[0].slug, '101-a');
+});
+
+// ─── ordering keys ──────────────────────────────────────────────────────────
+
+test('fewest running first: a project already running 1 job sorts behind one running 0, even with the older pending job', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('100-a-running', 'running', A),
+    job('101-a', 'pending', A, { queuedAt: '2026-09-01T00:00:00Z' }), // older
+    job('900-b', 'pending', B, { queuedAt: '2026-09-01T01:00:00Z' }), // newer, but B runs nothing
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(['100-a-running']), 1);
+  assert.equal(batch[0].slug, '900-b');
+});
+
+test('tiebreak on the oldest pending enqueue time when running counts are equal', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'pending', A, { queuedAt: '2026-09-01T01:00:00Z' }),
+    job('900-b', 'pending', B, { queuedAt: '2026-09-01T00:00:00Z' }), // older -> first
+  ];
+  assert.equal(pickNextBatch(jobs, new Set(), 1).batch[0].slug, '900-b');
+});
+
+test('unprovable ages sort LAST, and the final tiebreak is the cwd string', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'pending', A), // no timestamp
+    job('900-b', 'pending', B, { queuedAt: '2026-09-01T00:00:00Z' }),
+  ];
+  assert.equal(pickNextBatch(jobs, new Set(), 1).batch[0].slug, '900-b');
+  // Both unprovable -> the lexicographically smaller cwd wins: '.../burrow' (C) < '.../starry-night-ships' (A).
+  const tie = [job('900-b', 'pending', A), job('101-a', 'pending', C)];
+  assert.equal(pickNextBatch(tie, new Set(), 1).batch[0].slug, '101-a');
+});
+
+test('holds are aggregated once per slug across passes and reason is non-null only for an empty batch', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('100-dep', 'failed', A),
+    job('101-a', 'pending', A, { dependsOn: ['100-dep'] }),
+  ];
+  const r = pickNextBatch(jobs, new Set(), 3);
+  assert.equal(r.batch.length, 0);
+  assert.match(r.reason, /failed dependencies/);
+  assert.equal(r.holds.filter((h) => h.slug === '101-a').length, 1);
+});
+
+// ─── enqueueTimestamp ───────────────────────────────────────────────────────
+
+test('enqueueTimestamp resolves createdAt -> queuedAt -> statusHistory(to pending) -> startedAt -> Infinity', () => {
+  const t = (s) => Date.parse(s);
+  assert.equal(enqueueTimestamp({ createdAt: '2026-01-01T00:00:00Z', queuedAt: '2026-02-01T00:00:00Z' }), t('2026-01-01T00:00:00Z'));
+  assert.equal(enqueueTimestamp({ queuedAt: '2026-02-01T00:00:00Z' }), t('2026-02-01T00:00:00Z'));
+  assert.equal(enqueueTimestamp({ statusHistory: [{ from: null, to: 'pending', at: '2026-03-01T00:00:00Z' }] }), t('2026-03-01T00:00:00Z'));
+  assert.equal(enqueueTimestamp({ startedAt: '2026-04-01T00:00:00Z' }), t('2026-04-01T00:00:00Z'));
+  assert.equal(enqueueTimestamp({}), Infinity);
+  assert.equal(enqueueTimestamp({ queuedAt: 'garbage' }), Infinity);
+  assert.equal(enqueueTimestamp(null), Infinity);
+});
+
+// ─── findStarvedProjects (PRD 1087) ────────────────────────────────────────
+
+const NOW = Date.parse('2026-09-01T12:00:00Z');
+const H = 60 * 60_000;
+
+test('a genuinely starved project is reported with its oldest pending slug and age', () => {
+  const jobs = [
+    job('158-a', 'running', A),
+    job('3887-b', 'pending', B, { queuedAt: new Date(NOW - 3 * H).toISOString() }),
+    job('3888-b', 'pending', B, { queuedAt: new Date(NOW - 1 * H).toISOString() }),
+  ];
+  const out = findStarvedProjects(jobs, NOW, 45 * 60_000);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].cwd, B);
+  assert.equal(out[0].pendingCount, 2);
+  assert.equal(out[0].oldestPendingSlug, '3887-b');
+  assert.equal(out[0].ageMs, 3 * H);
+});
+
+test('NOT reported when no project at all is running (idle/paused machine)', () => {
+  const jobs = [job('3887-b', 'pending', B, { queuedAt: new Date(NOW - 5 * H).toISOString() })];
+  assert.deepEqual(findStarvedProjects(jobs, NOW, 45 * 60_000), []);
+});
+
+test('NOT reported when every pending job is younger than the threshold', () => {
+  const jobs = [
+    job('158-a', 'running', A),
+    job('3887-b', 'pending', B, { queuedAt: new Date(NOW - 10 * 60_000).toISOString() }),
+  ];
+  assert.deepEqual(findStarvedProjects(jobs, NOW, 45 * 60_000), []);
+});
+
+test('NOT reported when the project has a running job of its own', () => {
+  const jobs = [
+    job('158-a', 'running', A),
+    job('3880-b', 'running', B),
+    job('3887-b', 'pending', B, { queuedAt: new Date(NOW - 5 * H).toISOString() }),
+  ];
+  assert.deepEqual(findStarvedProjects(jobs, NOW, 45 * 60_000), []);
+});
+
+test('NOT reported (but warned) when the pending rows carry no provable enqueue time', () => {
+  const warns = [];
+  const orig = console.warn;
+  console.warn = (m) => warns.push(String(m));
+  try {
+    const jobs = [job('158-a', 'running', A), job('3887-b', 'pending', B)];
+    assert.deepEqual(findStarvedProjects(jobs, NOW, 45 * 60_000), []);
+    assert.ok(warns.some((w) => w.includes(B) && w.includes('cannot prove age')));
+  } finally {
+    console.warn = orig;
+  }
+});

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

@@ -0,0 +1,127 @@
+'use strict';
+
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerBatchProjectCap.test.cjs
+//
+// Regression coverage for the per-project job cap (PRD 1066): the global
+// sessionSlots pool is machine-wide and project-blind, so all of it can land
+// on one project — measured 2026-08-31 as 4 concurrent executors on one
+// project, loadavg 25.89/14 cores, silently converting that project's
+// timing-sensitive test gate into a no-op. These tests pin the fix: an INNER
+// per-cwd cap inside pickNextBatch/pickForProject, layered under the existing
+// global pool (never a replacement for it).
+
+const assert = require('node:assert/strict');
+const { pickNextBatch, pickForProject } = require('../schedulerBatch.cjs');
+
+const CWD_A = '/home/user/Projects/project-a';
+const CWD_B = '/home/user/Projects/project-b';
+
+function job(slug, status, cwd, extra = {}) {
+  return {
+    slug,
+    status,
+    cwd,
+    parallelGroup: Number(String(slug).match(/^(\d+)-/)?.[1] ?? 99),
+    dependsOn: [],
+    ...extra,
+  };
+}
+
+const ORIGINAL_CAP_ENV = process.env.SM_PROJECT_JOB_CAP;
+afterEach(() => {
+  if (ORIGINAL_CAP_ENV === undefined) delete process.env.SM_PROJECT_JOB_CAP;
+  else process.env.SM_PROJECT_JOB_CAP = ORIGINAL_CAP_ENV;
+});
+
+test('three eligible jobs in one project, default cap 2 -> exactly 2 selected', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'pending', CWD_A),
+    job('102-b', 'pending', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['101-a', '102-b']);
+});
+
+test('cap is per-project: two projects with 2 eligible jobs each (cap 2) both fire in full', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'pending', CWD_A),
+    job('102-b', 'pending', CWD_A),
+    job('201-a', 'pending', CWD_B),
+    job('202-b', 'pending', CWD_B),
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 5);
+  // A global cap of 2 would only ever admit 2 total; the per-project cap
+  // admits up to 2 PER cwd, so all 4 fire here against a 5-slot pool.
+  assert.deepEqual(
+    batch.map((j) => j.slug).sort(),
+    ['101-a', '102-b', '201-a', '202-b'],
+  );
+});
+
+test('SM_PROJECT_JOB_CAP=1 -> exactly 1 selected', () => {
+  process.env.SM_PROJECT_JOB_CAP = '1';
+  const jobs = [
+    job('101-a', 'pending', CWD_A),
+    job('102-b', 'pending', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  const { batch } = pickNextBatch(jobs, new Set(), 5);
+  assert.deepEqual(batch.map((j) => j.slug), ['101-a']);
+});
+
+test('a job deferred by the project cap stays eligible and fires once a sibling finishes', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'running', CWD_A),
+    job('102-b', 'running', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  // Tick 1: both slots for this project are already running (cap 2) -> 103-c
+  // is held, NOT failed/skipped, and remains 'pending' in the queue.
+  const running1 = new Set(['101-a', '102-b']);
+  const tick1 = pickNextBatch(jobs, running1, 5);
+  assert.deepEqual(tick1.batch, []);
+  assert.match(tick1.reason, /project-cap/);
+  assert.equal(jobs.find((j) => j.slug === '103-c').status, 'pending');
+
+  // Tick 2: 101-a finished (removed from running, its row now 'completed');
+  // 103-c is still eligible and fires on this later tick.
+  const jobsTick2 = [
+    job('101-a', 'completed', CWD_A),
+    job('102-b', 'running', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  const running2 = new Set(['102-b']);
+  const tick2 = pickNextBatch(jobsTick2, running2, 5);
+  assert.deepEqual(tick2.batch.map((j) => j.slug), ['103-c']);
+});
+
+test('cap counts an untracked running row (boot-orphan grace window), not just the tracked running Set', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    // status:running but its slug is absent from the caller's `running` Set —
+    // e.g. still alive during BOOT_ORPHAN_KILL_GRACE_MS before reconciliation
+    // catches up. Must still count against the cap.
+    job('101-a', 'running', CWD_A),
+    job('102-b', 'running', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  const { batch, reason } = pickNextBatch(jobs, new Set(), 5);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /project-cap/);
+});
+
+test('pickForProject: cap counts jobs already running in that project', () => {
+  delete process.env.SM_PROJECT_JOB_CAP;
+  const jobs = [
+    job('101-a', 'running', CWD_A),
+    job('102-b', 'running', CWD_A),
+    job('103-c', 'pending', CWD_A),
+  ];
+  const { batch, reason } = pickForProject(jobs, new Set(['101-a', '102-b']), 5);
+  assert.deepEqual(batch, []);
+  assert.match(reason, /project-cap/);
+});