claude-code-session-manager 0.72.0 → 0.73.0

package/src/main/lib/jobWorktree.cjs

@@ -2,28 +2,28 @@
  * jobWorktree.cjs — per-job `git worktree` isolation for concurrent scheduler
  * runs (PRD 994).
  *
- * Problem: once the queue genuinely runs several jobs wide in one project,
- * N headless `claude -p` processes edit the SAME working tree simultaneously.
- * Observed live on 2026-08-02 with only two concurrent writers: a full test
- * run failed on another job's half-written renderer files, a commit had to be
- * hand-staged to avoid sweeping a sibling job's WIP, and a commit was silently
- * rewritten to a new SHA by a concurrent rebase. This module gives each job
- * its own linked worktree — its edits, its test runs, its commit — isolated
- * from every sibling job and from the human's own interactive session in the
- * same repo.
+ * As of PRD 1032 this is a thin, byte-for-byte-compatible wrapper over the
+ * generalized primitives in gitWorktree.cjs (kind: 'job') — every export
+ * below keeps its original call shape so scheduler.cjs and any other
+ * existing caller need zero changes. New callers wanting the same isolation
+ * for a different kind of unit of work (e.g. an Epic session — kind: 'epic')
+ * should use gitWorktree.cjs's `create/integrate/cleanupEpicWorktree`
+ * directly rather than adding a second copy here.
  *
- * ---------- the ops-root hazard (read before touching cwd plumbing) ----------
+ * Problem this solves: once the queue genuinely runs several jobs wide in
+ * one project, N headless `claude -p` processes edit the SAME working tree
+ * simultaneously. Observed live on 2026-08-02 with only two concurrent
+ * writers: a full test run failed on another job's half-written renderer
+ * files, a commit had to be hand-staged to avoid sweeping a sibling job's
+ * WIP, and a commit was silently rewritten to a new SHA by a concurrent
+ * rebase. This module gives each job its own linked worktree — its edits,
+ * its test runs, its commit — isolated from every sibling job and from the
+ * human's own interactive session in the same repo.
  *
- * `<cwd>/session-manager-operations/` (PRDs, queue state, run logs) is
- * resolved from a project's cwd by lib/prdLocations.cjs and lib/queueStore.cjs
- * — every function there takes `cwd` as an explicit parameter, never
- * `process.cwd()`. That means the ops root follows WHATEVER cwd value the
- * caller passes in. A prior incident (recorded in this project's memory as
- * `no_schedule_self_e2e`) is exactly this mistake: swapping the job's cwd for
- * a worktree cwd gives the job a different, EMPTY ops root and orphans its own
- * PRD/queue row.
+ * ---------- the ops-root hazard (read before touching cwd plumbing) ----------
  *
- * The fix here is structural: this module never changes `job.cwd`. It hands
+ * See gitWorktree.cjs's own header comment for the full writeup — the rule
+ * carries forward unchanged: this module never changes `job.cwd`. It hands
  * back a SEPARATE `execCwd` (the worktree directory) that scheduler.cjs uses
  * ONLY as the spawned child process's `cwd` spawn option. Every PRD-path
  * resolution, queue read/write, and run-log path in scheduler.cjs keeps using
@@ -46,282 +46,25 @@
  */
 'use strict';
 
-const fs = require('node:fs');
-const fsp = require('node:fs/promises');
-const path = require('node:path');
-const os = require('node:os');
-const crypto = require('node:crypto');
-const { execFile } = require('node:child_process');
-
-// Root under which every job worktree is checked out. Kept OUTSIDE any
-// project's own tree (os.tmpdir(), not `<cwd>/.git/...`) so a job's worktree
-// never shows up in the main tree's own file listings, `find`, or a tsc
-// rootDir scan of `<cwd>`.
-const WORKTREE_ROOT = path.join(os.tmpdir(), 'session-manager-job-worktrees');
-
-// Disk estimate for this repo (session-manager): `git worktree add` checks
-// out only git-tracked source, not `node_modules`/`dist` — a fresh checkout
-// of this repo's tracked tree is ~30-40 MB (measured via `git ls-files | xargs
-// du -ch` on the working tree, minus the .git object store the worktree
-// shares with the main tree rather than duplicating). At the default cap of
-// 4 concurrent worktrees that's under 200 MB — negligible next to the
-// multi-GB `node_modules` a job's own `npm install`/build step may add inside
-// its worktree (uncounted here; that risk is bounded by MIN_FREE_MB_PER_JOB's
-// existing per-job memory gate in scheduler.cjs, not by this cap).
-const DEFAULT_MAX_CONCURRENT_WORKTREES = 4;
-
-function isWorktreeDisabled() {
-  return process.env.SM_JOB_WORKTREE_DISABLE === '1';
-}
-
-function getMaxConcurrentWorktrees() {
-  const raw = Number(process.env.SM_JOB_WORKTREE_MAX);
-  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_CONCURRENT_WORKTREES;
-}
-
-// In-memory count of worktrees currently checked out by THIS process. Reset
-// to 0 on every restart by design — a crash can never leave this counter
-// permanently wedged above the cap; reconcileWorktreesOnBoot cleans up any
-// leaked ON-DISK checkouts separately (see below).
-let activeWorktreeCount = 0;
-
-function execGit(args, { cwd, timeout = 20_000 } = {}) {
-  return new Promise((resolve, reject) => {
-    execFile('git', args, { cwd, timeout, windowsHide: true, encoding: 'utf8' }, (err, stdout, stderr) => {
-      if (err) {
-        err.stderrText = stderr;
-        reject(err);
-        return;
-      }
-      resolve(stdout || '');
-    });
-  });
-}
-
-async function isGitRepo(cwd) {
-  if (!cwd) return false;
-  try {
-    const out = await execGit(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 10_000 });
-    return out.trim() === 'true';
-  } catch {
-    return false;
-  }
-}
-
-/** True when `cwd`'s own working tree (not any worktree) has zero pending changes. */
-async function isBaseTreeClean(cwd) {
-  try {
-    const out = await execGit(['status', '--porcelain'], { cwd, timeout: 10_000 });
-    return out.trim().length === 0;
-  } catch {
-    return false;
-  }
-}
-
-function hashOf(input) {
-  return crypto.createHash('sha1').update(input).digest('hex').slice(0, 16);
-}
-
-function worktreeDirFor(cwd, slug) {
-  return path.join(WORKTREE_ROOT, hashOf(cwd), slug);
-}
-
-function branchNameFor(slug) {
-  return `sm-job/${slug}`;
-}
-
-/** Best-effort teardown of one worktree checkout — never throws. */
-async function removeWorktreeDir(cwd, dir) {
-  try {
-    await execGit(['worktree', 'remove', '--force', dir], { cwd, timeout: 15_000 });
-  } catch {
-    // Not registered (already removed) or dir already gone — fall through to
-    // a plain rm so a half-created checkout never leaks disk either.
-  }
-  try {
-    await fsp.rm(dir, { recursive: true, force: true });
-  } catch {
-    /* best-effort */
-  }
-}
-
-/**
- * Create a linked worktree for one job, on a fresh branch checked out from
- * the main tree's current HEAD. Returns `{ ok: true, dir, branch, baseCwd }`
- * on success, or `{ ok: false, reason }` — the reason is always a short,
- * human-readable string meant to be logged verbatim so a fallback to running
- * in place is never silent.
- *
- * Never throws: every failure mode (not a repo, dirty base, cap reached, git
- * error) is a normal, expected outcome for a project that hasn't opted into
- * — or currently can't support — isolation, not an exceptional one.
- */
-async function createJobWorktree({ cwd, slug }) {
-  if (isWorktreeDisabled()) return { ok: false, reason: 'disabled via SM_JOB_WORKTREE_DISABLE=1' };
-  if (!cwd || typeof cwd !== 'string') return { ok: false, reason: 'no cwd provided' };
-  if (!slug || typeof slug !== 'string') return { ok: false, reason: 'no slug provided' };
-
-  if (!(await isGitRepo(cwd))) return { ok: false, reason: 'not a git repository' };
-
-  // A dirty base tree means the job may be depending on the human's own
-  // uncommitted WIP in `cwd` — a worktree only ever checks out committed
-  // HEAD content, so isolating into one here would silently drop that WIP
-  // from what the job sees. Falling back to running in place is strictly
-  // safer than guessing.
-  if (!(await isBaseTreeClean(cwd))) return { ok: false, reason: 'base working tree has uncommitted changes' };
-
-  if (activeWorktreeCount >= getMaxConcurrentWorktrees()) {
-    return { ok: false, reason: `worktree cap reached (${getMaxConcurrentWorktrees()} concurrent)` };
-  }
-  // Reserve the slot SYNCHRONOUSLY (before any `await` below) so two jobs
-  // spawned in the same tick can't both pass the check above and both
-  // proceed — without this, the cap is a TOCTOU race: N concurrent callers
-  // all read the pre-increment count before either increments it. Released
-  // again below on any failure path so a failed create never permanently
-  // shrinks capacity.
-  activeWorktreeCount++;
-
-  const dir = worktreeDirFor(cwd, slug);
-  const branch = branchNameFor(slug);
-  try {
-    await fsp.mkdir(path.dirname(dir), { recursive: true });
-    // Defensive: a same-slug leftover from a prior crashed run (same slug can
-    // legitimately re-fire after a transient failure) must not collide with
-    // `git worktree add`'s own branch/path checks.
-    await removeWorktreeDir(cwd, dir);
-    try { await execGit(['branch', '-D', branch], { cwd, timeout: 10_000 }); } catch { /* didn't exist */ }
-    await execGit(['worktree', 'add', '-b', branch, dir, 'HEAD'], { cwd, timeout: 30_000 });
-  } catch (e) {
-    activeWorktreeCount = Math.max(0, activeWorktreeCount - 1);
-    return { ok: false, reason: `git worktree add failed: ${(e && (e.stderrText || e.message)) || e}` };
-  }
-  return { ok: true, dir, branch, baseCwd: cwd };
-}
-
-/**
- * Integrate a job's branch back into `cwd`'s current HEAD — fast-forward
- * when possible, a real merge commit when the main tree advanced underneath
- * (a sibling job merged first) since the worktree was created. Returns
- * `{ ok: true, integrated: boolean, ...}` on success (integrated:false means
- * the branch had no new commits — a legitimate no-op job, not a failure), or
- * `{ ok: false, reason }` when neither ff-only nor a real merge could land —
- * e.g. a genuine content conflict between two jobs that touched the same
- * lines. On failure the branch is left un-merged and NOT deleted (see
- * cleanupJobWorktree) so the work is recoverable, never silently discarded.
- */
-async function integrateJobBranch({ cwd, branch, slug }) {
-  if (!cwd || !branch) return { ok: false, reason: 'missing cwd/branch' };
-  let branchHead;
-  try {
-    branchHead = (await execGit(['rev-parse', branch], { cwd, timeout: 10_000 })).trim();
-  } catch (e) {
-    return { ok: false, reason: `branch ${branch} not found: ${(e && (e.stderrText || e.message)) || e}` };
-  }
-  let mergeBase = '';
-  try {
-    mergeBase = (await execGit(['merge-base', 'HEAD', branch], { cwd, timeout: 10_000 })).trim();
-  } catch {
-    mergeBase = '';
-  }
-  if (mergeBase && mergeBase === branchHead) {
-    return { ok: true, integrated: false, reason: 'branch has no new commits' };
-  }
-
-  try {
-    await execGit(['merge', '--ff-only', branch], { cwd, timeout: 30_000 });
-    return { ok: true, integrated: true, fastForward: true };
-  } catch {
-    // Main tree advanced since the worktree branched (a sibling job merged
-    // first) — a real merge commit still lands the job's own commit(s).
-  }
-  try {
-    await execGit(['merge', '--no-ff', '--no-edit', '-m', `merge scheduler job ${slug || branch}`, branch], { cwd, timeout: 30_000 });
-    return { ok: true, integrated: true, mergeCommit: true };
-  } catch (e) {
-    // Abort a half-applied merge so `cwd` isn't left in a mid-merge state.
-    try { await execGit(['merge', '--abort'], { cwd, timeout: 10_000 }); } catch { /* nothing to abort */ }
-    return { ok: false, reason: `merge failed (likely a real content conflict): ${(e && (e.stderrText || e.message)) || e}` };
-  }
-}
-
-/**
- * Tear down one job's worktree checkout after it has been integrated (or
- * failed to integrate). Always removes the linked-worktree checkout (freeing
- * its disk); only deletes the branch ref when `keepBranch` is falsy — a
- * failed integration keeps the branch around for manual recovery per
- * integrateJobBranch's contract above. Never throws.
- */
-async function cleanupJobWorktree({ cwd, dir, branch, keepBranch }) {
-  if (dir) await removeWorktreeDir(cwd, dir);
-  if (branch && !keepBranch) {
-    try { await execGit(['branch', '-D', branch], { cwd, timeout: 10_000 }); } catch { /* already gone */ }
-  }
-  try { await execGit(['worktree', 'prune'], { cwd, timeout: 10_000 }); } catch { /* best effort */ }
-  activeWorktreeCount = Math.max(0, activeWorktreeCount - 1);
-}
-
-/** Parse `git worktree list --porcelain` into `[{ worktree, branch }]`. */
-function parseWorktreeListPorcelain(text) {
-  const entries = [];
-  let cur = null;
-  for (const line of String(text || '').split('\n')) {
-    if (line.startsWith('worktree ')) {
-      cur = { worktree: line.slice('worktree '.length).trim(), branch: null };
-      entries.push(cur);
-    } else if (line.startsWith('branch ') && cur) {
-      cur.branch = line.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
-    }
-  }
-  return entries;
-}
+const gitWorktree = require('./gitWorktree.cjs');
 
-/**
- * Boot reconciliation: a job worktree that survives a process crash (app
- * killed mid-run, host reboot) leaks disk and a dangling branch forever
- * unless something cleans it up — this is that something. For each known
- * project cwd, lists every registered worktree, forcibly removes any that
- * live under WORKTREE_ROOT (ours; never touches a worktree a human created
- * for their own purposes), deletes its branch, and prunes stale registrations.
- * Never throws — a project that isn't a git repo, or has no worktrees, is a
- * silent no-op.
- */
-async function reconcileWorktreesOnBoot(cwds) {
-  const list = Array.isArray(cwds) ? cwds.filter(Boolean) : [];
-  for (const cwd of list) {
-    if (!(await isGitRepo(cwd))) continue;
-    let out = '';
-    try {
-      out = await execGit(['worktree', 'list', '--porcelain'], { cwd, timeout: 15_000 });
-    } catch {
-      continue;
-    }
-    const entries = parseWorktreeListPorcelain(out);
-    for (const entry of entries) {
-      if (!entry.worktree || !entry.worktree.startsWith(WORKTREE_ROOT + path.sep)) continue;
-      await removeWorktreeDir(cwd, entry.worktree);
-      if (entry.branch) {
-        try { await execGit(['branch', '-D', entry.branch], { cwd, timeout: 10_000 }); } catch { /* already gone */ }
-      }
-    }
-    try { await execGit(['worktree', 'prune'], { cwd, timeout: 10_000 }); } catch { /* best effort */ }
-  }
-}
+const KIND = 'job';
 
 module.exports = {
-  WORKTREE_ROOT,
-  DEFAULT_MAX_CONCURRENT_WORKTREES,
-  isWorktreeDisabled,
-  getMaxConcurrentWorktrees,
-  isGitRepo,
-  isBaseTreeClean,
-  worktreeDirFor,
-  branchNameFor,
-  createJobWorktree,
-  integrateJobBranch,
-  cleanupJobWorktree,
-  parseWorktreeListPorcelain,
-  reconcileWorktreesOnBoot,
+  WORKTREE_ROOT: gitWorktree.worktreeRootFor(KIND),
+  DEFAULT_MAX_CONCURRENT_WORKTREES: gitWorktree.KIND_CONFIG[KIND].defaultMax,
+  isWorktreeDisabled: () => gitWorktree.isWorktreeDisabled(KIND),
+  getMaxConcurrentWorktrees: () => gitWorktree.getMaxConcurrentWorktrees(KIND),
+  isGitRepo: gitWorktree.isGitRepo,
+  isBaseTreeClean: gitWorktree.isBaseTreeClean,
+  worktreeDirFor: (cwd, slug) => gitWorktree.worktreeDirFor(KIND, cwd, slug),
+  branchNameFor: (slug) => gitWorktree.branchNameFor(KIND, slug),
+  createJobWorktree: gitWorktree.createJobWorktree,
+  integrateJobBranch: gitWorktree.integrateJobBranch,
+  cleanupJobWorktree: gitWorktree.cleanupJobWorktree,
+  parseWorktreeListPorcelain: gitWorktree.parseWorktreeListPorcelain,
+  reconcileWorktreesOnBoot: (cwds) => gitWorktree.reconcileWorktreesOnBoot(cwds, { kind: KIND }),
   // Test-only escape hatch for the in-memory concurrency counter.
-  _resetActiveWorktreeCountForTests(n = 0) { activeWorktreeCount = n; },
-  _getActiveWorktreeCountForTests() { return activeWorktreeCount; },
+  _resetActiveWorktreeCountForTests(n = 0) { gitWorktree._resetActiveWorktreeCountForTests(KIND, n); },
+  _getActiveWorktreeCountForTests() { return gitWorktree._getActiveWorktreeCountForTests(KIND); },
 };

package/src/main/lib/promptSessionSchema.cjs

@@ -55,6 +55,17 @@ const EpicIntakeSectionSchema = z.object({
   source: z.string().optional(),
 });
 
+// Mirrors PromptSession's `worktree` field (src/renderer/state/
+// promptSessions.ts) — this Epic's isolated `git worktree` checkout, when
+// one exists. `baseCwd` is always the Epic's real owning-project cwd, never
+// the worktree dir itself (see gitWorktree.cjs's "ops-root hazard" comment).
+const EpicWorktreeSchema = z.object({
+  dir: z.string(),
+  branch: z.string(),
+  baseCwd: z.string(),
+  status: z.enum(['active', 'needs_merge_resolution', 'merged', 'disabled']),
+});
+
 // Mirrors PromptSession (src/renderer/state/promptSessions.ts:29-76).
 const PromptSessionSchema = z.object({
   id: z.string(),
@@ -73,6 +84,9 @@ const PromptSessionSchema = z.object({
   // rendering the flat `openingPrompt` as a single block (see
   // ChatTranscriptTurn.tsx's EpicIntakeCard).
   sections: z.array(EpicIntakeSectionSchema).optional(),
+  // Passthrough only as of PRD 1032 — nothing populates this yet; the next
+  // PRD in this chain wires Epic worktree minting.
+  worktree: EpicWorktreeSchema.optional(),
 });
 
 /**
@@ -97,5 +111,6 @@ module.exports = {
   EpicSourceSchema,
   EpicTagSchema,
   EpicIntakeSectionSchema,
+  EpicWorktreeSchema,
   assertValidPromptSession,
 };

package/src/main/lib/queueStore.cjs

@@ -40,8 +40,26 @@ const MACHINE_STATE_PATH = path.join(os.homedir(), '.claude', 'session-manager',
 const LEGACY_QUEUE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'queue.json');
 const STATE_SUBPATH = ['session-manager-operations', 'scheduler', 'state'];
 
+/**
+ * A project's `session-manager-operations/scheduler/state/` directory.
+ *
+ * The cwd MUST be absolute. `path.join()` happily accepts a relative one and
+ * silently resolves it against `process.cwd()`, which turns a bad caller into
+ * a whole ops root materialized in the wrong place — observed live on
+ * 2026-08-13 as five stray `session-manager-operations/scheduler/state/
+ * queue.json` trees under source directories (`src/main/lib/`,
+ * `src/renderer/state/`, …), each created by a caller that passed a
+ * repo-relative path like `src/main/lib`. That is the same ops-root hazard
+ * gitWorktree.cjs's header comment describes, reached from the other end: not
+ * a worktree dir substituted for a project cwd, but a relative fragment
+ * accepted as one. Fail closed — a caller that cannot name an absolute
+ * project cwd has no business writing that project's queue.
+ */
 function projectStateDir(cwd) {
   if (!cwd || typeof cwd !== 'string') throw new Error('projectStateDir: cwd is required');
+  if (!path.isAbsolute(cwd)) {
+    throw new Error(`projectStateDir: cwd must be an absolute path, got "${cwd}"`);
+  }
   return path.join(cwd, ...STATE_SUBPATH);
 }
 

package/src/main/lib/terminalRunOutcome.cjs

@@ -67,7 +67,16 @@ function latestTerminalOutcomeForSlug(slug, { runsDir, fsImpl = fs } = {}) {
     try {
       meta = JSON.parse(fsImpl.readFileSync(metaPath, 'utf8'));
     } catch {
-      return null;
+      // An unreadable/half-written sidecar in THIS dir says nothing about the
+      // older ones — fall through to the next-newest candidate rather than
+      // abandoning the scan. Returning null here made the caller treat the
+      // slug as having no terminal run at all, which resurrects and re-runs
+      // an already-completed PRD (the anti-resurrection guard silently
+      // switching itself off on the one input it exists to survive). This is
+      // also what makes MAX_DIRS_SCANNED mean what its name says: before,
+      // every branch below returned on the FIRST candidate, so the newest dir
+      // was the only one ever consulted.
+      continue;
     }
 
     // meta.json's finishedAt is an epoch-ms number; callers (e.g. the
@@ -86,7 +95,10 @@ function latestTerminalOutcomeForSlug(slug, { runsDir, fsImpl = fs } = {}) {
     try {
       verdicts = JSON.parse(fsImpl.readFileSync(verdictsPath, 'utf8'));
     } catch {
-      return null;
+      // Same reasoning as the meta read above: a run whose verdicts sidecar
+      // never landed (killed between the two writes) must not erase an older,
+      // complete terminal record for this slug.
+      continue;
     }
 
     if (COMPLETED_EQUIVALENT_VERDICTS.has(verdicts.verdict)) {

package/src/main/pty.cjs

@@ -21,6 +21,7 @@ const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { checkInsideHome } = require('./lib/insideHome.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const opsErrorLog = require('./lib/opsErrorLog.cjs');
+const { resolveEpicSpawnCwd } = require('./lib/epicSpawnCwd.cjs');
 
 // Absolute path to the installed package root (src/main/ -> ../../), shown in
 // the remediation message so the user can cd there and rebuild.
@@ -159,6 +160,15 @@ class PtyManager {
 
     const shell = process.env.SHELL || '/bin/bash';
     console.log('[pty] spawning shell', shell);
+    // Tab ID = claudeSessionId (see CLAUDE.md), so for an Epic-attached tab
+    // this resolves the Epic's own record in `cwd`'s active-index.json and
+    // returns its isolated worktree dir when one exists — `cwd` itself is
+    // NEVER repointed; only this actual PTY spawn option is. See
+    // epicSpawnCwd.cjs's header comment (the ops-root hazard) for why.
+    const spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: tabId });
+    if (spawnCwd !== cwd) {
+      console.log(`[pty] tabId=${tabId} isolated in worktree ${spawnCwd}`);
+    }
     let proc;
     try {
       // Interactive login shell so aliases / nvm / PATH resolve correctly.
@@ -166,7 +176,7 @@ class PtyManager {
         name: 'xterm-256color',
         cols,
         rows,
-        cwd,
+        cwd: spawnCwd,
         env,
       });
     } catch (err) {

package/src/main/queueOps.cjs

@@ -287,19 +287,44 @@ async function lintAll() {
 // ────────────────────────────────────────────── archive
 
 /**
- * Move PRDS_DIR/<slug>.md → PRDS_ARCHIVE_DIR/<ISO>/<slug>.md.
+ * Move <srcDir>/<slug>.md → <srcDir>/../prds-archived/<ISO>/<slug>.md.
  * Atomic rename. Path containment checks both source and destination.
  * Never deletes — always reversible from prds-archived/.
  */
-async function archiveOne(slug, archiveDir) {
+/**
+ * The archive directory a PRD found in `srcDir` belongs in: `prds-archived/`
+ * SIBLING to its own `prds/`, which for a per-project PRD is
+ * `<cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds-archived/`.
+ *
+ * PRD sources are per-project and per-Epic (CLAUDE.md's TAB → EPIC → PRD
+ * model); the machine-level `~/.claude/session-manager/scheduled-plans/` tree
+ * holds only run logs and PRD_AUTHORING.md. Archiving therefore has to follow
+ * the source, not a fixed global constant — otherwise a manual archive yanks a
+ * PRD out of its Epic and strands it in the retired global tree, splitting one
+ * Epic's history across two locations (observed 2026-08-13 with
+ * 1035-epic-worktree-ui-surfacing, whose three chain siblings sat in the Epic's
+ * own prds-archived/ while it landed under scheduled-plans/). A PRD still in
+ * the legacy flat `PRDS_DIR` resolves to `ROOT/prds-archived` here, which is
+ * exactly the old behavior — so that case is unchanged.
+ */
+function archiveDirForSource(srcDir, ts) {
+  return path.join(path.dirname(srcDir), 'prds-archived', ts);
+}
+
+async function archiveOne(slug, ts) {
   if (!SLUG_RE.test(slug)) return { ok: false, slug, error: 'invalid slug' };
   const srcDir = await findPrdDir(slug);
   if (!srcDir) return { ok: false, slug, error: 'not found in any PRDs dir' };
   const src = path.resolve(path.join(srcDir, `${slug}.md`));
   if (!src.startsWith(srcDir + path.sep)) return { ok: false, slug, error: 'path escape (src)' };
+  // Destination is derived per-slug (not once for the whole batch): a single
+  // archive call can span several projects/Epics, and each PRD has to land
+  // beside its own source.
+  const archiveDir = archiveDirForSource(srcDir, ts);
   const dst = path.resolve(path.join(archiveDir, `${slug}.md`));
-  if (!dst.startsWith(PRDS_ARCHIVE_DIR + path.sep)) return { ok: false, slug, error: 'path escape (dst)' };
+  if (!dst.startsWith(path.resolve(archiveDir) + path.sep)) return { ok: false, slug, error: 'path escape (dst)' };
   try {
+    await fsp.mkdir(archiveDir, { recursive: true });
     await fsp.rename(src, dst);
     return { ok: true, slug, archivedTo: dst };
   } catch (e) {
@@ -321,17 +346,14 @@ async function archiveMany(slugs) {
   if (!Array.isArray(slugs) || slugs.length === 0) {
     return { ok: true, archived: 0, archivedTo: null, results: [] };
   }
+  // One timestamp for the whole batch (so a multi-slug archive reads as one
+  // event), but each slug's destination DIRECTORY is resolved from its own
+  // source inside archiveOne — see archiveDirForSource. mkdir moved in there
+  // for the same reason: there is no single batch-wide dir to pre-create.
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const archiveDir = path.join(PRDS_ARCHIVE_DIR, ts);
-  try {
-    await fsp.mkdir(archiveDir, { recursive: true });
-  } catch (e) {
-    logs.writeLine({ level: 'error', scope: 'queueOps', message: 'archiveMany: mkdir failed', meta: { error: e?.message } });
-    return { ok: false, archived: 0, archivedTo: null, results: [], error: e?.message ?? 'mkdir failed' };
-  }
   const results = [];
   for (const slug of slugs) {
-    results.push(await archiveOne(slug, archiveDir));
+    results.push(await archiveOne(slug, ts));
   }
   const archived = results.filter((r) => r.ok).length;
   const archivedSlugs = results.filter((r) => r.ok).map((r) => r.slug);
@@ -340,7 +362,12 @@ async function archiveMany(slugs) {
       logs.writeLine({ level: 'warn', scope: 'queueOps', message: 'archiveMany: retireCompletedSlugs failed', meta: { error: e?.message } });
     });
   }
-  return { ok: true, archived, archivedTo: archiveDir, results };
+  // archivedTo reports where the batch actually landed. With per-source
+  // destinations that is only well-defined when every move agreed on one dir
+  // (the common single-project case); a genuinely cross-project batch reports
+  // null rather than naming one project's dir as if it covered them all.
+  const dirs = new Set(results.filter((r) => r.ok).map((r) => path.dirname(r.archivedTo)));
+  return { ok: true, archived, archivedTo: dirs.size === 1 ? [...dirs][0] : null, results };
 }
 
 // ────────────────────────────────────────────── auto-archive completed PRDs
@@ -597,6 +624,7 @@ module.exports = {
   retagMany,
   PRDS_DIR,
   PRDS_ARCHIVE_DIR,
+  archiveDirForSource,
   candidatePrdsDirs,
   findPrdDir,
 };

package/src/main/scheduler.cjs

@@ -124,6 +124,7 @@ function resolveOriginSessionId(cwd, epicId) {
 }
 const sessionSlots = require('./lib/sessionSlots.cjs');
 const jobWorktree = require('./lib/jobWorktree.cjs');
+const { reconcileEpicWorktreesOnBoot } = require('./lib/epicWorktreeBoot.cjs');
 const queueStore = require('./lib/queueStore.cjs');
 const { splitFrontmatter, parsePrdFile, serializePrdFile } = require('./lib/prdFrontmatter.cjs');
 const { migratePrds, consolidateFlatPrds, legacyAdoptExistingPrds } = require('./lib/prdMigration.cjs');
@@ -4967,6 +4968,19 @@ async function init() {
       console.error('[scheduler] boot worktree reconciliation failed', e?.message);
     }
 
+    // Epic worktree boot reconciliation (PRD 1033): same sweep, epic kind —
+    // reaps only a worktree whose owning Epic is no longer 'active' in that
+    // project's own active-index.json (see epicWorktreeBoot.cjs). Reuses the
+    // same known-cwd set as the job sweep above; best-effort, never blocks
+    // the rest of boot.
+    try {
+      const worktreeCwds = new Set(bootSnap.jobs.map((j) => j.cwd).filter(Boolean));
+      worktreeCwds.add(DEFAULT_PROJECT_CWD);
+      await reconcileEpicWorktreesOnBoot([...worktreeCwds]);
+    } catch (e) {
+      console.error('[scheduler] boot epic-worktree reconciliation failed', e?.message);
+    }
+
     const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
     const bootOutcomes = new Map();
     for (const j of bootSnap.jobs) {