claude-code-session-manager 0.75.3 → 0.76.0

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

@@ -0,0 +1,110 @@
+/**
+ * epicStatusMirror.test.cjs — every write path that changes an Epic's status
+ * in active-index.json must leave the SAME status mirrored onto
+ * prompt-sessions/<id>.json (epicStatusMirror.cjs), so a lost/clobbered index
+ * can be reconstructed (activeIndexRebuild.cjs) without silently erasing
+ * open Epics.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/epicStatusMirror.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 { ensureEpic, removeEpic, readActiveIndex, MINT_AUTHORITY_NEW_EPIC_UI } = require('../lib/epicMint.cjs');
+const { mergeActiveIndex } = require('../lib/activeIndexMerge.cjs');
+const { epicMirrorPath } = require('../lib/epicStatusMirror.cjs');
+const config = require('../config.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  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-statusmirror-cwd-'));
+  config.addAllowedRoot(cwd);
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+function readMirror(cwd, epicId) {
+  return JSON.parse(fs.readFileSync(epicMirrorPath(cwd, epicId), 'utf8'));
+}
+
+test('minting an Epic leaves the file\'s status equal to the index row\'s', async () => {
+  const cwd = await mkCwd();
+
+  const { epicId } = await ensureEpic(cwd, {
+    goalText: 'a fresh Epic',
+    mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI,
+  });
+
+  const index = readActiveIndex(cwd);
+  const mirror = readMirror(cwd, epicId);
+  expect(mirror.status).toBe(index.sessions[epicId].status);
+  expect(mirror.status).toBe('proposed');
+  expect(mirror.cwd).toBe(cwd);
+  expect(mirror.goalText).toBe('a fresh Epic');
+  expect(typeof mirror.indexedAt).toBe('string');
+  expect(mirror.archivedAt).toBeNull();
+});
+
+test('the approve/start transition (mergeActiveIndex) updates the file\'s status to match', async () => {
+  const cwd = await mkCwd();
+  const { epicId } = await ensureEpic(cwd, {
+    goalText: 'to be started',
+    mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI,
+  });
+
+  const proposedIndex = readActiveIndex(cwd);
+  const activated = { ...proposedIndex.sessions[epicId], status: 'active' };
+  await mergeActiveIndex(cwd, {
+    sessions: { [epicId]: activated },
+    events: proposedIndex.events,
+  });
+
+  const index = readActiveIndex(cwd);
+  const mirror = readMirror(cwd, epicId);
+  expect(index.sessions[epicId].status).toBe('active');
+  expect(mirror.status).toBe('active');
+  expect(mirror.status).toBe(index.sessions[epicId].status);
+});
+
+test('removeEpic (mint rollback) deletes the mirror file too, leaving no orphan', async () => {
+  const cwd = await mkCwd();
+  const { epicId } = await ensureEpic(cwd, {
+    goalText: 'will be rolled back',
+    mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI,
+  });
+  expect(fs.existsSync(epicMirrorPath(cwd, epicId))).toBe(true);
+
+  await removeEpic(cwd, epicId);
+
+  expect(fs.existsSync(epicMirrorPath(cwd, epicId))).toBe(false);
+  expect(readActiveIndex(cwd).sessions[epicId]).toBeUndefined();
+});
+
+test('a merge that tombstones an Epic leaves its prior mirror file in place (rebuild excludes it via the tombstone, not file deletion)', async () => {
+  const cwd = await mkCwd();
+  const { epicId } = await ensureEpic(cwd, {
+    goalText: 'to be removed',
+    mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI,
+  });
+
+  await mergeActiveIndex(cwd, { sessions: {}, events: {}, removedIds: [epicId] });
+
+  const index = readActiveIndex(cwd);
+  expect(index.sessions[epicId]).toBeUndefined();
+  expect(index.tombstones[epicId]).toBeDefined();
+  // The mirror file is untouched — activeIndexRebuild.cjs is what must keep
+  // this id out, by consulting tombstones, not by the file being gone.
+  expect(fs.existsSync(epicMirrorPath(cwd, epicId))).toBe(true);
+});

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

@@ -0,0 +1,105 @@
+/**
+ * health-delegation-chain.test.cjs — "can this machine actually delegate
+ * work to the scheduler?" health section (PRD 1049), built on top of the
+ * delegation-readiness probe (delegationReadiness.cjs, PRD 1048). Exercises
+ * evaluateDelegationChainHealth() directly since it's pure — no need to spawn
+ * the full check() to cover shaping/degradation — plus one end-to-end check()
+ * run against this repo's own real config, where every check is expected to
+ * pass (this repo registers the scheduler MCP in its own .mcp.json and wires
+ * guard-prd-writes in .claude/settings.json).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-delegation-chain.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluateDelegationChainHealth, check } = require('../health.cjs');
+
+function makeCheck(id, ok, overrides = {}) {
+  return { id, label: `${id} label`, ok, detail: `${id} detail`, fix: ok ? null : `fix ${id}`, ...overrides };
+}
+
+test('all checks passing -> component ok, no issues', () => {
+  const delegationResult = {
+    ok: true,
+    checks: [
+      makeCheck('scheduler-mcp', true),
+      makeCheck('scheduler-mcp-live', true),
+      makeCheck('scheduler-mcp-project-duplicate', true, { warn: false }),
+      makeCheck('dev-plugin', true),
+      makeCheck('agent-personas', true),
+      makeCheck('prd-write-guard', true),
+    ],
+  };
+  const { component, issues } = evaluateDelegationChainHealth(delegationResult);
+  expect(component.ok).toBe(true);
+  expect(component.checks).toHaveLength(6);
+  expect(issues).toEqual([]);
+});
+
+test('one failing check -> component not ok, one issue citing label/detail/fix', () => {
+  const delegationResult = {
+    ok: false,
+    checks: [
+      makeCheck('scheduler-mcp', false, { label: 'Scheduler MCP server registered', detail: 'no entry found', fix: 'claude mcp add ...' }),
+      makeCheck('scheduler-mcp-live', true, { skipped: true }),
+      makeCheck('scheduler-mcp-project-duplicate', true, { warn: false }),
+      makeCheck('dev-plugin', true),
+      makeCheck('agent-personas', true),
+      makeCheck('prd-write-guard', true),
+    ],
+  };
+  const { component, issues } = evaluateDelegationChainHealth(delegationResult);
+  expect(component.ok).toBe(false);
+  expect(issues).toHaveLength(1);
+  expect(issues[0]).toContain('Scheduler MCP server registered');
+  expect(issues[0]).toContain('no entry found');
+  expect(issues[0]).toContain('claude mcp add ...');
+});
+
+test('multiple failing checks -> one issue per failing check, passing checks silent', () => {
+  const delegationResult = {
+    ok: false,
+    checks: [
+      makeCheck('scheduler-mcp', false),
+      makeCheck('scheduler-mcp-live', false),
+      makeCheck('scheduler-mcp-project-duplicate', true, { warn: false }),
+      makeCheck('dev-plugin', false),
+      makeCheck('agent-personas', true),
+      makeCheck('prd-write-guard', true),
+    ],
+  };
+  const { issues } = evaluateDelegationChainHealth(delegationResult);
+  expect(issues).toHaveLength(3);
+});
+
+test('failing check with no fix omits the "(fix: ...)" suffix', () => {
+  const delegationResult = {
+    ok: false,
+    checks: [makeCheck('scheduler-mcp', false, { fix: null })],
+  };
+  const { issues } = evaluateDelegationChainHealth(delegationResult);
+  expect(issues[0]).not.toContain('(fix:');
+});
+
+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(6);
+  const ids = status.components.delegation_chain.checks.map((c) => c.id);
+  expect(ids).toEqual([
+    'scheduler-mcp',
+    'scheduler-mcp-live',
+    'scheduler-mcp-project-duplicate',
+    'dev-plugin',
+    'agent-personas',
+    'prd-write-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
+  // project-scope duplicate in its own .mcp.json, so on this machine every
+  // check is expected to pass — a failure here means the probe or the
+  // wiring is wrong, not that the assertion should be relaxed.
+  expect(status.components.delegation_chain.ok).toBe(true);
+}, 90_000);

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

@@ -110,6 +110,12 @@ async function startAdmin() {
   process.env.SM_E2E = '1';
   const admin = createAdminHttp();
   prdAdminRoutes.registerAdminRoute(admin, scheduler.remote);
+  // Also wires reset-job/jobs (scheduler.cjs's own admin routes) onto the
+  // SAME admin instance/port, against the real (not faked) `remote` — this
+  // file's real-filesystem setup is what the reset-job/cancel-job/archive-prd
+  // slug-vs-not-found split needs, unlike scheduler-admin-routes.test.cjs's
+  // fake remote.
+  scheduler.registerAdminRoutes(admin, scheduler.remote);
   const { port, token } = await admin.start();
   if (prevE2e === undefined) delete process.env.SM_E2E; else process.env.SM_E2E = prevE2e;
   return { admin, port, token };
@@ -388,6 +394,295 @@ test('POST /admin/scheduler/archive-prd moves a PRD to prds-archived/', async ()
   }
 });
 
+// ─────────────────────────────────────── invalid-slug vs unknown-slug split
+//
+// PRD: safeSlugPath used to collapse "malformed slug" and "well-formed slug
+// found nowhere" into the same `null` -> "invalid slug" response, so an
+// agent that typed a real slug for a PRD in the wrong project (or a since-
+// archived one) read the error as "I typed it wrong" and retried instead of
+// listing PRDs. These tests pin the split for all three verbs plus the new
+// optional `cwd` narrowing.
+
+test('POST /admin/scheduler/reset-job with a malformed slug returns "invalid slug"', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/reset-job', token, body: { slug: 'not a slug!!' },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).toBe('invalid slug');
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/reset-job with a well-formed slug that exists nowhere returns a distinct unknown-slug error', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const slug = uniqueSlug('definitely-not-a-real-prd');
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/reset-job', token, body: { slug },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).not.toBe('invalid slug');
+    expect(res.json.error).toMatch(/unknown slug/);
+    expect(res.json.error).toMatch(/scheduler_list_prds/);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/reset-job with a cwd naming a project with no PRD dir yields the unknown-slug error, not a crash', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-reset-cwd-miss';
+  const slug = uniqueSlug('reset-cwd-miss');
+  await writePrdFixture({ cwd, epicId, slug }); // exists under `cwd`, not under `otherCwd`
+
+  const otherCwd = path.join(tmpHome, 'fake-project-cwd-empty');
+  fs.mkdirSync(otherCwd, { recursive: true });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/reset-job', token, body: { slug, cwd: otherCwd },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).toMatch(/unknown slug/);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/reset-job with a matching cwd resets a known job', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-reset-cwd-hit';
+  const slug = uniqueSlug('reset-cwd-hit');
+  await writePrdFixture({ cwd, epicId, slug });
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'needs_review' }],
+    config: {},
+    paused: null,
+  });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/reset-job', token, body: { slug, cwd },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json).toEqual({ ok: true, slug, status: 'pending' });
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/reset-job with cwd resets the SAME-slug job belonging to that project, not a same-slug job from another project (cwd narrows the job lookup, not just the file lookup)', async () => {
+  // Slugs derive from title text with no cwd salt, so two different projects
+  // can legitimately queue an identically-slugged job. `cwd` must disambiguate
+  // which one gets reset, not just which PRD file gets read for existence.
+  const cwdA = projectCwd();
+  const cwdB = path.join(tmpHome, 'fake-project-cwd-collision-b');
+  fs.mkdirSync(cwdB, { recursive: true });
+  config.addAllowedRoot(cwdB);
+  // queueStore.cjs's readMerged only reads back a project's shard if that
+  // project's cwd is discoverable via allProjectCwds (scans ~/.claude/projects/
+  // *.jsonl for a `cwd` field) — same fake-transcript trick beforeAll used for
+  // the shared fixture cwd.
+  const projDirB = path.join(tmpHome, '.claude', 'projects', 'fake-project-slug-b');
+  fs.mkdirSync(projDirB, { recursive: true });
+  fs.writeFileSync(path.join(projDirB, 'session.jsonl'), `${JSON.stringify({ cwd: cwdB })}\n`, 'utf8');
+  const { bustCwdCache } = require('../lib/queueStore.cjs');
+  bustCwdCache();
+  const slug = uniqueSlug('collision-slug');
+  const epicId = 'epic-reset-collision';
+  await writePrdFixture({ cwd: cwdB, epicId, slug });
+  await scheduler.writeQueue({
+    jobs: [
+      { slug, title: 'project A job', cwd: cwdA, status: 'needs_review' },
+      { slug, title: 'project B job', cwd: cwdB, status: 'needs_review' },
+    ],
+    config: {},
+    paused: null,
+  });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/reset-job', token, body: { slug, cwd: cwdB },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json).toEqual({ ok: true, slug, status: 'pending' });
+
+    const state = await scheduler.remote.listJobs();
+    const jobA = state.find((j) => j.cwd === cwdA);
+    const jobB = state.find((j) => j.cwd === cwdB);
+    expect(jobA.status).toBe('needs_review'); // untouched
+    expect(jobB.status).toBe('pending'); // the one actually targeted
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/cancel-job with a malformed slug is rejected at the request-schema layer (400) — never reaches "not found"', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug: 'not a slug!!' },
+    });
+    expect(res.status).toBe(400);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).not.toMatch(/unknown slug|not found/i);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('remote.cancelJob itself (bypassing the HTTP schema layer) returns "invalid slug" for a malformed slug, distinct from "unknown slug"', async () => {
+  const malformed = await scheduler.remote.cancelJob('not a slug!!');
+  expect(malformed).toEqual({ ok: false, error: 'invalid slug' });
+
+  const wellFormedMissing = await scheduler.remote.cancelJob(uniqueSlug('cancel-remote-missing'));
+  expect(wellFormedMissing.ok).toBe(false);
+  expect(wellFormedMissing.error).not.toBe('invalid slug');
+  expect(wellFormedMissing.error).toMatch(/unknown slug/);
+});
+
+test('POST /admin/scheduler/cancel-job with a well-formed slug that has no queued job returns a distinct unknown-slug error (404)', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const slug = uniqueSlug('cancel-missing');
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug },
+    });
+    expect(res.status).toBe(404);
+    expect(res.json.ok).toBe(false);
+    expect(res.json.error).not.toBe('invalid slug');
+    expect(res.json.error).toMatch(/unknown slug/);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/cancel-job with cwd narrows job lookup to that project', async () => {
+  const cwd = projectCwd();
+  const slug = uniqueSlug('cancel-cwd-scope');
+  await scheduler.writeQueue({
+    jobs: [{ slug, title: 'x', cwd, status: 'pending' }],
+    config: {},
+    paused: null,
+  });
+  const otherCwd = path.join(tmpHome, 'fake-project-cwd-cancel-miss');
+  fs.mkdirSync(otherCwd, { recursive: true });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const missRes = await request(port, {
+      method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug, cwd: otherCwd },
+    });
+    expect(missRes.status).toBe(404);
+    expect(missRes.json.ok).toBe(false);
+
+    const hitRes = await request(port, {
+      method: 'POST', path: '/admin/scheduler/cancel-job', token, body: { slug, cwd },
+    });
+    expect(hitRes.status).toBe(200);
+    expect(hitRes.json.ok).toBe(true);
+  } finally {
+    await admin.stop();
+    await scheduler.writeQueue({ jobs: [], config: {}, paused: null });
+  }
+});
+
+test('POST /admin/scheduler/archive-prd with a malformed slug is rejected at the request-schema layer (400) — never reaches "not found"', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/archive-prd', token, body: { slugs: ['not a slug!!'] },
+    });
+    expect(res.status).toBe(400);
+    expect(res.json.ok).toBe(false);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('queueOps.archiveMany itself (bypassing the HTTP schema layer) splits "invalid slug" from "not found in any PRDs dir"', async () => {
+  const queueOps = require('../queueOps.cjs');
+  const malformed = await queueOps.archiveMany(['not a slug!!']);
+  expect(malformed.results[0]).toMatchObject({ ok: false, error: 'invalid slug' });
+
+  const missing = await queueOps.archiveMany([uniqueSlug('archive-remote-missing')]);
+  expect(missing.results[0]).toMatchObject({ ok: false, error: 'not found in any PRDs dir' });
+});
+
+test('POST /admin/scheduler/archive-prd with a well-formed slug found nowhere returns a distinct not-found error', async () => {
+  const { admin, port, token } = await startAdmin();
+  try {
+    const slug = uniqueSlug('archive-missing');
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/archive-prd', token, body: { slugs: [slug] },
+    });
+    expect(res.status).toBe(200);
+    expect(res.json.results[0].ok).toBe(false);
+    expect(res.json.results[0].error).toBe('not found in any PRDs dir');
+    expect(res.json.results[0].error).not.toBe('invalid slug');
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('POST /admin/scheduler/archive-prd with cwd narrows the search: a cwd with no PRD dir misses, the real cwd hits', async () => {
+  const cwd = projectCwd();
+  const epicId = 'epic-archive-cwd';
+  const slug = uniqueSlug('archive-cwd-scope');
+  const filePath = await writePrdFixture({ cwd, epicId, slug });
+
+  const otherCwd = path.join(tmpHome, 'fake-project-cwd-archive-miss');
+  fs.mkdirSync(otherCwd, { recursive: true });
+
+  const { admin, port, token } = await startAdmin();
+  try {
+    const missRes = await request(port, {
+      method: 'POST', path: '/admin/scheduler/archive-prd', token, body: { slugs: [slug], cwd: otherCwd },
+    });
+    expect(missRes.json.results[0].ok).toBe(false);
+    expect(missRes.json.results[0].error).toBe('not found in any PRDs dir');
+    expect(fs.existsSync(filePath)).toBe(true);
+
+    const hitRes = await request(port, {
+      method: 'POST', path: '/admin/scheduler/archive-prd', token, body: { slugs: [slug], cwd },
+    });
+    expect(hitRes.json.results[0].ok).toBe(true);
+    expect(fs.existsSync(filePath)).toBe(false);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('GET /admin/mcp/readiness requires cwd and returns the delegation-readiness checks for it', async () => {
+  const cwd = projectCwd();
+  const { admin, port, token } = await startAdmin();
+  try {
+    const missing = await request(port, { path: '/admin/mcp/readiness', token });
+    expect(missing.status).toBe(400);
+    expect(missing.json.ok).toBe(false);
+
+    const res = await request(port, { path: `/admin/mcp/readiness?cwd=${encodeURIComponent(cwd)}`, token });
+    expect(res.status).toBe(200);
+    expect(res.json.ok).toBe(true);
+    expect(typeof res.json.ready).toBe('boolean');
+    expect(Array.isArray(res.json.checks)).toBe(true);
+    expect(res.json.checks.some((c) => c.id === 'scheduler-mcp')).toBe(true);
+  } finally {
+    await admin.stop();
+  }
+});
+
 test('POST /admin/scheduler/retag-prd rewrites estimateMinutes frontmatter', async () => {
   const cwd = projectCwd();
   const epicId = 'epic-retag';

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

@@ -15,6 +15,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const http = require('node:http');
+const { execFileSync } = require('node:child_process');
 const {
   deriveSlugFromTitle,
   buildPrdBody,
@@ -583,6 +584,114 @@ test('createPrd resolves sourcePromptId from originClaudeSessionId when the call
 });
 
 // Same real-homedir rationale as the two tests above.
+// ──────────────────────────────────────────── worktree-cwd Epic-lookup
+// hazard (PRD: projectRootResolve.cjs) — reproduces the live starry-night-
+// ships shape: main's active-index.json has the Epic, a linked worktree's
+// own (git-tracked, frozen-at-branch-time) copy does not. Passing the
+// worktree's pwd as `cwd` must still resolve to main and join the Epic there.
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+test('createPrd resolves a worktree cwd to the main tree and joins the Epic whose row only exists in main\'s active-index (live starry-night-ships shape)', async () => {
+  const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-worktree-cwd-hazard-'));
+  const mainRepo = path.join(tmpRoot, 'main');
+  const worktreeDir = path.join(tmpRoot, 'worktree', 'epic-1');
+  config.addAllowedRoot(mainRepo);
+  try {
+    initRepo(mainRepo);
+    fs.mkdirSync(path.dirname(worktreeDir), { recursive: true });
+    git(['worktree', 'add', '-b', 'sm-epic/epic-1', worktreeDir, 'HEAD'], mainRepo);
+
+    // Main's index has the Epic; the worktree's own copy (as checked out at
+    // branch time) does not — the exact live-repro shape.
+    await writeActiveIndexFixture(mainRepo, {
+      'epic-1': { id: 'epic-1', claudeSessionId: 'claude-sess-epic-1', status: 'active' },
+    });
+
+    const prdsDir = path.join(mainRepo, 'session-manager-operations', 'scheduler', 'epics', 'epic-1', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+    const receivedCwds = [];
+    const realAllocate = remote.allocateParallelGroup.bind(remote);
+    remote.allocateParallelGroup = async (cwd) => { receivedCwds.push(cwd); return realAllocate(cwd); };
+
+    const result = await createPrd(
+      validCreateBody({ cwd: worktreeDir, slug: 'joins-from-worktree', sourcePromptId: 'epic-1' }),
+      remote,
+    );
+
+    expect(result.ok).toBe(true);
+    // Resolved and passed to the remote as the MAIN tree, never the worktree.
+    expect(receivedCwds.every((c) => c === mainRepo)).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(written).toMatch(/sourcePromptId: epic-1/);
+    expect(written).toMatch(new RegExp(`cwd: ${mainRepo.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+  } finally {
+    await fsp.rm(tmpRoot, { recursive: true, force: true });
+  }
+});
+
+test('createPrd omits cwd entirely and resolves the project purely from sourcePromptId (cwd optional inside an Epic session)', async () => {
+  const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-cwd-optional-epic-'));
+  config.addAllowedRoot(root);
+  // resolveProjectContext's cross-project scan (used when cwd is omitted
+  // entirely) is built on activeSessions.allProjectCwds — a scan of REAL
+  // ~/.claude/projects transcripts. In production this is always populated
+  // (the calling session itself opened `root` as a project), so seed a
+  // matching transcript here rather than the fixture root being invisible to
+  // the scan. Cleaned up in `finally`.
+  const transcriptDir = path.join(os.homedir(), '.claude', 'projects', `sm-cwd-optional-test-${Date.now()}`);
+  try {
+    await writeActiveIndexFixture(root, {
+      'epic-cwd-optional': { id: 'epic-cwd-optional', claudeSessionId: 'claude-sess-cwd-optional', status: 'active' },
+    });
+    await fsp.mkdir(transcriptDir, { recursive: true });
+    await fsp.writeFile(path.join(transcriptDir, 'a.jsonl'), `${JSON.stringify({ cwd: root })}\n`, 'utf8');
+
+    const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'epic-cwd-optional', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+    const body = validCreateBody({ slug: 'no-cwd-supplied', sourcePromptId: 'epic-cwd-optional' });
+    delete body.cwd;
+
+    const result = await createPrd(body, remote);
+
+    expect(result.ok).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(written).toMatch(/sourcePromptId: epic-cwd-optional/);
+  } finally {
+    await fsp.rm(transcriptDir, { recursive: true, force: true });
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('createPrd with neither cwd nor a resolvable Epic fails with a clear cwd-required error', async () => {
+  const remote = {
+    async allocateParallelGroup() { throw new Error('must not be called'); },
+    async readPrd() { throw new Error('must not be called'); },
+    async writePrd() { throw new Error('must not be called'); },
+  };
+  const body = validCreateBody();
+  delete body.cwd;
+
+  const result = await createPrd(body, remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(400);
+  expect(result.error).toMatch(/cwd is required/);
+});
+
 test('createPrd leaves sourcePromptId unset when originClaudeSessionId matches no known Epic (plain SessionTab chat)', async () => {
   const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-no-match-'));
   config.addAllowedRoot(root);