claude-code-session-manager 0.75.3 → 0.77.0

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

@@ -175,3 +175,154 @@ test('projectStateDir fails closed on an ops-internal cwd, naming the offending
 // The writeSplit half of this guard lives in opsRootNestedWrite.test.cjs —
 // it must override HOME before requiring queueStore (writeSplit persists
 // machine state to a homedir path), which cannot be done from this file.
+
+// ─── the third incident: a cwd INSIDE a linked git worktree ─────────────────
+//
+// Verified live 2026-09-01 in starry-night-ships: a transcript's last `cwd`
+// row pointed at `/tmp/session-manager-epic-worktrees/<hash>/<epicId>` — an
+// absolute, existing directory, so it was accepted as a project and the real
+// project root (`/home/bilko/Projects/starry-night-ships`) never entered the
+// list at all. `worktreeMainRootOf` reverses a linked worktree's `.git` FILE
+// (`gitdir: <main>/.git/worktrees/<name>`) back to `<main>`.
+
+const { worktreeMainRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('../gitWorktree.cjs');
+
+// A worktree's MAIN tree root must live outside os.tmpdir() for these fixtures
+// to double as a realistic "real project" for the tmp-drop-guard tests below
+// (a real project is never itself under /tmp — only the linked worktree is).
+// `test-results/` is already gitignored in this repo.
+const NON_TMP_SCRATCH_ROOT = path.join(process.cwd(), 'test-results', 'opsroot-fixtures');
+
+async function mkNonTmpDir(prefix) {
+  fs.mkdirSync(NON_TMP_SCRATCH_ROOT, { recursive: true });
+  return fsp.mkdtemp(path.join(NON_TMP_SCRATCH_ROOT, prefix));
+}
+
+async function makeWorktreeFixture() {
+  const main = await mkNonTmpDir('sm-opsroot-main-');
+  tmpDirs.push(main);
+  fs.mkdirSync(path.join(main, '.git'), { recursive: true });
+  const worktree = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-worktree-'));
+  tmpDirs.push(worktree);
+  const worktreeName = 'sm-epic-abc123';
+  const worktreeGitFile = path.join(worktree, '.git');
+  const adminDir = path.join(main, '.git', 'worktrees', worktreeName);
+  fs.mkdirSync(adminDir, { recursive: true });
+  // Real `git worktree add` writes this back-reference (the admin dir's own
+  // `gitdir` file points at the linked worktree's `.git` FILE) — required by
+  // worktreeMainRootOf's round-trip check so a crafted `.git` file elsewhere
+  // on disk can't redirect resolution to an arbitrary directory.
+  fs.writeFileSync(path.join(adminDir, 'gitdir'), `${worktreeGitFile}\n`, 'utf8');
+  fs.writeFileSync(worktreeGitFile, `gitdir: ${adminDir}\n`, 'utf8');
+  return { main, worktree };
+}
+
+test('worktreeMainRootOf resolves a linked worktree .git FILE back to the main tree root', async () => {
+  const { main, worktree } = await makeWorktreeFixture();
+  expect(worktreeMainRootOf(worktree)).toBe(main);
+});
+
+test('worktreeMainRootOf returns the ancestor unchanged when .git is a real directory', async () => {
+  const main = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-plain-main-'));
+  tmpDirs.push(main);
+  fs.mkdirSync(path.join(main, '.git'), { recursive: true });
+  const nested = path.join(main, 'src', 'main', 'lib');
+  fs.mkdirSync(nested, { recursive: true });
+  expect(worktreeMainRootOf(nested)).toBe(main);
+});
+
+test('worktreeMainRootOf returns null on a garbled .git file instead of throwing', async () => {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-garbled-'));
+  tmpDirs.push(dir);
+  fs.writeFileSync(path.join(dir, '.git'), 'not a gitdir line at all', 'utf8');
+  expect(worktreeMainRootOf(dir)).toBeNull();
+
+  const dir2 = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-garbled2-'));
+  tmpDirs.push(dir2);
+  fs.writeFileSync(path.join(dir2, '.git'), 'gitdir: /some/path/without/the/marker\n', 'utf8');
+  expect(worktreeMainRootOf(dir2)).toBeNull();
+});
+
+test('worktreeMainRootOf refuses a crafted .git file that redirects to an arbitrary directory with no back-reference', async () => {
+  // A `.git` FILE is an ordinary file — nothing stops an untrusted repo from
+  // shipping one at a nested path pointing anywhere. Without verifying the
+  // admin dir's own `gitdir` back-reference, this would let a crafted repo
+  // redirect activeSessions' project-root resolution (and therefore
+  // queueStore's ops-root writes) to an attacker-chosen absolute directory.
+  const arbitraryTarget = await mkNonTmpDir('sm-opsroot-arbitrary-target-');
+  tmpDirs.push(arbitraryTarget);
+  const attackerDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-attacker-'));
+  tmpDirs.push(attackerDir);
+  // No admin dir/back-reference file exists under arbitraryTarget/.git/worktrees/.
+  fs.writeFileSync(
+    path.join(attackerDir, '.git'),
+    `gitdir: ${path.join(arbitraryTarget, '.git', 'worktrees', 'x')}\n`,
+    'utf8',
+  );
+  expect(worktreeMainRootOf(attackerDir)).toBeNull();
+});
+
+test('worktreeMainRootOf refuses a crafted .git file whose admin dir exists but back-references a DIFFERENT worktree', async () => {
+  const { main } = await makeWorktreeFixture();
+  const attackerDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-attacker2-'));
+  tmpDirs.push(attackerDir);
+  // Points at a REAL admin dir (main's own), but that admin dir's gitdir
+  // back-reference points at the ORIGINAL worktree, not attackerDir.
+  fs.writeFileSync(
+    path.join(attackerDir, '.git'),
+    `gitdir: ${path.join(main, '.git', 'worktrees', 'sm-epic-abc123')}\n`,
+    'utf8',
+  );
+  expect(worktreeMainRootOf(attackerDir)).toBeNull();
+});
+
+test('worktreeMainRootOf returns null for a plain non-git directory', async () => {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-nogit-'));
+  tmpDirs.push(dir);
+  expect(worktreeMainRootOf(dir)).toBeNull();
+});
+
+test('projectRootOf resolves a worktree cwd to the main tree root', async () => {
+  const { main, worktree } = await makeWorktreeFixture();
+  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  expect(projectRootOf(worktree)).toBe(main);
+});
+
+test('projectRootOf resolves a cwd nested inside a worktree\'s OWN ops tree to the main root', async () => {
+  const { main, worktree } = await makeWorktreeFixture();
+  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  const nestedOps = path.join(worktree, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(nestedOps, { recursive: true });
+  expect(projectRootOf(nestedOps)).toBe(main);
+});
+
+test('activeProjectCwds resolves a worktree cwd to the real project and drops unresolvable tmp cwds', async () => {
+  const { main, worktree } = await makeWorktreeFixture();
+  // A bare, .git-less directory directly under the managed epic-worktree
+  // root — the shape a torn-down or mid-teardown worktree leaves behind.
+  // worktreeMainRootOf can't resolve it (no .git), so only the drop-guard's
+  // prefixDropRoots check keeps it out of the project list.
+  fs.mkdirSync(WORKTREE_KIND_CONFIG.epic.root, { recursive: true });
+  const bareWorktreeRoot = await fsp.mkdtemp(path.join(WORKTREE_KIND_CONFIG.epic.root, 'sm-opsroot-bare-'));
+  tmpDirs.push(bareWorktreeRoot);
+  const projectsDir = await mkProjectsDir({
+    resolvable: worktree,
+    unresolvable: bareWorktreeRoot,
+    bareTmpdir: os.tmpdir(),
+  });
+
+  const cwds = activeProjectCwds(Infinity, { projectsDir });
+  expect(cwds).toContain(main);
+  expect(cwds).not.toContain(worktree);
+  expect(cwds).not.toContain(bareWorktreeRoot);
+  expect(cwds).not.toContain(os.tmpdir());
+});
+
+test('a main-tree root resolved from a worktree dedupes against a directly-observed cwd for the same project', async () => {
+  const { main, worktree } = await makeWorktreeFixture();
+  const projectsDir = await mkProjectsDir({ direct: main, viaWorktree: worktree });
+
+  const cwds = activeProjectCwds(Infinity, { projectsDir });
+  expect(cwds.filter((c) => c === main)).toHaveLength(1);
+});

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

@@ -0,0 +1,149 @@
+'use strict';
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/opsRootResolve.test.cjs
+//
+// PRD 1082 — opsOwnership.cjs is THE ONE ops-root resolver. Every reader and
+// writer of `<project>/session-manager-operations/` builds its path through
+// resolveProjectRoot / resolveOpsRoot / opsPath, which normalize a worktree or
+// ops-internal cwd to the real project and refuse an ephemeral one. Before
+// this, each namespace did its own `path.join(cwd, 'session-manager-
+// operations', ...)`, so the worktree-cwd hazard had to be fixed one call site
+// at a time (2026-08-30, PRDs 1073/1074/1081).
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  resolveProjectRoot, resolveOpsRoot, opsPath, assertOpsWrite, OPS_ROOT_DIR,
+} = require('../opsOwnership.cjs');
+const { KIND_CONFIG } = require('../gitWorktree.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    await fsp.rm(tmpDirs.pop(), { recursive: true, force: true }).catch(() => {});
+  }
+});
+
+/** A fake main tree (has a real `.git` DIRECTORY) outside os.tmpdir(). */
+async function mkMainTree() {
+  const base = path.join(os.homedir(), '.cache', 'sm-opsroot-resolve-tests');
+  fs.mkdirSync(base, { recursive: true });
+  const main = await fsp.mkdtemp(path.join(base, 'main-'));
+  tmpDirs.push(main);
+  fs.mkdirSync(path.join(main, '.git'), { recursive: true });
+  return main;
+}
+
+/** A linked worktree of `main` (a `.git` FILE + the admin back-reference git writes). */
+async function mkLinkedWorktree(main) {
+  const worktree = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-resolve-wt-'));
+  tmpDirs.push(worktree);
+  const name = 'sm-epic-test';
+  const adminDir = path.join(main, '.git', 'worktrees', name);
+  fs.mkdirSync(adminDir, { recursive: true });
+  const gitFile = path.join(worktree, '.git');
+  fs.writeFileSync(path.join(adminDir, 'gitdir'), `${gitFile}\n`);
+  fs.writeFileSync(gitFile, `gitdir: ${adminDir}\n`);
+  return worktree;
+}
+
+// ─── byte-equality regression for the common case ──────────────────────────
+
+test('a plain project root resolves to <root>/session-manager-operations, byte-identical to the old join', async () => {
+  const main = await mkMainTree();
+  assert.equal(resolveProjectRoot(main), main);
+  assert.equal(resolveOpsRoot(main), path.join(main, OPS_ROOT_DIR));
+  assert.equal(
+    opsPath(main, 'prompt-sessions', 'active-index.json'),
+    path.join(main, 'session-manager-operations', 'prompt-sessions', 'active-index.json'),
+  );
+});
+
+test('a plain directory with no enclosing .git anywhere is returned unchanged', () => {
+  const p = '/definitely/not/a/real/project';
+  assert.equal(resolveProjectRoot(p), p);
+  assert.equal(opsPath(p, 'logs'), path.join(p, OPS_ROOT_DIR, 'logs'));
+});
+
+// ─── normalization ──────────────────────────────────────────────────────────
+
+test('a linked worktree root resolves to its MAIN tree', async () => {
+  const main = await mkMainTree();
+  const wt = await mkLinkedWorktree(main);
+  assert.equal(resolveProjectRoot(wt), main);
+  assert.equal(opsPath(wt, 'scheduler', 'state'), path.join(main, OPS_ROOT_DIR, 'scheduler', 'state'));
+});
+
+test("a cwd deep inside a worktree's OWN ops tree resolves to the main tree's ops root", async () => {
+  const main = await mkMainTree();
+  const wt = await mkLinkedWorktree(main);
+  const nested = path.join(wt, OPS_ROOT_DIR, 'scheduler', 'state');
+  fs.mkdirSync(nested, { recursive: true });
+  assert.equal(resolveOpsRoot(nested), path.join(main, OPS_ROOT_DIR));
+});
+
+test('an ops-internal cwd of a plain project is truncated to the project (default normalize)', async () => {
+  const main = await mkMainTree();
+  const inside = path.join(main, OPS_ROOT_DIR, 'scheduler', 'epics', 'e1', 'prds');
+  assert.equal(resolveProjectRoot(inside), main);
+});
+
+test("a subdirectory of a git repo resolves to the repo root (the 2026-08-13 'src/main' stray-root shape)", async () => {
+  const main = await mkMainTree();
+  const sub = path.join(main, 'src', 'main', 'lib');
+  fs.mkdirSync(sub, { recursive: true });
+  assert.equal(resolveProjectRoot(sub), main);
+});
+
+test('a nested project that is its OWN git repo keeps its own root', async () => {
+  const outer = await mkMainTree();
+  const inner = path.join(outer, 'apps', 'inner');
+  fs.mkdirSync(path.join(inner, '.git'), { recursive: true });
+  assert.equal(resolveProjectRoot(inner), inner);
+});
+
+// ─── refusals ───────────────────────────────────────────────────────────────
+
+test("opsInternal:'refuse' throws on an ops-internal cwd instead of normalizing (the writer posture)", async () => {
+  const main = await mkMainTree();
+  const inside = path.join(main, OPS_ROOT_DIR, 'scheduler', 'state');
+  assert.throws(() => resolveProjectRoot(inside, { opsInternal: 'refuse' }), /not a path inside session-manager-operations/);
+});
+
+test('os.tmpdir() itself is refused with a tagged ephemeral error', () => {
+  assert.throws(() => resolveOpsRoot(os.tmpdir()), (e) => e.ephemeral === true && /ephemeral/.test(e.message));
+});
+
+test('a bare, .git-less dir under a managed worktree root is refused (cannot be normalized)', async () => {
+  fs.mkdirSync(KIND_CONFIG.epic.root, { recursive: true });
+  const bare = await fsp.mkdtemp(path.join(KIND_CONFIG.epic.root, 'sm-opsroot-resolve-bare-'));
+  tmpDirs.push(bare);
+  assert.throws(() => opsPath(bare, 'logs'), (e) => e.ephemeral === true);
+});
+
+test('relative, empty and non-string cwds throw (never resolved against process.cwd())', () => {
+  assert.throws(() => resolveProjectRoot('src/main/lib'), /absolute/);
+  assert.throws(() => resolveProjectRoot(''), /required/);
+  assert.throws(() => resolveProjectRoot(null), /required/);
+  assert.throws(() => resolveProjectRoot(42), /required/);
+});
+
+// ─── the single-writer gate is also the last line ──────────────────────────
+
+test('assertOpsWrite refuses a well-owned write whose project root is a linked worktree', async () => {
+  const main = await mkMainTree();
+  const wt = await mkLinkedWorktree(main);
+  const target = path.join(wt, OPS_ROOT_DIR, 'scheduler', 'state', 'queue.json');
+  assert.throws(() => assertOpsWrite(target, 'scheduler'), (e) => e.ephemeral === true);
+  // ...while the same write against the main tree is fine.
+  assert.doesNotThrow(() => assertOpsWrite(path.join(main, OPS_ROOT_DIR, 'scheduler', 'state', 'queue.json'), 'scheduler'));
+});
+
+test('assertOpsWrite still refuses the wrong writer before it ever looks at the root', async () => {
+  const main = await mkMainTree();
+  assert.throws(
+    () => assertOpsWrite(path.join(main, OPS_ROOT_DIR, 'scheduler', 'state', 'queue.json'), 'epics'),
+    /single-writer law/,
+  );
+});

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

@@ -0,0 +1,82 @@
+/**
+ * prdDeclaredPaths.test.cjs — extracting a PRD's declared file paths for the
+ * reverify self-heal pass's widened evidence window (PRD 1102).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/prdDeclaredPaths.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { extractDeclaredPaths, declaredPathsForPrd } = require('../prdDeclaredPaths.cjs');
+
+test('extracts backtick-quoted paths from Implementation notes', () => {
+  const body = [
+    '# Implementation notes',
+    '',
+    'Edit `src/main/scheduler.cjs` and `src/main/lib/gitWorktree.cjs`.',
+    '',
+    '# Out of scope',
+    'Do not touch `src/main/should-not-appear.cjs` here.',
+  ].join('\n');
+  const paths = extractDeclaredPaths(body);
+  assert.deepStrictEqual(paths, ['src/main/scheduler.cjs', 'src/main/lib/gitWorktree.cjs']);
+});
+
+test('extracts paths from Acceptance criteria and strips trailing :line', () => {
+  const body = [
+    '# Acceptance criteria',
+    '- [ ] Fix the bug in `src/main/scheduler.cjs:490`',
+  ].join('\n');
+  assert.deepStrictEqual(extractDeclaredPaths(body), ['src/main/scheduler.cjs']);
+});
+
+test('dedupes paths mentioned in both sections', () => {
+  const body = [
+    '# Acceptance criteria',
+    '- [ ] Fix `src/main/scheduler.cjs`',
+    '# Implementation notes',
+    'See `src/main/scheduler.cjs` again.',
+  ].join('\n');
+  assert.deepStrictEqual(extractDeclaredPaths(body), ['src/main/scheduler.cjs']);
+});
+
+test('never fabricates a path — no match anywhere returns []', () => {
+  const body = [
+    '# Implementation notes',
+    'Just prose, no backticked paths here.',
+    '# Acceptance criteria',
+    '- [ ] npm run typecheck passes',
+  ].join('\n');
+  assert.deepStrictEqual(extractDeclaredPaths(body), []);
+});
+
+test('empty/non-string body returns []', () => {
+  assert.deepStrictEqual(extractDeclaredPaths(''), []);
+  assert.deepStrictEqual(extractDeclaredPaths(null), []);
+});
+
+test('declaredPathsForPrd reads a real file and strips frontmatter', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prd-declared-paths-'));
+  const prdPath = path.join(dir, '01-test.md');
+  fs.writeFileSync(prdPath, [
+    '---',
+    'title: Test',
+    '---',
+    '# Implementation notes',
+    'Touch `src/main/scheduler.cjs`.',
+  ].join('\n'));
+  assert.deepStrictEqual(declaredPathsForPrd(prdPath), ['src/main/scheduler.cjs']);
+});
+
+test('declaredPathsForPrd on a missing file returns [] without throwing', () => {
+  assert.deepStrictEqual(declaredPathsForPrd('/nonexistent/path/does-not-exist.md'), []);
+});
+
+test('declaredPathsForPrd with null path returns []', () => {
+  assert.deepStrictEqual(declaredPathsForPrd(null), []);
+});

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__/queueHealth.test.cjs

@@ -0,0 +1,58 @@
+/**
+ * queueHealth.test.cjs — computeQueueHealth: the pure per-project rollup
+ * behind the periodic queue-health sweep (PRD 1109).
+ *
+ * Pure helper, no electron import — mirrors reaperHelpers.test.cjs's pattern
+ * so it never needs scheduler.cjs's mocked IPC surface.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/queueHealth.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const { computeQueueHealth } = require('../queueHealth.cjs');
+
+test('counts never_ran, looksDone, and stuck per project cwd', () => {
+  const jobs = [
+    { slug: 'a', cwd: '/proj-1', status: 'failed', gateOutcome: 'never_ran' },
+    { slug: 'b', cwd: '/proj-1', status: 'failed', looksDone: { commits: ['abc1234'] } },
+    { slug: 'c', cwd: '/proj-1', status: 'needs_review' },
+    { slug: 'd', cwd: '/proj-2', status: 'quarantined' },
+  ];
+  const rollup = computeQueueHealth(jobs);
+  const byProj = Object.fromEntries(rollup.map((r) => [r.cwd, r]));
+  assert.deepStrictEqual(byProj['/proj-1'], { cwd: '/proj-1', neverRan: 1, looksDone: 1, stuck: 1 });
+  assert.deepStrictEqual(byProj['/proj-2'], { cwd: '/proj-2', neverRan: 0, looksDone: 0, stuck: 1 });
+});
+
+test('a project with zero drift across all three counters is omitted entirely', () => {
+  const jobs = [
+    { slug: 'clean', cwd: '/proj-clean', status: 'completed' },
+    { slug: 'running', cwd: '/proj-clean', status: 'running' },
+    { slug: 'pending', cwd: '/proj-clean', status: 'pending' },
+  ];
+  assert.deepStrictEqual(computeQueueHealth(jobs), []);
+});
+
+test('gateOutcome values other than never_ran do not count', () => {
+  const jobs = [
+    { slug: 'a', cwd: '/proj', status: 'completed', gateOutcome: 'passed' },
+    { slug: 'b', cwd: '/proj', status: 'failed', gateOutcome: 'failed' },
+    { slug: 'c', cwd: '/proj', status: 'failed', gateOutcome: 'unknown' },
+  ];
+  assert.deepStrictEqual(computeQueueHealth(jobs), []);
+});
+
+test('empty/missing jobs array is handled without throwing', () => {
+  assert.deepStrictEqual(computeQueueHealth([]), []);
+  assert.deepStrictEqual(computeQueueHealth(undefined), []);
+});
+
+test('is a pure read: never mutates the input jobs array or its rows', () => {
+  const jobs = [{ slug: 'a', cwd: '/proj', status: 'needs_review', gateOutcome: 'never_ran' }];
+  const snapshot = JSON.parse(JSON.stringify(jobs));
+  computeQueueHealth(jobs);
+  assert.deepStrictEqual(jobs, snapshot);
+});

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

@@ -0,0 +1,39 @@
+'use strict';
+
+// Run: timeout 60 npx vitest run src/main/lib/__tests__/quietMachineLease.test.cjs
+
+const assert = require('node:assert/strict');
+const lease = require('../quietMachineLease.cjs');
+
+afterEach(() => {
+  lease.__resetForTests();
+});
+
+test('free lease: isHeld false, acquire succeeds and reports the holder', () => {
+  assert.equal(lease.isHeld(), false);
+  assert.equal(lease.acquire('101-quiet'), true);
+  assert.equal(lease.isHeld(), true);
+  assert.equal(lease.holder(), '101-quiet');
+});
+
+test('a second acquire while held fails — exclusive by construction', () => {
+  assert.equal(lease.acquire('101-quiet'), true);
+  assert.equal(lease.acquire('102-other'), false);
+  assert.equal(lease.holder(), '101-quiet');
+});
+
+test('release frees the lease so the next acquire can succeed', () => {
+  lease.acquire('101-quiet');
+  assert.equal(lease.release('101-quiet'), true);
+  assert.equal(lease.isHeld(), false);
+  assert.equal(lease.acquire('102-other'), true);
+});
+
+test('release is idempotent: releasing an unheld lease, or a slug that does not hold it, is a no-op', () => {
+  assert.equal(lease.release('nobody'), false);
+  lease.acquire('101-quiet');
+  assert.equal(lease.release('wrong-slug'), false);
+  assert.equal(lease.isHeld(), true);
+  assert.equal(lease.release('101-quiet'), true);
+  assert.equal(lease.release('101-quiet'), false);
+});