mixdog 1.4.1 → 1.4.3

package/src/runtime/shared/worktrees/manager.mjs

@@ -40,6 +40,7 @@ import {
 } from './file-recovery.mjs';
 import { lstat, mkdir, readdir, readFile, rm, rmdir, stat } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
+import { isPidAlive } from '../pid-liveness.mjs';
 import {
   managedWorktreePath,
   managedWorktreeRoot,
@@ -58,7 +59,7 @@ import {
   restoreFromRecoveryRef,
   uncommittedChanges,
 } from './carry.mjs';
-import { freeBytesAt, requiredBytes, trackedCheckoutBytes } from './disk.mjs';
+import { cachedFolderBytes, forgetFolderSize, freeBytesAt, requiredBytes, trackedCheckoutBytes } from './disk.mjs';
 import {
   branchCommit,
   currentBranch,
@@ -67,7 +68,9 @@ import {
   inspectRepo,
   isDiskFullError,
   listWorktrees,
+  localBranchCommits,
   localBranches,
+  parseStatusEntries,
   parseStatusPaths,
   remoteDefaultBranches,
   runGit,
@@ -84,9 +87,9 @@ import {
   removeIncludeLinks,
   restoreIncludeLinks,
 } from './include.mjs';
-import { linkWorktreeDependencies } from './dependencies.mjs';
+import { dependencyArtefacts, linkedArtefacts } from './dependencies.mjs';
 import { withRepoLock as withRepoMutationLock } from './lock.mjs';
-import { holdWorkspaceActivity } from './activity-gate.mjs';
+import { holdWorkspaceActivityAsync } from './activity-gate.mjs';
 import { withAdvisoryLocks } from '../../agent/orchestrator/tools/builtin/advisory-lock.mjs';
 import { mergeBranchIntoCheckout, operationInProgress } from './merge.mjs';
 import { readOwnerLease, removeOwnerLease, sameOwner, writeOwnerLease } from './owner.mjs';
@@ -124,25 +127,23 @@ function sessionRootOf(record) {
 // ---------------------------------------------------------------------------
 // Host configuration (settings source, free-space probe); tests override it.
 
-/** pid probe (signal 0); EPERM means the process exists. */
-function processAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === 'EPERM';
-  }
-}
-
-const DEFAULT_CONFIG = Object.freeze({ settings: null, freeBytes: freeBytesAt, processAlive });
+const DEFAULT_CONFIG = Object.freeze({
+  settings: null,
+  freeBytes: freeBytesAt,
+  processAlive: isPidAlive,
+  // The automatic cleanup's one deleting step (removeCheckoutVerified).
+  gitWorktreeRemove: (cwd, path) => runGit(cwd, ['worktree', 'remove', '--force', path], { allowFailure: true }),
+});
 let config = { ...DEFAULT_CONFIG };
 
 /**
  * Override host hooks. `settings`: stored worktree settings object or a
  * function returning it (default: agent config `worktree`). `freeBytes(dir)`:
- * free-space probe. `processAlive(pid)`: lease holder liveness. Returns a
- * restore function.
- * @param {{ settings?: unknown, freeBytes?: (dir: string) => Promise<number>, processAlive?: (pid: number) => boolean }} overrides
+ * free-space probe. `processAlive(pid)`: lease holder liveness.
+ * `gitWorktreeRemove(cwd, path)`: the automatic cleanup's `git worktree
+ * remove --force` ({ code, stderr }). Returns a restore function.
+ * @param {{ settings?: unknown, freeBytes?: (dir: string) => Promise<number>, processAlive?: (pid: number) => boolean,
+ *   gitWorktreeRemove?: (cwd: string, path: string) => Promise<{ code: number, stderr: string }> }} overrides
  */
 export function configureWorktreeManager(overrides = {}) {
   const previous = config;
@@ -300,16 +301,22 @@ async function keepRemovedTip(record) {
   return { tip, recoveryRef: ref };
 }
 
-/** Managed checkouts whose registration is stale (directory missing). */
-async function staleManagedRegistrations(repoCommonDir) {
-  const root = managedWorktreeRoot(repoCommonDir);
+/**
+ * Repository-wide `git worktree prune`: every registration whose folder is
+ * gone (managed or not — a deleted scratch checkout, a crashed tool's) is
+ * dropped; git keeps locked ones. Only bookkeeping: no folder is touched.
+ * @returns {Promise<string[]>} the checkout paths whose registration went
+ */
+async function pruneStaleRegistrations(repoCommonDir) {
   const stale = [];
-  for (const { worktreePath } of await adminRegistrations(repoCommonDir)) {
-    if (!(await isGone(worktreePath))) continue;
-    const rel = relative(pathKey(root), pathKey(worktreePath));
-    if (rel && !rel.startsWith('..') && !rel.includes(sep)) stale.push(worktreePath);
+  for (const registration of await adminRegistrations(repoCommonDir)) {
+    if (await isGone(registration.worktreePath)) stale.push(registration);
   }
-  return stale;
+  if (!stale.length) return [];
+  await runGit(repoCommonDir, ['--git-dir', repoCommonDir, 'worktree', 'prune'], { allowFailure: true });
+  return stale
+    .filter((registration) => !existsSync(registration.admin))
+    .map((registration) => canonicalPath(registration.worktreePath));
 }
 
 async function setResource(record, name, status) {
@@ -335,23 +342,223 @@ async function unmergedCommitCount(record) {
   const reference = (record.mergeTarget && (await branchCommit(cwd, record.mergeTarget))) || record.baseCommit;
   if (!reference) return 0;
   const result = await runGit(cwd, ['rev-list', '--count', tip, '--not', reference]);
-  return Number(firstLine(result.stdout)) || 0;
+  const count = Number(firstLine(result.stdout)) || 0;
+  if (count === 0 || (await changesContainedIn(cwd, tip, reference))) return 0;
+  return count;
+}
+
+/**
+ * A squash, rebase or cherry-pick merge leaves the branch's commits
+ * unreachable from `reference` although their changes are there. Merged only
+ * when merging `tip` into `reference` would leave `reference`'s tree exactly
+ * as it is: a change the target later reverted would come back, so it is
+ * unmerged work. A patch-equivalence test alone (`git cherry`) is not enough
+ * for that reason and is not used. An unreachable merge commit of the branch's
+ * own is unmerged as well (its resolution is work of its own), and anything
+ * git cannot decide (a conflict, an old git) counts as unmerged.
+ */
+async function changesContainedIn(cwd, tip, reference) {
+  const merges = await runGit(cwd, ['rev-list', '--count', '--merges', tip, '--not', reference], {
+    allowFailure: true,
+    readOnly: true,
+  });
+  if (merges.code !== 0 || Number(firstLine(merges.stdout)) !== 0) return false;
+  const merged = await runGit(cwd, ['merge-tree', '--write-tree', reference, tip], { allowFailure: true });
+  if (merged.code !== 0) return false;
+  const target = await runGit(cwd, ['rev-parse', `${reference}^{tree}`], { allowFailure: true, readOnly: true });
+  return target.code === 0 && firstLine(merged.stdout) === firstLine(target.stdout);
+}
+
+/**
+ * A cheap fingerprint of what the cleanup's slow checks (dirtyPaths,
+ * unmergedCommitCount) looked at: the checkout's HEAD, its index file (any
+ * add, commit, checkout or refresh rewrites it), the folder's own mtime, the
+ * branch tip and the merge target's tip. One git call and two stats.
+ */
+async function checkoutToken(record) {
+  const cwd = repoCwd(record);
+  const [paths, tip, target] = await Promise.all([
+    runGit(record.path, ['rev-parse', 'HEAD', '--git-path', 'index'], { allowFailure: true, readOnly: true }),
+    record.branch ? branchCommit(cwd, record.branch) : null,
+    record.mergeTarget ? branchCommit(cwd, record.mergeTarget) : null,
+  ]);
+  const [head = '', index = ''] = paths.stdout.split(/\r?\n/);
+  const stamp = (path) =>
+    stat(path).then(
+      (info) => `${info.mtimeMs}:${info.size}`,
+      () => 'none'
+    );
+  return JSON.stringify([
+    paths.code,
+    head.trim(),
+    index ? await stamp(resolve(record.path, index.trim())) : 'none',
+    await stamp(record.path),
+    tip,
+    target,
+  ]);
+}
+
+const DIRTY_STATUS_ARGS = ['status', '--porcelain=v1', '-z', '--untracked-files=all'];
+// An automatic removal reads the ignored paths too; a folder an ignore
+// pattern matches is listed once, not its contents.
+const AUTOMATIC_STATUS_ARGS = [...DIRTY_STATUS_ARGS, '--ignored=matching'];
+// The Cache Directory Tagging signature a CACHEDIR.TAG starts with.
+const CACHEDIR_SIGNATURE = 'Signature: 8a477f597d28d172789f06886806bc55';
+
+function identityPath(record) {
+  return record.projectSubdir ? `${record.projectSubdir}/${SESSION_PROJECT_ID_PATH}` : SESSION_PROJECT_ID_PATH;
+}
+
+/** The status paths that are user work: not the session identity file, not an include copy. */
+function userStatusPaths(record, paths) {
+  const includes = record.resources?.includes || [];
+  const identity = identityPath(record);
+  return paths.filter((path) => path !== identity && !coveredByIncludes(includes, path));
 }
 
 /** Uncommitted/untracked paths plus modified include copies. */
 async function dirtyPaths(record) {
   if (!existsSync(record.path)) return [];
+  const status = await runGit(record.path, DIRTY_STATUS_ARGS, { readOnly: true });
+  return [
+    ...userStatusPaths(record, parseStatusPaths(status.stdout)),
+    ...(await modifiedIncludeCopies(record.resources?.includes)),
+  ];
+}
+
+/** AUTOMATIC_STATUS_ARGS output as the changed paths and the ignored entries. */
+function splitIgnored(stdout) {
+  const entries = parseStatusEntries(stdout);
+  return {
+    changed: entries.filter((entry) => entry.code !== '!!').map((entry) => entry.path),
+    ignored: entries.filter((entry) => entry.code === '!!').map((entry) => entry.path),
+  };
+}
+
+async function cacheDirTagged(dir) {
+  try {
+    return (await readFile(join(dir, 'CACHEDIR.TAG'), 'latin1')).startsWith(CACHEDIR_SIGNATURE);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Of the ignored status entries, the ones no install or rebuild restores:
+ * user data only this checkout holds (an env file, a dataset, build output).
+ * Left out as reproducible: the session identity file (or its folder holding
+ * nothing else), the recorded include items (links go with the removal, a
+ * changed copy is dirty already), the dependency artefacts a committed
+ * lockfile installs whole (`artefacts`, dependencyArtefacts: node_modules
+ * only, so hand edits inside node_modules are deliberately not protected —
+ * see the `reinstallable` flag there for why), `__pycache__`
+ * folders and folders a CACHEDIR.TAG marks as a cache.
+ */
+async function unreproducibleIgnored(record, entries, artefacts) {
   const includes = record.resources?.includes || [];
-  const status = await runGit(record.path, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], {
-    readOnly: true,
-  });
-  const identity = record.projectSubdir
-    ? `${record.projectSubdir}/${SESSION_PROJECT_ID_PATH}`
-    : SESSION_PROJECT_ID_PATH;
-  const dirty = parseStatusPaths(status.stdout).filter(
-    (path) => path !== identity && !coveredByIncludes(includes, path)
-  );
-  return [...dirty, ...(await modifiedIncludeCopies(includes))];
+  const identity = identityPath(record);
+  const identityDir = identity.slice(0, identity.lastIndexOf('/'));
+  const tagged = new Map();
+  const isCache = (dir) => {
+    if (!tagged.has(dir)) tagged.set(dir, cacheDirTagged(join(record.path, ...dir.split('/'))));
+    return tagged.get(dir);
+  };
+  const kept = [];
+  for (const entry of entries) {
+    const path = entry.replace(/\/$/, '');
+    if (path === identity || coveredByIncludes(includes, path)) continue;
+    if (artefacts.some((artefact) => path === artefact || path.startsWith(`${artefact}/`))) continue;
+    if (path === identityDir) {
+      const names = await readdir(join(record.path, ...path.split('/'))).catch(() => null);
+      if (names?.length === 1 && names[0] === 'project.id') continue;
+    }
+    const parts = path.split('/');
+    const folders = entry.endsWith('/') ? parts : parts.slice(0, -1);
+    if (folders.includes('__pycache__')) continue;
+    let cache = false;
+    for (let depth = 1; depth <= folders.length && !cache; depth++) {
+      cache = await isCache(folders.slice(0, depth).join('/'));
+    }
+    if (!cache) kept.push(path);
+  }
+  return kept;
+}
+
+/** The keep reason of a worktree holding unreproducible ignored files (`files` capped to a preview). */
+function ignoredKeep(paths) {
+  return { reason: 'ignored', files: paths.slice(0, DIRTY_CHOICE_PREVIEW), count: paths.length };
+}
+
+/**
+ * What keeps `record` from an automatic removal: `dirty` (dirtyPaths) and
+ * `ignored` (unreproducibleIgnored), with the `artefacts` that decided it.
+ */
+async function automaticKeepPaths(record) {
+  if (!existsSync(record.path)) return { dirty: [], ignored: [], artefacts: [] };
+  const [status, artefacts] = await Promise.all([
+    runGit(record.path, AUTOMATIC_STATUS_ARGS, { readOnly: true }),
+    dependencyArtefacts(record.path),
+  ]);
+  const { changed, ignored } = splitIgnored(status.stdout);
+  return {
+    dirty: [...userStatusPaths(record, changed), ...(await modifiedIncludeCopies(record.resources?.includes))],
+    ignored: await unreproducibleIgnored(record, ignored, artefacts),
+    artefacts,
+  };
+}
+
+/** How long the cleanup's last dirty check under the folder hold may take. */
+const FINAL_DIRTY_CHECK_TIMEOUT_MS = 1_500;
+/** How long a timed-out final status is given to exit after its kill. */
+const FINAL_CHECK_EXIT_WAIT_MS = 2_000;
+
+/**
+ * The cleanup's last word before a removal, under the folder hold: the full
+ * status (untracked files at any depth, unstaged edits of tracked ones,
+ * ignored files) and the include-copy check again, bounded by `timeoutMs`;
+ * `artefacts` are the dependency artefacts read before the hold. null:
+ * clean, remove it. `{ reason: 'dirty' }`: something is uncommitted now.
+ * `{ reason: 'ignored', files, count }`: unreproducibleIgnored. `{ reason: 'busy' }`:
+ * the check timed out, failed or could not finish — never read as clean. A
+ * timed-out git is killed and awaited (bounded) before this returns, so none
+ * keeps running in the folder; `gitRunning: true` reports one that outlived
+ * the wait.
+ */
+async function finalDirtyCheck(record, timeoutMs, artefacts) {
+  if (!existsSync(record.path)) return null;
+  const started = Date.now();
+  let status;
+  try {
+    status = await runGit(record.path, AUTOMATIC_STATUS_ARGS, {
+      readOnly: true,
+      timeoutMs,
+      waitForExitMs: FINAL_CHECK_EXIT_WAIT_MS,
+    });
+  } catch (error) {
+    return { reason: 'busy', ...(error?.childExited === false ? { gitRunning: true } : {}) };
+  }
+  const { changed, ignored } = splitIgnored(status.stdout);
+  if (userStatusPaths(record, changed).length) return { reason: 'dirty' };
+  // The include copies and the ignored entries: file reads only (no child), bounded by what is left.
+  let timer;
+  try {
+    const left = Math.max(0, timeoutMs - (Date.now() - started));
+    const [modified, unreproducible] = await Promise.race([
+      Promise.all([
+        modifiedIncludeCopies(record.resources?.includes),
+        unreproducibleIgnored(record, ignored, artefacts),
+      ]),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('include check timed out')), left);
+      }),
+    ]);
+    if (modified.length) return { reason: 'dirty' };
+    return unreproducible.length ? ignoredKeep(unreproducible) : null;
+  } catch {
+    return { reason: 'busy' };
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
 async function deleteBranchIfFree(record) {
@@ -515,6 +722,96 @@ async function removeCheckoutSafely(record) {
   return [];
 }
 
+/**
+ * Put back what an automatic removal attempt took apart in a checkout that
+ * survived (`undo` as recorded in `deleting.undo`): the recorded include
+ * links that are missing again, and Mixdog's worktree lock when the checkout
+ * is still registered but no longer locked. Never throws.
+ * @returns {Promise<object[]>} what could not be put back
+ */
+async function undoAutomaticAttempt(record, undo) {
+  if (!undo || !existsSync(record.path)) return [];
+  const failures = [];
+  try {
+    if (undo.links) {
+      for (const failure of await restoreIncludeLinks(record.resources?.includes)) {
+        failures.push({ kind: 'link', path: failure.path, error: failure.error });
+      }
+    }
+    const registration = undo.lock !== null && undo.lock !== undefined ? await registrationFor(record) : null;
+    if (registration && registration.locked === null) {
+      const locked = await runGit(repoCwd(record), ['worktree', 'lock', '--reason', String(undo.lock), record.path], {
+        allowFailure: true,
+      });
+      if (locked.code !== 0) failures.push({ kind: 'lock', path: record.path, error: firstLine(locked.stderr) });
+    }
+  } catch (error) {
+    failures.push({ kind: 'undo', path: record.path, error: String(error?.message || error) });
+  }
+  return failures;
+}
+
+/**
+ * The automatic cleanup's checkout removal (`deleting.automatic`): the caller
+ * verified the worktree under its folder hold just before (lease, live
+ * sessions, jobs, a full status). Only `git worktree remove --force` deletes
+ * here — there is no recursive fallback. When git fails or anything is left
+ * (or the checkout is not registered, or carries a lock that is not
+ * Mixdog's), it stops: the recorded links it unlinked are put back, its own
+ * lock is restored, and what is left is returned for the record to keep.
+ * @returns {Promise<object[]>} the remainder (empty when everything is gone)
+ */
+async function removeCheckoutVerified(record) {
+  await assertRecoveryStoresClear(record);
+  await assertManagedCheckoutPath(record);
+  await assertNoUnrecordedDirectoryLinks(record);
+  const cwd = repoCwd(record);
+  const registration = await registrationFor(record);
+  if (!registration) {
+    return existsSync(record.path) ? [{ kind: 'directory', path: record.path, error: 'not-registered' }] : [];
+  }
+  if (existsSync(record.path)) {
+    const lock = registration.locked ?? null;
+    if (lock !== null && !String(lock).startsWith('mixdog session=')) {
+      return [{ kind: 'lock', path: record.path, error: 'external-lock' }];
+    }
+    // What this attempt takes apart (the recorded links, Mixdog's lock) is
+    // written down first, so a failure here or a restart puts it back.
+    record.deleting = { ...record.deleting, undo: { links: true, lock } };
+    await putRecord(record);
+    let removed;
+    try {
+      const unlinked = await removeIncludeLinks(record.resources?.includes);
+      if (unlinked.length) {
+        return [
+          ...unlinked.map((path) => ({ kind: 'link', path })),
+          ...(await undoAutomaticAttempt(record, record.deleting.undo)),
+        ];
+      }
+      // A built-in fsmonitor daemon holds the folder open (Windows) until stopped.
+      await runGit(record.path, ['fsmonitor--daemon', 'stop'], { allowFailure: true });
+      if (lock !== null) await runGit(cwd, ['worktree', 'unlock', record.path], { allowFailure: true });
+      removed = await config.gitWorktreeRemove(cwd, record.path);
+    } catch (error) {
+      // A rejected git call (timeout, spawn failure) is a failed removal too.
+      removed = { code: null, stderr: String(error?.message || error) };
+    }
+    if (removed.code !== 0 || existsSync(record.path)) {
+      // Whatever git left stays as it is; put back what this attempt took apart.
+      return [
+        {
+          kind: 'git-remove',
+          path: record.path,
+          error: firstLine(removed.stderr) || (removed.code === 0 ? 'folder left behind' : `exit ${removed.code}`),
+        },
+        ...(await undoAutomaticAttempt(record, record.deleting.undo)),
+      ];
+    }
+  }
+  await pruneRegistration(record.repoCommonDir, record.path, { allowLocked: true });
+  return (await registrationFor(record)) ? [{ kind: 'registration', path: record.path }] : [];
+}
+
 /** Report what a failed safe removal could not put back on its error (never swallowed). */
 function withRollbackFailures(error, failures) {
   if (!failures.length) return error;
@@ -602,6 +899,21 @@ async function rollbackCreation(record, cause) {
   return { complete: false, remaining };
 }
 
+/**
+ * An automatic removal that did not finish (git refused, something was left,
+ * or it was interrupted) is not a decided deletion: the record goes back to
+ * `ready` with `removalIncomplete` ({ at, reason, remaining }), so only a
+ * later pass that verifies it afresh (lease, live sessions, jobs, the full
+ * dirty check) tries again — nothing resumes it blindly.
+ */
+async function keepIncompleteRemoval(record, remaining, reason = 'git-remove-failed') {
+  record.state = 'ready';
+  record.deleting = null;
+  record.removalIncomplete = { at: Date.now(), reason, remaining };
+  await putRecord(record);
+  return { removed: false, retryable: true, incomplete: true, remaining };
+}
+
 /** finishDeletion's folder step; what is left over goes to `remaining`. */
 async function removeFolder(record, remaining) {
   await removeOwnerLease(record);
@@ -613,7 +925,12 @@ async function removeFolder(record, remaining) {
   for (const result of results) {
     if (!result.ok) remaining.push({ kind: 'cleanup', name: result.name, error: result.error.message });
   }
-  remaining.push(...(await (record.deleting?.safeOnly ? removeCheckoutSafely(record) : removeCheckout(record))));
+  const remove = record.deleting?.automatic
+    ? removeCheckoutVerified
+    : record.deleting?.safeOnly
+      ? removeCheckoutSafely
+      : removeCheckout;
+  remaining.push(...(await remove(record)));
 }
 
 /**
@@ -638,6 +955,7 @@ async function finishDeletion(record) {
   } catch (error) {
     remaining.push({ kind: 'error', error: String(error?.message || error) });
   }
+  if (remaining.length && record.deleting?.automatic) return keepIncompleteRemoval(record, remaining);
   if (remaining.length) {
     record.deleting = { ...record.deleting, remaining, lastAttemptAt: Date.now() };
     await putRecord(record);
@@ -645,14 +963,21 @@ async function finishDeletion(record) {
   }
   let branch = { deleted: false, reason: 'kept' };
   let kept = { tip: null, recoveryRef: null };
-  const merged = (await unmergedCommitCount(record)) === 0;
+  // A cleanup decided the branch merged at `mergedTip`: no second commit walk
+  // while the tip is still that one.
+  const mergedTip = record.deleting?.mergedTip;
+  const merged =
+    (!!mergedTip && record.branch && (await branchCommit(repoCwd(record), record.branch)) === mergedTip) ||
+    (await unmergedCommitCount(record)) === 0;
   if (record.branch && !record.deleting?.preserveBranch && (record.deleting?.force || merged)) {
-    // Forced past unmerged commits: the tip stays reachable before `branch -D`.
-    if (!merged) kept = await keepRemovedTip(record);
+    // Forced past unmerged commits (or a cleanup that deletes branches): the
+    // tip stays reachable before `branch -D`.
+    if (!merged || record.deleting?.keepTip) kept = await keepRemovedTip(record);
     else kept.tip = await branchCommit(repoCwd(record), record.branch);
     branch = await deleteBranchIfFree(record);
   }
   await deleteRecord(record.id);
+  forgetFolderSize(record.path);
   await pruneEmptyRepoRoot(record.repoCommonDir);
   return {
     removed: true,
@@ -856,11 +1181,42 @@ export async function markWorktreeDisposable(entryId, disposable = true) {
     const current = await getRecord(entryId);
     if (!current) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
     current.disposable = disposable === true;
+    // A deleted session's mark: no archive rule applies to it.
+    delete current.disposableReason;
     await putRecord(current);
     return entryView(current);
   });
 }
 
+/**
+ * Mark (or unmark) every ready managed worktree `sessionIds` own disposable:
+ * an archived session's, so a removal pass deletes it once clean and merged.
+ * The mark carries `disposableReason: 'archived'`, so the automatic passes
+ * apply the archive rules to it (cleanupArchived, favorites, minimum age).
+ * Snapshots are left alone (they never outlive their turn anyway).
+ * @param {string[]} sessionIds
+ * @returns {Promise<string[]>} the entry ids whose mark changed
+ */
+export async function setSessionWorktreesDisposable(sessionIds, disposable = true) {
+  const owners = new Set((Array.isArray(sessionIds) ? sessionIds : []).filter((id) => typeof id === 'string' && id));
+  const changed = [];
+  if (!owners.size) return changed;
+  const want = disposable === true;
+  for (const record of Object.values((await readRegistry()).entries)) {
+    if (record.kind === WORKTREE_SNAPSHOT_KIND || !owners.has(record.ownerSessionId)) continue;
+    await withRepoLock(record.repoCommonDir, async () => {
+      const current = await getRecord(record.id);
+      if (current?.state !== 'ready' || !owners.has(current.ownerSessionId) || current.disposable === want) return;
+      current.disposable = want;
+      if (want) current.disposableReason = 'archived';
+      else delete current.disposableReason;
+      await putRecord(current);
+      changed.push(current.id);
+    });
+  }
+  return changed;
+}
+
 /**
  * Before a creation (under the repository lock): the entry this transaction
  * or session already has ready (its lease re-written), else null once every
@@ -979,6 +1335,164 @@ async function snapshotHolderLive(record, live) {
   return !!lease && lease.pid !== process.pid && leaseProcessAlive(lease);
 }
 
+/** The project folder's uncommitted changes under the requested `carryChanges` mode; `ask` refuses while there are any. */
+async function judgePendingChanges(repo, projectSubdir, carryChanges) {
+  // A carry is judged by the same status read that counts the changes.
+  let pendingChanges = [];
+  if (carryChanges === 'carry') pendingChanges = await assertCarryable(repo.topLevel, projectSubdir);
+  else if (carryChanges) pendingChanges = await uncommittedChanges(repo.topLevel, projectSubdir);
+  if (pendingChanges.length && carryChanges === 'ask') {
+    throw worktreeError('WORKTREE_DIRTY_CHOICE', undefined, {
+      count: pendingChanges.length,
+      paths: pendingChanges.slice(0, DIRTY_CHOICE_PREVIEW),
+    });
+  }
+  return pendingChanges;
+}
+
+/** The commit a new worktree starts from and the branch a merge targets by default. */
+async function resolveStartPoint(repo, { baseBranch, startCommit, signal }) {
+  let baseCommit = repo.headCommit;
+  let mergeTarget = repo.currentBranch;
+  if (baseBranch) {
+    baseCommit = await branchCommit(repo.projectPath, baseBranch, { signal });
+    if (!baseCommit) {
+      throw worktreeError('WORKTREE_UNSUPPORTED_REPO', `Base branch ${baseBranch} does not exist.`, { baseBranch });
+    }
+    mergeTarget = baseBranch;
+  }
+  // A new branch at an explicit start point (`git worktree add -b <b> <path> <commit-ish>`).
+  if (startCommit) baseCommit = await resolveCommit(repo.projectPath, startCommit, signal);
+  return { baseCommit, mergeTarget };
+}
+
+/** The record a creation reserves before git is asked to add the checkout. */
+function newCreationRecord({
+  slug,
+  branch,
+  repo,
+  owner,
+  txId,
+  baseCommit,
+  mergeTarget,
+  existingBranch,
+  exactBranch,
+  tracked,
+  includePlan,
+}) {
+  return {
+    id: slug,
+    txId,
+    repoCommonDir: repo.repoCommonDir,
+    projectPath: repo.projectPath,
+    projectSubdir: projectSubdirOf(repo.topLevel, repo.projectPath),
+    path: managedWorktreePath(repo.repoCommonDir, slug),
+    branch,
+    baseCommit,
+    // An existing branch has no base it branched from: it merges where a
+    // merge first takes it (recorded then), and until that its own work is
+    // what it gained here since baseCommit.
+    mergeTarget: existingBranch ? null : mergeTarget,
+    createdAt: Date.now(),
+    ownerSessionId: owner.sessionId,
+    existingBranch,
+    exactBranch,
+    state: 'creating',
+    disposable: false,
+    warnings: [...(tracked.submodules ? ['submodules'] : []), ...includePlan.warnings],
+    resources: { worktree: null, lock: null, owner: null, includes: [] },
+    deleting: null,
+    recovery: null,
+  };
+}
+
+/**
+ * Locks the fresh checkout, binds its owner lease, moves or leaves the
+ * project folder's changes and applies the includes.
+ * `carry.moved` is set as soon as changes were carried, so a later failure
+ * can put them back.
+ */
+async function populateCheckout({
+  record,
+  owner,
+  repo,
+  projectSubdir,
+  signal,
+  pendingChanges,
+  carryChanges,
+  baseCommit,
+  includePlan,
+  carry,
+}) {
+  await setResource(record, 'worktree', 'created');
+  throwIfAborted(signal);
+  await setResource(record, 'lock', 'pending');
+  await runGit(repo.projectPath, ['worktree', 'lock', '--reason', `mixdog session=${owner.sessionId}`, record.path]);
+  await setResource(record, 'lock', 'created');
+  await setResource(record, 'owner', 'pending');
+  await writeOwnerLease(record, owner);
+  await setResource(record, 'owner', 'created');
+  // Carried before the include entries are copied, so an include never
+  // stands in the way of a carried file; the status is read again here,
+  // right before acting.
+  let changes = pendingChanges.length ? { mode: 'left', count: pendingChanges.length } : null;
+  if (carryChanges === 'carry') {
+    carry.moved = await carryUncommittedChanges({
+      topLevel: repo.topLevel,
+      projectSubdir,
+      worktreePath: record.path,
+      baseCommit,
+      label: record.id,
+    });
+    // The recovery ref stays until the caller has committed the move
+    // (dropCarryRecoveryRef) or put the changes back (restoreCarriedChanges).
+    changes = carry.moved.count
+      ? { mode: 'carried', count: carry.moved.count, recoveryRef: carry.moved.recoveryRef }
+      : null;
+  }
+  const applied = await applyIncludes(includePlan, record.path, (ledger) => recordInclude(record, ledger));
+  throwIfAborted(signal);
+  record.warnings = [...record.warnings, ...applied.warnings];
+  const made = (record.resources.includes || []).filter((item) => item.status === 'created');
+  const rels = (predicate) => made.filter(predicate).map((item) => item.rel);
+  // What creation did, for the agent's note at the first turn there (transitions.mjs).
+  const prepared = {
+    root: repo.topLevel,
+    copied: rels((item) => item.mode === 'copy'),
+    linked: rels((item) => item.mode === 'link'),
+    skipped: [...includePlan.warnings, ...applied.warnings],
+  };
+  // Whichever path made it (a worktree task, a branch selection, `git
+  // worktree add`), the first turn a session runs here installs its
+  // dependencies in the worktree folder (claimWorktreeSetup).
+  record.setup = { pending: true, prepared };
+  record.state = 'ready';
+  await putRecord(record);
+  return { ...entryView(record), prepared, ...(changes ? { changes } : {}) };
+}
+
+/** The error a failed creation throws, after its carried changes and partial checkout are undone. */
+async function failCreation(error, { record, carried, repo, projectSubdir, needed, root }) {
+  // Carried already: the changes go back to the project folder before the
+  // worktree that holds them is rolled back (the recovery ref keeps them
+  // either way).
+  let carryRestore = null;
+  if (carried?.recoveryRef) {
+    carryRestore = await restoreFromRecoveryRef(repo.topLevel, projectSubdir, carried.recoveryRef)
+      .then(() => ({ restored: true, recoveryRef: carried.recoveryRef }))
+      .catch((restoreError) => ({
+        restored: false,
+        recoveryRef: carried.recoveryRef,
+        error: String(restoreError?.message || restoreError),
+      }));
+  }
+  const rollback = await rollbackCreation(record, error);
+  const failure = isDiskFullError(error) ? await diskFullFailure(error, { needed, root }) : error;
+  if (!rollback.complete) failure.rollback = rollback;
+  if (carryRestore) failure.carryRestore = carryRestore;
+  return failure;
+}
+
 /**
  * `carryChanges` decides the project folder's uncommitted changes (tracked
  * and untracked, ignored excluded), judged under the repository lock:
@@ -1034,29 +1548,10 @@ export async function createManagedWorktree({
     throwIfAborted(signal);
 
     const projectSubdir = projectSubdirOf(repo.topLevel, repo.projectPath);
-    // A carry is judged by the same status read that counts the changes.
-    let pendingChanges = [];
-    if (carryChanges === 'carry') pendingChanges = await assertCarryable(repo.topLevel, projectSubdir);
-    else if (carryChanges) pendingChanges = await uncommittedChanges(repo.topLevel, projectSubdir);
-    if (pendingChanges.length && carryChanges === 'ask') {
-      throw worktreeError('WORKTREE_DIRTY_CHOICE', undefined, {
-        count: pendingChanges.length,
-        paths: pendingChanges.slice(0, DIRTY_CHOICE_PREVIEW),
-      });
-    }
+    const pendingChanges = await judgePendingChanges(repo, projectSubdir, carryChanges);
 
     const settings = await currentWorktreeSettings();
-    let baseCommit = repo.headCommit;
-    let mergeTarget = repo.currentBranch;
-    if (baseBranch) {
-      baseCommit = await branchCommit(repo.projectPath, baseBranch, { signal });
-      if (!baseCommit) {
-        throw worktreeError('WORKTREE_UNSUPPORTED_REPO', `Base branch ${baseBranch} does not exist.`, { baseBranch });
-      }
-      mergeTarget = baseBranch;
-    }
-    // A new branch at an explicit start point (`git worktree add -b <b> <path> <commit-ish>`).
-    if (startCommit) baseCommit = await resolveCommit(repo.projectPath, startCommit, signal);
+    const { baseCommit, mergeTarget } = await resolveStartPoint(repo, { baseBranch, startCommit, signal });
 
     // The main checkout's local env files come along on their own;
     // `.worktreeinclude` applies on top.
@@ -1073,11 +1568,20 @@ export async function createManagedWorktree({
     });
     throwIfAborted(signal);
 
+    // Every existing local branch under the prefix (all of them with no
+    // prefix): a new worktree never takes over one, whoever made it.
     const branches = new Set(
       (await localBranches(repo.projectPath, { signal, prefix: settings.branchPrefix })).map((name) =>
         name.toLowerCase()
       )
     );
+    // `x` is also taken while a branch `x/...` exists (the ref would be a directory).
+    const branchTaken = (name) => {
+      const key = name.toLowerCase();
+      if (branches.has(key)) return true;
+      for (const existing of branches) if (existing.startsWith(`${key}/`)) return true;
+      return false;
+    };
     const base = slugFromHint(nameHint);
     const reserve = async () => {
       let reserved = null;
@@ -1099,7 +1603,7 @@ export async function createManagedWorktree({
         }
       );
     let record = await reserve();
-    let carried = null;
+    const carry = { moved: null };
 
     try {
       await mkdir(root, { recursive: true });
@@ -1120,84 +1624,20 @@ export async function createManagedWorktree({
         await setResource(record, 'worktree', 'pending');
         await addCheckout(record);
       }
-      await setResource(record, 'worktree', 'created');
-      throwIfAborted(signal);
-      await setResource(record, 'lock', 'pending');
-      await runGit(repo.projectPath, [
-        'worktree',
-        'lock',
-        '--reason',
-        `mixdog session=${owner.sessionId}`,
-        record.path,
-      ]);
-      await setResource(record, 'lock', 'created');
-      await setResource(record, 'owner', 'pending');
-      await writeOwnerLease(record, owner);
-      await setResource(record, 'owner', 'created');
-      // Carried before the include entries are copied, so an include never
-      // stands in the way of a carried file; the status is read again here,
-      // right before acting.
-      let changes = pendingChanges.length ? { mode: 'left', count: pendingChanges.length } : null;
-      if (carryChanges === 'carry') {
-        carried = await carryUncommittedChanges({
-          topLevel: repo.topLevel,
-          projectSubdir,
-          worktreePath: record.path,
-          baseCommit,
-          label: record.id,
-        });
-        // The recovery ref stays until the caller has committed the move
-        // (dropCarryRecoveryRef) or put the changes back (restoreCarriedChanges).
-        changes = carried.count ? { mode: 'carried', count: carried.count, recoveryRef: carried.recoveryRef } : null;
-      }
-      const applied = await applyIncludes(includePlan, record.path, (ledger) => recordInclude(record, ledger));
-      throwIfAborted(signal);
-      // After the includes: one that already brought a node_modules wins.
-      const linkedDependencies = await linkWorktreeDependencies({
-        mainDir: repo.projectPath,
-        worktreeDir: projectSubdir ? join(record.path, ...projectSubdir.split('/')) : record.path,
-        worktreeRel: projectSubdir,
+      return await populateCheckout({
+        record,
+        owner,
+        repo,
+        projectSubdir,
         signal,
-        record: (ledger) => recordInclude(record, ledger),
+        pendingChanges,
+        carryChanges,
+        baseCommit,
+        includePlan,
+        carry,
       });
-      throwIfAborted(signal);
-      record.warnings = [...record.warnings, ...applied.warnings];
-      const made = (record.resources.includes || []).filter((item) => item.status === 'created');
-      const rels = (predicate) => made.filter(predicate).map((item) => item.rel);
-      // What creation did, for the agent's note at the first turn there (transitions.mjs).
-      const prepared = {
-        root: repo.topLevel,
-        copied: rels((item) => item.mode === 'copy'),
-        linked: rels((item) => item.mode === 'link' && !item.dependency),
-        dependencies: linkedDependencies,
-        skipped: [...includePlan.warnings, ...applied.warnings],
-      };
-      // Whichever path made it (a worktree task, a branch selection, `git
-      // worktree add`), the first turn a session runs here prepares its
-      // dependencies (claimWorktreeSetup).
-      record.setup = { pending: true, prepared };
-      record.state = 'ready';
-      await putRecord(record);
-      return { ...entryView(record), prepared, ...(changes ? { changes } : {}) };
     } catch (error) {
-      // Carried already: the changes go back to the project folder before the
-      // worktree that holds them is rolled back (the recovery ref keeps them
-      // either way).
-      let carryRestore = null;
-      if (carried?.recoveryRef) {
-        carryRestore = await restoreFromRecoveryRef(repo.topLevel, projectSubdir, carried.recoveryRef)
-          .then(() => ({ restored: true, recoveryRef: carried.recoveryRef }))
-          .catch((restoreError) => ({
-            restored: false,
-            recoveryRef: carried.recoveryRef,
-            error: String(restoreError?.message || restoreError),
-          }));
-      }
-      const rollback = await rollbackCreation(record, error);
-      const failure = isDiskFullError(error) ? await diskFullFailure(error, { needed, root }) : error;
-      if (!rollback.complete) failure.rollback = rollback;
-      if (carryRestore) failure.carryRestore = carryRestore;
-      throw failure;
+      throw await failCreation(error, { record, carried: carry.moved, repo, projectSubdir, needed, root });
     }
 
     async function reserveName() {
@@ -1206,37 +1646,28 @@ export async function createManagedWorktree({
         base,
         (candidate) =>
           ids.has(candidate.toLowerCase()) ||
-          branches.has(`${settings.branchPrefix}${candidate}`.toLowerCase()) ||
+          branchTaken(`${settings.branchPrefix}${candidate}`) ||
           existsSync(join(root, candidate))
       );
       const branch = requestedBranch ?? worktreeBranchName(slug, settings.branchPrefix);
+      // A new checkout at this path: no size measured for an earlier one counts.
+      forgetFolderSize(managedWorktreePath(repo.repoCommonDir, slug));
       if (!(await validBranchName(repo.projectPath, branch))) {
         throw worktreeError('WORKTREE_UNSUPPORTED_REPO', `Branch name ${branch} is not valid.`, { branch });
       }
-      const candidate = {
-        id: slug,
-        txId,
-        repoCommonDir: repo.repoCommonDir,
-        projectPath: repo.projectPath,
-        projectSubdir: projectSubdirOf(repo.topLevel, repo.projectPath),
-        path: managedWorktreePath(repo.repoCommonDir, slug),
+      const candidate = newCreationRecord({
+        slug,
         branch,
+        repo,
+        owner,
+        txId,
         baseCommit,
-        // An existing branch has no base it branched from: it merges where a
-        // merge first takes it (recorded then), and until that its own work is
-        // what it gained here since baseCommit.
-        mergeTarget: existingBranch ? null : mergeTarget,
-        createdAt: Date.now(),
-        ownerSessionId: owner.sessionId,
+        mergeTarget,
         existingBranch,
         exactBranch: requestedBranch !== null,
-        state: 'creating',
-        disposable: false,
-        warnings: [...(tracked.submodules ? ['submodules'] : []), ...includePlan.warnings],
-        resources: { worktree: null, lock: null, owner: null, includes: [] },
-        deleting: null,
-        recovery: null,
-      };
+        tracked,
+        includePlan,
+      });
       return (await insertRecord(candidate)) ? candidate : null;
     }
   });
@@ -1362,9 +1793,12 @@ export async function createSnapshotWorktree({
  * one is admitted there until the returned release. A folder no longer a
  * checkout admits no consumer (activity-gate tracks git checkouts only).
  */
-function holdSnapshotFolder(record) {
+async function holdSnapshotFolder(record) {
   if (!existsSync(join(record.path, '.git'))) return () => {};
-  return holdWorkspaceActivity([record.path]);
+  const release = await holdWorkspaceActivityAsync([record.path]);
+  // Settles once the removal was attempted. It fails only when workspace
+  // admission stopped (reported there), which keeps the folder held.
+  return () => release().catch(() => {});
 }
 
 /** A refusal that only says "something still runs there" (retry once it ends). */
@@ -1429,21 +1863,78 @@ export async function removeSessionSnapshots(sessionId, { txIds = null } = {}) {
   return report;
 }
 
+/** The node_modules links into the main checkout an earlier version recorded at creation. */
+function dependencyLinks(record) {
+  return (record?.resources?.includes || []).filter((item) => item.mode === 'link' && item.dependency);
+}
+
+/** The links this worktree's .worktreeinclude asked for (rel from the worktree's top level). */
+function userIncludeLinks(record) {
+  return (record?.resources?.includes || []).filter(
+    (item) => item.mode === 'link' && item.status === 'created' && !item.dependency
+  );
+}
+
+/**
+ * Unlink (never empty) the recorded dependency links of a worktree made by
+ * an earlier version, through which a reset (`npm ci`) in the worktree
+ * empties the main checkout's node_modules, and forget those gone. One that
+ * cannot be unlinked stays recorded, so removal still unlinks it first, and
+ * blocks every install in the worktree (claimWorktreeSetup).
+ * @returns {Promise<boolean>} whether any is gone
+ */
+async function detachDependencyLinks(record) {
+  const links = dependencyLinks(record);
+  if (!links.length) return false;
+  const stuck = new Set(await removeIncludeLinks(links));
+  record.resources.includes = record.resources.includes.filter((item) => !links.includes(item) || stuck.has(item.path));
+  return stuck.size < links.length;
+}
+
 /**
  * The first turn a session runs in managed worktree `entryId` claims its
  * dependency preparation, once: `{ prepared }` (what creation did) while it
  * is still pending, else null. Claimed before it runs, so a failed or
- * cancelled preparation is never repeated.
+ * cancelled preparation is never repeated. A worktree that still holds an
+ * earlier version's dependency link has it detached at its next turn and is
+ * claimed again (`prepared` null), so that turn installs in the worktree.
+ * While one cannot be unlinked, or any other installed artefact in the
+ * project folder is a link (linkedArtefacts) that the worktree's
+ * .worktreeinclude did not ask for, the claim is `{ prepared: null,
+ * blocked }` (the links, relative to the worktree's top level) instead:
+ * nothing is installed, since an install reaches beyond its own folder
+ * (`npm ci` at the root resets every workspace package's node_modules), and
+ * the setup stays pending, so each later turn tries again.
  */
 export async function claimWorktreeSetup(entryId) {
   const record = await getRecord(entryId);
-  if (!record?.setup?.pending) return null;
+  if (!record?.setup?.pending && !dependencyLinks(record).length) return null;
   return withRepoLock(record.repoCommonDir, async () => {
     const current = await getRecord(entryId);
-    if (current?.state !== 'ready' || !current.setup?.pending) return null;
+    if (current?.state !== 'ready') return null;
+    const pending = current.setup?.pending === true;
+    const detached = await detachDependencyLinks(current);
+    const blocked = dependencyLinks(current).map((item) => item.rel);
+    if (!blocked.length && !pending && !detached) return null;
+    // Links the user asked for in .worktreeinclude (relative to the project
+    // folder): shared folders on purpose, which the planner leaves alone.
+    const shared = [];
+    if (!blocked.length) {
+      const asked = new Set(userIncludeLinks(current).map((item) => item.rel));
+      for (const rel of await linkedArtefacts(sessionRootOf(current))) {
+        const topLevel = [current.projectSubdir, rel].filter(Boolean).join('/');
+        if (asked.has(topLevel)) shared.push(rel);
+        else blocked.push(topLevel);
+      }
+    }
+    if (blocked.length) {
+      current.setup = { ...current.setup, pending: true };
+      await putRecord(current);
+      return { prepared: null, blocked };
+    }
     current.setup = { ...current.setup, pending: false, claimedAt: Date.now() };
     await putRecord(current);
-    return { prepared: current.setup.prepared ?? null };
+    return { prepared: pending ? (current.setup.prepared ?? null) : null, shared };
   });
 }
 
@@ -1554,11 +2045,16 @@ export async function releaseWorktreeOwner(entryId, owner, { forgetReference = f
 export async function listBranchOccupancy({ projectPath, sessionId } = {}) {
   requireText(projectPath, 'projectPath');
   const repo = await inspectRepo(projectPath);
-  const [branches, worktrees, doc] = await Promise.all([
-    localBranches(repo.projectPath),
+  const [commits, worktrees, doc] = await Promise.all([
+    localBranchCommits(repo.projectPath),
     listWorktrees(repo.projectPath),
     readRegistry(),
   ]);
+  const branches = commits.map((commit) => commit.name);
+  // The tip's committer time per branch: the menu groups recent branches by it.
+  const committedAt = Object.fromEntries(
+    commits.filter((commit) => commit.committedAt).map((commit) => [commit.name, commit.committedAt])
+  );
   const managed = Object.values(doc.entries).filter((record) => samePath(record.repoCommonDir, repo.repoCommonDir));
   const occupancy = branches.map((branch) => {
     // A prunable registration (its folder is gone) holds nothing.
@@ -1572,7 +2068,7 @@ export async function listBranchOccupancy({ projectPath, sessionId } = {}) {
   const retained = sessionId
     ? managed.find((record) => record.ownerSessionId === sessionId && record.state === 'ready')
     : null;
-  return { branches, occupancy, retainedWorktree: retained ? entryView(retained) : null };
+  return { branches, occupancy, committedAt, retainedWorktree: retained ? entryView(retained) : null };
 }
 
 /**
@@ -1830,7 +2326,11 @@ export async function assertWorktreeRemovable({ entryId, force = false, sessionI
  * `expected` ({ kind, txId, holderSessionId }) pins the record the caller
  * selected: one that no longer matches under the repository lock (removed,
  * its slug reused) is left alone and reported `{ removed: false, skipped: true }`.
- * @param {{ entryId: string, force?: boolean, expected?: { kind?: string, txId?: string, holderSessionId?: string }|null }} input
+ * `automatic` (a deleted session's leftover): the cleanup's verified path
+ * (removeAutomatically): no force, no recursive delete; a keep is raised as
+ * WORKTREE_DIRTY / WORKTREE_UNMERGED / WORKTREE_BUSY_JOBS, and an incomplete
+ * git removal returns `{ removed: false, incomplete: true }` with the record ready again.
+ * @param {{ entryId: string, force?: boolean, expected?: { kind?: string, txId?: string, holderSessionId?: string }|null, automatic?: boolean }} input
  * @returns {Promise<{ removed: boolean, skipped?: boolean, retryable?: boolean, remaining?: object[], branchDeleted?: boolean }>}
  */
 export async function removeManagedWorktree({
@@ -1840,6 +2340,7 @@ export async function removeManagedWorktree({
   preserveBranch = false,
   safeOnly = false,
   expected = null,
+  automatic = false,
 } = {}) {
   const skipped = { removed: false, skipped: true };
   const matches = (record) =>
@@ -1858,24 +2359,48 @@ export async function removeManagedWorktree({
       if (!current && !expected) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
       return skipped;
     }
-    return removeLocked(current, { force, sessionId, preserveBranch, safeOnly });
+    return removeLocked(current, { force, sessionId, preserveBranch, safeOnly, automatic });
   });
 }
 
+/** Kept reasons of removeAutomatically as the typed refusals removeManagedWorktree raises. */
+function automaticRefusal(record, kept) {
+  if (kept.reason === 'dirty') return worktreeError('WORKTREE_DIRTY', undefined, { entryId: record.id });
+  if (kept.reason === 'ignored') {
+    return worktreeError('WORKTREE_DIRTY', 'The worktree holds ignored files no install restores.', {
+      entryId: record.id,
+      ignored: kept.files,
+      count: kept.count,
+    });
+  }
+  if (kept.reason === 'unmerged') return worktreeError('WORKTREE_UNMERGED', undefined, { entryId: record.id });
+  return worktreeRefusal('folder-in-use', { entryId: record.id, kept: kept.reason });
+}
+
 /** The removal of `current`, under its repository lock. */
-async function removeLocked(current, { force, sessionId, preserveBranch = false, safeOnly = false }) {
+async function removeLocked(
+  current,
+  { force, sessionId, preserveBranch = false, safeOnly = false, automatic = false }
+) {
   assertNotShared(current, sessionId);
+  // A deleted session's leftover (cleanupDeletedSessionWorktree): the
+  // verified automatic path, never a forced or recursive one.
+  if (automatic && !force && current.state === 'ready' && current.kind !== WORKTREE_SNAPSHOT_KIND) {
+    const outcome = await removeAutomatically(current, { preserveBranch, keepTip: !preserveBranch });
+    if (!outcome.result) throw automaticRefusal(current, outcome.kept);
+    return outcome.result;
+  }
   if (current.state === 'creating' || current.state === 'recovery') {
     const rollback = await rollbackCreation(current);
     return rollback.complete ? { removed: true } : { removed: false, retryable: true, remaining: rollback.remaining };
   }
   // Every deletion attempt of a snapshot, a resumed one included, waits
   // for (refuses on) its consumers.
-  const release = current.kind === WORKTREE_SNAPSHOT_KIND ? holdSnapshotFolder(current) : () => {};
+  const release = current.kind === WORKTREE_SNAPSHOT_KIND ? await holdSnapshotFolder(current) : () => {};
   try {
     return await decideAndFinishDeletion(current, { force, preserveBranch, safeOnly });
   } finally {
-    release();
+    await release();
   }
 }
 
@@ -1885,13 +2410,17 @@ async function removeLocked(current, { force, sessionId, preserveBranch = false,
  * so an owner that came back (a live session, a running lease holder) or a
  * session the store still keeps it for refuses (WORKTREE_BUSY_JOBS). Then
  * the ordinary removal guards apply (dirty or unmerged work needs `force`).
- * @param {{ entryId: string, force?: boolean, liveSessionIds?: string[], retainedSessionIds?: string[] }} input
+ * `allowRetained` (the user deleting it from the worktree list): a session
+ * the store keeps no longer protects it, a live owner or another session's
+ * shared reference still does.
+ * @param {{ entryId: string, force?: boolean, liveSessionIds?: string[], retainedSessionIds?: string[], allowRetained?: boolean }} input
  */
 export async function removeOrphanedWorktree({
   entryId,
   force = false,
   liveSessionIds = [],
   retainedSessionIds = [],
+  allowRetained = false,
 } = {}) {
   const record = await getRecord(entryId);
   if (!record) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
@@ -1902,6 +2431,13 @@ export async function removeOrphanedWorktree({
     }
     const { ownerLive, removable } = await retentionOf(current, new Set(liveSessionIds), new Set(retainedSessionIds));
     if (ownerLive) throw worktreeRefusal('workspace-lease', { entryId });
+    // The owner was just checked (not live; retained only with allowRetained):
+    // only other sessions' shared references refuse below.
+    const sessionId = current.ownerSessionId;
+    if (allowRetained) {
+      await assertRecoveryStoresClear(current);
+      return removeLocked(current, { force, sessionId });
+    }
     if (!removable) {
       // Retained recovery data names itself; otherwise sessions still keep it.
       await assertRecoveryStoresClear(current);
@@ -1910,7 +2446,7 @@ export async function removeOrphanedWorktree({
         sessions: [current.ownerSessionId, ...(current.sharedSessionIds ?? [])].filter(Boolean),
       });
     }
-    return removeLocked(current, { force });
+    return removeLocked(current, { force, sessionId });
   });
 }
 
@@ -1937,21 +2473,53 @@ function leaseProcessAlive(lease) {
  * `retainedSessionIds`, i.e. still in the session store), `ownerLive` (a
  * live session or a running lease holder), and `removable` (what a prune
  * would remove: neither, or disposable and not live, with no retained recovery data).
- * @param {{ liveSessionIds?: string[], retainedSessionIds?: string[] }} input
+ * `inspect` adds, for a ready branch worktree, `dirty` (uncommitted paths,
+ * and the ignored files no install restores, also counted as `ignored`:
+ * both keep it from the automatic cleanup) and `unmerged` (commits the
+ * merge target lacks; 0 when merged) — what the
+ * cleanup policies and the worktree list read; `size` adds `sizeBytes` and
+ * `sizeComplete` (cachedFolderBytes: a cached size returns at once and
+ * refreshes in the background after its TTL).
+ * @param {{ liveSessionIds?: string[], retainedSessionIds?: string[], inspect?: boolean, size?: boolean }} input
  */
-export async function listManagedWorktrees({ liveSessionIds = [], retainedSessionIds = [] } = {}) {
+export async function listManagedWorktrees({
+  liveSessionIds = [],
+  retainedSessionIds = [],
+  inspect = false,
+  size = false,
+} = {}) {
   const live = new Set(liveSessionIds);
   const retained = new Set(retainedSessionIds);
   const rows = [];
   for (const record of Object.values((await readRegistry()).entries)) {
     const { ownerLive, retained: isRetained, removable } = await retentionOf(record, live, retained);
-    rows.push({
+    const row = {
       ...entryView(record),
       projectPath: record.projectPath,
+      sharedSessionIds: [...(record.sharedSessionIds ?? [])],
       retained: isRetained,
       ownerLive,
       removable,
-    });
+    };
+    if (inspect && record.kind !== WORKTREE_SNAPSHOT_KIND && record.state === 'ready') {
+      try {
+        const { dirty, ignored } = await automaticKeepPaths(record);
+        row.dirty = dirty.length + ignored.length;
+        row.ignored = ignored.length;
+        row.unmerged = await unmergedCommitCount(record);
+      } catch {
+        // Unreadable state counts as work to keep.
+        row.dirty = null;
+        row.ignored = null;
+        row.unmerged = null;
+      }
+    }
+    if (size) {
+      const measured = existsSync(record.path) ? await cachedFolderBytes(record.path) : null;
+      row.sizeBytes = measured?.bytes ?? null;
+      row.sizeComplete = measured?.complete ?? true;
+    }
+    rows.push(row);
   }
   return rows;
 }
@@ -1979,6 +2547,143 @@ async function retentionOf(record, live, retained) {
   return { ownerLive, retained: isRetained, removable };
 }
 
+/**
+ * One automatic removal of the ready worktree `record` (the cleanup's count,
+ * age, archive and orphan removals, and a deleted session's leftover), under
+ * its repository lock. The slow checks (full status with untracked and
+ * ignored files and include copies, the commit walk and merge-tree) run before the folder is
+ * held, so no turn waits through them. Then the folder's workspace admission
+ * is held (a turn, worker, shell or git command already in it refuses the
+ * hold; one starting now waits), and under it: the owner lease and
+ * `inUse(record)` (the caller's current live sessions and jobs), a cheap
+ * token (HEAD, index, tips) against the one taken before the checks, and one
+ * time-bounded full status (finalDirtyCheck). Only then is the deletion
+ * decided, `automatic`: removeCheckoutVerified deletes through git alone and
+ * an incomplete attempt goes back to `ready` (keepIncompleteRemoval).
+ * @returns {Promise<{ result: object } | { kept: { reason: string } & object }>}
+ */
+async function removeAutomatically(
+  record,
+  {
+    inUse = async () => false,
+    preserveBranch = false,
+    keepTip = false,
+    finalCheckTimeoutMs = FINAL_DIRTY_CHECK_TIMEOUT_MS,
+  } = {}
+) {
+  const token = await checkoutToken(record);
+  const { dirty, ignored, artefacts } = await automaticKeepPaths(record);
+  const unmerged = await unmergedCommitCount(record);
+  if (dirty.length || unmerged > 0) return { kept: { reason: dirty.length ? 'dirty' : 'unmerged' } };
+  if (ignored.length) return { kept: ignoredKeep(ignored) };
+  let release;
+  try {
+    release = await holdSnapshotFolder(record);
+  } catch (error) {
+    if (!snapshotInUse(error)) throw error;
+    return { kept: { reason: 'in-use' } };
+  }
+  try {
+    if (leaseProcessAlive(await readOwnerLease(record)) || (await inUse(record))) return { kept: { reason: 'in-use' } };
+    if ((await checkoutToken(record)) !== token) return { kept: { reason: 'changed' } };
+    // The token misses nested untracked files and unstaged edits: one
+    // bounded full status decides. Dirty, slow or failed → kept.
+    const finalCheck = await finalDirtyCheck(record, finalCheckTimeoutMs, artefacts);
+    if (finalCheck) return { kept: finalCheck };
+    await assertRecoveryStoresClear(record);
+    record.state = 'deleting';
+    delete record.removalIncomplete;
+    record.deleting = {
+      force: false,
+      automatic: true,
+      ...(preserveBranch ? { preserveBranch: true } : keepTip ? { keepTip: true } : {}),
+      // Checked above; finishDeletion trusts it while the tip is this one.
+      mergedTip: record.branch ? await branchCommit(repoCwd(record), record.branch) : null,
+      startedAt: Date.now(),
+      remaining: [],
+    };
+    await putRecord(record);
+    return { result: await finishDeletion(record) };
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Whether the automatic pass would try to remove the ready, not-live
+ * worktree `record` (the archive/policy rules of reconcileManagedWorktrees);
+ * the verification (dirty, unmerged, in use) still decides at removal time.
+ */
+function cleanupWants(record, isRetained, { selected, favorites, minAgeMs, now, cleanupArchived }) {
+  const ruleAllows = () =>
+    ![record.ownerSessionId, ...(record.sharedSessionIds ?? [])].some((id) => id && favorites.has(id)) &&
+    now - (Number(record.createdAt) || 0) >= minAgeMs;
+  if (!isRetained) return true;
+  if (record.disposable === true) {
+    if (record.disposableReason !== 'archived') return true;
+    if (cleanupArchived && ruleAllows()) return true;
+  }
+  return selected.has(record.id) && ruleAllows();
+}
+
+/**
+ * Read-only counterpart of reconcileManagedWorktrees: what a prune with the
+ * same options could act on, from the registry, the retention and the git
+ * admin folders alone (no status, merge or lock). A candidate may still be
+ * kept at removal time after verification. Same options as the reconcile;
+ * `removeOrphans` is implied.
+ * @returns {Promise<{ ids: string[], stale: string[] }>} entry ids and the
+ *   checkout paths of registrations whose folder is gone
+ */
+export async function previewManagedWorktreeCleanup({
+  liveSessionIds = [],
+  retainedSessionIds = [],
+  repoCommonDir: onlyRepo = null,
+  removeEntryIds = [],
+  protectedSessionIds = [],
+  minAgeMs = 0,
+  now = Date.now(),
+  cleanupArchived = true,
+} = {}) {
+  const live = new Set(liveSessionIds);
+  const retained = new Set(retainedSessionIds);
+  const rules = {
+    selected: new Set(removeEntryIds),
+    favorites: new Set(protectedSessionIds),
+    minAgeMs,
+    now,
+    cleanupArchived,
+  };
+  const ids = [];
+  const repos = new Map();
+  for (const record of Object.values((await readRegistry()).entries)) {
+    const key = pathKey(record.repoCommonDir);
+    if (onlyRepo && key !== pathKey(onlyRepo)) continue;
+    repos.set(key, record.repoCommonDir);
+    if (record.sharedSessionIds?.length) continue;
+    const { ownerLive, retained: isRetained } = await retentionOf(record, live, retained);
+    if (record.kind === WORKTREE_SNAPSHOT_KIND) {
+      if (!ownerLive) ids.push(record.id);
+    } else if (record.state === 'deleting') {
+      ids.push(record.id);
+    } else if (record.state === 'creating' || record.state === 'recovery') {
+      if (!isRetained) ids.push(record.id);
+    } else if (!ownerLive && (record.removalIncomplete || cleanupWants(record, isRetained, rules))) {
+      ids.push(record.id);
+    }
+  }
+  const stale = [];
+  for (const [, repoCommonDir] of repos) {
+    if (!existsSync(repoCommonDir)) continue;
+    for (const registration of await adminRegistrations(repoCommonDir)) {
+      // git keeps a locked registration (a `locked` file) through prune.
+      if (existsSync(join(registration.admin, 'locked'))) continue;
+      if (await isGone(registration.worktreePath)) stale.push(canonicalPath(registration.worktreePath));
+    }
+  }
+  return { ids, stale };
+}
+
 /**
  * Conservative reconcile (daemon startup, and the manual prune). Always:
  * resumes interrupted deletions, rolls back interrupted creations of no
@@ -1990,20 +2695,62 @@ async function retentionOf(record, live, retained) {
  * session in the store still references. A snapshot whose holder is neither
  * live nor running in another process is removed in either mode.
  * `repoCommonDir` limits the whole reconcile to that repository.
- * @param {{ liveSessionIds?: string[], retainedSessionIds?: string[], removeOrphans?: boolean, repoCommonDir?: string|null }} input
+ *
+ * The automatic cleanup (maintenance.mjs) adds, all with `removeOrphans`:
+ * `removeEntryIds` — worktrees its count/age limits selected, removed even
+ * though a stored session still names them; `protectedSessionIds` (favorite
+ * sessions) and `minAgeMs`/`now` (younger worktrees) exempt those and
+ * archived-session marks (`disposableReason: 'archived'`, which
+ * `cleanupArchived: false` ignores); a deleted session's mark and a true
+ * orphan are not subject to them. `preserveBranch` keeps the branch of every
+ * worktree it removes; otherwise `keepTip` writes the recovery ref before the
+ * branch goes. `maxRemovals` caps the count/age/archive removals of one pass
+ * together (`kept: budget` beyond it). Dirty, unmerged, live, shared or
+ * recovery-holding worktrees are always kept, as are ones holding ignored
+ * files no install restores (`kept: ignored` with `files`, `count`:
+ * unreproducibleIgnored), and every removal first holds
+ * the folder's workspace admission (a turn, worker, shell or git command in
+ * it keeps it; one starting meanwhile waits) and asks `inUse(record)` again
+ * under that hold (the caller's current live sessions and running jobs).
+ * @param {{ liveSessionIds?: string[], retainedSessionIds?: string[], removeOrphans?: boolean,
+ *   repoCommonDir?: string|null, removeEntryIds?: string[], protectedSessionIds?: string[],
+ *   minAgeMs?: number, now?: number, cleanupArchived?: boolean, preserveBranch?: boolean, keepTip?: boolean,
+ *   maxRemovals?: number, inUse?: (record: object) => Promise<boolean>|boolean,
+ *   finalCheckTimeoutMs?: number }} input
+ *   `finalCheckTimeoutMs` bounds the last dirty check under the hold (FINAL_DIRTY_CHECK_TIMEOUT_MS);
+ *   a check that does not finish in time keeps the worktree (`kept: busy`).
  */
 export async function reconcileManagedWorktrees({
   liveSessionIds = [],
   retainedSessionIds = [],
   removeOrphans = false,
   repoCommonDir: onlyRepo = null,
+  removeEntryIds = [],
+  protectedSessionIds = [],
+  minAgeMs = 0,
+  now = Date.now(),
+  cleanupArchived = true,
+  preserveBranch = false,
+  keepTip = false,
+  maxRemovals = Infinity,
+  inUse = async () => false,
+  finalCheckTimeoutMs = FINAL_DIRTY_CHECK_TIMEOUT_MS,
 } = {}) {
   const live = new Set(liveSessionIds);
   const retained = new Set(retainedSessionIds);
+  const selected = new Set(removeEntryIds);
+  let budgetUsed = 0;
+  const rules = { selected, favorites: new Set(protectedSessionIds), minAgeMs, now, cleanupArchived };
+  const wanted = (record, isRetained) => cleanupWants(record, isRetained, rules);
   const report = { removed: [], recovered: [], kept: [], leasesReleased: [], pruned: [], missing: [], errors: [] };
   const reportDeletion = (record, result) => {
     if (result.removed) report.removed.push(record.id);
-    else report.kept.push({ id: record.id, reason: 'deleting', remaining: result.remaining });
+    else
+      report.kept.push({
+        id: record.id,
+        reason: result.incomplete ? 'incomplete' : 'deleting',
+        remaining: result.remaining,
+      });
   };
   const byRepo = new Map();
   for (const record of Object.values((await readRegistry()).entries)) {
@@ -2044,7 +2791,7 @@ export async function reconcileManagedWorktrees({
               // surviving folder since still keeps it.
               let release;
               try {
-                release = holdSnapshotFolder(record);
+                release = await holdSnapshotFolder(record);
               } catch (error) {
                 if (!snapshotInUse(error)) throw error;
                 report.kept.push({ id: record.id, reason: 'snapshot-in-use' });
@@ -2053,10 +2800,23 @@ export async function reconcileManagedWorktrees({
               try {
                 reportDeletion(record, await finishDeletion(record));
               } finally {
-                release();
+                await release();
               }
               continue;
             }
+            if (record.state === 'deleting' && record.deleting?.automatic) {
+              // An automatic removal that was interrupted is never resumed
+              // blindly: what it took apart is put back (its recorded undo)
+              // and the record is ready again, verified afresh by a later pass.
+              const notRestored = await undoAutomaticAttempt(record, record.deleting.undo);
+              await keepIncompleteRemoval(
+                record,
+                [...(record.deleting.remaining ?? []), ...notRestored],
+                'interrupted'
+              );
+              report.kept.push({ id: record.id, reason: 'incomplete', remaining: record.removalIncomplete.remaining });
+              continue;
+            }
             if (record.state === 'deleting') {
               // A decided deletion: its session already left the folder.
               reportDeletion(record, await finishDeletion(record));
@@ -2069,7 +2829,7 @@ export async function reconcileManagedWorktrees({
               let release = null;
               if (!(await snapshotHolderLive(record, live))) {
                 try {
-                  release = holdSnapshotFolder(record);
+                  release = await holdSnapshotFolder(record);
                 } catch (error) {
                   if (!snapshotInUse(error)) throw error;
                 }
@@ -2085,7 +2845,7 @@ export async function reconcileManagedWorktrees({
                 await putRecord(record);
                 reportDeletion(record, await finishDeletion(record));
               } finally {
-                release();
+                await release();
               }
               continue;
             }
@@ -2096,26 +2856,31 @@ export async function reconcileManagedWorktrees({
               report.leasesReleased.push(record.id);
             }
             if (!existsSync(record.path)) report.missing.push(record.id);
-            if (removeOrphans === true && !ownerLive && (record.disposable === true || !isRetained)) {
-              const dirty = await dirtyPaths(record);
-              const unmerged = await unmergedCommitCount(record);
-              if (dirty.length || unmerged > 0) {
-                report.kept.push({ id: record.id, reason: dirty.length ? 'dirty' : 'unmerged' });
+            if (removeOrphans === true && !ownerLive && wanted(record, isRetained)) {
+              // Count, age and archive removals share one budget per pass.
+              const budgeted = isRetained && (selected.has(record.id) || record.disposableReason === 'archived');
+              if (budgeted && budgetUsed >= maxRemovals) {
+                report.kept.push({ id: record.id, reason: 'budget' });
                 continue;
               }
-              await assertRecoveryStoresClear(record);
-              record.state = 'deleting';
-              record.deleting = { force: false, startedAt: Date.now(), remaining: [] };
-              await putRecord(record);
-              reportDeletion(record, await finishDeletion(record));
+              const outcome = await removeAutomatically(record, {
+                inUse,
+                preserveBranch,
+                keepTip,
+                finalCheckTimeoutMs,
+              });
+              if (!outcome.result) {
+                report.kept.push({ id: record.id, ...outcome.kept });
+                continue;
+              }
+              reportDeletion(record, outcome.result);
+              if (budgeted && outcome.result.removed) budgetUsed += 1;
             }
           } catch (error) {
             report.errors.push({ id: record.id, error: String(error?.message || error) });
           }
         }
-        for (const stale of await staleManagedRegistrations(repoCommonDir)) {
-          if (await pruneRegistration(repoCommonDir, stale)) report.pruned.push(canonicalPath(stale));
-        }
+        report.pruned.push(...(await pruneStaleRegistrations(repoCommonDir)));
       });
     } catch (error) {
       report.errors.push({ repoCommonDir, error: String(error?.message || error) });