claude-code-session-manager 0.82.0 → 0.84.0

package/src/main/lib/gitWorktree.cjs

@@ -172,8 +172,31 @@ function isUnderRoot(p, root) {
 // versa). Reset to 0 per kind on every restart by design — a crash can never
 // leave either counter permanently wedged above its cap; reconcileWorktreesOnBoot
 // cleans up any leaked ON-DISK checkouts separately (see below).
+//
+// This counter can still drift UPWARD of reality (a missed decrement —
+// cleanupWorktree never ran because the owning process crashed, was
+// reaped, or SIGTERM'd before teardown) for as long as the app keeps
+// running. `reserveWorktreeSlot` below is what makes that drift
+// self-healing: instead of trusting this counter forever once it reaches
+// the cap, a rejection is verified against OBSERVED on-disk reality
+// (`getObservedWorktreeCount`) before being honored, and the counter is
+// corrected down to match reality when it's proven to have leaked.
 const activeWorktreeCount = { job: 0, epic: 0 };
 
+// Per-kind promise chain used as a simple async mutex (see `withKindLock`)
+// so the cap-check-and-reserve decision in `reserveWorktreeSlot` — which now
+// sometimes needs to `await` a fresh on-disk observation — stays a single
+// atomic step across concurrent callers, the same guarantee the old
+// purely-synchronous check+increment gave for free.
+const worktreeCapLockChain = { job: Promise.resolve(), epic: Promise.resolve() };
+
+// Short-TTL memo of `getObservedWorktreeCount`'s result, per kind, so a burst
+// of callers hitting the cap in quick succession (e.g. several scheduler
+// ticks in a row while the machine is genuinely full) doesn't turn into a
+// `git worktree list` storm. Cleared per-kind by the test hook below.
+const observedWorktreeCountCache = { job: { count: null, at: 0 }, epic: { count: null, at: 0 } };
+const OBSERVED_WORKTREE_COUNT_TTL_MS = 2000;
+
 function execGit(args, { cwd, timeout = 20_000 } = {}) {
   return new Promise((resolve, reject) => {
     execFile('git', args, { cwd, timeout, windowsHide: true, encoding: 'utf8' }, (err, stdout, stderr) => {
@@ -350,15 +373,27 @@ async function teardownOrphanedCheckout(dir) {
  *
  * A checkout younger than `staleAgeMs` (mtime-based) is NEVER touched — this
  * is what keeps an in-progress job or Epic safe from a concurrent boot sweep.
- * This intentionally does NOT accept an `isLive` predicate the way
+ * This intentionally does NOT accept a queue-aware `isLive` predicate the way
  * `reconcileWorktreesOnBoot`'s per-cwd pass does: that predicate is scoped to
  * ONE project's own active-index.json per call, but this sweep walks EVERY
  * project's checkouts under the shared kind root in one pass — applying one
  * project's liveness answer to another project's checkout would be worse
  * than no answer at all (a false "not live" for a foreign key would tear
  * down a genuinely active Epic before its own project's turn ever runs this
- * sweep). The age threshold (7 days for epics, by default) is the only
- * safety margin here, deliberately.
+ * sweep).
+ *
+ * It DOES, however, check `hasLiveHolder` on every candidate that clears the
+ * age threshold: unlike a queue-derived `isLive`, a live `/proc` cwd holder
+ * is project-agnostic and machine-global — a directory's mtime does NOT
+ * advance when a long-running process only writes into subdirectories of it
+ * (exactly the "starry-night-ships"-class workload), so an old mtime is not
+ * proof of abandonment. A process still holding the checkout as its cwd is
+ * authoritative over any timer and is never reaped, regardless of age.
+ * `holders` may be supplied precomputed (one `/proc` scan reused across many
+ * candidates/kinds); when omitted this computes its own. On darwin (no
+ * `/proc`) `listCwdHolders`/`hasLiveHolder` always report no holder, so the
+ * age threshold alone gates darwin — same accepted tradeoff as
+ * `reclaimTerminalJobOrphans`'s `isLive`.
  *
  * Every path visited is verified (`isUnderRoot`) to be nested under this
  * kind's own root before any read or delete, so a maliciously-shaped on-disk
@@ -371,6 +406,7 @@ async function sweepStaleWorktreeCheckouts(kind, opts = {}) {
   const staleAgeMs = Number.isFinite(opts.staleAgeMs) && opts.staleAgeMs >= 0
     ? opts.staleAgeMs
     : getStaleSweepAgeMs(kind);
+  const holders = opts.holders instanceof Set ? opts.holders : listCwdHolders();
   const result = { checkoutsRemoved: 0, emptyRootsRemoved: 0 };
 
   let hashEntries;
@@ -405,6 +441,11 @@ async function sweepStaleWorktreeCheckouts(kind, opts = {}) {
       }
       if (Date.now() - stat.mtimeMs < staleAgeMs) continue; // still fresh — never touched
 
+      if (hasLiveHolder(checkoutDir, holders)) {
+        console.log(`[gitWorktree] stale-age sweep (kind:${kind}): skipping ${checkoutDir} — live cwd holder outlasts the age threshold`);
+        continue;
+      }
+
       try {
         await teardownOrphanedCheckout(checkoutDir);
         result.checkoutsRemoved++;
@@ -465,6 +506,199 @@ async function captureAndCarryBaseDiff({ cwd, dir }) {
   return { ok: true, paths };
 }
 
+/**
+ * Counts how many worktrees of `kind` genuinely exist on disk RIGHT NOW,
+ * machine-wide — not limited to any one project's cwd, since the in-memory
+ * cap (`activeWorktreeCount`) is itself shared across every project using
+ * this kind. Walks the kind's own root directory (same enumeration
+ * `sweepStaleWorktreeCheckouts` uses) to find candidate checkouts, resolves
+ * each to its owning main tree via `mainTreeFromWorktreeGitFile` (never
+ * trusting a directory's mere presence — a half-created or already-removed
+ * checkout must not count), then asks EACH distinct main tree's own `git
+ * worktree list --porcelain` (the same invocation `reconcileWorktreesOnBoot`
+ * already uses, via `execGit`/`parseWorktreeListPorcelain` — no second
+ * git-invocation style) which of its registered worktrees still live under
+ * this kind's root. Never throws; an unreadable root or a git failure for a
+ * given main tree simply contributes 0 from that tree rather than aborting
+ * the whole count.
+ */
+async function computeObservedWorktreeCount(kind) {
+  const root = worktreeRootFor(kind);
+  let hashEntries;
+  try {
+    hashEntries = await fsp.readdir(root, { withFileTypes: true });
+  } catch {
+    return 0; // root doesn't exist (or unreadable) — nothing on disk
+  }
+
+  const checkoutDirs = [];
+  for (const hashEntry of hashEntries) {
+    if (!hashEntry.isDirectory()) continue;
+    const hashDir = path.join(root, hashEntry.name);
+    if (!isUnderRoot(hashDir, root)) continue;
+    let keyEntries;
+    try {
+      keyEntries = await fsp.readdir(hashDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const keyEntry of keyEntries) {
+      if (!keyEntry.isDirectory()) continue;
+      const checkoutDir = path.join(hashDir, keyEntry.name);
+      if (isUnderRoot(checkoutDir, root)) checkoutDirs.push(checkoutDir);
+    }
+  }
+  if (!checkoutDirs.length) return 0;
+
+  const mainTrees = new Set();
+  for (const dir of checkoutDirs) {
+    const mainTree = await mainTreeFromWorktreeGitFile(dir);
+    if (mainTree) mainTrees.add(mainTree);
+  }
+
+  const liveWorktreePaths = new Set();
+  for (const mainTree of mainTrees) {
+    let out = '';
+    try {
+      out = await execGit(['worktree', 'list', '--porcelain'], { cwd: mainTree, timeout: 15_000 });
+    } catch {
+      continue; // that main tree is unreadable right now — its worktrees simply don't count this pass
+    }
+    for (const entry of parseWorktreeListPorcelain(out)) {
+      if (entry.worktree && isUnderRoot(entry.worktree, root)) {
+        liveWorktreePaths.add(path.resolve(entry.worktree));
+      }
+    }
+  }
+  return liveWorktreePaths.size;
+}
+
+/**
+ * Enumerates every process on the machine currently holding some directory as
+ * its cwd, as a Set of resolved absolute paths (never throws). Linux-only —
+ * walks `/proc/*\/cwd` via `readlinkSync`, tolerating a per-pid `EACCES`
+ * (owned by another user) or `ENOENT`/`ESRCH` (process exited between the
+ * `readdir` and the `readlink`) by simply skipping that pid rather than
+ * aborting the whole scan. On darwin (no `/proc`) returns an empty Set with
+ * no log line — `hasLiveHolder`'s caller is expected to also gate on a live
+ * `runtime.pid`, which is the darwin-covering half of that check.
+ *
+ * A readlink target ending in ` (deleted)` (the kernel's marker for a cwd
+ * whose directory entry was unlinked while still held open) has that suffix
+ * stripped before being added, so a holder of an already-unlinked directory
+ * still counts as a holder of the original path.
+ */
+function listCwdHolders() {
+  const holders = new Set();
+  if (process.platform !== 'linux') return holders;
+  let pids;
+  try {
+    pids = fs.readdirSync('/proc').filter((name) => /^\d+$/.test(name));
+  } catch {
+    return holders;
+  }
+  const DELETED_SUFFIX = ' (deleted)';
+  for (const pid of pids) {
+    try {
+      const target = fs.readlinkSync(`/proc/${pid}/cwd`);
+      const clean = target.endsWith(DELETED_SUFFIX) ? target.slice(0, -DELETED_SUFFIX.length) : target;
+      holders.add(path.resolve(clean));
+    } catch {
+      // EACCES (not our process), ENOENT/ESRCH (pid exited mid-scan) — skip.
+    }
+  }
+  return holders;
+}
+
+/**
+ * True when any process on the machine holds `dir` (or a path nested under
+ * it) as its cwd — the liveness signal that lets boot reconciliation tell a
+ * worktree still backing a running `claude -p` executor (survives an Electron
+ * restart via `detached: true`) apart from a genuinely abandoned one. Never
+ * throws.
+ *
+ * `holders`, when supplied, must be a `Set` already produced by
+ * `listCwdHolders()` — this lets a caller sweeping N candidate worktrees
+ * compute the `/proc` scan once and reuse it, rather than paying a full
+ * `readdir` + per-pid `readlink` pass for every candidate. When omitted, this
+ * computes its own (a single-candidate convenience, and what the bare
+ * `hasLiveHolder(dir)` contract in the AC exercises directly).
+ */
+function hasLiveHolder(dir, holders) {
+  try {
+    if (!dir || typeof dir !== 'string') return false;
+    if (process.platform !== 'linux') return false;
+    const resolvedDir = path.resolve(dir);
+    const set = holders instanceof Set ? holders : listCwdHolders();
+    for (const holder of set) {
+      if (holder === resolvedDir || holder.startsWith(resolvedDir + path.sep)) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** TTL-memoized wrapper over `computeObservedWorktreeCount` — see the cache header above. */
+async function getObservedWorktreeCount(kind, ttlMs = OBSERVED_WORKTREE_COUNT_TTL_MS) {
+  const cache = observedWorktreeCountCache[kind];
+  const now = Date.now();
+  if (cache.count !== null && now - cache.at < ttlMs) return cache.count;
+  const count = await computeObservedWorktreeCount(kind);
+  cache.count = count;
+  cache.at = now;
+  return count;
+}
+
+/**
+ * Serializes `fn` per kind via a promise chain, so the cap-check-and-reserve
+ * decision below stays a single atomic step across concurrent callers even
+ * though it now sometimes needs to `await` a fresh on-disk observation.
+ * `worktreeCapLockChain[kind]` is deliberately kept always-resolving (its
+ * own rejection is swallowed) so one caller's failure can never wedge every
+ * later caller behind it.
+ */
+function withKindLock(kind, fn) {
+  const previous = worktreeCapLockChain[kind];
+  const result = previous.then(fn, fn);
+  worktreeCapLockChain[kind] = result.then(() => {}, () => {});
+  return result;
+}
+
+/**
+ * Decides whether a new worktree of `kind` may be created right now, and if
+ * so reserves the slot — the single choke point `createWorktree` calls
+ * before doing any actual git work. Replaces the old bare
+ * `if (activeWorktreeCount[kind] >= cap) reject; else activeWorktreeCount[kind]++`
+ * with the same fast path when comfortably under cap (no await at all, same
+ * as before), but when the in-memory counter is AT OR OVER the cap, verifies
+ * that against observed on-disk reality before honoring the rejection —
+ * self-healing a leaked (never-decremented) counter instead of wedging the
+ * cap at a stale high-water mark for the rest of the process's life.
+ *
+ * TOCTOU safety for concurrent callers: the entire decision (including the
+ * observed-count await) runs inside `withKindLock`, so only one caller per
+ * kind is ever mid-decision at a time — a strictly stronger guarantee than
+ * the old purely-synchronous check+increment, which only protected callers
+ * that happened to land in the same tick.
+ */
+async function reserveWorktreeSlot(kind) {
+  return withKindLock(kind, async () => {
+    const cap = getMaxConcurrentWorktrees(kind);
+    if (activeWorktreeCount[kind] >= cap) {
+      const observed = await getObservedWorktreeCount(kind);
+      if (observed < activeWorktreeCount[kind]) {
+        activeWorktreeCount[kind] = observed;
+      }
+      if (activeWorktreeCount[kind] >= cap) {
+        return { ok: false, reason: `worktree cap reached (${cap} concurrent)` };
+      }
+    }
+    activeWorktreeCount[kind]++;
+    return { ok: true };
+  });
+}
+
 /**
  * Create a linked worktree on a fresh branch checked out from the main
  * tree's current HEAD. Returns `{ ok: true, dir, branch, baseCwd,
@@ -500,16 +734,11 @@ async function createWorktree({ kind, cwd, key }) {
 
   const baseWasClean = await isBaseTreeClean(cwd);
 
-  if (activeWorktreeCount[kind] >= getMaxConcurrentWorktrees(kind)) {
-    return { ok: false, reason: `worktree cap reached (${getMaxConcurrentWorktrees(kind)} concurrent)` };
-  }
-  // Reserve the slot SYNCHRONOUSLY (before any `await` below) so two callers
-  // invoked 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[kind]++;
+  // Cap check + slot reservation as a single atomic step, per kind — see
+  // reserveWorktreeSlot's header. Released again below on any failure path
+  // so a failed create never permanently shrinks capacity.
+  const reservation = await reserveWorktreeSlot(kind);
+  if (!reservation.ok) return reservation;
 
   const dir = worktreeDirFor(kind, cwd, key);
   const branch = branchNameFor(kind, key);
@@ -607,6 +836,49 @@ function parseBlockingMergePaths(stderrText) {
   return { tracked: Array.from(new Set(tracked)), untracked: Array.from(new Set(untracked)) };
 }
 
+/**
+ * Resolves `cwd`'s default branch, without ever hardcoding `main`: prefers
+ * the remote-tracked default (`origin/HEAD`, set by `git clone`/`git remote
+ * set-head`), falls back to the repo's own `init.defaultBranch` config, then
+ * to whichever of a local `main`/`master` branch actually exists, and only
+ * as a last resort assumes `main`. Never throws — every git failure along
+ * this chain (no remote, no config, no matching local branch) simply falls
+ * through to the next source.
+ */
+async function resolveDefaultBranch(cwd) {
+  try {
+    const out = (await execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'], { cwd, timeout: 10_000 })).trim();
+    const match = out.match(/^refs\/remotes\/origin\/(.+)$/);
+    if (match && match[1]) return match[1];
+  } catch { /* no remote, or origin/HEAD not set — fall through */ }
+  try {
+    const out = (await execGit(['config', '--get', 'init.defaultBranch'], { cwd, timeout: 10_000 })).trim();
+    if (out) return out;
+  } catch { /* not configured — fall through */ }
+  try {
+    await execGit(['show-ref', '--verify', '--quiet', 'refs/heads/main'], { cwd, timeout: 10_000 });
+    return 'main';
+  } catch { /* no local main — fall through */ }
+  try {
+    await execGit(['show-ref', '--verify', '--quiet', 'refs/heads/master'], { cwd, timeout: 10_000 });
+    return 'master';
+  } catch { /* no local master either — fall through */ }
+  return 'main';
+}
+
+/**
+ * `cwd`'s current branch name, or `null` on a detached HEAD (or any other
+ * state `git symbolic-ref` can't resolve to a branch). Never throws.
+ */
+async function getCurrentBranch(cwd) {
+  try {
+    const out = (await execGit(['symbolic-ref', '-q', '--short', 'HEAD'], { cwd, timeout: 10_000 })).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Integrate a branch back into `cwd`'s current HEAD — fast-forward when
  * possible, a real merge commit when the main tree advanced underneath (a
@@ -625,9 +897,30 @@ function parseBlockingMergePaths(stderrText) {
  * job's own work — landing such a commit would just re-apply the human's
  * uncommitted edit back onto itself via a merge, and could conflict with
  * the base tree still holding that same path dirty.
+ *
+ * Refuses outright — before touching any other git state — when `cwd`'s
+ * HEAD is not on the repo's own default branch (resolved via
+ * `resolveDefaultBranch`, never hardcoded to `main`) or is detached. A
+ * stray checkout onto some other branch (e.g. a leftover `sm-job/*` branch
+ * from a prior run) would otherwise make every subsequent merge-base/merge
+ * silently target the WRONG tree, producing merge "conflicts" that are
+ * really just wrong-base artifacts (RCA: starry-night-ships, 2026-09-12).
+ * This refusal never checks out, resets, or switches anything — it only
+ * reports; a human fixes the checkout.
  */
 async function integrateBranch({ cwd, branch, key, kind, carriedPaths }) {
   if (!cwd || !branch) return { ok: false, reason: 'missing cwd/branch' };
+
+  const defaultBranch = await resolveDefaultBranch(cwd);
+  const currentBranch = await getCurrentBranch(cwd);
+  if (currentBranch !== defaultBranch) {
+    const actual = currentBranch === null ? 'detached HEAD' : currentBranch;
+    return {
+      ok: false,
+      reason: `refusing to integrate: HEAD is on "${actual}", not the repo's default branch "${defaultBranch}" — a stray checkout must be fixed before integration can proceed`,
+    };
+  }
+
   let branchHead;
   try {
     branchHead = (await execGit(['rev-parse', branch], { cwd, timeout: 10_000 })).trim();
@@ -901,6 +1194,99 @@ function keyFromBranch(kind, branch) {
   return branch.slice(prefix.length);
 }
 
+/**
+ * Reclaims a job-kind worktree checkout whose OWNING QUEUE ROW is already
+ * terminal (`completed`/`failed`/`skipped` — passed in via `terminalSlugs`)
+ * without waiting for either the stale-age sweep (`sweepStaleWorktreeCheckouts`,
+ * gated on `staleSweepAgeMs`, default 24h) or the next app boot
+ * (`reconcileWorktreesOnBoot` only runs once, at startup). A job whose run
+ * ended without ever reaching `cleanupWorktree` (crash, reap, SIGTERM, an
+ * exception before teardown) otherwise leaves its checkout on disk
+ * indefinitely even though the row itself already resolved.
+ *
+ * Never assumes it's safe to delete — proves it, two ways, for each
+ * candidate:
+ *   1. `isBranchMergedIntoHead`: the branch holds ZERO commits that aren't
+ *      already on `cwd`'s HEAD (equivalently, zero commits ahead of main) —
+ *      so integrating it again could add nothing, and removing it loses no
+ *      committed work.
+ *   2. Every path still dirty in the checkout itself (`git status
+ *      --porcelain` run with cwd = the checkout dir) lives under
+ *      `session-manager-operations/` — i.e. it's carried-over ops-folder
+ *      noise (queue.json/history.jsonl churn picked up by
+ *      `captureAndCarryBaseDiff` when the worktree was created), never real
+ *      uncommitted job output.
+ *
+ * A candidate failing either check is left alone for a human/the stale-age
+ * sweep to deal with. Returns the list of slugs actually reclaimed. Never
+ * throws.
+ *
+ * Neither proof above is a liveness check: a still-running executor that
+ * hasn't committed yet trivially satisfies proof 1 (zero commits ahead), and
+ * satisfies proof 2 whenever its in-progress output is gitignored. So an
+ * optional `isLive(slug, entry)` predicate — supplied by the caller, which
+ * alone knows the owning queue row's recorded pid; this module keeps no
+ * queue knowledge of its own — is checked FIRST, before either proof, since
+ * it is the cheapest and most decisive gate. A candidate it reports live is
+ * skipped and logged once, without ever reaching (or affecting) the
+ * merge/status proofs below. `isLive` throwing is treated fail-SAFE: assume
+ * live (skip), never assume dead — leaking a checkout one more sweep cycle
+ * is far cheaper than deleting a running job's worktree out from under it.
+ */
+async function reclaimTerminalJobOrphans({ cwd, terminalSlugs, isLive }) {
+  const kind = 'job';
+  const root = worktreeRootFor(kind);
+  const reclaimed = [];
+  if (!cwd || !(terminalSlugs instanceof Set) || terminalSlugs.size === 0) return reclaimed;
+  if (!(await isGitRepo(cwd))) return reclaimed;
+
+  let out = '';
+  try {
+    out = await execGit(['worktree', 'list', '--porcelain'], { cwd, timeout: 15_000 });
+  } catch {
+    return reclaimed;
+  }
+
+  for (const entry of parseWorktreeListPorcelain(out)) {
+    if (!entry.worktree || !isUnderRoot(entry.worktree, root)) continue;
+    const slug = keyFromBranch(kind, entry.branch);
+    if (!slug || !terminalSlugs.has(slug)) continue;
+
+    if (typeof isLive === 'function') {
+      let live;
+      try {
+        live = await isLive(slug, entry);
+      } catch {
+        live = true; // fail-safe: an isLive that throws must never be read as "dead"
+      }
+      if (live) continue;
+    }
+
+    const merged = await isBranchMergedIntoHead(cwd, entry.branch);
+    if (!merged) continue; // real un-landed work — never touch
+
+    let statusOut = '';
+    try {
+      statusOut = await execGit(['status', '--porcelain'], { cwd: entry.worktree, timeout: 15_000 });
+    } catch {
+      continue; // can't prove the checkout is clean-of-real-work — never assume
+    }
+    const dirtyPaths = statusOut.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+    const opsOnly = dirtyPaths.every(
+      (p) => p === 'session-manager-operations' || p.startsWith('session-manager-operations/')
+    );
+    if (!opsOnly) continue; // real non-ops dirty content present — leave for a human
+
+    await removeWorktreeDir(cwd, entry.worktree);
+    if (entry.branch) {
+      try { await execGit(['branch', '-D', entry.branch], { cwd, timeout: 10_000 }); } catch { /* already gone */ }
+    }
+    reclaimed.push(slug);
+  }
+  try { await execGit(['worktree', 'prune'], { cwd, timeout: 10_000 }); } catch { /* best-effort */ }
+  return reclaimed;
+}
+
 /**
  * Boot reconciliation: a worktree that survives a process crash (app killed
  * mid-run, host reboot) leaks disk and a dangling branch forever unless
@@ -916,9 +1302,14 @@ function keyFromBranch(kind, branch) {
  * what lets the epic kind skip a worktree whose owning Epic is still
  * `active` in the project's active-index.json (the caller supplies that
  * check; this module has no active-index.json knowledge of its own — see
- * this chain's next PRD for the real wiring). Job-kind reconciliation has no
- * equivalent concept (a job worktree found at boot is, by definition, from a
- * run that didn't finish) and typically omits `isLive`.
+ * this chain's next PRD for the real wiring). The job kind uses the same
+ * mechanism for a different signal: a job is spawned `detached: true`
+ * (scheduler.cjs), so its `claude -p` executor can survive an app restart —
+ * scheduler.cjs's own `isLive` treats a worktree as live when its owning
+ * queue row is still `running` with a live pid, OR `hasLiveHolder` finds a
+ * process whose cwd is still the checkout itself (see jobWorktreeBootLive.cjs).
+ * A caller that omits `isLive` entirely (e.g. an ad hoc test) still gets the
+ * old unconditional-reap behavior for that kind.
  *
  * After the per-cwd pass, this also runs `sweepStaleWorktreeCheckouts` —
  * a second, root-directory-driven pass that is NOT limited to `cwds`, so a
@@ -961,7 +1352,7 @@ async function reconcileWorktreesOnBoot(cwds, opts = {}) {
 
   let sweep = { checkoutsRemoved: 0, emptyRootsRemoved: 0 };
   try {
-    sweep = await sweepStaleWorktreeCheckouts(kind, { staleAgeMs: opts.staleAgeMs });
+    sweep = await sweepStaleWorktreeCheckouts(kind, { staleAgeMs: opts.staleAgeMs, holders: opts.holders });
   } catch {
     /* never let the orphan sweep take down boot reconciliation */
   }
@@ -1018,15 +1409,22 @@ module.exports = {
   createWorktree,
   captureAndCarryBaseDiff,
   pathsIdenticalToBranch,
+  resolveDefaultBranch,
+  getCurrentBranch,
   integrateBranch,
   cleanupWorktree,
   salvageWorktreeDiff,
   salvageDirtyDelta,
   isBranchMergedIntoHead,
   parseWorktreeListPorcelain,
+  listCwdHolders,
+  hasLiveHolder,
   reconcileWorktreesOnBoot,
   sweepStaleWorktreeCheckouts,
   mainTreeFromWorktreeGitFile,
+  getObservedWorktreeCount,
+  reserveWorktreeSlot,
+  reclaimTerminalJobOrphans,
   // Job-kind convenience wrappers — same call shape jobWorktree.cjs has
   // always exposed.
   createJobWorktree,
@@ -1047,4 +1445,16 @@ module.exports = {
     configFor(kind);
     return activeWorktreeCount[kind];
   },
+  // Test-only escape hatch for the observed-worktree-count TTL cache, so a
+  // test simulating a leak-then-recover sequence isn't at the mercy of a
+  // stale count left behind by an earlier test in the same process.
+  _resetObservedWorktreeCountCacheForTests(kind) {
+    if (kind) {
+      configFor(kind);
+      observedWorktreeCountCache[kind] = { count: null, at: 0 };
+    } else {
+      observedWorktreeCountCache.job = { count: null, at: 0 };
+      observedWorktreeCountCache.epic = { count: null, at: 0 };
+    }
+  },
 };

package/src/main/lib/jobWorktree.cjs

@@ -65,7 +65,8 @@ module.exports = {
   salvageJobWorktreeDiff: gitWorktree.salvageJobWorktreeDiff,
   salvageJobDirtyDelta: gitWorktree.salvageJobDirtyDelta,
   parseWorktreeListPorcelain: gitWorktree.parseWorktreeListPorcelain,
-  reconcileWorktreesOnBoot: (cwds) => gitWorktree.reconcileWorktreesOnBoot(cwds, { kind: KIND }),
+  reconcileWorktreesOnBoot: (cwds, opts = {}) => gitWorktree.reconcileWorktreesOnBoot(cwds, { kind: KIND, isLive: opts.isLive }),
+  reclaimTerminalJobOrphans: gitWorktree.reclaimTerminalJobOrphans,
   // Test-only escape hatch for the in-memory concurrency counter.
   _resetActiveWorktreeCountForTests(n = 0) { gitWorktree._resetActiveWorktreeCountForTests(KIND, n); },
   _getActiveWorktreeCountForTests() { return gitWorktree._getActiveWorktreeCountForTests(KIND); },

package/src/main/lib/jobWorktreeBootLive.cjs

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * jobWorktreeBootLive.cjs — builds the `isLive` predicate scheduler.cjs's
+ * boot sweep hands to `jobWorktree.reconcileWorktreesOnBoot` (PRD 1162).
+ *
+ * Kept in a separate lib file — same reasoning as reaperHelpers.cjs's header
+ * — so the predicate's logic is unit-testable without importing scheduler.cjs
+ * (which requires electron/ipcMain).
+ *
+ * A job is spawned `detached: true` (scheduler.cjs), so its `claude -p`
+ * executor SURVIVES the Electron app being killed/restarted — a worktree
+ * found at boot is NOT, by itself, proof the run that owns it died. This
+ * predicate treats a worktree as live via either signal:
+ *   1. its owning queue row is still `status: 'running'` with a `runtime.pid`
+ *      that `claudePidAlive` reports alive, or
+ *   2. `hasLiveHolder` finds a process whose cwd is the checkout itself (or a
+ *      path under it) — covers a row that went terminal (or was never
+ *      written) while the process is still actually running.
+ * Either match logs one line naming the slug and which check held it, so a
+ * persistently-skipped leak stays visible (RCA: PRD 1108).
+ */
+
+/**
+ * @param {{ bootJobs: Array<object>, claudePidAlive: (pid: number) => boolean, hasLiveHolder: (dir: string, holders?: Set<string>) => boolean, cwdHolders?: Set<string> }} deps
+ * @returns {(slug: string, entry: { worktree: string, branch: string|null }) => boolean}
+ */
+function buildJobWorktreeIsLive({ bootJobs, claudePidAlive, hasLiveHolder, cwdHolders }) {
+  const runningPidBySlug = new Map();
+  for (const j of Array.isArray(bootJobs) ? bootJobs : []) {
+    if (j && j.status === 'running' && j.runtime && j.runtime.pid) {
+      runningPidBySlug.set(j.slug, j.runtime.pid);
+    }
+  }
+
+  return function isLive(slug, entry) {
+    const pid = runningPidBySlug.get(slug);
+    if (pid && claudePidAlive(pid)) {
+      console.log(`[gitWorktree] boot sweep: skipping job worktree slug=${slug} — running row with live pid=${pid}`);
+      return true;
+    }
+    const dir = entry && entry.worktree;
+    if (dir && hasLiveHolder(dir, cwdHolders)) {
+      console.log(`[gitWorktree] boot sweep: skipping job worktree slug=${slug} — live cwd holder under ${dir}`);
+      return true;
+    }
+    return false;
+  };
+}
+
+module.exports = { buildJobWorktreeIsLive };

package/src/main/lib/jobWorktreeTerminalOrphanLive.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * jobWorktreeTerminalOrphanLive.cjs — builds the `isLive` predicate
+ * scheduler.cjs's `reclaimTerminalJobOrphansThrottled` hands to
+ * `jobWorktree.reclaimTerminalJobOrphans` (PRD 1163).
+ *
+ * Kept in a separate lib file — same reasoning as jobWorktreeBootLive.cjs's
+ * header — so the predicate's logic is unit-testable without importing
+ * scheduler.cjs (which requires electron/ipcMain).
+ *
+ * A queue row already resolved to a terminal status (completed/failed/
+ * skipped) is not, by itself, proof its executor actually stopped —
+ * overrunning-job escalation, a phantom pidless reap, or a cancel whose kill
+ * didn't land can all produce a terminal row while the real process keeps
+ * running. This predicate treats a candidate worktree as live via either
+ * signal, checked in this order (cheapest/most decisive first):
+ *   1. `hasLiveHolder` finds a process whose cwd is the checkout itself (or a
+ *      path under it) — project-agnostic, catches a still-running executor
+ *      regardless of what its queue row says.
+ *   2. the terminal row's own recorded `runtime.pid` is still alive
+ *      (`claudePidAlive`) — catches the case `hasLiveHolder` can't see
+ *      (darwin has no `/proc`, so `hasLiveHolder` always reports no holder
+ *      there; the pid check is the only gate on that platform, which is an
+ *      accepted, documented tradeoff).
+ * Either match logs one line naming the slug and the reason, and reports it
+ * to the optional `onLive(slug, reason)` callback — this is how the caller
+ * (scheduler.cjs) learns which terminal rows to stamp
+ * `worktreeReclaimBlockedLive` on, without this module ever reading or
+ * writing queue state itself.
+ */
+
+/**
+ * @param {{
+ *   terminalJobs: Array<object>,
+ *   claudePidAlive: (pid: number) => boolean,
+ *   hasLiveHolder: (dir: string, holders?: Set<string>) => boolean,
+ *   cwdHolders?: Set<string>,
+ *   onLive?: (slug: string, reason: string) => void,
+ * }} deps
+ * @returns {(slug: string, entry: { worktree: string, branch: string|null }) => boolean}
+ */
+function buildTerminalOrphanIsLive({ terminalJobs, claudePidAlive, hasLiveHolder, cwdHolders, onLive }) {
+  const pidBySlug = new Map();
+  for (const j of Array.isArray(terminalJobs) ? terminalJobs : []) {
+    if (j && j.slug && j.runtime && j.runtime.pid) pidBySlug.set(j.slug, j.runtime.pid);
+  }
+
+  return function isLive(slug, entry) {
+    const dir = entry && entry.worktree;
+    if (dir && hasLiveHolder(dir, cwdHolders)) {
+      const reason = `live cwd holder under ${dir}`;
+      console.log(`[gitWorktree] terminal orphan reclaim: skipping job worktree slug=${slug} — ${reason}`);
+      if (onLive) onLive(slug, reason);
+      return true;
+    }
+    const pid = pidBySlug.get(slug);
+    if (pid && claudePidAlive(pid)) {
+      const reason = `terminal row's recorded pid=${pid} still alive`;
+      console.log(`[gitWorktree] terminal orphan reclaim: skipping job worktree slug=${slug} — ${reason}`);
+      if (onLive) onLive(slug, reason);
+      return true;
+    }
+    return false;
+  };
+}
+
+module.exports = { buildTerminalOrphanIsLive };