claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/lib/gitWorktree.cjs

@@ -77,6 +77,12 @@ const { execFile } = require('node:child_process');
 // The job cap's assumptions (few, short-lived, quickly-reclaimed checkouts)
 // simply don't transfer, so the epic kind gets a separately-configurable,
 // much higher ceiling rather than sharing the job kind's default.
+// staleSweepAgeEnv/defaultStaleSweepAgeMs back the on-disk orphan sweep
+// (reconcileWorktreesOnBoot's root-level pass, below) — how old an on-disk
+// checkout must be before it's reclaimed even though no caller-supplied cwd
+// vouches for it. The job default (24h) matches a job's whole lifetime being
+// minutes; the epic default (7d) matches an Epic legitimately living for
+// days, same rationale as defaultMax above.
 const KIND_CONFIG = {
   job: {
     root: path.join(os.tmpdir(), 'session-manager-job-worktrees'),
@@ -84,6 +90,8 @@ const KIND_CONFIG = {
     disableEnv: 'SM_JOB_WORKTREE_DISABLE',
     maxEnv: 'SM_JOB_WORKTREE_MAX',
     defaultMax: 4,
+    staleSweepAgeEnv: 'SM_JOB_WORKTREE_STALE_MS',
+    defaultStaleSweepAgeMs: 24 * 60 * 60 * 1000,
   },
   epic: {
     root: path.join(os.tmpdir(), 'session-manager-epic-worktrees'),
@@ -91,6 +99,8 @@ const KIND_CONFIG = {
     disableEnv: 'SM_EPIC_WORKTREE_DISABLE',
     maxEnv: 'SM_EPIC_WORKTREE_MAX',
     defaultMax: 50,
+    staleSweepAgeEnv: 'SM_EPIC_WORKTREE_STALE_MS',
+    defaultStaleSweepAgeMs: 7 * 24 * 60 * 60 * 1000,
   },
 };
 
@@ -121,10 +131,40 @@ function isWorktreeDisabled(kind, cwd) {
   return false;
 }
 
+/**
+ * The job-kind default alone is floored at sessionSlots' machine-wide `claude
+ * -p` cap (lazily required to avoid a load-order cycle): a job that fails to
+ * get session-slot capacity already waits for a slot to free up rather than
+ * degrading, so the worktree cap below it must never be tighter than the
+ * slot pool — otherwise raising slots to 10 in the UI silently strands 6 jobs
+ * without isolation, running in-place instead of waiting (the exact bug this
+ * PRD fixes). An explicit SM_JOB_WORKTREE_MAX still wins verbatim — a
+ * deliberate operator override, not a value this floor should touch.
+ */
 function getMaxConcurrentWorktrees(kind) {
   const cfg = configFor(kind);
   const raw = Number(process.env[cfg.maxEnv]);
-  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : cfg.defaultMax;
+  if (Number.isFinite(raw) && raw > 0) return Math.floor(raw);
+  if (kind === 'job') {
+    const sessionSlots = require('./sessionSlots.cjs');
+    return Math.max(cfg.defaultMax, sessionSlots.totalSlots());
+  }
+  return cfg.defaultMax;
+}
+
+function getStaleSweepAgeMs(kind) {
+  const cfg = configFor(kind);
+  const raw = Number(process.env[cfg.staleSweepAgeEnv]);
+  return Number.isFinite(raw) && raw > 0 ? raw : cfg.defaultStaleSweepAgeMs;
+}
+
+/** True when resolved path `p` is `root` itself or nested under it — the one
+ *  gate every deletion routine below must pass before touching disk, so a
+ *  path-traversal-shaped key can never escape this kind's own tmpdir root. */
+function isUnderRoot(p, root) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedP = path.resolve(p);
+  return resolvedP === resolvedRoot || resolvedP.startsWith(resolvedRoot + path.sep);
 }
 
 // In-memory count of worktrees currently checked out by THIS process, kept
@@ -139,6 +179,11 @@ function execGit(args, { cwd, timeout = 20_000 } = {}) {
     execFile('git', args, { cwd, timeout, windowsHide: true, encoding: 'utf8' }, (err, stdout, stderr) => {
       if (err) {
         err.stderrText = stderr;
+        // Some git subcommands (e.g. `diff --no-index`) exit non-zero to mean
+        // "found a difference", not "failed" — stdout still carries the real
+        // result in that case, so callers that need it can recover it off
+        // the rejected error rather than losing it.
+        err.stdoutText = stdout;
         reject(err);
         return;
       }
@@ -157,10 +202,21 @@ async function isGitRepo(cwd) {
   }
 }
 
-/** True when `cwd`'s own working tree (not any worktree) has zero pending changes. */
+/**
+ * True when `cwd`'s own working tree (not any worktree) has zero pending
+ * changes to TRACKED files (modified or staged). Untracked files are
+ * deliberately excluded (`--untracked-files=no`): an untracked file is never
+ * tracked WIP a job depends on, and `git worktree add` checks out only
+ * committed HEAD content into the new worktree — it never touches, copies, or
+ * is affected by the base tree's untracked files either way. Counting them as
+ * "dirty" here bought no safety: one stray scratch file in a project silently
+ * disabled isolation for every job in that project, permanently, since a
+ * failed-to-commit job leaves the tree dirty and re-triggers the same
+ * fallback for every subsequent job (RCA: PRD 1064, starry-night-ships).
+ */
 async function isBaseTreeClean(cwd) {
   try {
-    const out = await execGit(['status', '--porcelain'], { cwd, timeout: 10_000 });
+    const out = await execGit(['status', '--porcelain', '--untracked-files=no'], { cwd, timeout: 10_000 });
     return out.trim().length === 0;
   } catch {
     return false;
@@ -179,7 +235,16 @@ function branchNameFor(kind, key) {
   return `${configFor(kind).branchPrefix}${key}`;
 }
 
-/** Best-effort teardown of one worktree checkout — never throws. */
+/**
+ * Best-effort teardown of one worktree checkout — never throws. Also rmdirs
+ * `dir`'s parent (the per-cwd hash directory `worktreeDirFor` nests every
+ * checkout under) when it's left empty, so a torn-down checkout doesn't
+ * leave a permanent empty leftover behind (RCA: PRD 1108 — 1125 of 1133
+ * on-disk hash dirs under the job root were exactly this, never reclaimed).
+ * Uses non-recursive `fs.rmdir`, which only succeeds on a truly empty
+ * directory, so a sibling checkout still living under the same hash dir can
+ * never be destroyed by this call.
+ */
 async function removeWorktreeDir(cwd, dir) {
   try {
     await execGit(['worktree', 'remove', '--force', dir], { cwd, timeout: 15_000 });
@@ -192,18 +257,238 @@ async function removeWorktreeDir(cwd, dir) {
   } catch {
     /* best-effort */
   }
+  const parentDir = path.dirname(dir);
+  // Guard against ever rmdir-ing os.tmpdir() itself — every real caller's
+  // `dir` is `<kind root>/<hash>/<key>`, so `parentDir` is always the hash
+  // dir, never the tmpdir root, but this keeps the guarantee explicit rather
+  // than relying solely on call-site discipline.
+  if (parentDir === os.tmpdir()) return;
+  try {
+    const remaining = await fsp.readdir(parentDir);
+    if (remaining.length === 0) await fsp.rmdir(parentDir);
+  } catch {
+    // Not empty (a sibling checkout survives), doesn't exist, or a race —
+    // all fine to ignore.
+  }
+}
+
+/**
+ * Reads a linked worktree checkout's own `.git` file (a plain text pointer,
+ * not a directory, for any `git worktree add` checkout) to recover the path
+ * of the MAIN tree it's registered against, without needing a caller-
+ * supplied cwd. Content looks like `gitdir: /path/to/main/.git/worktrees/
+ * <name>`; the main tree is that path with the trailing `/.git/worktrees/
+ * <name>` segment stripped off.
+ *
+ * Round-trip verified before being trusted, mirroring the same defense
+ * `scripts/lib/activeSessions.cjs`'s `worktreeMainRootOf` already applies: a
+ * `.git` pointer file is a plain text file, so its content must not be
+ * trusted to redirect `git worktree remove --force` at an arbitrary path
+ * without the candidate main tree's OWN admin dir
+ * (`<main>/.git/worktrees/<name>/gitdir`) agreeing this checkout is really
+ * one of its registered worktrees. Returns null on any read/parse/mismatch —
+ * never throws.
+ */
+async function mainTreeFromWorktreeGitFile(dir) {
+  try {
+    const gitFile = path.join(dir, '.git');
+    const content = await fsp.readFile(gitFile, 'utf8');
+    const match = content.match(/^gitdir:\s*(.+)$/m);
+    if (!match) return null;
+    const gitdir = match[1].trim();
+    const marker = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+    const idx = gitdir.lastIndexOf(marker);
+    if (idx === -1) return null;
+    const candidateMain = gitdir.slice(0, idx);
+    const worktreeName = gitdir.slice(idx + marker.length).split(path.sep)[0];
+    if (!worktreeName) return null;
+
+    const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
+    const backRef = (await fsp.readFile(adminGitdirFile, 'utf8')).trim();
+    if (path.resolve(backRef) !== path.resolve(gitFile)) return null;
+
+    return candidateMain;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tear down one orphaned on-disk checkout that `sweepStaleWorktreeCheckouts`
+ * found with no caller-supplied cwd to run `git worktree remove` against.
+ * Recovers the main tree from the checkout's own `.git` file and removes the
+ * registration there first, so the main repo's `git worktree list` is never
+ * left with a stale entry pointing at a directory we just deleted. Falls back
+ * to a plain `rm -rf` (plus a best-effort `worktree prune` run from inside
+ * the checkout itself, in case git can still resolve it) when that lookup
+ * fails. Never throws.
+ */
+async function teardownOrphanedCheckout(dir) {
+  const mainTree = await mainTreeFromWorktreeGitFile(dir);
+  if (mainTree) {
+    try {
+      await execGit(['worktree', 'remove', '--force', dir], { cwd: mainTree, timeout: 15_000 });
+    } catch {
+      // Registration already gone, or the main tree no longer agrees this is
+      // one of its worktrees — fall through to the plain rm below either way.
+    }
+    try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+    try { await execGit(['worktree', 'prune'], { cwd: mainTree, timeout: 10_000 }); } catch { /* best-effort */ }
+    return;
+  }
+  try { await execGit(['worktree', 'prune'], { cwd: dir, timeout: 10_000 }); } catch { /* best-effort */ }
+  try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+}
+
+/**
+ * Sweeps this kind's ENTIRE on-disk worktree root directly — not limited to
+ * any caller-supplied list of cwds — for checkouts belonging to a project
+ * `reconcileWorktreesOnBoot` was never handed a cwd for (a project removed
+ * from Session Manager, or a stray leftover from before this sweep existed).
+ * The per-cwd loop in `reconcileWorktreesOnBoot` can only clean what it's
+ * told about; this covers the rest.
+ *
+ * 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
+ * `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.
+ *
+ * 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
+ * name can never walk this sweep outside its own tmpdir root.
+ *
+ * Returns `{ checkoutsRemoved, emptyRootsRemoved }`. Never throws.
+ */
+async function sweepStaleWorktreeCheckouts(kind, opts = {}) {
+  const root = worktreeRootFor(kind);
+  const staleAgeMs = Number.isFinite(opts.staleAgeMs) && opts.staleAgeMs >= 0
+    ? opts.staleAgeMs
+    : getStaleSweepAgeMs(kind);
+  const result = { checkoutsRemoved: 0, emptyRootsRemoved: 0 };
+
+  let hashEntries;
+  try {
+    hashEntries = await fsp.readdir(root, { withFileTypes: true });
+  } catch {
+    return result; // root doesn't exist yet (or unreadable) — nothing to sweep
+  }
+
+  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)) continue;
+
+      let stat;
+      try {
+        stat = await fsp.stat(checkoutDir);
+      } catch {
+        continue;
+      }
+      if (Date.now() - stat.mtimeMs < staleAgeMs) continue; // still fresh — never touched
+
+      try {
+        await teardownOrphanedCheckout(checkoutDir);
+        result.checkoutsRemoved++;
+      } catch {
+        /* best-effort */
+      }
+    }
+
+    try {
+      const remaining = await fsp.readdir(hashDir);
+      if (remaining.length === 0) {
+        await fsp.rmdir(hashDir);
+        result.emptyRootsRemoved++;
+      }
+    } catch {
+      // Not empty (a fresh checkout survives, or one this pass just skipped),
+      // doesn't exist, or a race — all fine to ignore.
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Capture the base tree's outstanding TRACKED diff (`git diff HEAD
+ * --binary` — read-only, never stages or touches `cwd`) and apply it inside
+ * the freshly created worktree `dir`, so a job started against a dirty base
+ * tree sees the SAME content it would have seen running in place, without
+ * the base tree ever being written to. Returns `{ ok: true, paths }` or
+ * `{ ok: false, reason }`; never throws.
+ *
+ * This is deliberately read-context, not work-product: the authoritative
+ * copy of the human's WIP stays in `cwd` the whole time. Nothing here ever
+ * `git add`s or commits the carried paths on the job's behalf, and nothing
+ * ever restores them back into `cwd` — they were never removed from it.
+ */
+async function captureAndCarryBaseDiff({ cwd, dir }) {
+  let paths = [];
+  let patch = '';
+  try {
+    const nameOut = await execGit(['diff', 'HEAD', '--name-only'], { cwd, timeout: 15_000 });
+    paths = nameOut.split('\n').map((l) => l.trim()).filter(Boolean);
+    patch = await execGit(['diff', 'HEAD', '--binary'], { cwd, timeout: 30_000 });
+  } catch (e) {
+    return { ok: false, reason: `capturing base diff failed: ${(e && (e.stderrText || e.message)) || e}` };
+  }
+  if (!patch || !patch.trim()) return { ok: true, paths: [] };
+
+  const patchFile = path.join(os.tmpdir(), `sm-worktree-carry-${crypto.randomBytes(8).toString('hex')}.patch`);
+  try {
+    await fsp.writeFile(patchFile, patch, 'utf8');
+    await execGit(['apply', '--binary', patchFile], { cwd: dir, timeout: 30_000 });
+  } catch (e) {
+    return { ok: false, reason: `git apply failed: ${(e && (e.stderrText || e.message)) || e}` };
+  } finally {
+    try { await fsp.rm(patchFile, { force: true }); } catch { /* best-effort */ }
+  }
+  return { ok: true, paths };
 }
 
 /**
  * Create a linked worktree 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.
+ * tree's current HEAD. Returns `{ ok: true, dir, branch, baseCwd,
+ * carriedPaths }` 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.
+ *
+ * A dirty base tree (tracked modifications) no longer disables isolation —
+ * a worktree only ever checks out committed HEAD content, so the base
+ * tree's outstanding diff is captured and applied inside the fresh worktree
+ * (`captureAndCarryBaseDiff`) instead: the job sees the same content it
+ * would have seen running in place, while the shared base tree is never
+ * written to and stays untouchable for the run's whole duration. If that
+ * capture/apply fails for any reason (binary conflict, non-zero `git
+ * apply`), creation degrades to the OLD behaviour — the worktree is torn
+ * down and this returns `{ ok: false, reason: 'carry-over of base WIP
+ * failed: ...' }` — so this change can never turn a working fallback into a
+ * hard failure. `carriedPaths` (possibly empty) is threaded back so callers
+ * can exclude the human's carried WIP from branch integration.
  *
- * 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.
+ * Never throws: every failure mode (not a repo, cap reached, carry-over
+ * failure, 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 createWorktree({ kind, cwd, key }) {
   configFor(kind); // throws on an unknown kind before anything else runs
@@ -213,12 +498,7 @@ async function createWorktree({ kind, cwd, key }) {
 
   if (!(await isGitRepo(cwd))) return { ok: false, reason: 'not a git repository' };
 
-  // A dirty base tree means the caller 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 it 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' };
+  const baseWasClean = await isBaseTreeClean(cwd);
 
   if (activeWorktreeCount[kind] >= getMaxConcurrentWorktrees(kind)) {
     return { ok: false, reason: `worktree cap reached (${getMaxConcurrentWorktrees(kind)} concurrent)` };
@@ -245,7 +525,23 @@ async function createWorktree({ kind, cwd, key }) {
     activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
     return { ok: false, reason: `git worktree add failed: ${(e && (e.stderrText || e.message)) || e}` };
   }
-  return { ok: true, dir, branch, baseCwd: cwd };
+
+  let carriedPaths = [];
+  if (!baseWasClean) {
+    // Routed through module.exports (not the bare local function) so tests
+    // can substitute a failing carry-over without needing a real git-apply
+    // conflict fixture — see gitWorktree.test.cjs's carry-over-failure case.
+    const carry = await module.exports.captureAndCarryBaseDiff({ cwd, dir });
+    if (!carry.ok) {
+      await removeWorktreeDir(cwd, dir);
+      try { await execGit(['branch', '-D', branch], { cwd, timeout: 10_000 }); } catch { /* best-effort */ }
+      activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
+      return { ok: false, reason: `carry-over of base WIP failed: ${carry.reason}` };
+    }
+    carriedPaths = carry.paths;
+  }
+
+  return { ok: true, dir, branch, baseCwd: cwd, carriedPaths };
 }
 
 /**
@@ -258,8 +554,16 @@ async function createWorktree({ kind, cwd, key }) {
  * e.g. a genuine content conflict. On failure the branch is left un-merged
  * and NOT deleted (see cleanupWorktree) so the work is recoverable, never
  * silently discarded.
+ *
+ * `carriedPaths` (optional — from createWorktree's WIP carry-over) skips the
+ * merge entirely, returning `{ ok: true, integrated: false, reason:
+ * 'carried-wip-only' }`, when the branch's ONLY committed changes touch
+ * paths that were carried in as the human's base-tree WIP rather than the
+ * 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.
  */
-async function integrateBranch({ cwd, branch, key, kind }) {
+async function integrateBranch({ cwd, branch, key, kind, carriedPaths }) {
   if (!cwd || !branch) return { ok: false, reason: 'missing cwd/branch' };
   let branchHead;
   try {
@@ -277,6 +581,46 @@ async function integrateBranch({ cwd, branch, key, kind }) {
     return { ok: true, integrated: false, reason: 'branch has no new commits' };
   }
 
+  if (Array.isArray(carriedPaths) && carriedPaths.length) {
+    try {
+      const changedOut = await execGit(['diff', `${mergeBase || 'HEAD'}..${branch}`, '--name-only'], { cwd, timeout: 10_000 });
+      const changed = changedOut.split('\n').map((l) => l.trim()).filter(Boolean);
+      if (changed.length && changed.every((p) => carriedPaths.includes(p))) {
+        // Path membership alone is NOT enough: a job that legitimately edits
+        // the SAME file the base tree had carried-in WIP on (e.g. this
+        // repo's own scheduler.cjs churns queue.json/active-index.json while
+        // jobs run) would otherwise have its real commit misclassified as
+        // "just the carried WIP" and dropped — the caller treats
+        // `integrated: false` as safe-to-delete-the-branch, so that commit
+        // would be gone for good, worse than the ordinary merge-conflict
+        // path (branch kept, flagged for manual recovery) this shortcut is
+        // supposed to be a safe subset of. Content-verify: only when every
+        // changed path's committed blob on `branch` is byte-identical to
+        // what's STILL sitting dirty in `cwd` right now proves the job
+        // committed exactly the carried WIP and nothing more. Any mismatch
+        // (including a read failure — fail toward the safer default) falls
+        // through to the normal merge attempt below instead of skipping.
+        let allIdentical = true;
+        for (const p of changed) {
+          try {
+            const branchContent = await execGit(['show', `${branch}:${p}`], { cwd, timeout: 10_000 });
+            const baseContent = await fsp.readFile(path.join(cwd, p), 'utf8');
+            if (branchContent !== baseContent) { allIdentical = false; break; }
+          } catch {
+            allIdentical = false;
+            break;
+          }
+        }
+        if (allIdentical) {
+          return { ok: true, integrated: false, reason: 'carried-wip-only' };
+        }
+      }
+    } catch {
+      // Best-effort classification only — if the diff can't be read, fall
+      // through to the normal integration attempt below.
+    }
+  }
+
   try {
     await execGit(['merge', '--ff-only', branch], { cwd, timeout: 30_000 });
     return { ok: true, integrated: true, fastForward: true };
@@ -316,6 +660,121 @@ async function cleanupWorktree({ kind, cwd, dir, branch, keepBranch }) {
   activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
 }
 
+/**
+ * Best-effort dump of a worktree's full outstanding diff (tracked
+ * modifications AND untracked files) to `outFile`, for a caller about to
+ * tear the worktree down. A job killed before its finish-protocol commit
+ * (rate limit, timeout, crash, hard kill) otherwise loses that work
+ * outright the moment `cleanupWorktree` removes the checkout — no branch,
+ * no stash, no patch survives it. `git add -A --intent-to-add` stages
+ * untracked paths (empty blobs) without touching their content, so the
+ * subsequent `git diff HEAD --binary` includes their full contents exactly
+ * like a tracked modification; the result is a patch a later `git apply`
+ * can consume verbatim.
+ *
+ * Never throws — this always runs immediately before teardown and must
+ * never block branch integration/cleanup or change a job's verdict. Writes
+ * nothing (and returns `{ ok: false }`) when the worktree is clean or on
+ * any git failure, so a successful run's teardown never leaves a 0-byte
+ * artifact behind.
+ */
+async function salvageWorktreeDiff({ cwd, outFile }) {
+  try {
+    const status = await execGit(['status', '--porcelain'], { cwd, timeout: 15_000 });
+    if (!status.trim()) return { ok: false };
+    try {
+      await execGit(['add', '-A', '--intent-to-add'], { cwd, timeout: 30_000 });
+    } catch {
+      // Best-effort — the diff below still captures whatever staged/tracked
+      // changes exist even if intent-to-add partially failed.
+    }
+    const patch = await execGit(['diff', 'HEAD', '--binary'], { cwd, timeout: 30_000 });
+    if (!patch || !patch.trim()) return { ok: false };
+    const { writeTextAtomic } = require('../config.cjs');
+    await writeTextAtomic(outFile, patch);
+    return { ok: true, bytes: Buffer.byteLength(patch, 'utf8') };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Best-effort dump of a caller-supplied DELTA of paths — never the whole
+ * tree — to `outFile`. This is the shared-tree counterpart to
+ * salvageWorktreeDiff above: a job that ran IN PLACE (no throwaway worktree
+ * checkout to diff and discard) shares `cwd` with a human's own WIP and any
+ * sibling job, so it must never touch anything outside the exact paths the
+ * caller says this job itself dirtied (typically: `git status` at exit,
+ * minus a pre-run baseline snapshot).
+ *
+ * Deliberately does NOT reuse salvageWorktreeDiff's `git add -A
+ * --intent-to-add` — that stages the ENTIRE tree's untracked files into the
+ * shared index, which is exactly the kind of blanket mutation this function
+ * exists to avoid. Instead: tracked/modified delta paths are read via `git
+ * diff HEAD --binary -- <paths>` (never stages anything), and untracked
+ * delta paths are read individually via `git diff --no-index --binary --
+ * /dev/null <path>` (also never touches the index) — `--no-index` exits
+ * non-zero to mean "found a difference", which execGit rejects, so its
+ * stdout is recovered off the rejected error via `err.stdoutText`.
+ *
+ * Never throws, and never mutates `cwd` in any way (no add/stash/reset/
+ * checkout/clean) — a caller running this against a tree shared with a
+ * human or a sibling job must be able to trust `git status --porcelain` and
+ * the stash list are byte-identical before and after. Writes nothing (and
+ * returns `{ ok: false }`) when none of the given paths are actually dirty,
+ * or on any git failure, so a run with nothing to salvage never leaves a
+ * 0-byte artifact behind.
+ */
+async function salvageDirtyDelta({ cwd, paths, outFile }) {
+  try {
+    const list = Array.isArray(paths) ? [...new Set(paths.filter(Boolean))] : [];
+    if (!list.length) return { ok: false };
+
+    const statusOut = await execGit(['status', '--porcelain', '--', ...list], { cwd, timeout: 15_000 }).catch(() => '');
+    const trackedPaths = [];
+    const untrackedPaths = [];
+    for (const line of String(statusOut || '').split('\n')) {
+      if (!line) continue;
+      const code = line.slice(0, 2);
+      const p = line.slice(3);
+      if (!p) continue;
+      if (code === '??') untrackedPaths.push(p);
+      else trackedPaths.push(p);
+    }
+    // Any requested path `git status` didn't report on (already clean by the
+    // time this runs — e.g. a race with a concurrent write) is simply
+    // skipped, never guessed at.
+
+    let patch = '';
+    if (trackedPaths.length) {
+      try {
+        const d = await execGit(['diff', 'HEAD', '--binary', '--', ...trackedPaths], { cwd, timeout: 30_000 });
+        if (d) patch += d;
+      } catch {
+        // Best-effort — a diff failure for the tracked set must not block
+        // salvaging the untracked set below.
+      }
+    }
+    for (const p of untrackedPaths) {
+      try {
+        const d = await execGit(['diff', '--no-index', '--binary', '--', '/dev/null', p], { cwd, timeout: 15_000 });
+        if (d) patch += d;
+      } catch (e) {
+        // git diff --no-index exits 1 (not an error) whenever it finds a
+        // difference, which is the expected outcome here every time — the
+        // real diff text is on stdout despite the non-zero exit.
+        if (e && typeof e.stdoutText === 'string' && e.stdoutText) patch += e.stdoutText;
+      }
+    }
+    if (!patch.trim()) return { ok: false };
+    const { writeTextAtomic } = require('../config.cjs');
+    await writeTextAtomic(outFile, patch);
+    return { ok: true, bytes: Buffer.byteLength(patch, 'utf8') };
+  } catch {
+    return { ok: false };
+  }
+}
+
 /** Parse `git worktree list --porcelain` into `[{ worktree, branch }]`. */
 function parseWorktreeListPorcelain(text) {
   const entries = [];
@@ -358,6 +817,14 @@ function keyFromBranch(kind, branch) {
  * equivalent concept (a job worktree found at boot is, by definition, from a
  * run that didn't finish) and typically omits `isLive`.
  *
+ * After the per-cwd pass, this also runs `sweepStaleWorktreeCheckouts` —
+ * a second, root-directory-driven pass that is NOT limited to `cwds`, so a
+ * checkout belonging to a project no longer known to the caller (removed
+ * from Session Manager, or a leftover from before this sweep existed) still
+ * gets reclaimed once it's older than `opts.staleAgeMs` (default per-kind,
+ * see `KIND_CONFIG`). A one-shot log line reports the totals so a recurring
+ * leak stays visible (RCA: PRD 1108).
+ *
  * Never throws — a project that isn't a git repo, or has no worktrees, is a
  * silent no-op.
  */
@@ -366,6 +833,7 @@ async function reconcileWorktreesOnBoot(cwds, opts = {}) {
   const isLive = typeof opts.isLive === 'function' ? opts.isLive : null;
   const root = worktreeRootFor(kind);
   const list = Array.isArray(cwds) ? cwds.filter(Boolean) : [];
+  let checkoutsRemoved = 0;
   for (const cwd of list) {
     if (!(await isGitRepo(cwd))) continue;
     let out = '';
@@ -380,12 +848,29 @@ async function reconcileWorktreesOnBoot(cwds, opts = {}) {
       const key = keyFromBranch(kind, entry.branch);
       if (isLive && key && (await isLive(key, entry))) continue;
       await removeWorktreeDir(cwd, entry.worktree);
+      checkoutsRemoved++;
       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 */ }
   }
+
+  let sweep = { checkoutsRemoved: 0, emptyRootsRemoved: 0 };
+  try {
+    sweep = await sweepStaleWorktreeCheckouts(kind, { staleAgeMs: opts.staleAgeMs });
+  } catch {
+    /* never let the orphan sweep take down boot reconciliation */
+  }
+  const totals = {
+    checkoutsRemoved: checkoutsRemoved + sweep.checkoutsRemoved,
+    emptyRootsRemoved: sweep.emptyRootsRemoved,
+  };
+  console.log(
+    `[gitWorktree] boot sweep (kind:${kind}): reclaimed ${totals.checkoutsRemoved} checkout(s), ` +
+    `${totals.emptyRootsRemoved} empty root dir(s)`
+  );
+  return totals;
 }
 
 // ──────────────────────────────────────────── kind-scoped convenience wrappers
@@ -393,12 +878,18 @@ async function reconcileWorktreesOnBoot(cwds, opts = {}) {
 async function createJobWorktree({ cwd, slug }) {
   return createWorktree({ kind: 'job', cwd, key: slug });
 }
-async function integrateJobBranch({ cwd, branch, slug }) {
-  return integrateBranch({ kind: 'job', cwd, branch, key: slug });
+async function integrateJobBranch({ cwd, branch, slug, carriedPaths }) {
+  return integrateBranch({ kind: 'job', cwd, branch, key: slug, carriedPaths });
 }
 async function cleanupJobWorktree({ cwd, dir, branch, keepBranch }) {
   return cleanupWorktree({ kind: 'job', cwd, dir, branch, keepBranch });
 }
+async function salvageJobWorktreeDiff({ dir, outFile }) {
+  return salvageWorktreeDiff({ cwd: dir, outFile });
+}
+async function salvageJobDirtyDelta({ cwd, paths, outFile }) {
+  return salvageDirtyDelta({ cwd, paths, outFile });
+}
 
 async function createEpicWorktree({ cwd, epicId }) {
   return createWorktree({ kind: 'epic', cwd, key: epicId });
@@ -415,21 +906,29 @@ module.exports = {
   worktreeRootFor,
   isWorktreeDisabled,
   getMaxConcurrentWorktrees,
+  getStaleSweepAgeMs,
   isGitRepo,
   isBaseTreeClean,
   worktreeDirFor,
   branchNameFor,
   keyFromBranch,
   createWorktree,
+  captureAndCarryBaseDiff,
   integrateBranch,
   cleanupWorktree,
+  salvageWorktreeDiff,
+  salvageDirtyDelta,
   parseWorktreeListPorcelain,
   reconcileWorktreesOnBoot,
+  sweepStaleWorktreeCheckouts,
+  mainTreeFromWorktreeGitFile,
   // Job-kind convenience wrappers — same call shape jobWorktree.cjs has
   // always exposed.
   createJobWorktree,
   integrateJobBranch,
   cleanupJobWorktree,
+  salvageJobWorktreeDiff,
+  salvageJobDirtyDelta,
   // Epic-kind convenience wrappers.
   createEpicWorktree,
   integrateEpicBranch,