claude-code-session-manager 0.60.0 → 0.62.0

package/src/main/__tests__/scheduler-verify-prd-path.test.cjs

@@ -0,0 +1,109 @@
+/**
+ * scheduler-verify-prd-path.test.cjs — regression test for PRD 991: the
+ * verifier's `prdPath` must resolve to a REAL, existing file for an
+ * Epic-scoped PRD, both live and archived.
+ *
+ * Before this PRD, `verifyRun`'s two call sites (the post-run verify in
+ * spawnJob and reverifyNeedsReview) built `prdPath` via `prdPathForJob`,
+ * which resolves to the RETIRED flat
+ * `<cwd>/session-manager-operations/scheduler/prds/` dir — a dir that holds
+ * only zero-byte `.reserved-NNN` stubs for every project that has migrated
+ * to Epic-scoped PRDs (i.e. every project today). The verifier therefore
+ * silently lost access to the PRD body (dependsOn checks, soak-floor dates,
+ * deliverable-path checks, the merge-main PR-number exemption) on every
+ * single run.
+ *
+ * This test exercises actual path resolution against a temp tree — no
+ * resolver-stubbing — the same class of gap that let this bug (and PRD
+ * 985's sibling notify-path bug) ship green twice.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-verify-prd-path.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let resolveVerifyPrdPath;
+let archivedPrdPathForJob;
+let PRDS_DIR;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-verify-prd-path-'));
+  process.env.HOME = tmpHome;
+
+  // Load AFTER HOME is stubbed — scheduler.cjs snapshots os.homedir() into
+  // PRDS_DIR at module load, not lazily (see scheduler-find-prd-dir.test.cjs).
+  ({ resolveVerifyPrdPath, archivedPrdPathForJob, PRDS_DIR } = require('../scheduler.cjs'));
+
+  if (!PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+
+  // allProjectCwds()/activeProjectCwds() discover project cwds by scanning
+  // ~/.claude/projects/*/*.jsonl for a `cwd` field — fake one project with a
+  // transcript pointing at a real on-disk cwd.
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const projDir = path.join(projectsDir, 'fake-project-slug');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projDir, 'session.jsonl'),
+    `${JSON.stringify({ cwd: projectCwd() })}\n`,
+    'utf8',
+  );
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function projectCwd() {
+  return path.join(tmpHome, 'fake-project-cwd');
+}
+
+test('resolveVerifyPrdPath resolves a LIVE Epic-scoped PRD to a real existing path', async () => {
+  const cwd = projectCwd();
+  const epicId = 'test-epic-live';
+  const slug = `991-test-live-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  const prdPath = path.join(prdsDir, `${slug}.md`);
+  fs.writeFileSync(prdPath, '---\ntitle: live fixture\n---\n\n# Goal\n\ntest\n', 'utf8');
+
+  const resolved = await resolveVerifyPrdPath({ slug, cwd });
+  expect(resolved).toBe(prdPath);
+  expect(fs.existsSync(resolved)).toBe(true);
+});
+
+test('resolveVerifyPrdPath returns null for an ARCHIVED-only PRD; archivedPrdPathForJob fills the gap', async () => {
+  const cwd = projectCwd();
+  const epicId = 'test-epic-archived';
+  const slug = `991-test-archived-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const epicDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId);
+  const archiveDir = path.join(epicDir, 'prds-archived');
+  fs.mkdirSync(archiveDir, { recursive: true });
+  const archivedPath = path.join(archiveDir, `${slug}.md`);
+  fs.writeFileSync(archivedPath, '---\ntitle: archived fixture\n---\n\n# Goal\n\ntest\n', 'utf8');
+
+  const job = { slug, cwd };
+  const live = await resolveVerifyPrdPath(job);
+  expect(live).toBe(null);
+
+  const fallback = live ?? archivedPrdPathForJob(job);
+  expect(fallback).toBe(archivedPath);
+  expect(fs.existsSync(fallback)).toBe(true);
+});
+
+test('resolveVerifyPrdPath returns null for a slug that exists nowhere (never falls back to the retired flat dir)', async () => {
+  const cwd = projectCwd();
+  const slug = `991-test-nonexistent-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+  const resolved = await resolveVerifyPrdPath({ slug, cwd });
+  expect(resolved).toBe(null);
+});

package/src/main/__tests__/scheduler-worktree-exec-cwd.test.cjs

@@ -0,0 +1,122 @@
+/**
+ * scheduler-worktree-exec-cwd.test.cjs — PRD 994, LOAD-BEARING acceptance
+ * criterion: when a job is isolated into a worktree, its PRD file, queue
+ * state, and run logs must still resolve to the MAIN tree, never the
+ * worktree — `session-manager-operations/` is resolved from a `cwd` param
+ * (lib/prdLocations.cjs), so a naive cwd swap would give the job a
+ * different, empty ops root and orphan its own PRD.
+ *
+ * Drives executeJob's real `execCwd` parameter (the 5th arg scheduler.cjs
+ * passes when a worktree was created) with a stub `claude` binary, proving:
+ *   1. the child process's OWN cwd is the worktree dir (execCwd) — verified
+ *      by having the stub write a marker file to `process.cwd()`;
+ *   2. the PRD source is still found via job.cwd (the main tree) even though
+ *      the worktree dir has no PRD file in it at all;
+ *   3. the run's meta.json still records job.cwd, not the worktree dir.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-worktree-exec-cwd.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let executeJob;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-worktree-execcwd-'));
+  process.env.HOME = tmpHome;
+  ({ executeJob } = require('../scheduler.cjs'));
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  delete process.env.SM_CLAUDE_BIN;
+});
+
+// Stub `claude` binary: writes a marker file into its OWN process.cwd() (proving
+// where it actually ran), captures the '-p' prompt, then emits a stream-json
+// success result and exits 0.
+function writeClaudeStub() {
+  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    const path = require('path');
+    fs.writeFileSync(path.join(process.cwd(), 'ran-here.marker'), 'yes', 'utf8');
+    process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok' }) + '\\n');
+    process.exit(0);
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+test('executeJob spawns the child in execCwd (worktree) while resolving the PRD from job.cwd (main tree)', async () => {
+  const mainCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-worktree-main-'));
+  const worktreeCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-worktree-exec-'));
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-worktree-run-'));
+
+  try {
+    const slug = `994-test-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const prdsDir = path.join(mainCwd, 'session-manager-operations', 'scheduler', 'prds');
+    fs.mkdirSync(prdsDir, { recursive: true });
+    const bodyText = 'Do the isolated-worktree thing.';
+    fs.writeFileSync(path.join(prdsDir, `${slug}.md`), bodyText, 'utf8');
+
+    process.env.SM_CLAUDE_BIN = writeClaudeStub();
+
+    const job = { slug, cwd: mainCwd };
+    const result = await executeJob(job, runDir, mainCwd, () => Promise.resolve(), worktreeCwd);
+
+    expect(result.exitCode).toBe(0);
+
+    // 1. The child process really ran with cwd = worktreeCwd, not mainCwd.
+    expect(fs.existsSync(path.join(worktreeCwd, 'ran-here.marker'))).toBe(true);
+    expect(fs.existsSync(path.join(mainCwd, 'ran-here.marker'))).toBe(false);
+
+    // 2. The PRD source itself is untouched — resolved via job.cwd, not execCwd.
+    const onDiskPrd = fs.readFileSync(path.join(prdsDir, `${slug}.md`), 'utf8');
+    expect(onDiskPrd).toBe(bodyText);
+
+    // 3. The run's meta.json records job.cwd (the main tree), not the worktree.
+    const metaPath = path.join(runDir, `${slug}.meta.json`);
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    expect(meta.cwd).toBe(mainCwd);
+  } finally {
+    fs.rmSync(mainCwd, { recursive: true, force: true });
+    fs.rmSync(worktreeCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});
+
+test('executeJob falls back to job.cwd for the spawn cwd when no execCwd is supplied (unchanged behaviour)', async () => {
+  const mainCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-worktree-fallback-'));
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-worktree-run2-'));
+  try {
+    const slug = `994-test-fallback-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const prdsDir = path.join(mainCwd, 'session-manager-operations', 'scheduler', 'prds');
+    fs.mkdirSync(prdsDir, { recursive: true });
+    fs.writeFileSync(path.join(prdsDir, `${slug}.md`), 'no worktree here', 'utf8');
+    process.env.SM_CLAUDE_BIN = writeClaudeStub();
+
+    const job = { slug, cwd: mainCwd };
+    const result = await executeJob(job, runDir, mainCwd, () => Promise.resolve());
+
+    expect(result.exitCode).toBe(0);
+    expect(fs.existsSync(path.join(mainCwd, 'ran-here.marker'))).toBe(true);
+  } finally {
+    fs.rmSync(mainCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});

package/src/main/chatRunner.cjs

@@ -891,6 +891,10 @@ module.exports = {
   splitStopSignal,
   parseContextUsageMarkdown,
   STOP_SENTINEL,
+  // Both instruction blocks are exported so the renderer's preamble splitter
+  // (lib/promptPreamble.ts) can be drift-tested against the REAL text rather
+  // than a copy — see chat-preamble-anchors.test.cjs.
+  STOP_SIGNAL_INSTRUCTION,
   CHAT_MODE_TRUTH_INSTRUCTION,
   KILL_CEILING_MS,
   KILL_CEILING_MIN,

package/src/main/config.cjs

@@ -70,6 +70,30 @@ function addAllowedRoot(dir) {
   if (dir) allowedRoots.add(path.resolve(dir));
 }
 
+// PromptSession archive writes (state/promptSessions.ts's markCompleted ->
+// window.api.config.writeJson(promptSessionArchivePath(...))) reach this
+// generic IPC handler with no pty ever having spawned for their cwd (a
+// chat-only Epic on a cold boot), same hazard prdCreate.cjs:152-155 already
+// documents for PRD creation. Registering the root here — narrowly, only
+// when the resolved path is actually under a project's
+// session-manager-operations/prompt-sessions/ — mirrors that precedent for
+// the one other write path (besides mergeActiveIndex's own) that needs it,
+// without widening addAllowedRoot's use to every config:write-json call.
+const PROMPT_SESSIONS_MARKER = `${path.sep}session-manager-operations${path.sep}prompt-sessions${path.sep}`;
+
+function registerPromptSessionsRoot(p) {
+  if (!p || typeof p !== 'string') return;
+  let abs;
+  try {
+    abs = path.resolve(expandHome(p));
+  } catch {
+    return;
+  }
+  const idx = abs.indexOf(PROMPT_SESSIONS_MARKER);
+  if (idx === -1) return;
+  addAllowedRoot(abs.slice(0, idx));
+}
+
 function validatePath(abs) {
   const real = realResolve(abs);
   for (const root of allowedRoots) {
@@ -438,7 +462,10 @@ function registerConfigHandlers() {
   ipcMain.handle('config:read-text', v(s.configPath, ({ path: p }) => readText(p)));
   // `writer` is the renderer's declared owner id for the single-writer law
   // (lib/opsOwnership.cjs). Ignored outside the ops root; required inside it.
-  ipcMain.handle('config:write-json', v(s.configWriteJson, ({ path: p, data, writer }) => writeJson(p, data, { writer })));
+  ipcMain.handle('config:write-json', v(s.configWriteJson, ({ path: p, data, writer }) => {
+    registerPromptSessionsRoot(p);
+    return writeJson(p, data, { writer });
+  }));
   ipcMain.handle('config:write-text', v(s.configWriteText, ({ path: p, text, writer }) => writeTextAtomic(p, text, { writer })));
   ipcMain.handle('config:list-dir', v(s.configListDir, ({ path: p, opts }) => listDir(p, opts || {})));
   ipcMain.handle('config:exists', v(s.configPath, ({ path: p }) => exists(p)));
@@ -469,6 +496,7 @@ module.exports = {
   listDir,
   exists,
   addAllowedRoot,
+  registerPromptSessionsRoot,
   validatePath,
   validateWrite,
 };

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

@@ -0,0 +1,87 @@
+/**
+ * coldBootPromptSessionsWrite.test.cjs — regression coverage for the
+ * "Epics marked Completed come back Open" bug.
+ *
+ * config.cjs's allowedRoots starts as just {os.homedir()}, and
+ * validateWrite() explicitly skips the homedir root (a project cwd must be
+ * registered via addAllowedRoot() before writeJson()/writeTextAtomic() will
+ * accept a write under it). addAllowedRoot's only callers used to be pty.cjs
+ * (Terminal spawn) and lib/prdCreate.cjs — never the Epic persistence path —
+ * so on a cold boot, before any Terminal/PRD activity for a project, both
+ * mergeActiveIndex's own write and the renderer's Epic-archive write
+ * (config:write-json of promptSessionArchivePath) were silently rejected.
+ *
+ * Both cases below use a tmp dir INSIDE the homedir so validatePath (the
+ * READ boundary, satisfied by the homedir root alone) succeeds while
+ * validateWrite (which skips the homedir root, per config.cjs:113) still
+ * requires an explicit per-project root registration — reproducing the
+ * exact cold-boot gap without needing an out-of-home tmp root.
+ *
+ * Run: timeout 300 npx vitest run src/main/lib/__tests__/coldBootPromptSessionsWrite.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { mergeActiveIndex } = require('../activeIndexMerge.cjs');
+const { readActiveIndex } = require('../epicMint.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 mkColdBootCwd(prefix) {
+  // Deliberately under homedir (so validatePath's read boundary passes via
+  // the default homedir root) and deliberately NOT registered via
+  // config.addAllowedRoot() — simulates the exact state of allowedRoots
+  // right after app boot, before any Terminal/PRD activity for this project.
+  const cwd = await fsp.mkdtemp(path.join(os.homedir(), prefix));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+function session(id, overrides = {}) {
+  return {
+    id,
+    cwd: overrides.cwd || '/proj',
+    goalText: overrides.goalText || `goal for ${id}`,
+    claudeSessionId: overrides.claudeSessionId || `claude-${id}`,
+    status: overrides.status || 'active',
+    createdAt: overrides.createdAt || '2026-08-06T13:48:00.000Z',
+    completedAt: overrides.completedAt ?? null,
+  };
+}
+
+test('mergeActiveIndex writes active-index.json on a cold boot with only the homedir registered', async () => {
+  const cwd = await mkColdBootCwd('.sm-test-activeindex-coldboot-');
+  const s = session('psess-coldboot-1');
+
+  await mergeActiveIndex(cwd, { sessions: { [s.id]: s }, events: {} });
+
+  const index = readActiveIndex(cwd);
+  expect(index.sessions[s.id]).toEqual(s);
+});
+
+// Mirrors what the 'config:write-json' IPC handler now does before calling
+// writeJson (config.cjs's registerPromptSessionsRoot) — the main-process fix
+// for state/promptSessions.ts's markCompleted -> writeJson(promptSessionArchivePath).
+test('an Epic archive write succeeds on a cold boot with only the homedir registered', async () => {
+  const cwd = await mkColdBootCwd('.sm-test-archive-coldboot-');
+  const archivePath = path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'psess-archived-1.json');
+  const archive = { ...session('psess-archived-1', { status: 'completed' }), completedAt: '2026-08-06T14:00:00.000Z' };
+
+  config.registerPromptSessionsRoot(archivePath);
+  await config.writeJson(archivePath, archive, { writer: 'epics' });
+
+  const result = await config.readJson(archivePath);
+  expect(result.exists).toBe(true);
+  expect(result.data).toEqual(archive);
+});

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

@@ -0,0 +1,197 @@
+/**
+ * jobWorktree.test.cjs — PRD 994: per-job `git worktree` isolation.
+ *
+ * Exercises the real `git worktree` plumbing against throwaway repos under
+ * os.tmpdir() (fast — no network, no Electron). Covers: create/integrate/
+ * cleanup happy path, the two documented fallback reasons (non-git cwd, dirty
+ * base tree), the concurrency cap, the kill-switch env var, a real merge
+ * conflict surfacing as an explicit integration failure (branch preserved,
+ * not silently discarded), and boot-time reconciliation of a leaked worktree.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/jobWorktree.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const jobWorktree = require('../jobWorktree.cjs');
+
+let tmpRoot;
+let repoCwd;
+let originalDisable;
+let originalMax;
+
+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);
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-jobworktree-'));
+  repoCwd = path.join(tmpRoot, 'repo');
+  initRepo(repoCwd);
+  originalDisable = process.env.SM_JOB_WORKTREE_DISABLE;
+  originalMax = process.env.SM_JOB_WORKTREE_MAX;
+  delete process.env.SM_JOB_WORKTREE_DISABLE;
+  delete process.env.SM_JOB_WORKTREE_MAX;
+  jobWorktree._resetActiveWorktreeCountForTests(0);
+});
+
+afterEach(async () => {
+  if (originalDisable === undefined) delete process.env.SM_JOB_WORKTREE_DISABLE;
+  else process.env.SM_JOB_WORKTREE_DISABLE = originalDisable;
+  if (originalMax === undefined) delete process.env.SM_JOB_WORKTREE_MAX;
+  else process.env.SM_JOB_WORKTREE_MAX = originalMax;
+  // Best-effort: prune any worktree this test created before removing the repo.
+  try { await jobWorktree.reconcileWorktreesOnBoot([repoCwd]); } catch { /* ignore */ }
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+test('createJobWorktree creates a linked worktree on a fresh branch from HEAD', async () => {
+  const slug = 'test-slug-create';
+  const result = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(result.ok).toBe(true);
+  expect(fs.existsSync(result.dir)).toBe(true);
+  expect(fs.existsSync(path.join(result.dir, 'README.md'))).toBe(true);
+  expect(result.branch).toBe(`sm-job/${slug}`);
+
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: result.dir, branch: result.branch });
+  expect(fs.existsSync(result.dir)).toBe(false);
+});
+
+test('a commit made inside the worktree becomes visible on the main tree HEAD after integrateJobBranch', async () => {
+  const slug = 'test-slug-integrate';
+  const worktree = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(worktree.ok).toBe(true);
+
+  fs.writeFileSync(path.join(worktree.dir, 'new-file.txt'), 'job output\n', 'utf8');
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job commit'], worktree.dir);
+  const jobCommitSha = git(['rev-parse', 'HEAD'], worktree.dir).trim();
+
+  const headBefore = git(['rev-parse', 'HEAD'], repoCwd).trim();
+  const outcome = await jobWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(true);
+  expect(outcome.integrated).toBe(true);
+
+  const headAfter = git(['rev-parse', 'HEAD'], repoCwd).trim();
+  expect(headAfter).not.toBe(headBefore);
+  // Fast-forward, since the main tree never advanced independently.
+  expect(headAfter).toBe(jobCommitSha);
+  expect(fs.existsSync(path.join(repoCwd, 'new-file.txt'))).toBe(true);
+
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch });
+  expect(fs.existsSync(worktree.dir)).toBe(false);
+});
+
+test('integrateJobBranch is a no-op (integrated:false) when the branch has no new commits', async () => {
+  const slug = 'test-slug-noop';
+  const worktree = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  const outcome = await jobWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(true);
+  expect(outcome.integrated).toBe(false);
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch });
+});
+
+test('a real merge conflict surfaces as an explicit integration failure and preserves the branch', async () => {
+  const slug = 'test-slug-conflict';
+  const worktree = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug });
+
+  // Job edits README.md in its worktree and commits.
+  fs.writeFileSync(path.join(worktree.dir, 'README.md'), 'job edit\n', 'utf8');
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job edits README'], worktree.dir);
+
+  // Main tree ALSO advances with a conflicting edit to the same line.
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'main tree edit\n', 'utf8');
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'main tree edits README'], repoCwd);
+
+  const outcome = await jobWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.reason).toMatch(/conflict|merge failed/i);
+
+  // cwd must not be left mid-merge.
+  const status = git(['status', '--porcelain'], repoCwd);
+  expect(status.trim()).toBe('');
+
+  // Branch is preserved (keepBranch) — the job's commit is not discarded.
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+  const branches = git(['branch', '--list', worktree.branch], repoCwd);
+  expect(branches).toContain(worktree.branch.replace('sm-job/', ''));
+});
+
+test('falls back with a reason for a non-git cwd', async () => {
+  const nonGitDir = path.join(tmpRoot, 'not-a-repo');
+  fs.mkdirSync(nonGitDir, { recursive: true });
+  const result = await jobWorktree.createJobWorktree({ cwd: nonGitDir, slug: 'x' });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/not a git repository/);
+});
+
+test('falls back with a reason for a dirty base tree (never silently drops uncommitted human WIP)', async () => {
+  fs.writeFileSync(path.join(repoCwd, 'dirty.txt'), 'uncommitted\n', 'utf8');
+  const result = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug: 'x' });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/uncommitted changes/);
+});
+
+test('falls back once the concurrency cap is reached, and recovers after cleanup', async () => {
+  process.env.SM_JOB_WORKTREE_MAX = '1';
+  const first = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cap-1' });
+  expect(first.ok).toBe(true);
+
+  const second = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cap-2' });
+  expect(second.ok).toBe(false);
+  expect(second.reason).toMatch(/cap reached/);
+
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: first.dir, branch: first.branch });
+
+  const third = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cap-3' });
+  expect(third.ok).toBe(true);
+  await jobWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: third.dir, branch: third.branch });
+});
+
+test('SM_JOB_WORKTREE_DISABLE=1 restores in-place behaviour', async () => {
+  process.env.SM_JOB_WORKTREE_DISABLE = '1';
+  const result = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug: 'x' });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/SM_JOB_WORKTREE_DISABLE/);
+});
+
+test('reconcileWorktreesOnBoot removes a leaked worktree (simulated crash) and its branch', async () => {
+  const slug = 'test-slug-leak';
+  const worktree = await jobWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(fs.existsSync(worktree.dir)).toBe(true);
+  // Simulate a crash: the in-memory counter resets (as it would on restart)
+  // and nothing calls cleanupJobWorktree — the checkout is left registered.
+  jobWorktree._resetActiveWorktreeCountForTests(0);
+
+  await jobWorktree.reconcileWorktreesOnBoot([repoCwd]);
+
+  expect(fs.existsSync(worktree.dir)).toBe(false);
+  const branches = git(['branch', '--list', worktree.branch], repoCwd);
+  expect(branches.trim()).toBe('');
+});
+
+test('reconcileWorktreesOnBoot never touches a worktree outside WORKTREE_ROOT', async () => {
+  const humanWorktreeDir = path.join(tmpRoot, 'human-made-worktree');
+  git(['worktree', 'add', '-b', 'human-branch', humanWorktreeDir, 'HEAD'], repoCwd);
+  await jobWorktree.reconcileWorktreesOnBoot([repoCwd]);
+  expect(fs.existsSync(humanWorktreeDir)).toBe(true);
+  // cleanup so afterEach's rm doesn't leave a dangling worktree registration.
+  git(['worktree', 'remove', '--force', humanWorktreeDir], repoCwd);
+});

package/src/main/lib/activeIndexMerge.cjs

@@ -33,6 +33,7 @@
  * explicit "un-tombstone" path; today one would be dead code.
  */
 
+const path = require('path');
 const { activeIndexPath, withPathLock } = require('./epicMint.cjs');
 const config = require('../config.cjs');
 
@@ -69,6 +70,14 @@ function compareEventsChainAware(a, b) {
  */
 async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events: rawMemoryEvents = {}, removedIds = [] } = {}) {
   if (!cwd || typeof cwd !== 'string') throw new Error('mergeActiveIndex: cwd is required');
+  // Register this project's cwd as a write-allowed root (config.cjs's
+  // validateWrite gate) — mirrors the precedent + comment in
+  // lib/prdCreate.cjs:152-155. A chat-only Epic (headless claude -p, no
+  // Terminal PTY ever spawned for this cwd) reaches this merge on a cold
+  // boot before pty.cjs's addAllowedRoot call has ever run for it — without
+  // this, every active-index.json write for such a project fails with
+  // "Write outside allowed write boundaries".
+  config.addAllowedRoot(path.resolve(cwd));
   const filePath = activeIndexPath(cwd);
   // Null-prototype copies of the CALLER'S OWN payload too: an Epic id equal
   // to "__proto__" is a plain string key from the caller's perspective, but

package/src/main/lib/epicContextDigest.cjs

@@ -76,26 +76,38 @@ async function buildContextDigest({ cwd, epicId, maxChars } = {}) {
 const TASK_RESTATEMENT = 'Your task is the PRD at the top of this prompt. Implement it now.';
 
 /**
- * composeExecutorPrompt({ prdBody, digestText, maxChars }) → string
+ * composeExecutorPrompt({ prdBody, digestText, finishProtocol, maxChars }) → string
  *
- * Orders the executor prompt so the PRD body is unambiguously the task and
- * the Epic digest is unambiguously subordinate background: PRD body first,
- * then the fenced digest (if any), then a one-line restatement of the task
- * last (recency matters — a prompt that ends in someone else's conversation
- * invites a conversational reply instead of a diff).
+ * Orders the executor prompt so the PRD body is unambiguously the task, the
+ * Epic digest is unambiguously subordinate background, and the mandatory
+ * finish protocol (review → security-review → verify → commit → verdict
+ * sentinel) stays in the prompt's tail where it belongs: PRD body first,
+ * then the fenced digest (if any), then the finish protocol (if supplied),
+ * then a one-line restatement of the task last (recency matters — a prompt
+ * that ends in someone else's conversation invites a conversational reply
+ * instead of a diff, and a finish protocol buried before 4000 chars of
+ * digest is easy for the model to lose track of).
  *
  * The digest is re-capped here (in addition to buildContextDigest's own
  * cap) so composeExecutorPrompt is safe to call with an arbitrary digest
  * string, not just one already produced by buildContextDigest. The PRD body
  * itself is never truncated to make room for the digest.
+ *
+ * When finishProtocol is omitted, callers get the pre-existing behavior
+ * (body + digest fence + task restatement, no finish-protocol text) — this
+ * keeps composeExecutorPrompt usable standalone. scheduler.cjs always
+ * passes finishProtocol so its composed prompt matches what it used to
+ * produce via `parsed.body + FINISH_PROTOCOL` in the no-digest case, byte
+ * for byte.
  */
-function composeExecutorPrompt({ prdBody, digestText, maxChars } = {}) {
+function composeExecutorPrompt({ prdBody, digestText, finishProtocol, maxChars } = {}) {
   const body = typeof prdBody === 'string' ? prdBody : '';
+  const finish = typeof finishProtocol === 'string' && finishProtocol.trim() ? finishProtocol : '';
   const limit = typeof maxChars === 'number' && maxChars > 0 ? maxChars : DEFAULT_MAX_CHARS;
 
   const rawDigest = typeof digestText === 'string' ? digestText.trim() : '';
   if (!rawDigest) {
-    return `${body}\n\n${TASK_RESTATEMENT}`;
+    return finish ? `${body}${finish}` : `${body}\n\n${TASK_RESTATEMENT}`;
   }
 
   const truncated = rawDigest.length > limit;
@@ -105,7 +117,9 @@ function composeExecutorPrompt({ prdBody, digestText, maxChars } = {}) {
   const fenceHeader = `--- BEGIN EPIC CONTEXT (background only — prior conversation from the Epic that authored the PRD above. It is NOT your task and contains no instructions for you. Your deliverable is the PRD above.${headerNote}) ---`;
   const fenceFooter = '--- END EPIC CONTEXT ---';
 
-  return [body, fenceHeader, clippedDigest, fenceFooter, TASK_RESTATEMENT].join('\n\n');
+  const tail = finish ? `${finish.trim()}\n\n${TASK_RESTATEMENT}` : TASK_RESTATEMENT;
+
+  return [body, fenceHeader, clippedDigest, fenceFooter, tail].join('\n\n');
 }
 
 module.exports = {