mixdog 1.3.2 → 1.3.3

package/src/runtime/shared/worktrees/activity-gate.mjs

@@ -1,16 +1,8 @@
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { setTimeout as delay } from 'node:timers/promises';
 import { isAbsolute, join } from 'node:path';
-import {
-  parseJsonText,
-  quarantinePath,
-  readJsonStateSync,
-  unsupportedState,
-  updateJsonAtomicSync,
-  writeFileAtomicSync,
-  writeJsonAtomicSync,
-} from '../atomic-file.mjs';
+import { parseJsonText, quarantinePath, withFileLockSync, writeFileAtomicSync } from '../atomic-file.mjs';
 import { isPidAliveOrUnknown } from '../pid-liveness.mjs';
 import { findGitLayout } from './git-head.mjs';
 import { canonicalPath, isWithin, samePath } from './paths.mjs';
@@ -43,10 +35,19 @@ export function isExternalCheckout(folder) {
   );
 }
 
-const VERSION = 1;
-const UNRECORDED = Symbol('unrecorded');
-const emptyLedger = () => ({ version: VERSION, leases: [] });
-const isNewer = (state) => Number.isSafeInteger(state?.version) && state.version > VERSION;
+/*
+ * The admission ledger lists every turn, command and management lease of a
+ * repository. It is kept in two copies with the same content in the Git
+ * common directory: `mixdog-workspace-admission.json` and its `.management`
+ * mirror. A grant returns its release only once both copies hold it, and a
+ * release is forgotten only once both copies dropped it, so damage to either
+ * copy alone never loses an acknowledged lease. `recoveredAt` marks a ledger
+ * that may be missing leases because no complete copy survived: readers still
+ * run, management refuses, and only a quiescent reset that removes both
+ * copies clears it (docs/git-github-integration.md). Time, healing and
+ * releases never do.
+ */
+const VERSION = 2;
 const isLease = (lease) =>
   !!lease &&
   ['turn', 'command', 'management'].includes(lease.kind) &&
@@ -55,256 +56,245 @@ const isLease = (lease) =>
   lease.pid > 0 &&
   typeof lease.path === 'string' &&
   isAbsolute(lease.path);
-const hasLedgerShape = (state) => state?.version === VERSION && Array.isArray(state.leases);
-
-// The whole-file check: a newer build's ledger is intact data in a format this
-// build cannot honour (left in place), anything else off-shape is damage. One
-// bad lease record is not a damaged file; mutate() drops just that record.
-function validateLedger(state) {
-  if (isNewer(state)) throw unsupportedState('Workspace admission ledger was written by a newer build.');
-  if (!hasLedgerShape(state)) throw new TypeError('Workspace admission ledger is malformed.');
-  return state;
-}
-
-const refuseUnreadable = () => {
-  throw worktreeRefusal('workspace-admission-unreadable');
+// Only a pid PROVEN dead (ESRCH) drops its lease, whatever its kind; an
+// unprobeable pid still counts as running. A live runtime keeps a command
+// whose tree it cannot verify reserved under its own (live) pid until the
+// tree is confirmed gone, so a lease that outlives every pid belongs to a
+// restarted runtime that can no longer release it.
+const aliveLease = (lease) => isPidAliveOrUnknown(lease.pid);
+// A management hold shares one token across its folders, so a lease is
+// identified by token and path.
+const leaseKey = (lease) => `${lease.token}\0${lease.path}`;
+const unverifiable = () => worktreeRefusal('workspace-admission-unreadable');
+const copyPaths = (commonDir) => {
+  const primary = join(commonDir, FILE);
+  return [primary, `${primary}.management`];
 };
 const envMs = (name, fallback) => {
   const value = Number(process.env[name]);
   return Number.isFinite(value) && value > 0 ? value : fallback;
 };
-// How long the leases of a recovered ledger stay unknown. Every process
-// holding a lease republishes it within one heal period, so after this window
-// the ledger is whole again and destructive operations resume on their own.
-const recoveryWindowMs = () => envMs('MIXDOG_ADMISSION_RECOVERY_MS', 15_000);
 const healIntervalMs = () => envMs('MIXDOG_ADMISSION_HEAL_MS', 2_000);
 
-// A path that cannot be read at all (access denied, in use, a directory) is an
-// I/O failure, not damage: it refuses everything and is never touched.
-function assertLedgerReadable(path) {
-  try {
-    readFileSync(path);
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw worktreeRefusal('workspace-admission-unreadable');
-  }
-}
+// The leases this process holds, put back into a ledger that lost them, and
+// the tokens it released or failed to grant whose removal from both copies is
+// not confirmed yet (token -> common dir), retried until it is.
+const held = new Map();
+const pending = new Map();
+let healTimer = null;
 
 /**
- * A damaged ledger (NUL, truncated, malformed) must not block every prompt and
- * shell command of the workspace, nor may it make a destructive operation fail
- * open. Called under the ledger lock: its bytes are COPIED aside as
- * `<ledger>.corrupt-<ts>` and the same locked update replaces it with a ledger
- * carrying `recoveredAt`. The ledger is never moved away: a missing ledger
- * reads as "no leases", so any gap between the move and the publish (another
- * process taking the lock, or a crash) would admit management beside a live
- * foreign turn. A crash before the publish leaves the damaged file in place,
- * which the next writer recovers the same way. If the copy cannot be kept the
- * ledger is left untouched and everything refuses.
+ * One copy as read under the ledger lock. A copy that cannot be read (access
+ * denied, in use, a directory) or that a newer build wrote refuses everything
+ * and is never written: neither may pass for an empty ledger. Anything else
+ * that is not a ledger, or holds an invalid lease record, is damaged; its
+ * valid records still count. A copy is complete when it accounts for every
+ * acknowledged lease: intact, not uncertain, and version 2 — or the version 1
+ * primary, since the version 1 mirror held management leases only.
  */
-function keepDamagedAside(path) {
-  const aside = quarantinePath(path);
+function readCopy(path, primary) {
+  let bytes;
   try {
-    writeFileAtomicSync(aside, readFileSync(path));
-  } catch {
-    throw worktreeRefusal('workspace-admission-unreadable');
+    bytes = readFileSync(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { path, leases: [] };
+    throw unverifiable();
   }
-  process.stderr.write(`[state] ${path} is damaged; kept as ${aside}\n`);
-}
-
-function keepAside(path, value) {
-  const aside = quarantinePath(path);
+  let ledger = null;
   try {
-    writeFileAtomicSync(aside, JSON.stringify(value));
-    process.stderr.write(`[state] ${path} held invalid lease records; kept as ${aside}\n`);
+    ledger = parseJsonText(bytes.toString('utf8'));
   } catch {
-    // Best effort: the valid records carry on either way.
+    // Unparseable: damaged below.
+  }
+  if (Number.isSafeInteger(ledger?.version) && ledger.version > VERSION) throw unverifiable();
+  if (![1, VERSION].includes(ledger?.version) || !Array.isArray(ledger.leases)) {
+    return { path, bytes, leases: [], damaged: true };
   }
+  const leases = ledger.leases.filter(isLease);
+  const damaged = leases.length !== ledger.leases.length;
+  const uncertain = Object.hasOwn(ledger, 'recoveredAt');
+  const complete = !damaged && !uncertain && (ledger.version === VERSION || primary);
+  return { path, bytes, leases, damaged, uncertain, complete, recoveredAt: ledger.recoveredAt };
 }
 
-const aliveLease = (lease) => isPidAliveOrUnknown(lease.pid);
-
-// Management leases live in a mirror file as well as the ledger: damage to
-// one never hides an operation in progress from the readers.
-function readMirror(mirror) {
-  try {
-    const state = readJsonStateSync(mirror, { validate: validateLedger, strictOwner: true });
-    return (state?.leases ?? []).filter((lease) => isLease(lease) && lease.kind === 'management' && aliveLease(lease));
-  } catch {
-    return [];
+/**
+ * The ledger recovered from both copies: the union of their valid lease
+ * records (one copy lacking a lease never drops it), less proven-dead pids
+ * and this process's pending removals, plus the leases this process holds.
+ * It stays uncertain when either copy is, and becomes so when a copy exists
+ * but none is complete. Both copies missing reads as a new repository.
+ */
+function recover(commonDir, copies) {
+  const own = [...held.values()].filter((entry) => entry.commonDir === commonDir).map((entry) => entry.lease);
+  const leases = new Map();
+  for (const lease of [...copies.flatMap((copy) => copy.leases), ...own]) {
+    const key = leaseKey(lease);
+    if (!leases.has(key) && pending.get(lease.token) !== commonDir && aliveLease(lease)) leases.set(key, lease);
   }
+  const ledger = { version: VERSION, leases: [...leases.values()] };
+  const uncertain =
+    copies.some((copy) => copy.uncertain) ||
+    (copies.some((copy) => copy.bytes) && !copies.some((copy) => copy.complete));
+  if (uncertain) ledger.recoveredAt = copies.map((copy) => copy.recoveredAt).find(Number.isFinite) ?? Date.now();
+  return ledger;
 }
 
-function writeMirror(mirror, leases) {
-  try {
-    writeJsonAtomicSync(mirror, { version: VERSION, leases }, { compact: true });
-  } catch (error) {
-    process.stderr.write(`[state] ${mirror} could not be written (${error?.message})\n`);
+/**
+ * #117: the bytes of a damaged copy are copied aside as `<copy>.corrupt-<ts>`
+ * before it is rewritten. If they cannot be kept, nothing is written and
+ * everything refuses.
+ */
+function keepDamagedAside(copies) {
+  for (const copy of copies.filter((each) => each.damaged)) {
+    const aside = quarantinePath(copy.path);
+    try {
+      writeFileAtomicSync(aside, copy.bytes);
+    } catch {
+      throw unverifiable();
+    }
+    process.stderr.write(`[state] ${copy.path} is damaged; kept as ${aside}\n`);
   }
 }
 
-// Leases this process holds, republished into any ledger that lost them.
-const held = new Map();
-let healTimer = null;
-
-// A management hold shares one token across its folders, so a lease is
-// identified by token and path.
-const leaseKey = (lease) => `${lease.token}\0${lease.path}`;
+/** Writes the primary, then the mirror; a copy that already holds the ledger is left alone. */
+function publish(copies, ledger) {
+  const text = Buffer.from(`${JSON.stringify(ledger, null, 2)}\n`);
+  for (const copy of copies) {
+    if (copy.bytes?.equals(text)) continue;
+    copy.bytes = null; // Unknown until the write lands.
+    writeFileAtomicSync(copy.path, text);
+    copy.bytes = text;
+  }
+}
 
-function track(commonDir, lease) {
-  held.set(leaseKey(lease), { commonDir, lease });
-  healTimer ??= setInterval(healHeld, healIntervalMs());
-  healTimer.unref?.();
+function settle(tokens) {
+  for (const token of tokens) pending.delete(token);
+  syncHealTimer();
 }
 
-function untrack(token) {
-  for (const [key, { lease }] of held) if (lease.token === token) held.delete(key);
-  if (!held.size && healTimer) {
-    clearInterval(healTimer);
-    healTimer = null;
-  }
+/**
+ * Runs `update(leases, { unknown })` on the recovered ledger under the
+ * primary copy's lock and publishes the result to both copies before
+ * returning. `unknown`: the ledger may be missing leases. A refused update
+ * still publishes the repaired ledger. A grant that cannot be published is
+ * refused: its leases become pending removals and the ledger without them is
+ * published again; whatever that leaves behind is withdrawn by the next
+ * mutation or heal tick, which also blocks every later grant until it lands.
+ */
+function mutate(commonDir, update = () => {}) {
+  const paths = copyPaths(commonDir);
+  return withFileLockSync(
+    `${paths[0]}.lock`,
+    () => {
+      const copies = paths.map((path, index) => readCopy(path, index === 0));
+      keepDamagedAside(copies);
+      const withdrawn = [...pending].filter(([, dir]) => dir === commonDir).map(([token]) => token);
+      const base = recover(commonDir, copies);
+      const leases = [...base.leases];
+      let result;
+      let refusal = null;
+      try {
+        result = update(leases, { unknown: Object.hasOwn(base, 'recoveredAt') });
+      } catch (error) {
+        refusal = error;
+      }
+      const granted = refusal ? [] : leases.filter((lease) => !base.leases.includes(lease));
+      try {
+        publish(copies, refusal ? base : { ...base, leases });
+        settle(withdrawn);
+      } catch (error) {
+        process.stderr.write(`[state] ${paths[0]} could not be published (${error?.message})\n`);
+        if (refusal) throw refusal;
+        for (const lease of granted) pending.set(lease.token, commonDir);
+        if (granted.length) {
+          try {
+            publish(copies, base);
+            settle([...withdrawn, ...granted.map((lease) => lease.token)]);
+          } catch {
+            syncHealTimer();
+          }
+        }
+        throw unverifiable();
+      }
+      if (refusal) throw refusal;
+      return result;
+    },
+    { strictOwner: true }
+  );
 }
 
-function ledgerLacks(commonDir, keys) {
-  let state;
+// Without the lock, a cheap check that both copies are the same current
+// ledger holding every live lease this process holds there and none of the
+// tokens it is withdrawing. Repair, never proof that the ledger is complete.
+function inSync(commonDir) {
+  let ledger;
   try {
-    state = parseJsonText(readFileSync(join(commonDir, FILE), 'utf8'));
-  } catch (error) {
-    return error?.code === 'ENOENT' || error instanceof SyntaxError;
+    const [primary, mirror] = copyPaths(commonDir).map((path) => readFileSync(path));
+    if (!primary.equals(mirror)) return false;
+    ledger = parseJsonText(primary.toString('utf8'));
+  } catch {
+    return false;
   }
-  if (isNewer(state)) return false;
-  if (!hasLedgerShape(state)) return true;
-  const stored = new Set(state.leases.filter(Boolean).map(leaseKey));
-  return keys.some((key) => !stored.has(key));
+  if (ledger?.version !== VERSION || !Array.isArray(ledger.leases)) return false;
+  const stored = new Set(ledger.leases.filter(isLease).map(leaseKey));
+  return (
+    [...held].every(([key, entry]) => entry.commonDir !== commonDir || stored.has(key) || !aliveLease(entry.lease)) &&
+    !ledger.leases.some((lease) => pending.get(lease?.token) === commonDir)
+  );
 }
 
 function healHeld() {
-  const byDir = new Map();
-  for (const [key, { commonDir }] of held) byDir.set(commonDir, [...(byDir.get(commonDir) ?? []), key]);
-  for (const [commonDir, keys] of byDir) {
-    if (!ledgerLacks(commonDir, keys)) continue;
+  const dirs = new Set([...[...held.values()].map((entry) => entry.commonDir), ...pending.values()]);
+  for (const commonDir of dirs) {
+    if (inSync(commonDir)) continue;
     try {
-      mutate(
-        commonDir,
-        () => {},
-        () => {}
-      );
+      mutate(commonDir);
     } catch {
       // Retried on the next tick.
     }
   }
+  syncHealTimer();
 }
 
-/**
- * Runs `update(leases, { unknown })` under the ledger lock. `unknown`: the
- * ledger was recovered recently and may be missing other processes' leases.
- * `onNewer` answers for a ledger of a newer build, which is left untouched:
- * it refuses by default; readers pass an answer that admits them unrecorded.
- */
-function mutate(commonDir, update, onNewer = refuseUnreadable) {
-  const path = join(commonDir, FILE);
-  const mirror = `${path}.management`;
-  assertLedgerReadable(path);
-  let result;
-  let refusal = null;
-  updateJsonAtomicSync(
-    path,
-    (current) => {
-      if (isNewer(current)) {
-        result = onNewer();
-        return undefined;
-      }
-      const now = Date.now();
-      let state;
-      let recovered = false;
-      if (current === null) {
-        state = emptyLedger();
-        // `keepWithoutBackup` leaves a ledger whose text does not parse in
-        // place, so null with a file present is damage; no file is a new ledger.
-        if (existsSync(path)) {
-          keepDamagedAside(path);
-          recovered = true;
-        }
-      } else if (!hasLedgerShape(current)) {
-        keepAside(path, current);
-        state = emptyLedger();
-        recovered = true;
-      } else {
-        state = { ...current, leases: current.leases.filter(isLease) };
-        if (state.leases.length !== current.leases.length) {
-          keepAside(path, current);
-          recovered = true;
-        }
-      }
-      if (recovered) state.recoveredAt = now;
-      // Only a pid PROVEN dead (ESRCH) drops its lease, whatever its kind; an
-      // unprobeable pid still counts as running. A live runtime keeps a command
-      // whose tree it cannot verify reserved under its own (live) pid until the
-      // tree is confirmed gone, so a lease that outlives every pid belongs to a
-      // restarted runtime that can no longer release it.
-      state.leases = state.leases.filter(aliveLease);
-      const present = new Set(state.leases.map(leaseKey));
-      const restore = [
-        ...(recovered ? readMirror(mirror) : []),
-        ...[...held.values()].filter((own) => own.commonDir === commonDir).map((own) => own.lease),
-      ];
-      for (const lease of restore) {
-        if (present.has(leaseKey(lease)) || !aliveLease(lease)) continue;
-        present.add(leaseKey(lease));
-        state.leases.push(lease);
-      }
-      const unknown = Number.isFinite(state.recoveredAt) && now - state.recoveredAt < recoveryWindowMs();
-      if (!unknown) delete state.recoveredAt;
-      const managementTokens = () =>
-        state.leases
-          .filter((lease) => lease.kind === 'management')
-          .map((lease) => lease.token)
-          .join();
-      const before = managementTokens();
-      const unchanged = [...state.leases];
-      try {
-        result = update(state.leases, { unknown });
-      } catch (error) {
-        // A refusal still publishes the recovery: dropping the write would
-        // leave the damaged file, and every retry would recover it again and
-        // restart the window, so management would never resume.
-        if (!recovered) throw error;
-        refusal = error;
-        state.leases = unchanged;
-      }
-      if (recovered || managementTokens() !== before) {
-        writeMirror(
-          mirror,
-          state.leases.filter((lease) => lease.kind === 'management')
-        );
-      }
-      return state;
-    },
-    // No backup restore: an older ledger would resurrect leases long released.
-    { strictOwner: true, keepWithoutBackup: true, restoreBackup: false }
-  );
-  if (refusal) throw refusal;
-  return result;
+function syncHealTimer() {
+  if (held.size || pending.size) {
+    healTimer ??= setInterval(healHeld, healIntervalMs());
+    healTimer.unref?.();
+  } else if (healTimer) {
+    clearInterval(healTimer);
+    healTimer = null;
+  }
+}
+
+function track(commonDir, lease) {
+  held.set(leaseKey(lease), { commonDir, lease });
+  syncHealTimer();
 }
 
+// Forgotten as held first, so nothing puts the lease back; its token stays
+// pending until both copies dropped it.
 function release(commonDir, token) {
   let done = false;
   return () => {
     if (done) return;
-    mutate(
-      commonDir,
-      (leases) => {
-        for (let i = leases.length - 1; i >= 0; i--) if (leases[i].token === token) leases.splice(i, 1);
-      },
-      () => {}
-    );
     done = true;
-    untrack(token);
+    for (const [key, entry] of held) if (entry.lease.token === token) held.delete(key);
+    pending.set(token, commonDir);
+    try {
+      mutate(commonDir);
+    } catch {
+      // Retried by the next mutation or heal tick.
+    }
+    syncHealTimer();
   };
 }
 
 /**
  * Readers share a checkout freely. Null means a management writer currently
- * owns it; a reader in an external checkout is never held back.
+ * owns it; a reader in an external checkout is never held back. Throws
+ * `workspace-admission-unreadable` when the ledger cannot be read, was
+ * written by a newer build, or the grant could not be made durable in both
+ * copies: no work may run unrecorded.
  */
 export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, kind = 'turn' } = {}) {
   if (!['turn', 'command'].includes(kind)) throw new TypeError('Invalid workspace reader kind.');
@@ -314,18 +304,11 @@ export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, k
   const path = canonicalPath(cwd);
   const token = randomUUID();
   const lease = { kind, sessionId, pid, token, path };
-  const admitted = mutate(
-    layout.commonDir,
-    (leases) => {
-      if (!external && leases.some((other) => other.kind === 'management' && overlaps(other.path, path))) return false;
-      leases.push(lease);
-      return true;
-    },
-    // A newer build's ledger cannot be written: the reader goes unrecorded
-    // (prompts never wait on it) while management refuses on it.
-    () => UNRECORDED
-  );
-  if (admitted === UNRECORDED) return () => {};
+  const admitted = mutate(layout.commonDir, (leases) => {
+    if (!external && leases.some((other) => other.kind === 'management' && overlaps(other.path, path))) return false;
+    leases.push(lease);
+    return true;
+  });
   if (!admitted) return null;
   track(layout.commonDir, lease);
   return release(layout.commonDir, token);
@@ -374,9 +357,8 @@ export function holdWorkspaceActivity(folders, { sessionId = null } = {}) {
             paths.some(({ path }) => overlaps(path, lease.path))
         );
         if (conflicts.length) throw worktreeRefusal('folder-in-use');
-        // A recovered ledger may be missing a live foreign turn: wait for the
-        // holders to republish (bounded by the recovery window).
-        if (unknown) throw worktreeRefusal('workspace-admission-unreadable');
+        // The ledger may be missing a live foreign lease: refused until reset.
+        if (unknown) throw unverifiable();
         for (const { path, external } of paths) {
           if (external) continue;
           const lease = { kind: 'management', pid: process.pid, token, path };

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

@@ -265,13 +265,19 @@ export function nextRevision(workspace) {
  * @property {string} repoCommonDir
  * @property {string} projectPath
  * @property {string} path Absolute worktree folder (see managedWorktreePath).
- * @property {string} branch Full branch name, e.g. "mixdog/fix-login".
+ * @property {string|null} branch Full branch name, e.g. "mixdog/fix-login"; null only for a snapshot.
  * @property {string|null} baseCommit
  * @property {number} createdAt Epoch milliseconds.
- * @property {string|null} ownerSessionId Lead session that retains it; null once released.
+ * @property {string|null} ownerSessionId Lead session that retains it; null once released (and for a snapshot).
  * @property {WorktreeEntryState} state
+ * @property {'snapshot'} [kind] A read-only detached checkout of `baseCommit`
+ *   (WORKTREE_SNAPSHOT_KIND): no branch, bound to no session, removed with
+ *   the turn that made it.
  */
 
+/** `kind` of a managed read-only snapshot: a detached checkout no session works in. */
+export const WORKTREE_SNAPSHOT_KIND = 'snapshot';
+
 /**
  * @param {unknown} input
  * @returns {WorktreeEntry}
@@ -284,16 +290,18 @@ export function normalizeWorktreeEntry(input) {
   const id = text(value.id, 'worktree.id');
   const idError = worktreeNameError(id);
   if (idError) throw new TypeError(`worktree.id is invalid: ${idError}`);
+  const snapshot = value.kind === WORKTREE_SNAPSHOT_KIND;
   return {
     id,
     repoCommonDir: text(value.repoCommonDir, 'worktree.repoCommonDir'),
     projectPath: text(value.projectPath, 'worktree.projectPath'),
     path: text(value.path, 'worktree.path'),
-    branch: text(value.branch, 'worktree.branch'),
+    branch: snapshot ? nullableText(value.branch, 'worktree.branch') : text(value.branch, 'worktree.branch'),
     baseCommit: nullableCommit(value.baseCommit, 'worktree.baseCommit'),
     createdAt: value.createdAt,
     ownerSessionId: nullableText(value.ownerSessionId, 'worktree.ownerSessionId'),
     state: oneOf(value.state, WORKTREE_ENTRY_STATES, 'worktree.state'),
+    ...(snapshot ? { kind: WORKTREE_SNAPSHOT_KIND } : {}),
   };
 }
 

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

@@ -72,14 +72,21 @@ export async function listWorktreesWithRetention({
  * The manual prune (an explicit request, so independent of autoCleanup):
  * the startup reconcile plus removal of clean, merged worktrees that no
  * stored or live session retains. Dirty or unmerged ones are reported kept.
- * @param {{ liveSessionIds?: string[], listSessionIds?: () => Promise<string[]>, manager?: object }} [options]
+ * `repoCommonDir` limits the prune to that repository's worktrees.
+ * @param {{ liveSessionIds?: string[], listSessionIds?: () => Promise<string[]>, manager?: object, repoCommonDir?: string|null }} [options]
  */
-export async function pruneWorktrees({ liveSessionIds = [], listSessionIds = storedSessionIds, manager = null } = {}) {
+export async function pruneWorktrees({
+  liveSessionIds = [],
+  listSessionIds = storedSessionIds,
+  manager = null,
+  repoCommonDir = null,
+} = {}) {
   const backend = manager || (await loadManager());
   return backend.reconcileManagedWorktrees({
     liveSessionIds,
     retainedSessionIds: await listSessionIds(),
     removeOrphans: true,
+    ...(repoCommonDir ? { repoCommonDir } : {}),
   });
 }
 
@@ -93,6 +100,8 @@ export async function pruneWorktrees({ liveSessionIds = [], listSessionIds = sto
 export async function cleanupDeletedSessionWorktree(sessionId, { manager = null, autoCleanup } = {}) {
   const backend = manager || (await loadManager());
   await backend.forgetSharedWorktreeSession?.(sessionId);
+  // Its read-only snapshots go whatever autoCleanup says (they never outlive their holder).
+  await backend.removeSessionSnapshots?.(sessionId);
   const entry = await backend.getSessionWorktree(sessionId);
   if (!entry) return null;
   const enabled = autoCleanup ?? (await backend.currentWorktreeSettings()).autoCleanup;