claude-code-session-manager 0.75.2 → 0.76.0

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

@@ -0,0 +1,159 @@
+'use strict';
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/loadGate.test.cjs
+//
+// PRD 1085 — CPU-load launch gate. The static per-project cap
+// (schedulerBatchProjectCap.test.cjs) cannot see the feedback loop observed
+// 2026-09-01 on starry-night-ships: 4 Godot test batteries under Xvfb,
+// loadavg 12.95 / 14 cores = 0.93, every battery stretching past its
+// executor's timeout and spawning fix-chain reruns that launch more
+// batteries. These tests pin the pure decision, the audit rate-limit and the
+// escalation, with loadavg/cores/clock all injected.
+const assert = require('node:assert/strict');
+const { isLoadGated, createLoadGate, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
+const { loadGateThreshold, LOAD_GATE_PER_CORE } = require('../schedulerConfig.cjs');
+
+const ORIGINAL_ENV = process.env.SM_LOAD_GATE_PER_CORE;
+afterEach(() => {
+  if (ORIGINAL_ENV === undefined) delete process.env.SM_LOAD_GATE_PER_CORE;
+  else process.env.SM_LOAD_GATE_PER_CORE = ORIGINAL_ENV;
+});
+
+// ─── isLoadGated ────────────────────────────────────────────────────────────
+
+test('the live incident shape gates: 12.95 / 14 cores = 0.93 > 0.85', () => {
+  assert.equal(isLoadGated(12.95, 14, 0.85), true);
+});
+
+test('below threshold does not gate', () => {
+  assert.equal(isLoadGated(5, 14, 0.85), false);
+});
+
+test('exactly AT threshold does not gate (strictly greater)', () => {
+  assert.equal(isLoadGated(0.85 * 14, 14, 0.85), false);
+});
+
+test('zero cores never gates (unknown topology must not wedge the queue)', () => {
+  assert.equal(isLoadGated(100, 0, 0.85), false);
+});
+
+test('loadavg [0,0,0] (Windows / unsupported) never gates', () => {
+  assert.equal(isLoadGated(0, 14, 0.85), false);
+});
+
+test('a disabled threshold (0) never gates regardless of load', () => {
+  assert.equal(isLoadGated(1000, 1, 0), false);
+});
+
+// ─── loadGateThreshold (env) ────────────────────────────────────────────────
+
+test('default threshold is the documented 0.85', () => {
+  delete process.env.SM_LOAD_GATE_PER_CORE;
+  assert.equal(LOAD_GATE_PER_CORE, 0.85);
+  assert.equal(loadGateThreshold(), 0.85);
+});
+
+test('SM_LOAD_GATE_PER_CORE is honored and clamped to [0.25, 4]; 0 disables; garbage falls back', () => {
+  process.env.SM_LOAD_GATE_PER_CORE = '1.5';
+  assert.equal(loadGateThreshold(), 1.5);
+  process.env.SM_LOAD_GATE_PER_CORE = '0.01';
+  assert.equal(loadGateThreshold(), 0.25);
+  process.env.SM_LOAD_GATE_PER_CORE = '99';
+  assert.equal(loadGateThreshold(), 4);
+  process.env.SM_LOAD_GATE_PER_CORE = '0';
+  assert.equal(loadGateThreshold(), 0);
+  process.env.SM_LOAD_GATE_PER_CORE = 'banana';
+  assert.equal(loadGateThreshold(), 0.85);
+});
+
+// ─── createLoadGate: decision, 1-minute-only, bypass ───────────────────────
+
+function gateWith({ l1 = 12.95, l5 = 0, l15 = 0, cores = 14, threshold = 0.85, clock }) {
+  let t = clock ?? 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, l5, l15],
+    cores: () => cores,
+    now: () => t,
+    threshold,
+  });
+  return { g, tick: (ms) => { t += ms; } };
+}
+
+test('evaluate() gates on the incident shape and reports ratio/threshold', () => {
+  const { g } = gateWith({});
+  const r = g.evaluate();
+  assert.equal(r.gated, true);
+  assert.equal(r.bypassed, false);
+  assert.equal(r.ratio, 0.925);
+  assert.equal(r.threshold, 0.85);
+  assert.equal(r.loadavg1, 12.95);
+  assert.equal(r.cores, 14);
+});
+
+test('only the 1-minute average is consulted — a saturated 5/15-minute history with a quiet last minute launches', () => {
+  const { g } = gateWith({ l1: 2, l5: 13, l15: 13 });
+  assert.equal(g.evaluate().gated, false);
+});
+
+test('an explicit Run now bypasses the gate but records that it did', () => {
+  const { g } = gateWith({});
+  const r = g.evaluate({ bypass: true });
+  assert.equal(r.gated, false);
+  assert.equal(r.bypassed, true);
+});
+
+test('bypass on an UNgated tick is not reported as a bypass', () => {
+  const { g } = gateWith({ l1: 1 });
+  const r = g.evaluate({ bypass: true });
+  assert.deepEqual([r.gated, r.bypassed], [false, false]);
+});
+
+// ─── audit rate limit + escalation (fake clock) ─────────────────────────────
+
+test('audits once, then not again until AUDIT_INTERVAL_MS has elapsed', () => {
+  const { g, tick } = gateWith({});
+  assert.equal(g.evaluate().shouldAudit, true, 'first gated tick audits');
+  tick(60_000);
+  assert.equal(g.evaluate().shouldAudit, false, '1 min later: silent');
+  tick(AUDIT_INTERVAL_MS - 60_000 - 1);
+  assert.equal(g.evaluate().shouldAudit, false, 'just under the interval: silent');
+  tick(1);
+  assert.equal(g.evaluate().shouldAudit, true, 'at the interval: audits again');
+});
+
+test('an ungated tick never audits', () => {
+  const { g } = gateWith({ l1: 1 });
+  assert.equal(g.evaluate().shouldAudit, false);
+});
+
+test('escalates once the gated stretch exceeds the escalation window, and the stretch resets when load drops', () => {
+  let l1 = 12.95;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    escalateAfterMs: 45 * 60_000,
+  });
+  assert.equal(g.evaluate().escalate, false);
+  t += 44 * 60_000;
+  assert.equal(g.evaluate().escalate, false, 'under 45m: no escalation');
+  t += 60_000;
+  const r = g.evaluate();
+  assert.equal(r.escalate, true, 'at 45m: escalates');
+  assert.equal(r.gatedSinceMs, 45 * 60_000);
+  l1 = 1; t += 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'load dropped: stretch resets');
+  l1 = 12.95; t += 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'a fresh stretch starts from zero');
+});
+
+test('snapshot() reflects the last evaluation and is null before any', () => {
+  const { g } = gateWith({});
+  assert.equal(g.snapshot(), null);
+  g.evaluate();
+  const s = g.snapshot();
+  assert.equal(s.gated, true);
+  assert.equal(typeof s.at, 'string');
+  assert.equal('shouldAudit' in s, false, 'per-tick flags are not part of the persisted snapshot');
+});

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

@@ -0,0 +1,101 @@
+/**
+ * mcpToolCatalog.test.cjs — parity + shape gate for PRD (mcpToolCatalog):
+ * asserts the catalog and the live scheduler-mcp-server.cjs TOOLS array can
+ * never drift apart, that every catalog entry is a well-formed
+ * documentation record, and that each tool's exampleArgs is actually
+ * runnable against that tool's own inputSchema.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/mcpToolCatalog.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const path = require('node:path');
+const { MCP_TOOL_CATALOG, MCP_RECIPES, CatalogEntrySchema, composeDescription } = require('../mcpToolCatalog.cjs');
+// scheduler-mcp-server.cjs guards its stdio-server main() behind
+// `require.main === module`, so requiring it here (require.main is the test
+// runner, not this file) just loads TOOLS without opening a stdio transport.
+const { TOOLS } = require(path.join(__dirname, '../../../../scripts/scheduler-mcp-server.cjs'));
+
+const LIVE_MCP_TOOL_NAMES = TOOLS.map((t) => t.name);
+
+test('every live MCP tool name has a catalog entry', () => {
+  const catalogNames = new Set(MCP_TOOL_CATALOG.map((e) => e.name));
+  const missing = LIVE_MCP_TOOL_NAMES.filter((n) => !catalogNames.has(n));
+  expect(missing).toEqual([]);
+});
+
+test('every catalog entry corresponds to a live MCP tool', () => {
+  const liveNames = new Set(LIVE_MCP_TOOL_NAMES);
+  const extra = MCP_TOOL_CATALOG.filter((e) => !liveNames.has(e.name)).map((e) => e.name);
+  expect(extra).toEqual([]);
+});
+
+test.each(TOOLS)('$name description is composed from the catalog, not a separate literal', (tool) => {
+  const entry = MCP_TOOL_CATALOG.find((e) => e.name === tool.name);
+  expect(entry).toBeTruthy();
+  expect(tool.description).toBe(composeDescription(entry));
+  expect(tool.description.length).toBeGreaterThan(0);
+});
+
+test.each(MCP_TOOL_CATALOG)('$name has all required catalog fields', (entry) => {
+  expect(() => CatalogEntrySchema.parse(entry)).not.toThrow();
+  expect(entry.name).toBeTruthy();
+  expect(entry.group).toBeTruthy();
+  expect(entry.purpose).toBeTruthy();
+  expect(entry.whenToUse).toBeTruthy();
+  expect(entry.whenNotToUse).toBeTruthy();
+  expect(entry.exampleArgs).toBeTruthy();
+});
+
+test('a catalog entry missing a required field fails schema validation', () => {
+  const broken = {
+    name: 'some_tool',
+    group: 'scheduler',
+    purpose: '',
+    whenToUse: 'x',
+    whenNotToUse: 'y',
+    exampleArgs: {},
+    notes: null,
+  };
+  expect(() => CatalogEntrySchema.parse(broken)).toThrow();
+
+  const missingField = {
+    name: 'some_tool',
+    group: 'scheduler',
+    purpose: 'x',
+    whenToUse: 'y',
+    // whenNotToUse omitted entirely
+    exampleArgs: {},
+    notes: null,
+  };
+  expect(() => CatalogEntrySchema.parse(missingField)).toThrow();
+});
+
+test.each(MCP_TOOL_CATALOG)('$name composeDescription joins purpose/whenToUse/whenNotToUse/notes deterministically', (entry) => {
+  const expected = [entry.purpose, entry.whenToUse, entry.whenNotToUse, entry.notes].filter(Boolean).join(' ');
+  expect(composeDescription(entry)).toBe(expected);
+  expect(composeDescription(entry).length).toBeGreaterThan(0);
+});
+
+test('MCP_RECIPES covers queue-work, unstick-needs-review, and hand-off-to-another-project', () => {
+  const ids = MCP_RECIPES.map((r) => r.id);
+  expect(ids).toContain('queue-work-via-develop');
+  expect(ids).toContain('unstick-needs-review-job');
+  expect(ids).toContain('hand-finding-to-another-project');
+  for (const recipe of MCP_RECIPES) {
+    expect(recipe.title).toBeTruthy();
+    expect(Array.isArray(recipe.steps)).toBe(true);
+    expect(recipe.steps.length).toBeGreaterThan(0);
+  }
+});
+
+test.each(MCP_TOOL_CATALOG)('$name exampleArgs satisfies its own inputSchema required fields', (entry) => {
+  const tool = TOOLS.find((t) => t.name === entry.name);
+  expect(tool).toBeTruthy();
+  const required = tool.inputSchema?.required ?? [];
+  for (const key of required) {
+    expect(Object.prototype.hasOwnProperty.call(entry.exampleArgs, key)).toBe(true);
+    expect(entry.exampleArgs[key]).not.toBeUndefined();
+  }
+});

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

@@ -124,3 +124,205 @@ test('the guards compose: no relative cwd from a transcript can reach an ops-roo
   // And even if one somehow did, the write path itself refuses it.
   expect(() => queueStore.projectStateDir('src/renderer/state')).toThrow(/absolute path/);
 });
+
+// ─── the second incident: an ABSOLUTE cwd INSIDE an ops root ────────────────
+//
+// Reported from starry-night-ships on 2026-08-30: 14 stray
+// `.../session-manager-operations/scheduler/state/queue.json` stubs, each
+// nested under another ops directory (`scheduler/prds/`, `prompt-sessions/`,
+// `scheduler/epics/<id>/prds/`), every one holding `{"jobs": []}` and mtimes
+// spanning 8 days. The 2026-08-13 absolute-path guard above could not catch
+// them: these cwds ARE absolute and DO exist. They came from transcripts
+// where an agent had `cd`'d into the artifact directory it was writing, so
+// the last transcript row recorded that subdirectory as the session cwd.
+
+test('a transcript cwd inside an ops root is normalized to the project root, not taken literally', async () => {
+  const project = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-nested-'));
+  tmpDirs.push(project);
+  const prdDir = path.join(project, 'session-manager-operations', 'scheduler', 'epics', 'e-1', 'prds');
+  fs.mkdirSync(prdDir, { recursive: true });
+  const projectsDir = await mkProjectsDir({ nested: prdDir });
+
+  const cwds = activeProjectCwds(Infinity, { projectsDir });
+  expect(cwds).toContain(project);
+  expect(cwds).not.toContain(prdDir);
+});
+
+test('normalization keeps the active-project signal rather than dropping the row', () => {
+  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  expect(projectRootOf('/p/session-manager-operations/prompt-sessions')).toBe('/p');
+  expect(projectRootOf('/p/session-manager-operations')).toBe('/p');
+  expect(projectRootOf('/p/session-manager-operations/scheduler/state')).toBe('/p');
+  // Already-nested strays truncate at the FIRST segment — the inner one is
+  // itself the bug, never a project.
+  expect(projectRootOf('/p/session-manager-operations/x/session-manager-operations/y')).toBe('/p');
+  // A plain project cwd is untouched.
+  expect(projectRootOf('/p/src/main')).toBe('/p/src/main');
+  // A directory that merely CONTAINS the name as a substring is not a segment.
+  expect(projectRootOf('/p/session-manager-operations-archive')).toBe('/p/session-manager-operations-archive');
+});
+
+test('projectStateDir fails closed on an ops-internal cwd, naming the offending value', () => {
+  expect(() => queueStore.projectStateDir('/p/session-manager-operations/scheduler/prds'))
+    .toThrow(/must be a project root/);
+  expect(() => queueStore.projectStateDir('/p/session-manager-operations/scheduler/prds'))
+    .toThrow(/scheduler\/prds/);
+  // The guard is segment-exact, not a substring match.
+  expect(queueStore.projectStateDir('/p/session-manager-operations-archive'))
+    .toBe(path.join('/p/session-manager-operations-archive', 'session-manager-operations', 'scheduler', 'state'));
+});
+
+// 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__/opsRootNestedWrite.test.cjs

@@ -0,0 +1,51 @@
+/**
+ * opsRootNestedWrite.test.cjs — writeSplit must never materialize a second
+ * ops root beneath the first.
+ *
+ * Companion to opsRootAbsoluteCwd.test.cjs; separate file because HOME must
+ * be overridden BEFORE requiring queueStore — MACHINE_STATE_PATH is baked
+ * into a top-level const from os.homedir() at require time, and writeSplit
+ * writes it on every call. (Learned the hard way: running this assertion in
+ * the shared file overwrote the real ~/.claude/session-manager/
+ * scheduler-machine.json, dropping the user's firePolicy and concurrencyCap.)
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/opsRootNestedWrite.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-opsroot-home-'));
+process.env.HOME = tmpHome;
+
+const queueStore = require('../queueStore.cjs');
+
+const tmpDirs = [tmpHome];
+afterEach(async () => {
+  while (tmpDirs.length > 1) {
+    await fsp.rm(tmpDirs.pop(), { recursive: true, force: true }).catch(() => {});
+  }
+});
+
+test('one ops-internal cwd in a write batch is skipped without losing the other projects', async () => {
+  const good = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-opsroot-good-'));
+  tmpDirs.push(good);
+  const bad = path.join(good, 'session-manager-operations', 'scheduler', 'epics', 'e-1', 'prds');
+  fs.mkdirSync(bad, { recursive: true });
+
+  await queueStore.writeSplit({
+    config: {},
+    sourceCwds: [bad, good],
+    jobs: [{ slug: 'keeper', cwd: good }, { slug: 'stray', cwd: bad }],
+  });
+
+  const written = JSON.parse(fs.readFileSync(queueStore.projectQueuePath(good), 'utf8'));
+  expect(written.jobs.map((j) => j.slug)).toEqual(['keeper']);
+  // The doubled-suffix stub the starry-night-ships report was about.
+  expect(fs.existsSync(path.join(bad, 'session-manager-operations'))).toBe(false);
+});

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/,
+  );
+});