claude-code-session-manager 0.85.0 → 0.87.0

package/src/main/__tests__/prdLocationsArchived.test.cjs

@@ -21,7 +21,7 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
@@ -150,3 +150,45 @@ test('scheduler.cjs exports candidateArchivedPrdsDirs alongside candidatePrdsDir
   expect(Array.isArray(candidatePrdsDirs())).toBe(true);
   expect(Array.isArray(candidateArchivedPrdsDirs())).toBe(true);
 });
+
+test('resolveArchivedPrdsDirs: a prds-archived/ dir created inside an ALREADY-EXISTING Epic (the archiveCompletedPrd shape — does not bump the Epics root mtime) is bounded-stale, not stale forever', async () => {
+  // archiveCompletedPrd (scheduler.cjs) creates `epics/<id>/prds-archived/`
+  // as a new entry INSIDE an already-existing `epics/<id>/` dir — unlike a
+  // brand-new Epic's `prds/` (created in the same mkdirSync call as
+  // `epics/<id>/` itself), this does NOT bump the Epics root's own mtime,
+  // so the mtime-keyed freshness key alone would never invalidate. The
+  // short TTL backstop (same idiom as activeSessions.cjs's cwdScanCache)
+  // bounds that blind spot instead of leaving it stale indefinitely.
+  vi.useFakeTimers();
+  try {
+    const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-blindspot-projects-'));
+    tmpDirs.push(projectsDir);
+    const projectCwd = await mkEpicProject();
+    tmpDirs.push(projectCwd);
+
+    const epicId = `blindspot-epic-${process.pid}`;
+    const epicPrdsDir = resolveEpicPrdWriteDir(projectCwd, epicId);
+    fs.mkdirSync(epicPrdsDir, { recursive: true }); // Epic already exists, well before archiving.
+
+    const projDir = path.join(projectsDir, 'blindspot-project');
+    fs.mkdirSync(projDir, { recursive: true });
+    fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+
+    // Prime the cache — no prds-archived/ dir exists yet.
+    const before = resolveArchivedPrdsDirs(90, { projectsDir });
+    const epicArchiveDir = path.join(epicPrdsDir, '..', 'prds-archived');
+    expect(before).not.toContain(path.resolve(epicArchiveDir));
+
+    // The archiveCompletedPrd shape: a NEW prds-archived/ dir appears inside
+    // the ALREADY-EXISTING epic dir. This does not change the Epics root's
+    // own mtime.
+    fs.mkdirSync(epicArchiveDir, { recursive: true });
+
+    // Bounded staleness is acceptable — but it must actually be bounded.
+    vi.advanceTimersByTime(31_000);
+    const after = resolveArchivedPrdsDirs(90, { projectsDir });
+    expect(after.map((d) => path.resolve(d))).toContain(path.resolve(epicArchiveDir));
+  } finally {
+    vi.useRealTimers();
+  }
+});

package/src/main/__tests__/prdSetDisposition.test.cjs

@@ -0,0 +1,222 @@
+/**
+ * prdSetDisposition.test.cjs — scheduler wave-disposition PRD:
+ * scheduler.remote.setPrdDisposition (backing the renderer's
+ * `schedule:set-prd-disposition` IPC action) is how a human changes an
+ * already-written PRD's disposition from the Scheduler UI — promoting an
+ * appended wave to its own head, or re-attaching a head behind another
+ * chain. Validates via prdDisposition.cjs's computeDispositionRewrite
+ * (cycle-safety, running/completed rows untouched) before delegating the
+ * actual write to the SAME remote.updatePrd every other PRD edit path uses.
+ *
+ * Mirrors prdUpdateDependsOn.test.cjs's HOME-isolation fixture.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdSetDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+let config;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-set-disposition-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+  config = require('../config.cjs');
+
+  if (!scheduler.PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${scheduler.PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  config.addAllowedRoot(cwd);
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  const prdsDir = path.join(opsRoot, 'scheduler', 'epics', 'test-epic-1', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+  queueStore.bustCwdCache();
+  return { cwd, prdsDir, stateDir };
+}
+
+function writePrd(prdsDir, filename, cwd, extraFrontmatter = '') {
+  fs.writeFileSync(
+    path.join(prdsDir, filename),
+    `---\ntitle: ${filename}\ncwd: ${cwd}\nestimateMinutes: 10\ncreatedVia: scheduler-api\n${extraFrontmatter}---\n\n# Goal\nDo the thing.\n`,
+    'utf8',
+  );
+}
+
+/** Seeds a queue.json row for `slug` with the given status — setPrdDisposition
+ *  (like updatePrd) reads job status off the live queue, not the PRD file. */
+function seedQueueJob(stateDir, slug, status) {
+  fs.writeFileSync(
+    path.join(stateDir, 'queue.json'),
+    JSON.stringify({ jobs: [{ slug, status, title: slug, cwd: '' }] }, null, 2),
+    'utf8',
+  );
+  queueStore.bustCwdCache();
+}
+
+test('append sets the expected edges', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-append-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd);
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'append',
+      dependsOn: ['3-wave1-tail'],
+    });
+
+    expect(result.ok).toBe(true);
+    const written = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(written).toMatch(/^dependsOn: \[3-wave1-tail\]$/m);
+    expect(written).toMatch(/^disposition: append$/m);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('new-head sets none', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-new-head-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(true);
+    const written = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(written).not.toContain('dependsOn');
+    expect(written).toMatch(/^disposition: new-head$/m);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('promoting a wave to a head removes exactly its root edges', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-promote-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '5-other-head.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(true);
+    const promoted = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(promoted).not.toContain('dependsOn');
+    // The unrelated sibling head is untouched by this call.
+    const other = fs.readFileSync(path.join(prdsDir, '5-other-head.md'), 'utf8');
+    expect(other).not.toContain('dependsOn');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('a change that would create a cycle is rejected, and nothing is written', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-cycle-');
+  try {
+    writePrd(prdsDir, '3-a.md', cwd, 'dependsOn: [b]\n');
+    writePrd(prdsDir, '4-b.md', cwd);
+    const before = fs.readFileSync(path.join(prdsDir, '4-b.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-b',
+      cwd,
+      disposition: 'append',
+      dependsOn: ['3-a'],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/cycle/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-b.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('running rows are untouched', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-set-disposition-running-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+    seedQueueJob(stateDir, '4-wave2-root', 'running');
+    const before = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/running/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('completed rows are untouched', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-set-disposition-completed-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+    seedQueueJob(stateDir, '4-wave2-root', 'completed');
+    const before = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/completed/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/pty-session-open-telemetry.test.cjs

@@ -0,0 +1,96 @@
+/**
+ * pty-session-open-telemetry.test.cjs — proves the `session.open` counter tap
+ * (telemetryCounters.trackSessionOpen(), wired at pty.cjs's spawn() call
+ * site) actually fires on a real fresh PTY spawn, and documents/locks in the
+ * deliberate choice that a reattach (same tabId already registered in this
+ * process — a renderer HMR reload, or switching back to an Epic's Terminal
+ * pane that's already running) does NOT fire it a second time, since it's
+ * the same underlying session, not a new one (see pty.cjs's spawn() comment
+ * above the reattach branch, and telemetry.md).
+ *
+ * Same monkey-patch-node-pty pattern as pty-epic-worktree-spawn-cwd.test.cjs
+ * — no existing test in this repo mocks a module import.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/pty-session-open-telemetry.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let manager;
+let nodePty;
+let originalSpawn;
+let telemetryCounters;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-pty-sessionopen-home-'));
+  process.env.HOME = tmpHome;
+  ({ manager } = require('../pty.cjs'));
+  nodePty = require('node-pty');
+  originalSpawn = nodePty.spawn;
+  telemetryCounters = require('../lib/telemetryCounters.cjs');
+});
+
+afterAll(() => {
+  nodePty.spawn = originalSpawn;
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  nodePty.spawn = originalSpawn;
+  manager.sessions.clear();
+  manager.buffers.clear();
+  manager.killed.clear();
+  vi.restoreAllMocks();
+});
+
+function fakeProc() {
+  return {
+    pid: 4242,
+    exitCode: null,
+    onData: () => {},
+    onExit: () => {},
+    resize: () => {},
+    kill: () => {},
+    write: () => {},
+  };
+}
+
+test('a fresh spawn() fires trackSessionOpen exactly once', () => {
+  const spy = vi.spyOn(telemetryCounters, 'trackSessionOpen').mockImplementation(() => {});
+  const cwd = fs.mkdtempSync(path.join(tmpHome, 'sm-pty-fresh-'));
+  const tabId = 'fresh-tab-1';
+  nodePty.spawn = () => fakeProc();
+
+  manager.spawn({ tabId, cwd, cols: 80, rows: 24 });
+
+  expect(spy).toHaveBeenCalledTimes(1);
+  manager.kill(tabId);
+});
+
+test('a reattach to an already-registered tabId does NOT fire trackSessionOpen again', () => {
+  const spy = vi.spyOn(telemetryCounters, 'trackSessionOpen').mockImplementation(() => {});
+  const cwd = fs.mkdtempSync(path.join(tmpHome, 'sm-pty-reattach-'));
+  const tabId = 'reattach-tab-1';
+  nodePty.spawn = () => fakeProc();
+
+  const first = manager.spawn({ tabId, cwd, cols: 80, rows: 24 });
+  expect(first.reattached).toBe(false);
+  expect(spy).toHaveBeenCalledTimes(1);
+
+  const second = manager.spawn({ tabId, cwd, cols: 80, rows: 24 });
+  expect(second.reattached).toBe(true);
+  // Still exactly one call — the reattach path returns before the counter
+  // tap, by design (same session, not a new one).
+  expect(spy).toHaveBeenCalledTimes(1);
+
+  manager.kill(tabId);
+});

package/src/main/__tests__/queue-health-verdict.test.cjs

@@ -0,0 +1,170 @@
+/**
+ * queue-health-verdict.test.cjs — classifyQueueHealth is the Scheduler
+ * page's queue-health header: the single honest read of WHY a queue looks
+ * stale (saturated slots / blocked dependencies / genuinely idle / the
+ * dispatch driver itself stalled / a decision to pause / an open launch
+ * circuit breaker), reusing classifyQueueStarvation so the header can never
+ * disagree with the starvation watchdog's own read of the same state.
+ *
+ * Run: timeout 180 npx vitest run src/main/__tests__/queue-health-verdict.test.cjs
+ */
+
+'use strict';
+
+import { test, afterAll } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// HOME before require: every state path is baked from os.homedir() at load.
+const originalHome = process.env.HOME;
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'queue-health-test-'));
+process.env.HOME = tmpHome;
+fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager'), { recursive: true });
+fs.mkdirSync(path.join(tmpHome, '.claude', 'projects'), { recursive: true });
+
+const { classifyQueueHealth, QUEUE_STARVATION_MS } = require('../scheduler.cjs');
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+const CWD = '/home/bilko/Projects/starry-night-ships';
+const NOW = Date.parse('2026-09-13T20:00:00.000Z');
+const LONG = QUEUE_STARVATION_MS + 60_000;
+
+test('saturated: jobs running, zero free slots', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'running', startedAt: new Date(NOW - LONG).toISOString(), dependsOn: [] },
+    { slug: '2-b', cwd: CWD, status: 'pending', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(['1-a']),
+    freeSlots: 0, totalSlots: 4, lastDispatchAttemptAtMs: NOW, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'saturated');
+  assert.equal(v.runningCount, 1);
+  assert.equal(v.totalSlots, 4);
+  // Dispatchable/blocked counts stay real numbers even in a kind whose
+  // headline cause is slot saturation, not dependency shape — the header
+  // must still be able to show them alongside the verdict.
+  assert.equal(v.pending, 1);
+  assert.equal(v.dispatchable, 1);
+  assert.deepEqual(v.blockedChains, []);
+});
+
+test('blocked: every pending row terminates in a failed dependency', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'failed', dependsOn: [] },
+    { slug: '2-b', cwd: CWD, status: 'pending', dependsOn: ['1-a'] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - 5_000, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'blocked');
+  assert.equal(v.pending, 1);
+  assert.equal(v.dispatchable, 0);
+  assert.equal(v.blockedChains.length, 1);
+  assert.deepEqual(v.blockedChains[0].blockedBy, ['1-a']);
+});
+
+test('idle: nothing pending', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'completed', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'idle');
+  assert.equal(v.pending, 0);
+  assert.equal(v.dispatchable, 0);
+});
+
+test('stalled: dispatchable work, nothing running, driver idle past threshold', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'pending', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - LONG, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'stalled');
+  assert.equal(v.dispatchable, 1);
+  assert.ok(v.idleMs >= QUEUE_STARVATION_MS);
+});
+
+test('running: dispatchable work, nothing running yet, but driver has not been idle long enough to call it a stall', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'pending', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - 5_000, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'running');
+});
+
+test('paused: a decision, not a stall — takes priority over everything else', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'pending', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: { reason: 'manual', since: NOW }, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 0, totalSlots: 4, lastDispatchAttemptAtMs: NOW - LONG, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'paused');
+  assert.equal(v.reason, 'manual');
+  assert.equal(v.pending, 1);
+  assert.equal(v.dispatchable, 1);
+});
+
+test('launch-blocked: an open circuit breaker for a persona a pending row actually uses', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'pending', dependsOn: [], agentType: 'dev-lead' },
+  ];
+  const launchBlocks = {
+    'dev-lead': { kind: 'model_config_rejected', attempts: 3, hint: 'update the CLI', until: null },
+  };
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - LONG, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.kind, 'launch-blocked');
+  assert.equal(v.agentType, 'dev-lead');
+  assert.equal(v.pending, 1);
+  assert.equal(v.dispatchable, 1);
+});
+
+test('launch-blocked is scoped: a breaker for a persona nothing pending here uses does not fire', () => {
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'pending', dependsOn: [], agentType: 'dev-lead' },
+  ];
+  const launchBlocks = {
+    'architect': { kind: 'model_config_rejected', attempts: 3, hint: 'update the CLI', until: null },
+  };
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - 5_000, now: NOW, cwd: CWD,
+  });
+  assert.notEqual(v.kind, 'launch-blocked');
+});
+
+test('needsReviewCount and cwd scoping: another project\'s rows never leak into this scope\'s counts', () => {
+  const other = '/home/bilko/Projects/session-manager';
+  const jobs = [
+    { slug: '1-a', cwd: CWD, status: 'needs_review', dependsOn: [] },
+    { slug: '2-b', cwd: CWD, status: 'pending', dependsOn: [] },
+    { slug: '3-c', cwd: other, status: 'pending', dependsOn: [] },
+    { slug: '4-d', cwd: other, status: 'needs_review', dependsOn: [] },
+  ];
+  const v = classifyQueueHealth({
+    jobs, paused: null, launchBlocks: {}, runningSet: new Set(),
+    freeSlots: 4, totalSlots: 4, lastDispatchAttemptAtMs: NOW - 5_000, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.pending, 1);
+  assert.equal(v.needsReviewCount, 1);
+});

package/src/main/__tests__/queue-starvation-per-project.test.cjs

@@ -0,0 +1,147 @@
+/**
+ * queue-starvation-per-project.test.cjs — classifyQueueStarvation's
+ * runningCount used to be fed the MACHINE-WIDE runningSet.size, so one
+ * long-lived job in ANY project disarmed the starvation watchdog for EVERY
+ * other project on the box. Observed live 2026-09-12: a job in
+ * starry-night-ships ran 80+ minutes while two other projects sat
+ * starved/blocked for hours — the watchdog never fired once because "work is
+ * flowing" was true somewhere else.
+ *
+ * classifyQueueStarvationByProject partitions jobs by cwd (the same grouping
+ * computeBlockedChains already uses) and evaluates each project on its OWN
+ * running/pending/idle evidence.
+ *
+ * Run: timeout 180 npx vitest run src/main/__tests__/queue-starvation-per-project.test.cjs
+ */
+
+'use strict';
+
+import { test, afterAll } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// HOME before require: every state path is baked from os.homedir() at load.
+// beforeAll runs AFTER module evaluation, so this assignment must stay at
+// top level — see pollLoop-dispatch-on-failure.test.cjs:40-56 for the
+// beforeAll/afterAll pattern this restore mirrors.
+const originalHome = process.env.HOME;
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'starve-per-project-test-'));
+process.env.HOME = tmpHome;
+fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager'), { recursive: true });
+fs.mkdirSync(path.join(tmpHome, '.claude', 'projects'), { recursive: true });
+
+const {
+  classifyQueueStarvation,
+  classifyQueueStarvationByProject,
+  QUEUE_STARVATION_MS,
+} = require('../scheduler.cjs');
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+const PROJECT_A = '/home/bilko/Projects/starry-night-ships';
+const PROJECT_B = '/home/bilko/Projects/session-manager';
+const NOW = Date.parse('2026-09-12T20:00:00.000Z');
+const LONG = QUEUE_STARVATION_MS + 60_000;
+const idleFor = (ms) => NOW - ms;
+
+test('one long-running job in project A no longer masks project B being starved', () => {
+  const jobs = [
+    { slug: '246-neptune', cwd: PROJECT_A, status: 'running', dependsOn: [] },
+    { slug: '1169-x', cwd: PROJECT_B, status: 'pending', dependsOn: [] },
+    { slug: '1170-y', cwd: PROJECT_B, status: 'pending', dependsOn: [] },
+  ];
+
+  // Pre-change shape: the machine-wide runningCount (1, from project A) hides
+  // project B's starvation entirely. This is the bug this PRD fixes — assert
+  // it still holds for the old, single-project entry point so a revert of
+  // the new driver is caught by this test going red.
+  const globalVerdict = classifyQueueStarvation({
+    jobs,
+    paused: false,
+    runningCount: 1,
+    lastRunAtMs: idleFor(LONG),
+    now: NOW,
+  });
+  assert.equal(globalVerdict, null);
+
+  // Per-project: project B has 0 of its OWN rows running and 2 dispatchable
+  // pending rows idle past the threshold — it must be reported as starved
+  // regardless of project A's running job.
+  const verdicts = classifyQueueStarvationByProject({
+    jobs,
+    paused: false,
+    runningSet: new Set(),
+    lastRunAtMs: idleFor(LONG),
+    now: NOW,
+  });
+  const forB = verdicts.find((v) => v.cwd === PROJECT_B);
+  assert.ok(forB, 'expected a verdict naming project B cwd');
+  assert.equal(forB.kind, 'starved');
+  assert.equal(forB.pending, 2);
+  assert.equal(forB.dispatchable, 2);
+
+  // Project A itself has a running row — never starved on its own account.
+  const forA = verdicts.find((v) => v.cwd === PROJECT_A);
+  assert.equal(forA, undefined);
+});
+
+test('a project fully blocked behind a terminal dependency is "blocked", not "starved", even while another project is starved in the same pass', () => {
+  const jobs = [
+    // Project A: every pending row sits behind a failed dependency — a tick
+    // cannot help this project, it needs a human/heal pass.
+    { slug: '206-lava-ape', cwd: PROJECT_A, status: 'failed', dependsOn: [] },
+    { slug: '207-body', cwd: PROJECT_A, status: 'pending', dependsOn: ['206-lava-ape'] },
+    // Project B: dispatchable right now — genuinely starved.
+    { slug: '1171-z', cwd: PROJECT_B, status: 'pending', dependsOn: [] },
+  ];
+
+  const verdicts = classifyQueueStarvationByProject({
+    jobs,
+    paused: false,
+    runningSet: new Set(),
+    lastRunAtMs: idleFor(LONG),
+    now: NOW,
+  });
+
+  const forA = verdicts.find((v) => v.cwd === PROJECT_A);
+  assert.ok(forA, 'expected a verdict for the blocked project');
+  assert.equal(forA.kind, 'blocked');
+
+  const forB = verdicts.find((v) => v.cwd === PROJECT_B);
+  assert.ok(forB, 'expected a verdict for the starved project');
+  assert.equal(forB.kind, 'starved');
+});
+
+test('the whole-machine paused short-circuit is preserved for every project', () => {
+  const jobs = [
+    { slug: '1169-x', cwd: PROJECT_A, status: 'pending', dependsOn: [] },
+    { slug: '1170-y', cwd: PROJECT_B, status: 'pending', dependsOn: [] },
+  ];
+  const verdicts = classifyQueueStarvationByProject({
+    jobs,
+    paused: { reason: 'rate_limit', resumeAt: null },
+    runningSet: new Set(),
+    lastRunAtMs: idleFor(LONG),
+    now: NOW,
+  });
+  assert.deepEqual(verdicts, []);
+});
+
+test('a running-set membership (not just a status:"running" row) counts as that project having flowing work', () => {
+  const jobs = [
+    { slug: '9001-a', cwd: PROJECT_A, status: 'pending', dependsOn: [] },
+  ];
+  const verdicts = classifyQueueStarvationByProject({
+    jobs,
+    paused: false,
+    runningSet: new Set(['9001-a']),
+    lastRunAtMs: idleFor(LONG),
+    now: NOW,
+  });
+  assert.deepEqual(verdicts, []);
+});