mixdog 1.1.1 → 1.2.0

package/src/session-runtime/workspace/admission-gate.mjs

@@ -0,0 +1,197 @@
+/**
+ * Process-wide admission gate shared by Lead workspace transitions, turn
+ * admission and worker spawning.
+ *
+ * - A transition and a worker spawn of the same Lead never overlap: a
+ *   transition refuses while a spawn is being prepared, a spawn refuses while
+ *   a transition is in flight.
+ * - Turns and transitions are mutually exclusive: an admitted turn is
+ *   registered until it settles; a turn that arrives while its own session
+ *   transitions, or while another session changes the checkout its cwd lies
+ *   in (a held checkout folder), waits for that change to settle. A checkout
+ *   folder can only be held while no other session's admitted turn runs in it.
+ * - Each worktree-bound Lead's execution root, which every worker of that Lead
+ *   runs in.
+ */
+import { worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
+import { isWithin } from '../../runtime/shared/worktrees/paths.mjs';
+
+/** @type {Map<string, { txId: string, settled: Promise<void> }>} Lead session id → in-flight transition. */
+const transitions = new Map();
+/** @type {Map<string, number>} Lead session id → spawns being prepared. */
+const spawns = new Map();
+/** @type {Map<string, string>} Lead session id → bound worktree execution root. */
+const cwdLocks = new Map();
+/** @type {Map<symbol, { sessionId: string, cwd: () => string }>} Admitted turns (live cwd). */
+const turns = new Map();
+/** @type {Map<symbol, { sessionId: string, folder: string, settled: Promise<void> }>} Checkouts being changed. */
+const folderHolds = new Map();
+
+const key = (sessionId) => String(sessionId || '').trim();
+
+function latch() {
+  let resolve;
+  const settled = new Promise((done) => {
+    resolve = done;
+  });
+  return { settled, resolve };
+}
+
+function once(fn) {
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    fn();
+  };
+}
+
+const within = (folder, cwd) => Boolean(folder && cwd) && isWithin(folder, cwd);
+
+/**
+ * Enter a transition for `sessionId`; the returned function leaves it.
+ * @returns {() => void}
+ */
+export function beginWorkspaceTransition(sessionId, txId) {
+  const id = key(sessionId);
+  if (!id) throw new TypeError('workspace transition requires a session id.');
+  if (transitions.has(id)) {
+    throw worktreeError('WORKTREE_BUSY_JOBS', 'Another workspace change is in progress for this session.', {
+      reason: 'transition',
+    });
+  }
+  if ((spawns.get(id) || 0) > 0) {
+    throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'workers', starting: spawns.get(id) });
+  }
+  const gate = latch();
+  transitions.set(id, { txId: String(txId || 'tx'), settled: gate.settled });
+  return once(() => {
+    transitions.delete(id);
+    gate.resolve();
+  });
+}
+
+/**
+ * Hold `folder` (a checkout root) while its branch changes or a merge lands
+ * in it. Refuses (WORKTREE_BUSY_JOBS, `folder-in-use`) while another session's
+ * admitted turn runs inside it, and (`transition`) while another change holds
+ * an overlapping checkout; turns arriving meanwhile wait (admitTurn). The
+ * holder's own turns are its own business (the Lead busy check).
+ * @param {string|null} sessionId The changing session; '' / null for a session-less change.
+ * @returns {() => void} Release.
+ */
+export function holdCheckoutFolder(sessionId, folder) {
+  const id = key(sessionId);
+  const users = new Set();
+  for (const turn of turns.values()) {
+    if (turn.sessionId !== id && within(folder, turn.cwd())) users.add(turn.sessionId);
+  }
+  if (users.size) {
+    throw worktreeError('WORKTREE_BUSY_JOBS', 'Other sessions are working in the project folder.', {
+      reason: 'folder-in-use',
+      sessions: [...users],
+    });
+  }
+  if ([...folderHolds.values()].some((hold) => within(hold.folder, folder) || within(folder, hold.folder))) {
+    throw worktreeError('WORKTREE_BUSY_JOBS', 'Another branch change is in progress in the project folder.', {
+      reason: 'transition',
+    });
+  }
+  const token = Symbol('checkout-folder');
+  const gate = latch();
+  folderHolds.set(token, { sessionId: id, folder, settled: gate.settled });
+  return once(() => {
+    folderHolds.delete(token);
+    gate.resolve();
+  });
+}
+
+function admissionBlocker(id, cwd) {
+  const own = transitions.get(id);
+  if (own) return own.settled;
+  const path = cwd();
+  for (const hold of folderHolds.values()) {
+    if (hold.sessionId !== id && within(hold.folder, path)) return hold.settled;
+  }
+  return null;
+}
+
+function settledOrAborted(promise, signal) {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      try {
+        throwIfAborted(signal);
+      } catch (error) {
+        reject(error);
+      }
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(() => {
+      signal.removeEventListener('abort', abort);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Admit one turn of `sessionId`, whose live cwd is `cwd()`: waits while the
+ * session itself transitions or another session holds the checkout the cwd
+ * lies in, then registers the turn until the returned release is called.
+ * An abort while waiting rejects and registers nothing.
+ * @param {{ sessionId: string, cwd: () => string, signal?: AbortSignal }} input
+ * @returns {Promise<() => void>}
+ */
+export async function admitTurn({ sessionId, cwd, signal }) {
+  const id = key(sessionId);
+  for (let blocker = admissionBlocker(id, cwd); blocker; blocker = admissionBlocker(id, cwd)) {
+    throwIfAborted(signal);
+    await settledOrAborted(blocker, signal);
+  }
+  throwIfAborted(signal);
+  const token = Symbol('turn');
+  turns.set(token, { sessionId: id, cwd });
+  return once(() => turns.delete(token));
+}
+
+/**
+ * Admit one worker spawn preparation for the Lead(s) in `sessionIds`.
+ * @param {Array<string|null|undefined>} sessionIds Owner and caller session ids.
+ * @returns {() => void}
+ */
+export function enterWorkerSpawn(sessionIds) {
+  const ids = [...new Set(sessionIds.map(key).filter(Boolean))];
+  if (ids.some((id) => transitions.has(id))) {
+    throw worktreeError('WORKTREE_BUSY_JOBS', 'The Lead workspace is changing; spawn the worker after it settles.', {
+      reason: 'transition',
+    });
+  }
+  for (const id of ids) spawns.set(id, (spawns.get(id) || 0) + 1);
+  let left = false;
+  return () => {
+    if (left) return;
+    left = true;
+    for (const id of ids) {
+      const next = (spawns.get(id) || 1) - 1;
+      if (next > 0) spawns.set(id, next);
+      else spawns.delete(id);
+    }
+  };
+}
+
+/** Record (or clear with null) the worktree root a Lead's workers must run in. */
+export function setWorkspaceCwdLock(sessionId, cwd) {
+  const id = key(sessionId);
+  if (!id) return;
+  if (cwd) cwdLocks.set(id, String(cwd));
+  else cwdLocks.delete(id);
+}
+
+/** The locked worker cwd for the first Lead id that has one, or null. */
+export function workspaceCwdLock(sessionIds) {
+  for (const id of sessionIds.map(key)) {
+    if (id && cwdLocks.has(id)) return cwdLocks.get(id);
+  }
+  return null;
+}

package/src/session-runtime/workspace/project-branches.mjs

@@ -0,0 +1,136 @@
+/**
+ * Session-less branch operations on a registered Project's folder (a New
+ * Task draft, the source-control dock): its branch menu, a guarded checkout
+ * and a guarded merge. They act only on a registered Project (a repository
+ * subfolder Project included) and hold the checkout (withProjectFolder) while
+ * git changes it.
+ */
+import { branchMenuEntries, projectWorkspace, worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+
+function requireText(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+
+/**
+ * WORKTREE_UNSUPPORTED_REPO when the project folder has no checked-out branch
+ * to merge into; WORKTREE_TARGET_MISMATCH when the confirmed `target` (null:
+ * none confirmed) is no longer the checked-out branch.
+ */
+export function assertMergeTarget(currentBranch, target) {
+  if (!currentBranch) {
+    throw worktreeError('WORKTREE_UNSUPPORTED_REPO', 'The project folder has no checked-out branch to merge into.');
+  }
+  if (target !== null && target !== currentBranch) {
+    throw worktreeError(
+      'WORKTREE_TARGET_MISMATCH',
+      `The project folder is now on "${currentBranch}"; confirm the merge again.`,
+      { target, current: currentBranch }
+    );
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {() => Promise<any>} deps.backend The managed-worktree backend.
+ * @param {(path: string) => Promise<any>} deps.inspectProject
+ * @param {(path: string) => Promise<string|null>} deps.findRegisteredProject
+ * @param {<T>(sessionId: string|null, folder: string, fn: () => Promise<T>) => Promise<T>} deps.withProjectFolder
+ */
+export function createProjectBranchOps({ backend, inspectProject, findRegisteredProject, withProjectFolder }) {
+  /** WORKTREE_PROJECT_UNKNOWN unless `projectPath` is a registered Project. */
+  async function registeredProject(projectPath) {
+    const path = requireText(projectPath, 'projectPath');
+    const registered = await findRegisteredProject(path);
+    if (!registered) throw worktreeError('WORKTREE_PROJECT_UNKNOWN', undefined, { projectPath: path });
+    return registered;
+  }
+
+  /**
+   * A Project's branch menu with no session: the project folder's workspace
+   * and the real occupancy (current / session / external / free).
+   */
+  async function getProjectBranchMenu({ projectPath } = {}) {
+    const path = await registeredProject(projectPath);
+    const project = await inspectProject(path);
+    const menu = await (await backend()).listBranchOccupancy({ projectPath: path, sessionId: null });
+    return {
+      workspace: projectWorkspace({
+        projectPath: path,
+        repoCommonDir: project.repoCommonDir,
+        branch: project.currentBranch,
+      }),
+      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      occupancy: menu.occupancy,
+      retainedWorktree: null,
+    };
+  }
+
+  /**
+   * Check out (or create) `branch` in a Project folder with no session: the
+   * same guarded path a session's branch change takes — refused while another
+   * session works in the checkout, which is held until the switch is done;
+   * the manager's repository lock, occupancy and no-carry (dirty) checks.
+   */
+  async function selectProjectBranch({
+    projectPath,
+    branch,
+    create = false,
+    remote = false,
+    startPoint = null,
+    detach = null,
+  } = {}) {
+    const path = await registeredProject(projectPath);
+    if (detach !== null) {
+      // A history entry checked out detached: the same guard, no branch.
+      if (branch !== undefined || create === true || remote === true || startPoint !== null) {
+        throw new TypeError('detach excludes branch, create, remote and startPoint.');
+      }
+      const commit = requireText(detach, 'detach');
+      const project = await inspectProject(path);
+      return withProjectFolder(null, project.topLevel || path, async () =>
+        (await backend()).checkoutProjectBranch({ projectPath: path, detach: commit })
+      );
+    }
+    const name = requireText(branch, 'branch');
+    if (create === true && remote === true) throw new TypeError('create and remote are exclusive.');
+    if (startPoint !== null && create !== true) throw new TypeError('startPoint needs create.');
+    const project = await inspectProject(path);
+    if (create !== true && remote !== true && project.currentBranch === name) return { branch: name, changed: false };
+    return withProjectFolder(null, project.topLevel || path, async () => {
+      const backendApi = await backend();
+      return backendApi.checkoutProjectBranch({
+        projectPath: path,
+        branch: name,
+        create: create === true,
+        remote: remote === true,
+        ...(startPoint !== null ? { startPoint: requireText(startPoint, 'startPoint') } : {}),
+      });
+    });
+  }
+
+  /**
+   * Merge a local branch into a Project folder's checked-out branch with no
+   * session: `target` is the branch the user confirmed and must still be
+   * checked out (WORKTREE_TARGET_MISMATCH); refused while another session
+   * works in that checkout, which is held (turn admission waits) until the
+   * merge is done.
+   */
+  async function mergeProjectBranch({ projectPath, branch, target } = {}) {
+    const path = await registeredProject(projectPath);
+    const source = requireText(branch, 'branch');
+    const confirmedTarget = requireText(target, 'target');
+    const project = await inspectProject(path);
+    assertMergeTarget(project.currentBranch, confirmedTarget);
+    return withProjectFolder(null, project.topLevel || path, async () =>
+      (await backend()).mergeBranchIntoProject({
+        projectPath: path,
+        source,
+        target: confirmedTarget,
+        confirmed: true,
+      })
+    );
+  }
+
+  return { getProjectBranchMenu, selectProjectBranch, mergeProjectBranch };
+}

package/src/session-runtime/workspace/transition-steps.mjs

@@ -0,0 +1,364 @@
+/**
+ * The steps of one Lead workspace transaction (transitions.mjs runs them
+ * serialized): commit a new workspace, enter the retained or a new worktree,
+ * move to a project-folder branch, remove the retained worktree. Every step
+ * pushes the exact undo of what it changed onto the transaction `journal`;
+ * the caller runs it (undoAll) when the transaction fails.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import {
+  isWorktreeBound,
+  isWorktreeError,
+  nextRevision,
+  normalizeSessionWorkspace,
+  worktreeError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
+import { checkoutFolder, projectSubdirOf, samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { setWorkspaceCwdLock, workspaceCwdLock } from './admission-gate.mjs';
+import { copyProjectIdentity } from './workspace-state.mjs';
+
+const PROMPT_FIELDS = ['bp3EnvironmentContext', 'bp3CoreContext', 'sessionStartMetaInjected'];
+
+/** Everything a prompt refresh rewrites on `target`, restorable exactly. */
+function snapshotPrompt(target) {
+  const fields = PROMPT_FIELDS.map((name) => [name, Object.hasOwn(target, name), target[name]]);
+  const messages = Array.isArray(target.messages) ? [...target.messages] : null;
+  return () => {
+    for (const [name, had, value] of fields) {
+      if (had) target[name] = value;
+      else delete target[name];
+    }
+    if (!messages) return;
+    if (Array.isArray(target.messages)) target.messages.splice(0, target.messages.length, ...messages);
+    else target.messages = messages;
+  };
+}
+
+/** Run a failed transaction's undo steps newest first; every step runs. */
+export async function undoAll(journal, error) {
+  const failures = [];
+  for (const undo of journal.reverse()) {
+    try {
+      await undo();
+    } catch (cause) {
+      failures.push(cause);
+    }
+  }
+  if (failures.length && error && typeof error === 'object') error.rollbackErrors = failures;
+}
+
+/**
+ * WORKTREE_PROJECT_MISMATCH unless the retained `entry` was created for the
+ * same repository and the same Project folder inside it (a Project switch may
+ * have left it behind).
+ */
+export function assertRetainedFits(entry, project, projectPath) {
+  const subdir = projectSubdirOf(project.topLevel, project.projectPath || projectPath);
+  if (samePath(entry.repoCommonDir, project.repoCommonDir) && (entry.projectSubdir || '') === subdir) return;
+  throw worktreeError('WORKTREE_PROJECT_MISMATCH', undefined, {
+    worktreeId: entry.id,
+    worktreeProject: entry.projectPath,
+    projectPath,
+  });
+}
+
+/**
+ * WORKTREE_REMOVAL_INCOMPLETE: the deletion started (the record stays
+ * `deleting`) but something in the folder is still held. The session keeps
+ * the project folder — never a cwd that may already be deleted — and
+ * removeWorktree again resumes the deletion.
+ */
+function incompleteRemoval(journal, entry, result, outcome) {
+  journal.length = 0;
+  return worktreeError('WORKTREE_REMOVAL_INCOMPLETE', undefined, {
+    entryId: entry.id,
+    path: entry.path,
+    retryable: outcome?.retryable !== false,
+    remaining: Array.isArray(outcome?.remaining) ? outcome.remaining : [],
+    ...(outcome?.reason ? { reason: outcome.reason } : {}),
+    revision: result.revision,
+  });
+}
+
+/**
+ * @param {object} deps The host hooks of createWorkspaceTransitions plus its
+ *   `backend()` loader, `workersOf(session)` and `withProjectFolder`.
+ */
+export function createTransitionSteps({
+  backend,
+  inspectProject,
+  runtimeToken,
+  getCurrentCwd,
+  applyResolvedCwd,
+  persistSession,
+  refreshWorkspaceContext,
+  invalidateCaches,
+  updateLeadWorkerCwd,
+  workersOf,
+  withProjectFolder,
+}) {
+  const owner = (sessionId) => ({ sessionId, runtimeToken, pid: process.pid });
+
+  /** Point this Lead's idle workers at the new root so a reused worker never keeps an old workspace. */
+  async function retargetWorkers(session, cwd, journal) {
+    for (const worker of workersOf(session)) {
+      if (samePath(worker.cwd || '', cwd)) continue;
+      const priorCwd = worker.cwd;
+      const restorePrompt = snapshotPrompt(worker);
+      journal.push(() => {
+        worker.cwd = priorCwd;
+        restorePrompt();
+        worker.updatedAt = Date.now();
+        persistSession(worker);
+      });
+      worker.cwd = cwd;
+      await refreshWorkspaceContext(worker, cwd);
+      worker.updatedAt = Date.now();
+      persistSession(worker);
+    }
+  }
+
+  /**
+   * Apply the new workspace: runtime cwd, record, worker lock, prompt context
+   * of the Lead and its idle workers, persistence. Journals the exact undo
+   * (cwd, record, lock, prompts, worker roots) for a transaction that fails
+   * after this point.
+   */
+  async function commit(session, previous, fields, journal) {
+    const moveLeadRow = (cwd) => {
+      try {
+        updateLeadWorkerCwd(session.id, cwd);
+      } catch {
+        /* the Lead pool must never break a transition */
+      }
+    };
+    const next = normalizeSessionWorkspace({
+      ...fields,
+      revision: nextRevision(previous),
+      transition: { state: 'idle', txId: null },
+    });
+    const prior = {
+      cwd: getCurrentCwd(),
+      sessionCwd: session.cwd,
+      workspace: session.workspace,
+      lock: workspaceCwdLock([session.id]),
+      prompt: snapshotPrompt(session),
+    };
+    journal.push(() => {
+      applyResolvedCwd(prior.cwd);
+      session.cwd = prior.sessionCwd;
+      session.workspace = prior.workspace;
+      setWorkspaceCwdLock(session.id, prior.lock);
+      prior.prompt();
+      session.updatedAt = Date.now();
+      persistSession(session);
+      moveLeadRow(prior.sessionCwd || prior.cwd);
+      invalidateCaches();
+    });
+    applyResolvedCwd(next.cwd);
+    session.cwd = next.cwd;
+    session.workspace = next;
+    moveLeadRow(next.cwd);
+    setWorkspaceCwdLock(session.id, isWorktreeBound(next) ? next.cwd : null);
+    await refreshWorkspaceContext(session, next.cwd);
+    await retargetWorkers(session, next.cwd, journal);
+    session.updatedAt = Date.now();
+    persistSession(session);
+    invalidateCaches();
+    return { revision: next.revision, workspace: next };
+  }
+
+  async function releaseOwner(backendApi, entryId, sessionId) {
+    try {
+      await backendApi.releaseWorktreeOwner(entryId, owner(sessionId));
+    } catch (error) {
+      // A worktree that vanished has no owner left to release.
+      if (!isWorktreeError(error, 'WORKTREE_MISSING')) throw error;
+    }
+  }
+
+  async function enterWorktree(session, previous, { name, nameHint, confirmLarge, signal, txId, journal }) {
+    const backendApi = await backend();
+    const projectPath = previous.projectPath;
+    const project = await inspectProject(projectPath, { signal });
+    let entry = await backendApi.getSessionWorktree(session.id);
+    if (entry) {
+      if (!existsSync(entry.path)) {
+        throw worktreeError('WORKTREE_MISSING', undefined, { worktreeId: entry.id, path: entry.path });
+      }
+      if (isWorktreeBound(previous) && previous.worktreeId === entry.id) {
+        return { revision: previous.revision, workspace: previous };
+      }
+      assertRetainedFits(entry, project, projectPath);
+      await backendApi.claimWorktreeOwner(entry.id, owner(session.id));
+      journal.push(() => releaseOwner(backendApi, entry.id, session.id));
+    } else {
+      // The backend resolves the base branch commit (from the project
+      // folder's checked-out branch), sizes and creates the checkout; the
+      // txId makes a retried or duplicate send return the same worktree.
+      entry = await backendApi.createManagedWorktree({
+        projectPath,
+        sessionId: session.id,
+        runtimeToken,
+        baseBranch: project.currentBranch,
+        nameHint: name ?? nameHint ?? '',
+        confirmLarge: confirmLarge === true,
+        txId,
+        signal,
+      });
+    }
+    // Cancelled after the worktree exists: it stays retained (same txId on
+    // retry), the session does not move.
+    throwIfAborted(signal);
+    // A Project registered below the repository root runs in the same
+    // subfolder of the worktree (and returns to its own folder on the way back).
+    const cwd = checkoutFolder(entry.path, projectSubdirOf(project.topLevel, project.projectPath || projectPath));
+    if (!existsSync(cwd)) mkdirSync(cwd, { recursive: true });
+    copyProjectIdentity(projectPath, cwd);
+    const entered = await commit(
+      session,
+      previous,
+      {
+        projectPath,
+        repoCommonDir: entry.repoCommonDir || project.repoCommonDir,
+        cwd,
+        worktreeId: entry.id,
+        branch: entry.branch,
+        baseCommit: entry.baseCommit,
+        mergeTarget: project.currentBranch,
+      },
+      journal
+    );
+    // Creation notes (submodules, include entries missing or already present).
+    return { ...entered, warnings: Array.isArray(entry.warnings) ? [...entry.warnings] : [] };
+  }
+
+  async function enterProjectBranch(session, previous, { branch, create, signal, journal }) {
+    const backendApi = await backend();
+    const projectPath = previous.projectPath;
+    const project = await inspectProject(projectPath, { signal });
+    const bound = isWorktreeBound(previous);
+    const finalize = async () => {
+      const result = await commit(
+        session,
+        previous,
+        { projectPath, repoCommonDir: project.repoCommonDir, cwd: projectPath, branch },
+        journal
+      );
+      if (bound) await releaseOwner(backendApi, previous.worktreeId, session.id);
+      return result;
+    };
+    if (create !== true && project.currentBranch === branch) {
+      if (!bound && previous.branch === branch && samePath(previous.cwd, projectPath)) {
+        return { revision: previous.revision, workspace: previous };
+      }
+      return finalize();
+    }
+    // The checkout stays held until the session is finalized on it, or put
+    // back: no other session's turn starts on a half-switched folder.
+    return withProjectFolder(session.id, project.topLevel || projectPath, async () => {
+      await backendApi.checkoutProjectBranch({ projectPath, branch, create: create === true });
+      try {
+        return await finalize();
+      } catch (error) {
+        await undoAll(journal, error);
+        journal.length = 0;
+        const context = { backendApi, projectPath, project, branch, bound, error };
+        throw await revertProjectCheckout(session, previous, context);
+      }
+    });
+  }
+
+  /**
+   * A branch switch whose finalization failed after git switched: switch the
+   * project folder back when that is safe (the manager refuses a dirty tree
+   * or a vanished branch) and rethrow the cause. Otherwise the session record
+   * is made to match the real checkout and the failure becomes
+   * WORKTREE_PARTIAL_TRANSITION naming the branch actually checked out.
+   */
+  async function revertProjectCheckout(session, previous, context) {
+    const { backendApi, projectPath, project, branch, bound, error } = context;
+    const previousBranch = project.currentBranch;
+    let revertError = null;
+    if (previousBranch) {
+      try {
+        await backendApi.checkoutProjectBranch({ projectPath, branch: previousBranch });
+        return error;
+      } catch (cause) {
+        revertError = cause;
+      }
+    }
+    if (!bound) {
+      // The session runs in the project folder, which is now on `branch`.
+      session.workspace = normalizeSessionWorkspace({
+        ...previous,
+        repoCommonDir: project.repoCommonDir,
+        branch,
+        revision: nextRevision(previous),
+        transition: { state: 'idle', txId: null },
+      });
+      session.updatedAt = Date.now();
+      persistSession(session);
+      invalidateCaches();
+    }
+    return worktreeError(
+      'WORKTREE_PARTIAL_TRANSITION',
+      `The branch change failed (${error?.message || error}) and the project folder could not be switched back` +
+        `${previousBranch ? ` to "${previousBranch}"` : ''}; it is now on "${branch}".`,
+      {
+        checkout: branch,
+        previousBranch: previousBranch ?? null,
+        reason: String(error?.message || error),
+        revertReason: revertError ? String(revertError.message || revertError) : 'detached',
+      }
+    );
+  }
+
+  /**
+   * Validate the removal first (a dirty or unmerged worktree without `force`
+   * refuses with the session untouched), then return the session to its
+   * project folder, release the live lease and remove. A removal that still
+   * fails puts the session back exactly (the transaction journal).
+   */
+  async function removeRetainedWorktree(session, previous, { force, signal, journal }) {
+    const backendApi = await backend();
+    const entry = await backendApi.getSessionWorktree(session.id);
+    if (entry) await backendApi.assertWorktreeRemovable({ entryId: entry.id, force: force === true });
+    let result = { revision: previous.revision, workspace: previous };
+    if (isWorktreeBound(previous)) {
+      const project = await inspectProject(previous.projectPath, { signal });
+      result = await commit(
+        session,
+        previous,
+        {
+          projectPath: previous.projectPath,
+          repoCommonDir: project.repoCommonDir,
+          cwd: previous.projectPath,
+          branch: project.currentBranch,
+        },
+        journal
+      );
+      if (entry) {
+        await releaseOwner(backendApi, entry.id, session.id);
+        journal.push(() => backendApi.claimWorktreeOwner(entry.id, owner(session.id)));
+      }
+    }
+    if (!entry) return { ...result, removed: null };
+    let removed;
+    try {
+      removed = await backendApi.removeManagedWorktree({ entryId: entry.id, force: force === true });
+    } catch (error) {
+      // Refused before anything was deleted: the journal puts the session back.
+      // Once the checkout may be (partly) gone, the session stays in the
+      // project folder and the removal is reported incomplete.
+      const now = await backendApi.getSessionWorktree(session.id).catch(() => entry);
+      if (now?.id === entry.id && now.state === 'ready' && existsSync(entry.path)) throw error;
+      throw incompleteRemoval(journal, entry, result, { reason: String(error?.message || error) });
+    }
+    if (removed?.removed !== true) throw incompleteRemoval(journal, entry, result, removed);
+    return { ...result, removed };
+  }
+
+  return { enterWorktree, enterProjectBranch, removeRetainedWorktree };
+}