mixdog 1.2.1 → 1.2.3

package/src/runtime/shared/worktrees/file-recovery.mjs

@@ -0,0 +1,68 @@
+/** Persistent file-host journal scopes. No payload is read or deleted here.
+ * A retained record (even resolved) needs an explicit discard before its
+ * workspace can be removed. An unreadable/symlinked store is never empty. */
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { lstat, opendir } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { worktreeError } from './contract.mjs';
+import { isWithin } from './paths.mjs';
+
+const fail = (record, root) => worktreeError('WORKTREE_FILE_RECOVERY', undefined, {
+  entryId: record.id, path: record.path, recoveryRoot: root,
+});
+export function validateRecoveryScope(record, scope) {
+  if (!scope || typeof scope.root !== 'string' || !isAbsolute(scope.root) ||
+      typeof scope.directory !== 'string' || !isAbsolute(scope.directory) ||
+      !isWithin(record.path, scope.root) || basename(dirname(scope.directory)) !== 'editor-recovery' ||
+      basename(scope.directory) !== createHash('sha256').update(resolve(scope.root)).digest('hex'))
+    throw fail(record, record.path);
+  return scope;
+}
+export function recoveryScopes(record) {
+  const scopes = record.editorRecoveryStores ?? [];
+  if (!Array.isArray(scopes) || scopes.length > 64) throw fail(record, record.path);
+  return scopes.map((scope) => validateRecoveryScope(record, scope));
+}
+async function recoveryStoreIsEmpty(scope) {
+  try {
+    // Check every existing ancestor of the private journal store; missing
+    // stores are permitted because registration deliberately precedes mkdir.
+    for (const directory of [dirname(dirname(scope.directory)), dirname(scope.directory), scope.directory]) {
+      let info;
+      try { info = await lstat(directory); }
+      catch (error) { if (error?.code === 'ENOENT') continue; throw error; }
+      // Use the same path spelling as the file host's store validation;
+      // async/native realpath can expand Windows short names differently.
+      if (!info.isDirectory() || info.isSymbolicLink() || realpathSync(directory) !== resolve(directory))
+        return false;
+    }
+    let directory;
+    try { directory = await opendir(scope.directory); }
+    catch (error) { if (error?.code === 'ENOENT') return true; throw error; }
+    for await (const entry of directory) {
+      // Also retain unknown/tampered entries, rather than guessing they are
+      // expendable. No manifest or phase can authorize deleting the workspace.
+      if (entry) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Call under the repository lock. Only descriptors for verifiably empty or
+// missing stores may be pruned; this never removes storage or backup bytes.
+export async function retainedRecoveryScopes(record) {
+  const retained = [];
+  for (const scope of recoveryScopes(record)) {
+    if (!(await recoveryStoreIsEmpty(scope))) retained.push(scope);
+  }
+  return retained;
+}
+
+export async function assertRecoveryStoresClear(record) {
+  for (const scope of recoveryScopes(record)) {
+    if (!(await recoveryStoreIsEmpty(scope))) throw fail(record, scope.root);
+  }
+}

package/src/runtime/shared/worktrees/git-head.mjs

@@ -0,0 +1,205 @@
+/**
+ * Spawn-free read of a checkout's HEAD: the repository layout (work tree root,
+ * git dir, common dir) is found by walking up from a folder to its `.git`
+ * (a directory, or a `gitdir:` file for linked worktrees and submodules), and
+ * HEAD is the one small file in the git dir. Packed refs never matter: HEAD
+ * names a branch (`ref: refs/heads/x`) or holds a commit id.
+ */
+import { readFileSync, statSync, watch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { canonicalPath } from './paths.mjs';
+
+const OBJECT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i;
+const NOT_A_REPO_TTL_MS = 1000;
+
+/** start dir → { topLevel, gitDir, commonDir } for folders inside a checkout. */
+const layouts = new Map();
+/** start dir → time a walk found no repository. */
+const notRepos = new Map();
+/** git dir → last HEAD read, kept across a half-written HEAD. */
+const lastHeads = new Map();
+
+function readText(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function layoutAbove(start) {
+  for (let dir = start; ; dir = dirname(dir)) {
+    const dotGit = resolve(dir, '.git');
+    let gitDir = null;
+    if (isDirectory(dotGit)) {
+      gitDir = dotGit;
+    } else if (isFile(dotGit)) {
+      const pointer = /^gitdir:\s*(.+?)\s*$/m.exec(readText(dotGit) ?? '');
+      if (pointer) gitDir = resolve(dir, pointer[1]);
+    }
+    if (gitDir && isFile(resolve(gitDir, 'HEAD'))) {
+      const common = readText(resolve(gitDir, 'commondir'))?.trim();
+      return {
+        topLevel: canonicalPath(dir),
+        gitDir,
+        commonDir: canonicalPath(common ? resolve(gitDir, common) : gitDir),
+      };
+    }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/** The checkout layout containing `cwd`, or null outside a repository. */
+export function findGitLayout(cwd) {
+  const start = resolve(String(cwd || '.'));
+  const known = layouts.get(start);
+  if (known && isFile(resolve(known.gitDir, 'HEAD'))) return known;
+  layouts.delete(start);
+  const missedAt = notRepos.get(start);
+  if (missedAt !== undefined && Date.now() - missedAt < NOT_A_REPO_TTL_MS) return null;
+  const found = layoutAbove(start);
+  if (!found) {
+    notRepos.set(start, Date.now());
+    return null;
+  }
+  notRepos.delete(start);
+  layouts.set(start, found);
+  return found;
+}
+
+const MAX_SYMREF_DEPTH = 5;
+const PER_WORKTREE_REFS = /^refs\/(?:bisect|worktree|rewritten)\//;
+
+/** Where a ref's loose file lives: per-worktree refs in the git dir, the rest in the common dir. */
+function refFile(layout, name) {
+  return resolve(PER_WORKTREE_REFS.test(name) ? layout.gitDir : layout.commonDir, name);
+}
+
+/**
+ * Follows HEAD's symbolic refs like git does (packed-refs never holds a
+ * symref, so only loose ref files are read). Returns `{ name, files }`: the
+ * ref HEAD finally resolves to (the first non-symbolic ref, or the first
+ * missing target: an unborn branch) and every file read along the chain, or
+ * `{ name: null, files }` for a cycle or a chain over the depth limit.
+ */
+function followHead(layout, text) {
+  const files = [resolve(layout.gitDir, 'HEAD')];
+  let name = /^ref:\s*(.+)$/.exec(text)?.[1].trim();
+  const seen = new Set();
+  for (let depth = 0; name && depth < MAX_SYMREF_DEPTH; depth++) {
+    if (seen.has(name)) return { name: null, files };
+    seen.add(name);
+    const file = refFile(layout, name);
+    files.push(file);
+    const next = /^ref:\s*(.+)$/.exec(readText(file)?.trim() ?? '')?.[1].trim();
+    if (!next) return { name, files };
+    name = next;
+  }
+  return { name: null, files };
+}
+
+/** Files whose change can change what `gitDir`'s HEAD resolves to. */
+function headChainFiles(layout) {
+  const text = readText(resolve(layout.gitDir, 'HEAD'))?.trim();
+  return text && /^ref:/.test(text) ? followHead(layout, text).files : [resolve(layout.gitDir, 'HEAD')];
+}
+
+/**
+ * What `cwd`'s checkout has checked out: `{ topLevel, gitDir, repoCommonDir,
+ * branch, commit }` (`branch` null when detached or when the symbolic-ref
+ * chain is broken, `commit` null on a branch), or null when `cwd` is not
+ * inside a git repository. A branch alias resolves to the branch it points at.
+ */
+export function readGitHead(cwd) {
+  const layout = findGitLayout(cwd);
+  if (!layout) return null;
+  const text = readText(resolve(layout.gitDir, 'HEAD'))?.trim();
+  let head = lastHeads.get(layout.gitDir) ?? { branch: null, commit: null };
+  if (text && /^ref:\s*(.+)$/.test(text)) {
+    const { name } = followHead(layout, text);
+    head = { branch: name?.startsWith('refs/heads/') ? name.slice('refs/heads/'.length) : null, commit: null };
+  } else if (text && OBJECT_ID.test(text)) {
+    head = { branch: null, commit: text.toLowerCase() };
+  }
+  lastHeads.set(layout.gitDir, head);
+  return {
+    topLevel: layout.topLevel,
+    gitDir: layout.gitDir,
+    repoCommonDir: layout.commonDir,
+    branch: head.branch,
+    commit: head.commit,
+  };
+}
+
+/**
+ * Calls `onChange` shortly after the HEAD of the checkout `getCwd()` names
+ * changes (a `git switch` from any terminal). Call `retarget()` whenever the
+ * folder may have changed; `dispose()` ends the watch.
+ */
+export function createGitHeadWatcher({ getCwd, onChange, debounceMs = 40 }) {
+  let target = '';
+  let watchers = [];
+  let timer = null;
+  const closeWatchers = () => {
+    for (const watcher of watchers) watcher.close();
+    watchers = [];
+  };
+  const notify = () => {
+    clearTimeout(timer);
+    timer = setTimeout(onChange, debounceMs);
+    timer.unref?.();
+  };
+  const retarget = () => {
+    const layout = findGitLayout(getCwd());
+    // HEAD and every symbolic ref it passes through: a change anywhere in
+    // that chain can change the branch.
+    const files = layout ? headChainFiles(layout) : [];
+    const key = files.join('\n');
+    if (key === target) return;
+    closeWatchers();
+    target = key;
+    // The directories, not the files: git replaces a ref by renaming <ref>.lock.
+    const dirs = [...new Set(files.map((file) => dirname(file)))];
+    for (const dir of dirs) {
+      try {
+        const watcher = watch(dir, { persistent: false }, (_event, name) => {
+          if (name && !files.includes(resolve(dir, String(name)))) return;
+          retarget();
+          notify();
+        });
+        watcher.on('error', () => {
+          watcher.close();
+          watchers = watchers.filter((w) => w !== watcher);
+          target = '';
+        });
+        watchers.push(watcher);
+      } catch {
+        // A chain directory that does not exist (an unborn target) is not watched.
+      }
+    }
+  };
+  return {
+    retarget,
+    dispose() {
+      clearTimeout(timer);
+      closeWatchers();
+      target = '';
+    },
+  };
+}

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

@@ -68,14 +68,19 @@ const READ_ONLY_FLAGS = ['--no-optional-locks', '-c', 'core.fsmonitor=false'];
 /**
  * @param {string} cwd
  * @param {string[]} args
- * @param {{ signal?: AbortSignal, timeoutMs?: number, maxBytes?: number, allowFailure?: boolean, readOnly?: boolean }} [options]
+ * @param {{ signal?: AbortSignal, timeoutMs?: number, maxBytes?: number, allowFailure?: boolean, readOnly?: boolean, env?: Record<string, string> }} [options]
+ *   `env`: variables set on top of the pinned environment (a temporary GIT_INDEX_FILE, a commit identity).
  * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
  */
-export async function runGit(cwd, args, { signal, timeoutMs, maxBytes, allowFailure = false, readOnly = false } = {}) {
+export async function runGit(
+  cwd,
+  args,
+  { signal, timeoutMs, maxBytes, allowFailure = false, readOnly = false, env = null } = {}
+) {
   throwIfAborted(signal);
   const result = await runGitOffThread([...(readOnly ? READ_ONLY_FLAGS : []), ...SCOPED_CONFIG, ...args], {
     cwd,
-    env: gitEnvironment(),
+    env: env ? { ...gitEnvironment(), ...env } : gitEnvironment(),
     timeoutMs: timeoutMs ?? DEFAULT_TIMEOUT_MS,
     maxBytes: maxBytes ?? DEFAULT_MAX_BYTES,
   });

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

@@ -88,7 +88,7 @@ export async function cleanupDeletedSessionWorktree(sessionId, { manager = null,
   try {
     return { entryId: entry.id, ...(await backend.removeManagedWorktree({ entryId: entry.id })) };
   } catch (error) {
-    if (isWorktreeError(error, 'WORKTREE_DIRTY') || isWorktreeError(error, 'WORKTREE_UNMERGED')) {
+    if (isWorktreeError(error, 'WORKTREE_DIRTY') || isWorktreeError(error, 'WORKTREE_UNMERGED') || isWorktreeError(error, 'WORKTREE_FILE_RECOVERY')) {
       return { entryId: entry.id, removed: false, reason: error.code };
     }
     throw error;

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

@@ -26,8 +26,9 @@
  * -d` forgets it).
  */
 import { existsSync } from 'node:fs';
+import { assertRecoveryStoresClear, recoveryScopes, retainedRecoveryScopes, validateRecoveryScope } from './file-recovery.mjs';
 import { lstat, mkdir, readdir, readFile, rm, rmdir } from 'node:fs/promises';
-import { dirname, join, relative, sep } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import {
   managedWorktreePath,
   managedWorktreeRoot,
@@ -37,6 +38,13 @@ import {
   worktreeBranchName,
   worktreeError,
 } from './contract.mjs';
+import {
+  assertCarryable,
+  carryUncommittedChanges,
+  dropRecoveryRef,
+  restoreFromRecoveryRef,
+  uncommittedChanges,
+} from './carry.mjs';
 import { freeBytesAt, requiredBytes, trackedCheckoutBytes } from './disk.mjs';
 import {
   branchCommit,
@@ -64,7 +72,7 @@ import { withRepoLock as withRepoMutationLock } from './lock.mjs';
 import { mergeBranchIntoCheckout } from './merge.mjs';
 import { readOwnerLease, removeOwnerLease, sameOwner, writeOwnerLease } from './owner.mjs';
 import { canonicalPath, checkoutFolder, isWithin, pathKey, projectSubdirOf, samePath } from './paths.mjs';
-import { deleteRecord, entryView, getRecord, insertRecord, putRecord, readRegistry } from './registry.mjs';
+import { deleteRecord, entryView, getRecord, insertRecord, putRecord, readRegistry, registryPath } from './registry.mjs';
 import { normalizeWorktreeSettings } from './settings.mjs';
 import { slugFromHint, uniqueSlug } from './slug.mjs';
 
@@ -74,6 +82,8 @@ const REMOVE_RETRY_DELAY_MS = 150;
 // The session copies the project identity into each managed worktree; it is
 // Mixdog metadata, not user data, so it alone never makes a worktree dirty.
 const SESSION_PROJECT_ID_PATH = '.mixdog/project.id';
+// Changed paths WORKTREE_DIRTY_CHOICE lists for the dialog's preview (the count is exact).
+const DIRTY_CHOICE_PREVIEW = 50;
 
 export { registerRootReleaser } from './contract.mjs';
 
@@ -327,6 +337,7 @@ async function deleteBranchIfFree(record) {
  * still present (empty when everything is gone).
  */
 async function removeCheckout(record) {
+  await assertRecoveryStoresClear(record);
   await assertManagedCheckoutPath(record);
   const remaining = [];
   for (const path of await removeIncludeLinks(record.resources?.includes)) remaining.push({ kind: 'link', path });
@@ -437,6 +448,7 @@ async function rollbackCreation(record, cause) {
  * and retried with the deletion; it never keeps the checkout.
  */
 async function finishDeletion(record) {
+  await assertRecoveryStoresClear(record);
   const remaining = [];
   try {
     await removeOwnerLease(record);
@@ -516,6 +528,46 @@ export async function findWorktreeContaining(path) {
   return record ? entryView(record) : null;
 }
 
+/** File-host seam, not a user capability. Persist the host-owned scope before
+ * preparing a byte journal, and hold the same repository lock as every removal
+ * through the operation. The descriptor survives daemon exit/startup reconcile.
+ * @template T
+ * @param {string} root
+ * @param {string} directory
+ * @param {'write'|'restore'|'inspect'|'discard'} action
+ * @param {() => Promise<T>} run
+ * @returns {Promise<T>}
+ */
+export async function withWorktreeRecoveryStore(root, directory, action, run) {
+  const entry = await findWorktreeContaining(root);
+  if (!entry) {
+    // A managed checkout can disappear between host authorization and this
+    // lookup. Its reserved namespace must never become an ordinary project.
+    // Retain a lexical check as well, so a replacement link cannot escape it.
+    const store = dirname(registryPath());
+    const lexicalKey = (path) => process.platform === 'win32' ? resolve(path).toLowerCase() : resolve(path);
+    const requested = lexicalKey(root);
+    if (isWithin(store, root) || [store, canonicalPath(store)].some((path) =>
+      requested === lexicalKey(path) || requested.startsWith(lexicalKey(path) + sep)))
+      throw worktreeError('WORKTREE_MISSING', undefined, { path: root });
+    return run();
+  }
+  return withRepoLock(entry.repoCommonDir, async () => {
+    const record = await getRecord(entry.id);
+    if (!record || ((action === 'write' || action === 'restore') && record.state !== 'ready'))
+      throw worktreeError('WORKTREE_MISSING', undefined, { entryId: entry.id });
+    const scope = validateRecoveryScope(record, { root, directory });
+    let scopes = recoveryScopes(record);
+    if (!scopes.some((item) => item.root === root && item.directory === directory)) {
+      if (scopes.length >= 64) scopes = await retainedRecoveryScopes(record);
+      if (scopes.length >= 64) throw worktreeError('WORKTREE_FILE_RECOVERY');
+      record.editorRecoveryStores = [...scopes, scope];
+      await putRecord(record);
+    }
+    return run();
+  });
+}
+
 /** Mark an entry disposable: startup reconcile may remove it once clean and merged. */
 export async function markWorktreeDisposable(entryId, disposable = true) {
   const record = await getRecord(entryId);
@@ -600,8 +652,20 @@ async function diskFullFailure(error, { needed, root }) {
 }
 
 /**
+ * `carryChanges` decides the project folder's uncommitted changes (tracked
+ * and untracked, ignored excluded), judged under the repository lock:
+ * omitted/null leaves them unexamined; `ask` refuses with
+ * WORKTREE_DIRTY_CHOICE (`details: { count, paths }`, paths capped) while
+ * there are any; `leave` keeps them in the project folder; `carry` moves
+ * them into the new worktree (carry.mjs: whole checkout, ignored files stay)
+ * — refused (WORKTREE_DIRTY) during a merge, rebase or cherry-pick, with
+ * unmerged entries, dirty submodules, filtered (LFS) paths or oversized
+ * untracked files. The result's `changes` (`{ mode: 'carried'|'left',
+ * count, recoveryRef? }`) reports what happened to them; a carried move's
+ * `recoveryRef` stays until dropCarryRecoveryRef / restoreCarriedChanges.
  * @param {{ projectPath: string, sessionId: string, runtimeToken: string, baseBranch?: string|null,
- *   nameHint?: string, confirmLarge?: boolean, txId: string, signal?: AbortSignal }} input
+ *   nameHint?: string, confirmLarge?: boolean, txId: string, signal?: AbortSignal,
+ *   carryChanges?: 'ask'|'leave'|'carry'|null }} input
  */
 export async function createManagedWorktree({
   projectPath,
@@ -612,9 +676,13 @@ export async function createManagedWorktree({
   confirmLarge = false,
   txId,
   signal,
+  carryChanges = null,
 } = {}) {
   requireText(projectPath, 'projectPath');
   requireText(txId, 'txId');
+  if (![null, 'ask', 'leave', 'carry'].includes(carryChanges)) {
+    throw new TypeError('carryChanges must be ask, leave or carry.');
+  }
   const owner = normalizeWorktreeOwner({ sessionId, runtimeToken, pid: process.pid });
   throwIfAborted(signal);
   const repo = await inspectRepo(projectPath, { signal });
@@ -623,6 +691,18 @@ export async function createManagedWorktree({
     if (existing) return existing;
     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 settings = await currentWorktreeSettings();
     let baseCommit = repo.headCommit;
     let mergeTarget = repo.currentBranch;
@@ -675,6 +755,7 @@ export async function createManagedWorktree({
         timeoutMs: WORKTREE_ADD_TIMEOUT_MS,
       });
     let record = await reserve();
+    let carried = null;
 
     try {
       await mkdir(root, { recursive: true });
@@ -708,16 +789,46 @@ export async function createManagedWorktree({
       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);
       record.warnings = [...record.warnings, ...applied.warnings];
       record.state = 'ready';
       await putRecord(record);
-      return entryView(record);
+      return { ...entryView(record), ...(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;
     }
 
@@ -758,6 +869,30 @@ export async function createManagedWorktree({
   });
 }
 
+/**
+ * After a carry whose session move failed: put the changes kept at
+ * `recoveryRef` back into the project folder (refused, ref kept, when the
+ * folder changed meanwhile). The ref stays; drop it with dropCarryRecoveryRef.
+ * @param {{ projectPath: string, recoveryRef: string }} input
+ */
+export async function restoreCarriedChanges({ projectPath, recoveryRef } = {}) {
+  requireText(projectPath, 'projectPath');
+  const repo = await inspectRepo(projectPath);
+  return withRepoLock(repo.repoCommonDir, () =>
+    restoreFromRecoveryRef(repo.topLevel, projectSubdirOf(repo.topLevel, repo.projectPath), recoveryRef)
+  );
+}
+
+/**
+ * Forget a carry's recovery ref once the session move it protected is committed.
+ * @param {{ projectPath: string, recoveryRef: string }} input
+ */
+export async function dropCarryRecoveryRef({ projectPath, recoveryRef } = {}) {
+  requireText(projectPath, 'projectPath');
+  const repo = await inspectRepo(projectPath);
+  return withRepoLock(repo.repoCommonDir, () => dropRecoveryRef(repo.topLevel, recoveryRef));
+}
+
 /**
  * Claim the live lease of a retained worktree for one runtime of its session.
  * @param {string} entryId
@@ -1054,12 +1189,14 @@ async function assertRemovable(record) {
 /**
  * The refusal removeManagedWorktree would raise, checked before anything
  * moves (a session leaves its worktree only for a removal that can proceed).
- * Unknown entries are WORKTREE_MISSING; `force` and non-ready entries pass.
+ * Unknown entries are WORKTREE_MISSING. Recovery records block even `force`
+ * and non-ready entries; ordinary dirty/unmerged checks apply only to ready ones.
  * @param {{ entryId: string, force?: boolean }} input
  */
 export async function assertWorktreeRemovable({ entryId, force = false } = {}) {
   const record = await getRecord(entryId);
   if (!record) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
+  await assertRecoveryStoresClear(record);
   if (record.state !== 'ready') return;
   await assertManagedCheckoutPath(record);
   if (!force) await assertRemovable(record);
@@ -1067,7 +1204,8 @@ export async function assertWorktreeRemovable({ entryId, force = false } = {}) {
 
 /**
  * Remove a managed worktree. Refuses dirty (incl. untracked and modified
- * include copies) or unmerged worktrees unless `force`.
+ * include copies) or unmerged worktrees unless `force`. Retained file recovery
+ * data blocks removal regardless of force.
  * @param {{ entryId: string, force?: boolean }} input
  * @returns {Promise<{ removed: boolean, retryable?: boolean, remaining?: object[], branchDeleted?: boolean }>}
  */
@@ -1082,6 +1220,7 @@ export async function removeManagedWorktree({ entryId, force = false } = {}) {
       return rollback.complete ? { removed: true } : { removed: false, retryable: true, remaining: rollback.remaining };
     }
     if (current.state === 'ready') {
+      await assertRecoveryStoresClear(current);
       await assertManagedCheckoutPath(current);
       if (!force) await assertRemovable(current);
       current.state = 'deleting';
@@ -1101,7 +1240,7 @@ function leaseProcessAlive(lease) {
  * Every managed worktree with who keeps it: `retained` (its session is in
  * `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).
+ * would remove: neither, or disposable and not live, with no retained recovery data).
  * @param {{ liveSessionIds?: string[], retainedSessionIds?: string[] }} input
  */
 export async function listManagedWorktrees({ liveSessionIds = [], retainedSessionIds = [] } = {}) {
@@ -1112,12 +1251,20 @@ export async function listManagedWorktrees({ liveSessionIds = [], retainedSessio
     const ownerLive =
       (!!record.ownerSessionId && live.has(record.ownerSessionId)) || leaseProcessAlive(await readOwnerLease(record));
     const isRetained = !!record.ownerSessionId && retained.has(record.ownerSessionId);
+    let removable = record.state !== 'ready' || (!ownerLive && (record.disposable === true || !isRetained));
+    if (removable) {
+      try { await assertRecoveryStoresClear(record); }
+      catch (error) {
+        if (error?.code !== 'WORKTREE_FILE_RECOVERY') throw error;
+        removable = false;
+      }
+    }
     rows.push({
       ...entryView(record),
       projectPath: record.projectPath,
       retained: isRetained,
       ownerLive,
-      removable: record.state !== 'ready' || (!ownerLive && (record.disposable === true || !isRetained)),
+      removable,
     });
   }
   return rows;
@@ -1194,6 +1341,7 @@ export async function reconcileManagedWorktrees({
                 report.kept.push({ id: record.id, reason: dirty.length ? 'dirty' : 'unmerged' });
                 continue;
               }
+              await assertRecoveryStoresClear(record);
               record.state = 'deleting';
               record.deleting = { force: false, startedAt: Date.now(), remaining: [] };
               await putRecord(record);