claude-code-session-manager 0.82.0 → 0.84.0

package/scripts/hooks/guard-inline-implementation.cjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * guard-inline-implementation.cjs — PreToolUse hook that denies a raw
+ * Write/Edit/NotebookEdit tool call against application source (`src/`,
+ * `scripts/`, `plugins/`, `bin/`) when the calling session resolves to an
+ * Epic whose Mission tag is `feature` or `bug`.
+ *
+ * Why this exists: CLAUDE.md already tells an Actor to decompose feature/bug
+ * work into scheduled PRDs via /develop rather than implementing inline, but
+ * a prompt-level instruction is advisory — nothing stops an Epic from
+ * reaching for the Write tool directly anyway. guard-prd-writes.cjs proved
+ * the lever: a PreToolUse hook sits OUTSIDE the app and can intercept the
+ * tool call before it touches disk, which an in-app ownership check
+ * structurally cannot do. This is the sibling guard for the same reason,
+ * applied to application source instead of scheduler/ PRDs.
+ *
+ * This is a NUDGE, not an ownership law — unlike guard-prd-writes.cjs (which
+ * is deliberately fail-closed), this hook fails OPEN twice over: on any
+ * internal error, and whenever the calling Epic can't be resolved to a
+ * feature/bug tag at all. A false deny blocks a human who deliberately asked
+ * for an inline fix, which is worse than an occasional missed catch.
+ *
+ * ── Escape hatches ───────────────────────────────────────────────────────
+ * - Set `SM_ALLOW_INLINE_IMPLEMENTATION=1` in the environment the session
+ *   runs under to allow everything, for the whole process.
+ * - Set a truthy `allowInlineImplementation` field on the Epic's record in
+ *   `session-manager-operations/prompt-sessions/active-index.json` to allow
+ *   everything for that one Epic only.
+ *
+ * ── Install (per-project, NOT machine-wide) ─────────────────────────────
+ * Adopting project: press "Fix it" on the "Inline-implementation guard hook
+ * installed" row of the New Epic readiness banner — it runs
+ * installInlineImplementationGuard() (src/main/lib/delegationReadiness.cjs),
+ * which merges a hook referencing THIS repo's own absolute script path into
+ * `<your project>/.claude/settings.json`'s `Write|Edit|NotebookEdit` matcher,
+ * the same reference-not-vendor path guard-prd-writes.cjs uses. Hand-editing
+ * settings.json (below) is a degraded last resort for when the app isn't
+ * running — add the command alongside guard-prd-writes.cjs in the SAME
+ * `Write|Edit|NotebookEdit` matcher's `hooks` array:
+ *
+ *   {
+ *     "hooks": {
+ *       "PreToolUse": [
+ *         {
+ *           "matcher": "Write|Edit|NotebookEdit",
+ *           "hooks": [
+ *             { "type": "command", "command": "node scripts/hooks/guard-prd-writes.cjs" },
+ *             { "type": "command", "command": "node scripts/hooks/guard-inline-implementation.cjs" }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * ── Uninstall ────────────────────────────────────────────────────────────
+ * Remove this hook's entry from `.claude/settings.json`. The script is inert
+ * with no settings.json entry pointing at it.
+ *
+ * ── Contract ─────────────────────────────────────────────────────────────
+ * - Reads a PreToolUse payload on stdin: { session_id, tool_name, tool_input,
+ *   cwd, ... }.
+ * - Only inspects Write/Edit/NotebookEdit; every other tool is allowed by
+ *   construction.
+ * - Resolves `session_id` against `claudeSessionId` in
+ *   `<cwd>/session-manager-operations/prompt-sessions/active-index.json`'s
+ *   `sessions` map. An unresolvable session is ALLOWED — this hook only ever
+ *   denies when it can positively confirm a feature/bug Epic.
+ * - Only denies when the resolved Epic's `tag` is exactly `feature` or `bug`.
+ *   Any other tag (`discussion`, `build`, etc.) is ALLOWED.
+ * - Only denies when the target path resolves under the project's `src/`,
+ *   `scripts/`, `plugins/`, or `bin/` directories. Paths outside the project
+ *   cwd, and anything under `session-manager-operations/`, are ALLOWED.
+ * - Fails OPEN: any internal error (malformed stdin JSON, unreadable index,
+ *   unexpected shape) is logged to stderr and allowed through.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const SOURCE_DIRS = ['src', 'scripts', 'plugins', 'bin'];
+const DENY_TAGS = new Set(['feature', 'bug']);
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function targetPathFor(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  if (toolName === 'NotebookEdit') return toolInput.notebook_path ?? null;
+  return toolInput.file_path ?? null;
+}
+
+function isApplicationSource(cwd, absPath) {
+  const rel = path.relative(cwd, absPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return false; // outside cwd
+  const topLevel = rel.split(path.sep)[0];
+  return SOURCE_DIRS.includes(topLevel);
+}
+
+/**
+ * The PreToolUse payload's `cwd` is the CLI process's actual spawn cwd. For
+ * an Epic running in its default isolated `git worktree` (gitWorktree.cjs,
+ * epicSpawnCwd.cjs — "both the Terminal PTY and headless Chat spawn cwd
+ * resolve to it"), that is a throwaway checkout under os.tmpdir(), which
+ * never contains `session-manager-operations/` — the ops root always lives
+ * in the real project tree (see gitWorktree.cjs's "ops-root hazard" header:
+ * "spawn cwd = worktree dir, ops-root cwd = real project cwd, always").
+ * Resolve back to the real project cwd via git's shared `.git` dir before
+ * giving up, so this guard isn't silently inert for every Epic running in
+ * its default worktree.
+ */
+function resolveOpsRootCwd(rawCwd) {
+  if (fs.existsSync(path.join(rawCwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json'))) {
+    return rawCwd;
+  }
+  try {
+    const commonDir = execFileSync(
+      'git',
+      ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { cwd: rawCwd, encoding: 'utf8', timeout: 5000 },
+    ).trim();
+    if (!commonDir) return rawCwd;
+    return path.basename(commonDir) === '.git' ? path.dirname(commonDir) : commonDir;
+  } catch {
+    return rawCwd;
+  }
+}
+
+function resolveEpicTag(cwd, sessionId) {
+  if (!sessionId) return null;
+  const indexPath = path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+  if (!fs.existsSync(indexPath)) return null;
+  const raw = fs.readFileSync(indexPath, 'utf8');
+  const index = JSON.parse(raw);
+  const sessions = index && typeof index === 'object' ? index.sessions : null;
+  if (!sessions || typeof sessions !== 'object') return null;
+  for (const record of Object.values(sessions)) {
+    if (record && record.claudeSessionId === sessionId) return record;
+  }
+  return null;
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.exit(0);
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-inline-implementation] malformed stdin JSON, failing open: ${e?.message}`);
+    return allow();
+  }
+
+  try {
+    if (process.env.SM_ALLOW_INLINE_IMPLEMENTATION === '1') return allow();
+
+    const toolName = payload.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'NotebookEdit') {
+      return allow();
+    }
+
+    const rawPath = targetPathFor(toolName, payload.tool_input);
+    if (!rawPath || typeof rawPath !== 'string') return allow();
+
+    const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+    const absPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(cwd, rawPath);
+
+    if (!isApplicationSource(cwd, absPath)) return allow();
+
+    const sessionId = typeof payload.session_id === 'string' ? payload.session_id : null;
+    const opsRootCwd = resolveOpsRootCwd(cwd);
+    const epic = resolveEpicTag(opsRootCwd, sessionId);
+    if (!epic) return allow(); // unresolvable session — allow by construction
+
+    if (epic.allowInlineImplementation) return allow();
+    if (!DENY_TAGS.has(epic.tag)) return allow();
+
+    const reason = [
+      `Direct ${toolName} to application source ("${path.relative(cwd, absPath)}") is discouraged inside a "${epic.tag}" Epic.`,
+      'Feature and bug work should be decomposed and queued via /develop rather than implemented inline, so it runs through the scheduler with acceptance criteria and review.',
+      'If this inline edit is deliberate, set SM_ALLOW_INLINE_IMPLEMENTATION=1 in the environment, or set allowInlineImplementation: true on this Epic\'s record in active-index.json, and retry.',
+    ].join(' ');
+    return deny(reason);
+  } catch (e) {
+    console.error(`[guard-inline-implementation] internal error, failing open: ${e?.message}`);
+    return allow();
+  }
+}
+
+main().catch((e) => {
+  console.error(`[guard-inline-implementation] unhandled error, failing open: ${e?.message}`);
+  allow();
+});

package/scripts/hooks/guard-prd-writes.cjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * guard-prd-writes.cjs — PreToolUse hook that denies a raw Write/Edit/
+ * NotebookEdit tool call whose target path falls under
+ * `**\/session-manager-operations/scheduler/**`.
+ *
+ * Why this exists: opsOwnership.cjs's assertOpsWrite already enforces the
+ * single-writer law for scheduler/ (see src/main/lib/opsOwnership.cjs), but
+ * it can only guard the app's OWN in-process write helpers — it is
+ * structurally incapable of stopping an agent that reaches for the Write
+ * tool directly, which is exactly what CLAUDE.md itself documents as the
+ * degraded last-resort path. A PreToolUse hook is the one lever that sits
+ * OUTSIDE the app and can intercept that call before it ever touches disk:
+ * the harness adjudicates the tool call, not the app.
+ *
+ * Together with the create-time provenance stamp (prdCreate.cjs's
+ * buildPrdBody) and reconcile()'s quarantine of any PRD missing that stamp
+ * (scheduler.cjs), this makes the scheduler_create_prd/scheduler_update_prd/
+ * scheduler_archive_prd MCP tools the only path IN, from outside the app
+ * (this hook) and from inside it (the provenance gate) alike.
+ *
+ * ── Install (per-project, NOT machine-wide) ─────────────────────────────
+ * Add to this project's `.claude/settings.json` (not `~/.claude/settings.json`
+ * — project scope only, so the guard applies to sessions run against THIS
+ * repo, not every project on the machine):
+ *
+ *   {
+ *     "hooks": {
+ *       "PreToolUse": [
+ *         {
+ *           "matcher": "Write|Edit|NotebookEdit",
+ *           "hooks": [
+ *             { "type": "command", "command": "node scripts/hooks/guard-prd-writes.cjs" }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * ── Adopting this hook in a DIFFERENT (non-session-manager) project ──────
+ * DON'T HAND-WRITE THIS. Session Manager installs it: open New Session in
+ * that project and press "Fix it" on the readiness banner's PRD-write-guard
+ * row (src/main/lib/delegationReadiness.cjs's installPrdWriteGuard, which
+ * merges into any existing hooks block instead of clobbering it).
+ *
+ * The standardized approach is REFERENCE, not vendor — do NOT copy this file
+ * into the adopting repo. Vendoring drifts (it already did, with exactly one
+ * adopter), and what is being guarded is session-manager-operations/scheduler/,
+ * Session Manager's own territory inside someone else's repo, so the
+ * enforcement logic belongs with the owner.
+ *
+ * This file lives in the session-manager repo, so a relative
+ * `node scripts/hooks/guard-prd-writes.cjs` command only resolves when the
+ * hook runs with THIS repo as cwd. Pasting that relative string into another
+ * project yields a hook that exits non-zero WITHOUT code 2 — a non-blocking
+ * error — so it silently guards nothing. Any other project's
+ * `.claude/settings.json` must reference this file by its ABSOLUTE path:
+ *
+ *   {
+ *     "hooks": {
+ *       "PreToolUse": [
+ *         {
+ *           "matcher": "Write|Edit|NotebookEdit",
+ *           "hooks": [
+ *             {
+ *               "type": "command",
+ *               "command": "node /home/bilko/Projects/session-manager/scripts/hooks/guard-prd-writes.cjs"
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * This is still opt-in per project, same as above — never auto-install this
+ * into every project's settings without the human choosing to add it there.
+ *
+ * Roll out to another project by copying this file + the same settings.json
+ * entry into that project — deliberately not published as a global/user-
+ * scoped hook so a project can opt in individually (see this PRD's
+ * Implementation notes: "scope the hook to the session-manager repo first").
+ *
+ * ── Uninstall ────────────────────────────────────────────────────────────
+ * Remove the `PreToolUse` entry above from `.claude/settings.json`. The
+ * script is inert with no settings.json entry pointing at it — deleting the
+ * file itself is optional and has no other effect.
+ *
+ * ── Contract ─────────────────────────────────────────────────────────────
+ * - Reads a PreToolUse payload on stdin: { tool_name, tool_input, cwd, ... }.
+ * - Reads (any tool that isn't a mutation, and any Read/Grep/Glob/Bash) is
+ *   NEVER denied — this hook only inspects Write/Edit/NotebookEdit calls;
+ *   everything else is allowed by construction (the matcher already scopes
+ *   this hook to those three tools, but the tool_name check below is a
+ *   second, defense-in-depth gate in case the matcher is ever widened).
+ * - A fix-plan PRD (`NN-fix-*.md`) is exempt: scheduler.cjs's own
+ *   spawnInvestigation probe writes that file directly by design (a trusted,
+ *   scheduler-spawned internal loop, not an agent/human authoring a PRD) —
+ *   see scheduler.cjs's isFixPlanSlug and reconcile()'s matching exemption.
+ * - Fails OPEN: any internal error (malformed stdin JSON, an unreadable
+ *   payload, an unexpected shape) is logged to stderr and allowed through —
+ *   a broken guard must never brick the whole Write/Edit tool.
+ */
+'use strict';
+
+const path = require('node:path');
+
+const SCHEDULER_SEGMENT = `${path.sep}session-manager-operations${path.sep}scheduler${path.sep}`;
+const FIX_PLAN_RE = /^\d+-fix-.*\.md$/;
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    // Fail open if stdin never closes/errors for some reason.
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+/** Extract the single filesystem path a Write/Edit/NotebookEdit call targets. */
+function targetPathFor(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  if (toolName === 'NotebookEdit') return toolInput.notebook_path ?? null;
+  return toolInput.file_path ?? null;
+}
+
+/** MCP tool name to point the agent at, based on the attempted operation. */
+function suggestedToolFor(toolName, absPath) {
+  const isArchived = absPath.includes(`${path.sep}prds-archived${path.sep}`);
+  if (isArchived) return 'mcp__session-manager-scheduler__scheduler_archive_prd';
+  // Write = the file doesn't exist yet from the agent's point of view (a
+  // brand-new PRD); Edit/NotebookEdit = mutating an existing file in place.
+  if (toolName === 'Write') return 'mcp__session-manager-scheduler__scheduler_create_prd';
+  return 'mcp__session-manager-scheduler__scheduler_update_prd';
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.exit(0);
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-prd-writes] malformed stdin JSON, failing open: ${e?.message}`);
+    return allow();
+  }
+
+  try {
+    const toolName = payload.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'NotebookEdit') {
+      return allow();
+    }
+
+    const rawPath = targetPathFor(toolName, payload.tool_input);
+    if (!rawPath || typeof rawPath !== 'string') return allow();
+
+    const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+    const absPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(cwd, rawPath);
+
+    if (!absPath.includes(SCHEDULER_SEGMENT)) return allow();
+
+    const base = path.basename(absPath);
+    if (FIX_PLAN_RE.test(base)) return allow();
+
+    const suggested = suggestedToolFor(toolName, absPath);
+    const reason = [
+      `Direct ${toolName} to a session-manager-operations/scheduler/ path is blocked.`,
+      `PRDs must be authored through the scheduler API, not a raw file write — use the "${suggested}" MCP tool instead.`,
+      'If the Session Manager app is not running (the admin API this MCP tool talks to only exists while it is), the degraded fallback documented in the develop skill applies: hand-write the file as a last resort and say so visibly in your report.',
+    ].join(' ');
+    return deny(reason);
+  } catch (e) {
+    console.error(`[guard-prd-writes] internal error, failing open: ${e?.message}`);
+    return allow();
+  }
+}
+
+main().catch((e) => {
+  console.error(`[guard-prd-writes] unhandled error, failing open: ${e?.message}`);
+  allow();
+});

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

@@ -0,0 +1,64 @@
+/**
+ * epicMintTelemetryTap.test.cjs — ensureEpic() fires the 'epic.create'
+ * counter exactly once on a genuine mint (created: true), and not when an
+ * existing open Epic is joined instead.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/epicMintTelemetryTap.test.cjs
+ */
+'use strict';
+
+import { test, expect, afterEach, beforeEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const countersPath = require.resolve('../lib/telemetryCounters.cjs');
+const epicMintPath = require.resolve('../lib/epicMint.cjs');
+
+let calls;
+const tmpDirs = [];
+
+beforeEach(() => {
+  calls = [];
+  require.cache[countersPath] = {
+    id: countersPath,
+    filename: countersPath,
+    loaded: true,
+    exports: { trackEpicCreate: () => calls.push(true) },
+  };
+  delete require.cache[epicMintPath];
+});
+
+afterEach(async () => {
+  delete require.cache[countersPath];
+  delete require.cache[epicMintPath];
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkCwd() {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-epicmint-telemetry-cwd-'));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+test('a genuine mint fires epic.create exactly once', async () => {
+  const { ensureEpic, MINT_AUTHORITY_NEW_EPIC_UI } = require('../lib/epicMint.cjs');
+  const cwd = await mkCwd();
+  const result = await ensureEpic(cwd, { mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI, goalText: 'do the thing' });
+  expect(result.created).toBe(true);
+  expect(calls).toEqual([true]);
+});
+
+test('joining an existing open Epic does NOT fire epic.create', async () => {
+  const { ensureEpic, MINT_AUTHORITY_NEW_EPIC_UI } = require('../lib/epicMint.cjs');
+  const cwd = await mkCwd();
+  const minted = await ensureEpic(cwd, { mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI, goalText: 'do the thing' });
+  calls.length = 0;
+
+  const joined = await ensureEpic(cwd, { epicId: minted.epicId, goalText: 'do the thing' });
+  expect(joined.created).toBe(false);
+  expect(calls).toEqual([]);
+});

package/src/main/__tests__/health-delegation-chain.test.cjs

@@ -86,7 +86,7 @@ test('failing check with no fix omits the "(fix: ...)" suffix', () => {
 test('end-to-end: check() reports delegation_chain for this repo, expected to pass here', async () => {
   const status = await check();
   expect(status.components.delegation_chain).toBeDefined();
-  expect(status.components.delegation_chain.checks).toHaveLength(7);
+  expect(status.components.delegation_chain.checks).toHaveLength(8);
   const ids = status.components.delegation_chain.checks.map((c) => c.id);
   expect(ids).toEqual([
     'scheduler-mcp',
@@ -96,6 +96,7 @@ test('end-to-end: check() reports delegation_chain for this repo, expected to pa
     'agent-personas',
     'prd-write-guard',
     'destructive-git-guard',
+    'inline-implementation-guard',
   ]);
   // This repo registers the scheduler MCP at user scope (~/.claude.json) and
   // wires guard-prd-writes in .claude/settings.json, and no longer carries a

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

@@ -0,0 +1,84 @@
+/**
+ * health-queue-dispatch.test.cjs — `npm run health` must report non-GREEN
+ * when there is at least one DISPATCHABLE pending job (reusing
+ * classifyQueueStarvation's own 'starved' verdict, not merely "pending"),
+ * nothing running, and no dispatch attempt in a long time — the exact shape
+ * of the 2026-09-11 incident (27 pending across two projects, 0 running, for
+ * days, every other health surface reporting green). A dependsOn-blocked
+ * queue must NOT trip this the same way: ticking can't fix a blocked chain,
+ * so it stays GREEN (reported as 'blocked' instead, distinctly).
+ *
+ * Exercises evaluateQueueDispatchHealth() directly — pure, no fs — matching
+ * every other evaluate* helper's test pattern in this file (see
+ * health-usage-poller.test.cjs's header).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-queue-dispatch.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluateQueueDispatchHealth, DISPATCH_STALL_THRESHOLD_MS } = require('../health.cjs');
+
+const CWD = '/home/bilko/Projects/starry-night-ships';
+const NOW = Date.parse('2026-09-11T12:00:00.000Z');
+const idleFor = (ms) => new Date(NOW - ms).toISOString();
+
+test('a dispatchable pending job, 0 running, stale past the threshold — non-GREEN, starved', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result.ok).toBe(false);
+  expect(result.starved).toBe(true);
+  expect(result.dispatchable).toBe(1);
+  expect(result.message).toMatch(/dispatch appears stuck/);
+});
+
+test('every pending row behind a blocked dependsOn chain stays GREEN, reported as blocked', () => {
+  const state = {
+    jobs: [
+      { slug: 'dead', cwd: CWD, status: 'failed', dependsOn: [] },
+      { slug: 'blocked-child', cwd: CWD, status: 'pending', dependsOn: ['dead'] },
+    ],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result.ok).toBe(true);
+  expect(result.blocked).toBe(true);
+  expect(result.starved).toBeUndefined();
+  expect(result.message).toMatch(/blocked/);
+});
+
+test('healthy queue (recent dispatch attempt) is GREEN with no verdict', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result).toEqual({ ok: true });
+});
+
+test('nothing pending is GREEN regardless of how stale the dispatch timestamp is', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'completed' }],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 0, NOW);
+  expect(result).toEqual({ ok: true });
+});
+
+test('work already running is GREEN — the queue is flowing', () => {
+  const state = {
+    jobs: [{ slug: 'a', cwd: CWD, status: 'pending', dependsOn: [] }],
+    paused: null,
+    lastDispatchAttemptAt: idleFor(DISPATCH_STALL_THRESHOLD_MS + 60_000),
+  };
+  const result = evaluateQueueDispatchHealth(state, 1, NOW);
+  expect(result).toEqual({ ok: true });
+});