claude-code-session-manager 0.86.0 → 0.88.0

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

@@ -1,11 +1,7 @@
 /**
- * projectPages.test.cjs — unit tests for projectPages.cjs's read-only get(),
- * including the regression this PRD's AC calls out explicitly: adding the
- * 5th 'brief' lens must not make every pre-existing 4-lens project suddenly
- * read as having no output at all — and the shipped-default fallback added
- * by the "project-home-hosted-html-spec" PRD: a project with no generated
- * output gets the build-time default home.html (isDefault: true) instead of
- * the bare `{ output: null }` empty-state signal.
+ * projectPages.test.cjs — projectPages.cjs's read-only surface: get() of the
+ * single project-pages/home.html ({html|null, mtimeMs}) plus the refcounted
+ * watcher that pushes `project-pages:changed`.
  *
  * Run: timeout 120 npx vitest run src/main/__tests__/projectPages.test.cjs
  */
@@ -20,8 +16,6 @@ const path = require('node:path');
 const config = require('../config.cjs');
 const {
   get,
-  DEFAULT_HOME_PATH,
-  readDefaultHomeHtml,
   attachWindow,
   watchOutput,
   unwatchOutput,
@@ -31,6 +25,7 @@ const {
 
 const tmpDirs = [];
 afterEach(async () => {
+  closeAllOutputWatchers();
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
     await fsp.rm(d, { recursive: true, force: true });
@@ -44,179 +39,98 @@ async function mkTmpCwd() {
   return dir;
 }
 
-function outputDir(cwd) {
-  return path.join(cwd, 'session-manager-operations', 'project-pages', 'output');
+function pagesDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'project-pages');
 }
 
-function writeOutput(cwd, lenses, manifest = { generatedAt: '2026-08-02T00:00:00.000Z' }) {
-  const dir = outputDir(cwd);
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest));
-  for (const [lens, html] of Object.entries(lenses)) {
-    fs.writeFileSync(path.join(dir, `${lens}.html`), html);
-  }
+function writeHome(cwd, html) {
+  fs.mkdirSync(pagesDir(cwd), { recursive: true });
+  fs.writeFileSync(path.join(pagesDir(cwd), 'home.html'), html);
 }
 
-test('the shipped default asset exists on disk at a fixed app-relative path', () => {
-  expect(fs.existsSync(DEFAULT_HOME_PATH)).toBe(true);
-  expect(path.isAbsolute(DEFAULT_HOME_PATH)).toBe(true);
-});
-
-test('(a) generated output present: get() returns it with isDefault false', async () => {
-  const cwd = await mkTmpCwd();
-  writeOutput(cwd, {
-    home: 'HOME',
-    marketing: 'MARKETING',
-    feature: 'FEATURE',
-    architecture: 'ARCHITECTURE',
-    brief: 'BRIEF',
-  });
-  const result = await get({ cwd });
-  expect(result.output).not.toBeNull();
-  expect(result.output.home).toBe('HOME');
-  expect(result.output.brief).toBe('BRIEF');
-  expect(result.output.generatedAt).toBe('2026-08-02T00:00:00.000Z');
-  expect(result.output.isDefault).toBe(false);
-});
+function makeFakeWindow(sent) {
+  return {
+    isDestroyed: () => false,
+    webContents: {
+      isDestroyed: () => false,
+      isCrashed: () => false,
+      send: (channel, payload) => sent.push({ channel, payload }),
+    },
+  };
+}
 
-// The regression this PRD's AC explicitly guards against: a project that
-// generated its output BEFORE the 'brief' lens existed has the original 4
-// files but no brief.html — that must still read as "has output", not the
-// shipped-default fallback, and `brief` must simply be absent from the payload.
-test('4 original lenses present but brief.html missing still returns generated output, with brief omitted', async () => {
-  const cwd = await mkTmpCwd();
-  writeOutput(cwd, {
-    home: 'HOME',
-    marketing: 'MARKETING',
-    feature: 'FEATURE',
-    architecture: 'ARCHITECTURE',
-  });
-  const result = await get({ cwd });
-  expect(result.output).not.toBeNull();
-  expect(result.output.home).toBe('HOME');
-  expect(result.output.marketing).toBe('MARKETING');
-  expect(result.output.feature).toBe('FEATURE');
-  expect(result.output.architecture).toBe('ARCHITECTURE');
-  expect(result.output.brief).toBeUndefined();
-  expect(result.output.isDefault).toBe(false);
-});
+async function waitFor(predicate, ms = 5000) {
+  const deadline = Date.now() + ms;
+  while (!predicate() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
 
-// (b) output absent → returns the shipped default with isDefault true.
-test('(b) no manifest at all: get() returns the shipped default with isDefault true', async () => {
+test('get() returns the home.html text and its mtimeMs', async () => {
   const cwd = await mkTmpCwd();
+  writeHome(cwd, '<html>HOME</html>');
   const result = await get({ cwd });
-  expect(result.output).not.toBeNull();
-  expect(result.output.isDefault).toBe(true);
-  expect(result.output.generatedAt).toBeNull();
-  expect(result.output.home).toBe(readDefaultHomeHtml());
-  expect(result.output.marketing).toBeUndefined();
-  expect(result.output.feature).toBeUndefined();
-  expect(result.output.architecture).toBeUndefined();
+  expect(result.html).toBe('<html>HOME</html>');
+  expect(typeof result.mtimeMs).toBe('number');
+  expect(Object.keys(result).sort()).toEqual(['html', 'mtimeMs']);
 });
 
-test('one of the required 4 lenses missing falls back to the shipped default, even if brief.html exists', async () => {
+test('get() with no home.html returns {html: null, mtimeMs: null} — no shipped default', async () => {
   const cwd = await mkTmpCwd();
-  writeOutput(cwd, {
-    home: 'HOME',
-    marketing: 'MARKETING',
-    feature: 'FEATURE',
-    // architecture.html deliberately missing
-    brief: 'BRIEF',
-  });
-  const result = await get({ cwd });
-  expect(result.output).not.toBeNull();
-  expect(result.output.isDefault).toBe(true);
-  expect(result.output.home).toBe(readDefaultHomeHtml());
+  expect(await get({ cwd })).toEqual({ html: null, mtimeMs: null });
 });
 
-test('manifest with no generatedAt string falls back to the shipped default', async () => {
+test('get() ignores legacy manifest/lens files — only home.html counts', async () => {
   const cwd = await mkTmpCwd();
-  writeOutput(
-    cwd,
-    { home: 'HOME', marketing: 'MARKETING', feature: 'FEATURE', architecture: 'ARCHITECTURE', brief: 'BRIEF' },
-    {},
-  );
-  const result = await get({ cwd });
-  expect(result.output).not.toBeNull();
-  expect(result.output.isDefault).toBe(true);
+  const out = path.join(pagesDir(cwd), 'output');
+  fs.mkdirSync(out, { recursive: true });
+  fs.writeFileSync(path.join(out, 'home.html'), 'OLD');
+  fs.writeFileSync(path.join(out, 'manifest.json'), '{"generatedAt":"2026-08-02T00:00:00.000Z"}');
+  expect(await get({ cwd })).toEqual({ html: null, mtimeMs: null });
 });
 
-// (c) the default path resolution does not depend on cwd.
-test('(c) default fallback content is identical regardless of which project cwd requests it', async () => {
-  const cwdA = await mkTmpCwd();
-  const cwdB = await mkTmpCwd();
-  const resultA = await get({ cwd: cwdA });
-  const resultB = await get({ cwd: cwdB });
-  expect(resultA.output.isDefault).toBe(true);
-  expect(resultB.output.isDefault).toBe(true);
-  expect(resultA.output.home).toBe(resultB.output.home);
-  expect(resultA.output.home).toBe(readDefaultHomeHtml());
-});
-
-test('the shipped default is honest: no fabricated project-specific content, and prompts Generate My Project Home', () => {
-  const html = readDefaultHomeHtml();
-  expect(html).toContain('Generate My Project Home');
-  expect(html.toLowerCase()).not.toContain('lorem ipsum');
-});
-
-// ── ephemeral cwd: get() must fall back, never throw/reject ────────────────
-test('get() with an ephemeral cwd (os.tmpdir() itself) returns the shipped default instead of throwing', async () => {
+test('get() with an ephemeral cwd (os.tmpdir() itself) returns null instead of throwing', async () => {
   config.addAllowedRoot(os.tmpdir());
-  const result = await get({ cwd: os.tmpdir() });
-  expect(result.output).not.toBeNull();
-  expect(result.output.isDefault).toBe(true);
-});
-
-// ── watcher ──────────────────────────────────────────────────────────────
-afterEach(() => {
-  closeAllOutputWatchers();
+  expect(await get({ cwd: os.tmpdir() })).toEqual({ html: null, mtimeMs: null });
 });
 
 test('watchOutput() on an ephemeral cwd refuses instead of crashing', async () => {
   config.addAllowedRoot(os.tmpdir());
-  const result = await watchOutput(os.tmpdir());
-  expect(result).toEqual({ ok: false, reason: 'ephemeral' });
+  expect(await watchOutput(os.tmpdir())).toEqual({ ok: false, reason: 'ephemeral' });
   expect(_outputWatchers.size).toBe(0);
 });
 
-test('watchOutput() pushes project-pages:changed when manifest.json appears, and unwatchOutput() tears it down', async () => {
+test('watchOutput() is refcounted: two watches share one watcher, closed at the last unwatch', async () => {
+  const cwd = await mkTmpCwd();
+  expect(await watchOutput(cwd)).toEqual({ ok: true });
+  expect(await watchOutput(cwd)).toEqual({ ok: true });
+  expect(_outputWatchers.size).toBe(1);
+  unwatchOutput(cwd);
+  expect(_outputWatchers.size).toBe(1);
+  unwatchOutput(cwd);
+  expect(_outputWatchers.size).toBe(0);
+});
+
+test('watchOutput() pushes {cwd, html, mtimeMs} on project-pages:changed when home.html lands, ignoring sibling files', async () => {
   const cwd = await mkTmpCwd();
   const sent = [];
-  const fakeWindow = {
-    isDestroyed: () => false,
-    webContents: {
-      isDestroyed: () => false,
-      isCrashed: () => false,
-      send: (channel, payload) => sent.push({ channel, payload }),
-    },
-  };
-  attachWindow(fakeWindow);
+  attachWindow(makeFakeWindow(sent));
 
-  const watchResult = await watchOutput(cwd);
-  expect(watchResult).toEqual({ ok: true });
+  expect(await watchOutput(cwd)).toEqual({ ok: true });
   expect(_outputWatchers.size).toBe(1);
 
-  writeOutput(cwd, {
-    home: 'HOME',
-    marketing: 'MARKETING',
-    feature: 'FEATURE',
-    architecture: 'ARCHITECTURE',
-  });
-
-  // Bounded poll for the debounced (awaitWriteFinish) push instead of a bare
-  // sleep — chokidar's stability window is 50ms, so this gives it generous
-  // headroom without hanging the suite on a broken watcher.
-  const deadline = Date.now() + 5000;
-  while (sent.length === 0 && Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
+  fs.writeFileSync(path.join(pagesDir(cwd), 'summary.json'), '{}');
+  writeHome(cwd, '<html>HOME</html>');
+  await waitFor(() => sent.length > 0);
 
   expect(sent.length).toBeGreaterThan(0);
+  for (const msg of sent) expect(msg.channel).toBe('project-pages:changed');
   const last = sent[sent.length - 1];
-  expect(last.channel).toBe('project-pages:changed');
   expect(last.payload.cwd).toBe(fs.realpathSync(cwd));
-  expect(last.payload.output.isDefault).toBe(false);
-  expect(last.payload.output.home).toBe('HOME');
+  expect(last.payload.html).toBe('<html>HOME</html>');
+  expect(typeof last.payload.mtimeMs).toBe('number');
+  // summary.json alone must not have produced a push carrying no html
+  expect(sent.every((m) => m.payload.html === '<html>HOME</html>')).toBe(true);
 
   unwatchOutput(cwd);
   expect(_outputWatchers.size).toBe(0);

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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: 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, lastRunAtMs: NOW - 5_000, now: NOW, cwd: CWD,
+  });
+  assert.equal(v.pending, 1);
+  assert.equal(v.needsReviewCount, 1);
+});

package/src/main/__tests__/queue-starvation-dispatch-driver.test.cjs

@@ -23,14 +23,16 @@
 
 'use strict';
 
-import { test, expect, beforeAll, afterAll } from 'vitest';
+import { test, expect, beforeAll, afterAll, vi } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const claudeStub = require('../../../tests/helpers/claudeStub.cjs');
 
 let tmpHome;
 let originalHome;
 let originalClaudeBin;
+let originalAutofixDisable;
 let scheduler;
 let queueStore;
 
@@ -41,21 +43,26 @@ let queueStore;
 // guard then makes runQueueStarvationWatchdog return null for a reason that
 // has nothing to do with what that test is actually checking.
 function writeClaudeStub() {
-  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-starve-driver-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
-  const body = `
+  return claudeStub.writeClaudeStub({ body: `
     process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok\\nSCHEDULER_VERDICT: PASS' }) + '\\n');
     process.exit(0);
-  `;
-  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
-  return stubPath;
+  ` });
 }
 
 beforeAll(() => {
   originalHome = process.env.HOME;
   originalClaudeBin = process.env.SM_CLAUDE_BIN;
+  originalAutofixDisable = process.env.SM_AUTOFIX_DISABLE;
   tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-starve-driver-'));
   process.env.HOME = tmpHome;
   process.env.SM_CLAUDE_BIN = writeClaudeStub();
+  // The forced tick's dispatched job has no PRD file and makes no commit, so
+  // it lands 'needs_review' and (without this) immediately fires a
+  // fire-and-forget auto-fix investigation — ANOTHER real claude spawn, under
+  // its own queue row, that can still be in runningSet by the time the next
+  // test in this file reads it (see writeClaudeStub's header comment; this
+  // closes the same gap one layer further down the cascade).
+  process.env.SM_AUTOFIX_DISABLE = '1';
   fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager'), { recursive: true });
   fs.mkdirSync(path.join(tmpHome, '.claude', 'projects'), { recursive: true });
   scheduler = require('../scheduler.cjs');
@@ -66,6 +73,8 @@ afterAll(() => {
   process.env.HOME = originalHome;
   if (originalClaudeBin === undefined) delete process.env.SM_CLAUDE_BIN;
   else process.env.SM_CLAUDE_BIN = originalClaudeBin;
+  if (originalAutofixDisable === undefined) delete process.env.SM_AUTOFIX_DISABLE;
+  else process.env.SM_AUTOFIX_DISABLE = originalAutofixDisable;
   fs.rmSync(tmpHome, { recursive: true, force: true });
 });
 
@@ -81,7 +90,7 @@ function mkProject() {
   return { cwd, slug };
 }
 
-test('the watchdog reads idleness from lastDispatchAttemptAt, not the always-fresh poll timestamp', async () => {
+test('ticks that launch nothing do NOT refresh the clock — idleness reads lastRunAt, not lastDispatchAttemptAt', async () => {
   const { cwd, slug } = mkProject();
   await scheduler.writeQueue({
     jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
@@ -90,18 +99,37 @@ test('the watchdog reads idleness from lastDispatchAttemptAt, not the always-fre
   });
 
   const now = Date.now();
-  // The exact shape of the live incident: the poll timestamp is seconds old
-  // (the poll loop itself keeps succeeding), but nothing has actually
-  // attempted a dispatch in 40 minutes.
+  // The structural repeat of f18e161: the loop ticks every 30 s (so
+  // lastDispatchAttemptAt is seconds old) but nothing has LAUNCHED in 40
+  // minutes (lastRunAt). The boot stamp is aged out so it can't mask it.
+  const bootedAtMs = now - 3 * 60 * 60_000;
   const state = {
     ...queueStore.readMergedSync(),
-    lastRunAt: new Date(now - 5_000).toISOString(),
-    lastDispatchAttemptAt: new Date(now - 40 * 60_000).toISOString(),
+    lastRunAt: new Date(now - 40 * 60_000).toISOString(),
+    lastDispatchAttemptAt: new Date(now - 5_000).toISOString(),
   };
 
-  const verdict = await scheduler.runQueueStarvationWatchdog(state, { now });
+  const verdict = await scheduler.runQueueStarvationWatchdog(state, { now, bootedAtMs });
   expect(verdict).not.toBeNull();
   expect(verdict.kind).toBe('starved');
+
+  // The watchdog's forced tick above dispatches this job for real (see
+  // writeClaudeStub's header comment) — tickQueue doesn't await the spawned
+  // process to completion, so runningSet can still hold this slug for a
+  // moment after this test's own `await` returns. Under a fast, unloaded
+  // machine the stub exits before the NEXT test's watchdog call ever reads
+  // runningSet, which is racy rather than deterministic — under a heavily
+  // loaded machine (e.g. the full test:unit run) it reliably loses,
+  // stranding a slug in runningSet and making
+  // classifyQueueStarvation's `runningCount > 0` guard return null for the
+  // next test, which has nothing to do with what that test actually checks.
+  // Wait for this job to actually leave 'running' before moving on.
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    const row = queueStore.readMergedSync().jobs.find((j) => j.slug === slug);
+    if (!row || row.status !== 'running') break;
+    await new Promise((r) => setTimeout(r, 25));
+  }
 });
 
 test('a wedged cancelToken does not block the watchdog from actually driving a tick', async () => {
@@ -117,21 +145,34 @@ test('a wedged cancelToken does not block the watchdog from actually driving a t
   // applyPauseCleared reset (a direct state write, not the clearPause()
   // helper) — leaving the token permanently cancelled with paused: null.
   await scheduler.setPaused('rate_limit', null);
-  await scheduler.writeQueue({
-    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
-    config: {},
-    paused: null,
-  });
+  // setPaused's own broadcast({flush:true}) and a still-draining
+  // fire-and-forget mutate() from the PRIOR test's forced dispatch (e.g.
+  // tickQueue's own finally-chained call) both write through the SAME
+  // serialized mutate() queue this raw writeQueue() call bypasses — one of
+  // them can land AFTER this write and re-persist the stale paused:{...}
+  // object it read before this clear, purely by losing the race. Re-assert
+  // paused:null until it actually sticks, rather than trusting one write to
+  // win a race against mutations this test doesn't control the timing of.
+  const pausedClearDeadline = Date.now() + 5_000;
+  do {
+    await scheduler.writeQueue({
+      jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
+      config: {},
+      paused: null,
+    });
+    if (!queueStore.readMergedSync().paused) break;
+    await new Promise((r) => setTimeout(r, 25));
+  } while (Date.now() < pausedClearDeadline);
 
   const before = queueStore.readMergedSync().lastDispatchAttemptAt;
 
   const now = Date.now();
   const state = {
     ...queueStore.readMergedSync(),
-    lastRunAt: null,
+    lastRunAt: new Date(now - 40 * 60_000).toISOString(),
     lastDispatchAttemptAt: new Date(now - 40 * 60_000).toISOString(),
   };
-  const verdict = await scheduler.runQueueStarvationWatchdog(state, { now });
+  const verdict = await scheduler.runQueueStarvationWatchdog(state, { now, bootedAtMs: now - 3 * 60 * 60_000 });
   expect(verdict.kind).toBe('starved');
 
   // tickQueue() only stamps lastDispatchAttemptAt once it gets PAST the
@@ -141,3 +182,59 @@ test('a wedged cancelToken does not block the watchdog from actually driving a t
   expect(after).not.toBe(before);
   expect(after).not.toBeNull();
 });
+
+const NOW = Date.parse('2026-09-18T12:00:00.000Z');
+const CWD = '/tmp/sm-starve-clock-project';
+const pendingRow = (slug, extra = {}) => ({ slug, cwd: CWD, status: 'pending', dependsOn: [], ...extra });
+const idleFor = (ms) => NOW - ms;
+
+test('a real launch (fresh lastRunAt) refreshes the clock; so do a pause clear and a boot', () => {
+  const jobs = [pendingRow('a')];
+  const base = { jobs, paused: null, runningCount: 0, now: NOW };
+  const stale = idleFor(3 * 60 * 60_000);
+  expect(scheduler.classifyQueueStarvation({ ...base, lastRunAtMs: stale }).kind).toBe('starved');
+  expect(scheduler.classifyQueueStarvation({ ...base, lastRunAtMs: idleFor(5_000) })).toBeNull();
+  expect(scheduler.classifyQueueStarvation({ ...base, lastRunAtMs: stale, lastPauseClearedAtMs: idleFor(5_000) })).toBeNull();
+  expect(scheduler.classifyQueueStarvation({ ...base, lastRunAtMs: stale, schedulerBootedAtMs: idleFor(5_000) })).toBeNull();
+  expect(scheduler.dispatchIdleMs({ lastRunAtMs: 1000, lastPauseClearedAtMs: 4000, schedulerBootedAtMs: 2000, now: 10_000 })).toBe(6000);
+  expect(scheduler.dispatchIdleMs({ now: 10_000 })).toBe(Infinity);
+});
+
+test('rows held by a launch breaker / lease read blocked, not starved (per project too)', () => {
+  const jobs = [pendingRow('a'), pendingRow('b')];
+  const args = { jobs, paused: null, runningCount: 0, lastRunAtMs: idleFor(3 * 60 * 60_000), now: NOW };
+  expect(scheduler.classifyQueueStarvation(args).kind).toBe('starved');
+  const partial = scheduler.classifyQueueStarvation({ ...args, heldSlugs: new Set(['a']) });
+  expect(partial.kind).toBe('starved');
+  expect(partial.dispatchable).toBe(1);
+  const all = scheduler.classifyQueueStarvation({ ...args, heldSlugs: new Map([['a', 'x'], ['b', 'y']]) });
+  expect(all.kind).toBe('blocked');
+  expect(all.dispatchable).toBe(0);
+  const byProject = scheduler.classifyQueueStarvationByProject({
+    jobs, paused: null, runningSet: new Set(), lastRunAtMs: args.lastRunAtMs, heldSlugs: new Set(['a', 'b']), now: NOW,
+  });
+  expect(byProject.map((v) => v.kind)).toEqual(['blocked']);
+});
+
+test('the watchdog latches: one forced tick / audit per starve episode, re-armed by threshold or running-count change', async () => {
+  const cwd = '/tmp/sm-starve-latch-project';
+  const jobs = [{ slug: 'latch-a', cwd, status: 'pending', dependsOn: [] }];
+  const opts = { bootedAtMs: NOW - 3 * 60 * 60_000 };
+  const state = { jobs, paused: null, lastRunAt: new Date(NOW - 40 * 60_000).toISOString() };
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  const starvedLogs = () => warn.mock.calls.filter((c) => String(c[0]).includes('QUEUE STARVED')).length;
+  try {
+    // The row exists only in this hand-built state, never in queue.json, so
+    // the forced tick has nothing real to launch.
+    expect((await scheduler.runQueueStarvationWatchdog(state, { now: NOW, ...opts })).kind).toBe('starved');
+    expect(starvedLogs()).toBe(1);
+    // Same episode, well inside QUEUE_STARVATION_MS: still reported, not re-forced.
+    expect((await scheduler.runQueueStarvationWatchdog(state, { now: NOW + 60_000, ...opts })).kind).toBe('starved');
+    expect(starvedLogs()).toBe(1);
+    // QUEUE_STARVATION_MS elapsed again: a new episode.
+    await scheduler.runQueueStarvationWatchdog(state, { now: NOW + scheduler.QUEUE_STARVATION_MS + 1, ...opts });
+    expect(starvedLogs()).toBe(2);
+  } finally {
+    warn.mockRestore();
+  }
+});