mixdog 1.2.2 → 1.2.3

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

@@ -54,12 +54,14 @@ export function createProjectBranchOps({ backend, inspectProject, findRegistered
     const path = await registeredProject(projectPath);
     const project = await inspectProject(path);
     const menu = await (await backend()).listBranchOccupancy({ projectPath: path, sessionId: null });
+    const workspace = projectWorkspace({
+      projectPath: path,
+      repoCommonDir: project.repoCommonDir,
+      branch: project.currentBranch,
+    });
     return {
-      workspace: projectWorkspace({
-        projectPath: path,
-        repoCommonDir: project.repoCommonDir,
-        branch: project.currentBranch,
-      }),
+      // Detached: branch null and the checked-out commit in baseCommit.
+      workspace: project.currentBranch ? workspace : { ...workspace, baseCommit: project.headCommit ?? null },
       branches: branchMenuEntries(menu.branches, menu.occupancy),
       occupancy: menu.occupancy,
       retainedWorktree: null,

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

@@ -18,7 +18,9 @@ import { checkoutFolder, projectSubdirOf, samePath } from '../../runtime/shared/
 import { setWorkspaceCwdLock, workspaceCwdLock } from './admission-gate.mjs';
 import { copyProjectIdentity } from './workspace-state.mjs';
 
-const PROMPT_FIELDS = ['bp3EnvironmentContext', 'bp3CoreContext', 'sessionStartMetaInjected'];
+// workspaceReroot: the staged working-folder change and its pending notice
+// (prompt-utils stageWorkspaceReroot); a rollback drops the notice with it.
+const PROMPT_FIELDS = ['bp3EnvironmentContext', 'bp3CoreContext', 'sessionStartMetaInjected', 'workspaceReroot'];
 
 /** Everything a prompt refresh rewrites on `target`, restorable exactly. */
 function snapshotPrompt(target) {
@@ -90,6 +92,8 @@ export function createTransitionSteps({
   inspectProject,
   runtimeToken,
   getCurrentCwd,
+  getDesktopSession,
+  setDesktopSession,
   applyResolvedCwd,
   persistSession,
   refreshWorkspaceContext,
@@ -97,11 +101,19 @@ export function createTransitionSteps({
   updateLeadWorkerCwd,
   workersOf,
   withProjectFolder,
+  assertCheckoutQuiet = async () => {},
 }) {
   const owner = (sessionId) => ({ sessionId, runtimeToken, pid: process.pid });
+  const moveLeadRow = (sessionId, cwd) => {
+    try {
+      updateLeadWorkerCwd(sessionId, cwd);
+    } catch {
+      /* the Lead pool must never break a transition */
+    }
+  };
 
   /** 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) {
+  async function retargetWorkers(session, cwd, journal, move = null) {
     for (const worker of workersOf(session)) {
       if (samePath(worker.cwd || '', cwd)) continue;
       const priorCwd = worker.cwd;
@@ -113,7 +125,7 @@ export function createTransitionSteps({
         persistSession(worker);
       });
       worker.cwd = cwd;
-      await refreshWorkspaceContext(worker, cwd);
+      await refreshWorkspaceContext(worker, cwd, move);
       worker.updatedAt = Date.now();
       persistSession(worker);
     }
@@ -123,16 +135,10 @@ export function createTransitionSteps({
    * 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.
+   * after this point. `move` ({ from, changes }: a move out of the project
+   * folder into a worktree) extends the prompt's working-folder notice.
    */
-  async function commit(session, previous, fields, journal) {
-    const moveLeadRow = (cwd) => {
-      try {
-        updateLeadWorkerCwd(session.id, cwd);
-      } catch {
-        /* the Lead pool must never break a transition */
-      }
-    };
+  async function commit(session, previous, fields, journal, move = null) {
     const next = normalizeSessionWorkspace({
       ...fields,
       revision: nextRevision(previous),
@@ -153,22 +159,70 @@ export function createTransitionSteps({
       prior.prompt();
       session.updatedAt = Date.now();
       persistSession(session);
-      moveLeadRow(prior.sessionCwd || prior.cwd);
+      moveLeadRow(session.id, prior.sessionCwd || prior.cwd);
       invalidateCaches();
     });
     applyResolvedCwd(next.cwd);
     session.cwd = next.cwd;
     session.workspace = next;
-    moveLeadRow(next.cwd);
+    moveLeadRow(session.id, next.cwd);
     setWorkspaceCwdLock(session.id, isWorktreeBound(next) ? next.cwd : null);
-    await refreshWorkspaceContext(session, next.cwd);
-    await retargetWorkers(session, next.cwd, journal);
+    await refreshWorkspaceContext(session, next.cwd, move);
+    await retargetWorkers(session, next.cwd, journal, move);
     session.updatedAt = Date.now();
-    persistSession(session);
+    // Awaited: a failed save fails the transaction (and its journal undoes it).
+    await persistSession(session);
     invalidateCaches();
     return { revision: next.revision, workspace: next };
   }
 
+  /**
+   * A Project switch (session set-project, the desktop/remote setCwd): the
+   * runtime cwd, session.cwd, workspace record and desktop classification
+   * move together (applyResolvedCwd with persistProjectSelection), then the
+   * prompt context of the Lead and its idle workers follows, awaited, before
+   * the switch completes. Journals the exact undo, so a failed refresh puts
+   * everything back and the failure reaches the caller.
+   */
+  async function switchProject(session, cwd, journal, { classifyByMembership = false } = {}) {
+    const sessionFields = ['cwd', 'workspace', 'desktopSession'].map((name) => [
+      name,
+      Object.hasOwn(session, name),
+      session[name],
+    ]);
+    const prior = {
+      cwd: getCurrentCwd(),
+      desktop: getDesktopSession(),
+      lock: workspaceCwdLock([session.id]),
+      prompt: snapshotPrompt(session),
+    };
+    journal.push(() => {
+      applyResolvedCwd(prior.cwd);
+      for (const [name, had, value] of sessionFields) {
+        if (had) session[name] = value;
+        else delete session[name];
+      }
+      setDesktopSession(prior.desktop);
+      setWorkspaceCwdLock(session.id, prior.lock);
+      prior.prompt();
+      session.updatedAt = Date.now();
+      persistSession(session);
+      moveLeadRow(session.id, session.cwd || prior.cwd);
+      invalidateCaches();
+    });
+    const changed = !samePath(prior.cwd || '', cwd);
+    applyResolvedCwd(cwd, { persistProjectSelection: true, classifyByMembership });
+    if (changed) {
+      moveLeadRow(session.id, cwd);
+      await refreshWorkspaceContext(session, cwd);
+      await retargetWorkers(session, cwd, journal);
+      session.updatedAt = Date.now();
+      persistSession(session);
+    }
+    invalidateCaches();
+    return { cwd: getCurrentCwd(), workspace: session.workspace ?? null };
+  }
+
   async function releaseOwner(backendApi, entryId, sessionId) {
     try {
       await backendApi.releaseWorktreeOwner(entryId, owner(sessionId));
@@ -178,7 +232,14 @@ export function createTransitionSteps({
     }
   }
 
-  async function enterWorktree(session, previous, { name, nameHint, confirmLarge, signal, txId, journal }) {
+  /**
+   * `changes` (a new worktree only): the project folder's uncommitted
+   * changes — `ask` refuses with WORKTREE_DIRTY_CHOICE while there are any,
+   * `leave` keeps them there, `carry` moves them into the worktree while the
+   * project folder is held (refused while other sessions work in it);
+   * omitted, they are not examined (lazy provisioning).
+   */
+  async function enterWorktree(session, previous, { name, nameHint, confirmLarge, changes, signal, txId, journal }) {
     const backendApi = await backend();
     const projectPath = previous.projectPath;
     const project = await inspectProject(projectPath, { signal });
@@ -197,16 +258,39 @@ export function createTransitionSteps({
       // 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,
-      });
+      const create = () =>
+        backendApi.createManagedWorktree({
+          projectPath,
+          sessionId: session.id,
+          runtimeToken,
+          baseBranch: project.currentBranch,
+          nameHint: name ?? nameHint ?? '',
+          confirmLarge: confirmLarge === true,
+          txId,
+          signal,
+          carryChanges: changes ?? null,
+        });
+      // A carry clears the project folder: it is held, and every session
+      // sharing it must be quiet (no turn, agents or background shells).
+      entry =
+        changes === 'carry'
+          ? await withProjectFolder(session.id, project.topLevel || projectPath, async () => {
+              await assertCheckoutQuiet(session, project.topLevel || projectPath);
+              return create();
+            })
+          : await create();
+      const recoveryRef = entry.changes?.recoveryRef;
+      if (recoveryRef) {
+        // Anything that fails before the move is committed puts the changes
+        // back into the project folder and drops the worktree made for them;
+        // a restore that is refused keeps both (and the recovery ref).
+        const created = entry;
+        journal.push(async () => {
+          await backendApi.restoreCarriedChanges({ projectPath, recoveryRef });
+          await backendApi.removeManagedWorktree({ entryId: created.id, force: true });
+          await backendApi.dropCarryRecoveryRef({ projectPath, recoveryRef });
+        });
+      }
     }
     // Cancelled after the worktree exists: it stays retained (same txId on
     // retry), the session does not move.
@@ -228,10 +312,24 @@ export function createTransitionSteps({
         baseCommit: entry.baseCommit,
         mergeTarget: project.currentBranch,
       },
-      journal
+      journal,
+      // The tail notice: what happened to the uncommitted changes, and how
+      // the project-folder paths of the conversation so far map to the worktree.
+      isWorktreeBound(previous) ? null : { from: previous.cwd, changes: entry.changes?.mode ?? null }
     );
+    // The move is committed and persisted: the carried changes' recovery ref
+    // has done its job (a failure to drop it only leaves a spare ref).
+    if (entry.changes?.recoveryRef) {
+      await backendApi
+        .dropCarryRecoveryRef({ projectPath, recoveryRef: entry.changes.recoveryRef })
+        .catch(() => {});
+    }
     // Creation notes (submodules, include entries missing or already present).
-    return { ...entered, warnings: Array.isArray(entry.warnings) ? [...entry.warnings] : [] };
+    return {
+      ...entered,
+      warnings: Array.isArray(entry.warnings) ? [...entry.warnings] : [],
+      ...(entry.changes ? { changes: { mode: entry.changes.mode, count: entry.changes.count } } : {}),
+    };
   }
 
   async function enterProjectBranch(session, previous, { branch, create, signal, journal }) {
@@ -360,5 +458,5 @@ export function createTransitionSteps({
     return { ...result, removed };
   }
 
-  return { enterWorktree, enterProjectBranch, removeRetainedWorktree };
+  return { enterWorktree, enterProjectBranch, removeRetainedWorktree, switchProject };
 }

package/src/session-runtime/workspace/transitions.mjs

@@ -12,7 +12,9 @@
  * (runtime/shared/worktrees/manager.mjs), loaded on first use.
  */
 import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import {
+  WORKTREE_CARRY_CHOICES,
   branchMenuEntries,
   isWorktreeBound,
   isWorktreeError,
@@ -24,6 +26,7 @@ import { normalizeWorktreeSettings } from '../../runtime/shared/worktrees/settin
 import * as maintenance from '../../runtime/shared/worktrees/maintenance.mjs';
 import { inspectRepo, throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
 import { isWithin, samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { readGitHead } from '../../runtime/shared/worktrees/git-head.mjs';
 import { sessionHasConversationMessages } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import { buildWorkspacePromptContext } from '../../runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs';
 import {
@@ -53,6 +56,9 @@ async function defaultOwnShellJobCount(sessionIds) {
 
 const lower = (value) => String(value || '').toLowerCase();
 
+const WORKTREE_BOUND_SWITCH =
+  'The session works in a managed worktree; exit the worktree first (switch to a project-folder branch, or merge or remove the worktree) before moving it to another project.';
+
 /** The registered Project (projects.json) at `path`, or null. */
 async function defaultRegisteredProject(path) {
   const { listProjectsStrict } = await import('../../runtime/shared/projects.mjs');
@@ -62,9 +68,12 @@ async function defaultRegisteredProject(path) {
 /**
  * Re-root one session's prompt at `cwd`: environment facts and instruction
  * files for every session, project memory for the Lead only (workers never
- * carried it).
+ * carried it). A session with a conversation keeps its system prompt (cache
+ * intact) and gets a tail notice instead (refreshSessionWorkspaceContext);
+ * `move` ({ from, changes }: the session left the project folder `from` for
+ * a worktree) adds the uncommitted-changes and path lines to that notice.
  */
-export async function refreshWorkspacePrompt(session, cwd, { loadCoreMemoryContext } = {}) {
+export async function refreshWorkspacePrompt(session, cwd, { loadCoreMemoryContext, move = null } = {}) {
   const { environmentContext, instructionFilesContext } = buildWorkspacePromptContext(session, cwd);
   const coreMemoryContext =
     session?.owner === AGENT_OWNER || typeof loadCoreMemoryContext !== 'function'
@@ -75,6 +84,7 @@ export async function refreshWorkspacePrompt(session, cwd, { loadCoreMemoryConte
     environmentContext,
     coreMemoryContext,
     instructionFilesContext,
+    ...(move ? { move } : {}),
   });
 }
 
@@ -137,9 +147,10 @@ const TRANSITION_STATE = { worktree: 'provisioning', branch: 'switching', 'remov
  * @param {object} deps
  * @param {() => any} deps.getSession The Lead session this runtime hosts.
  * @param {() => string} deps.getCurrentCwd
- * @param {(cwd: string) => unknown} deps.applyResolvedCwd Retargets rt cwd, session.cwd and the cwd override.
+ * @param {(cwd: string, options?: { persistProjectSelection?: boolean }) => unknown} deps.applyResolvedCwd Retargets rt cwd, session.cwd and the cwd override (and, persisting, the Project selection).
+ * @param {(desktopSession: any) => unknown} [deps.setDesktopSession] Restores the runtime's desktop metadata on a rollback.
  * @param {(session: any) => unknown} deps.persistSession
- * @param {(session: any, cwd: string) => Promise<unknown>} deps.refreshWorkspaceContext
+ * @param {(session: any, cwd: string, move?: { from: string, changes: 'carried'|'left'|null }|null) => Promise<unknown>} deps.refreshWorkspaceContext
  * @param {() => number} deps.getActiveTurnCount
  * @param {() => { agentWorkers?: any[], agentJobs?: any[] }} deps.agentStatusState
  * @param {(sessionId: string, cwd: string) => unknown} [deps.updateLeadWorkerCwd] Moves the Lead's pool row (lead-workers.json).
@@ -149,6 +160,7 @@ export function createWorkspaceTransitions({
   getReservedSessionId = () => null,
   getCurrentCwd,
   getDesktopSession = () => null,
+  setDesktopSession = () => {},
   getConfig = () => null,
   createCurrentSession = null,
   applyResolvedCwd,
@@ -207,6 +219,37 @@ export function createWorkspaceTransitions({
     return normalizeSessionWorkspace({ projectPath, cwd: getCurrentCwd() || projectPath, revision: 0 });
   }
 
+  let liveWorkspace = null;
+
+  /**
+   * The workspace the session publishes: a worktree-bound record as stored; a
+   * project-folder session (never moved, back from a worktree, or carrying a
+   * transition stub) with the folder's checked-out branch / detached commit and
+   * repoCommonDir read straight from HEAD — no git process. Null outside a git
+   * repository for a session without a record. Identity-stable while equal.
+   */
+  function getLiveWorkspace() {
+    const session = getSession();
+    const stored = readSessionWorkspace(session);
+    if (isWorktreeBound(stored)) return session.workspace;
+    let base;
+    try {
+      base = stored ?? currentWorkspace(session);
+    } catch {
+      return session?.workspace ?? null;
+    }
+    const head = readGitHead(base.cwd);
+    if (!head) return session?.workspace ?? null;
+    const next = {
+      ...base,
+      repoCommonDir: head.repoCommonDir,
+      branch: head.branch,
+      baseCommit: head.branch ? base.baseCommit : head.commit,
+    };
+    if (!liveWorkspace || !isDeepStrictEqual(liveWorkspace, next)) liveWorkspace = next;
+    return liveWorkspace;
+  }
+
   function isSessionActive(session) {
     const runtime = sessionManager?.getSessionRuntime?.(session.id);
     if (runtime?.controller?.signal && !runtime.controller.signal.aborted) return true;
@@ -223,8 +266,11 @@ export function createWorkspaceTransitions({
         (candidate.ownerSessionId === session.id || candidate.parentSessionId === session.id)
     );
 
-  /** WORKTREE_BUSY_JOBS while this Lead has a turn, workers or background shells running. */
-  async function assertLeadIdle(session, { ownTurn = false } = {}) {
+  /**
+   * WORKTREE_BUSY_JOBS while this Lead has a turn, workers or background
+   * shells running (`shellJobs: false` tolerates background shells).
+   */
+  async function assertLeadIdle(session, { ownTurn = false, shellJobs: checkShellJobs = true } = {}) {
     if (!ownTurn && getActiveTurnCount() > 0) {
       throw worktreeError('WORKTREE_BUSY_JOBS', 'The session is running a turn; wait for it to finish.', {
         reason: 'turn',
@@ -240,6 +286,7 @@ export function createWorkspaceTransitions({
     if (busyWorkers || busyJobs) {
       throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'workers', workers: busyWorkers, jobs: busyJobs });
     }
+    if (!checkShellJobs) return;
     const ids = new Set([session.id, ...workers.map((row) => row?.sessionId).filter(Boolean)]);
     for (const worker of workersOf(session)) ids.add(worker.id);
     const shellJobs = await countOwnShellJobs([...ids]);
@@ -284,11 +331,44 @@ export function createWorkspaceTransitions({
     }
   }
 
+  /**
+   * Before a carry clears the shared checkout `folder` (held by the caller,
+   * so no new turn starts there): WORKTREE_BUSY_JOBS while any other session
+   * working in it — idle or not, this Lead's workers included — owns a
+   * running background shell (holdProjectFolder already refused running
+   * turns and agents there, assertLeadIdle this Lead's own). Processes
+   * outside Mixdog (editors, watchers) cannot be excluded.
+   */
+  async function assertCheckoutQuiet(session, folder) {
+    const sharing = listLiveSessions()
+      .filter(
+        (candidate) =>
+          candidate?.id &&
+          candidate.id !== session.id &&
+          candidate.closed !== true &&
+          typeof candidate.cwd === 'string' &&
+          isWithin(folder, candidate.cwd)
+      )
+      .map((candidate) => candidate.id);
+    if (!sharing.length) return;
+    const shellJobs = await countOwnShellJobs(sharing);
+    if (shellJobs > 0) {
+      throw worktreeError(
+        'WORKTREE_BUSY_JOBS',
+        'Background shells of other sessions are running in the project folder; carrying the changes needs it quiet.',
+        { reason: 'folder-shell-jobs', shellJobs }
+      );
+    }
+  }
+
   const steps = createTransitionSteps({
+    assertCheckoutQuiet,
     backend,
     inspectProject,
     runtimeToken,
     getCurrentCwd,
+    getDesktopSession,
+    setDesktopSession,
     applyResolvedCwd,
     persistSession,
     refreshWorkspaceContext,
@@ -331,6 +411,7 @@ export function createWorkspaceTransitions({
           name: target.name,
           nameHint: options.nameHint,
           confirmLarge: options.confirmLarge,
+          changes: options.changes,
         });
       }
       if (target.kind === 'branch') {
@@ -442,9 +523,22 @@ export function createWorkspaceTransitions({
     });
     // A session in the project folder (never moved, or back from a worktree)
     // is on whatever that folder has checked out now.
-    const checkedOut = menu.occupancy.find((row) => row.kind === 'current')?.branch ?? null;
+    // Its repository is the project's (a never-moved session has no stored
+    // record), and a detached checkout shows branch null with the commit in
+    // baseCommit — never mistaken for "not a repository".
+    let view = workspace;
+    if (!isWorktreeBound(workspace)) {
+      const project = await inspectProject(workspace.projectPath);
+      const checkedOut = project.currentBranch ?? null;
+      view = {
+        ...workspace,
+        repoCommonDir: project.repoCommonDir ?? workspace.repoCommonDir,
+        branch: checkedOut,
+        baseCommit: checkedOut ? workspace.baseCommit : (project.headCommit ?? null),
+      };
+    }
     return {
-      workspace: isWorktreeBound(workspace) || !checkedOut ? workspace : { ...workspace, branch: checkedOut },
+      workspace: view,
       pendingWorktree: pendingIntent ? { name: pendingIntent.name } : null,
       branches: branchMenuEntries(menu.branches, menu.occupancy),
       occupancy: menu.occupancy,
@@ -510,17 +604,28 @@ export function createWorkspaceTransitions({
    * reuse it. Typed failures (large repository, disk, busy) therefore reach
    * the sender while its draft is still unsent, and the turn that follows
    * finds the session already bound.
+   *
+   * A provisioning that creates a new worktree decides the project folder's
+   * uncommitted changes (tracked and untracked): none → it proceeds; without
+   * `carryChanges` it refuses with WORKTREE_DIRTY_CHOICE (`details.count`);
+   * `leave` starts the worktree at HEAD and leaves them; `carry` moves them
+   * into it (the result's `changes` reports which). Re-entering a retained
+   * worktree never touches them.
    */
   async function requestWorktree({
     name = null,
     confirmLarge = false,
     provision = false,
+    carryChanges,
     prompt = '',
     txId = '',
     expectedRevision,
   } = {}) {
     const nameHint = validName(name);
     const expected = validRevision(expectedRevision);
+    if (carryChanges !== undefined && carryChanges !== null && !WORKTREE_CARRY_CHOICES.includes(carryChanges)) {
+      throw new TypeError(`carryChanges must be one of ${WORKTREE_CARRY_CHOICES.join(', ')}.`);
+    }
     const session = provision === true ? await ensureSession() : getSession();
     // No session yet: the menu it was read from had revision 0.
     const current = session?.id ? currentWorkspace(session) : null;
@@ -536,6 +641,7 @@ export function createWorkspaceTransitions({
         return { ...entered, pending: false };
       }
     }
+    const priorIntent = pendingIntent;
     pendingIntent = {
       name: nameHint ?? pendingIntent?.name ?? null,
       confirmLarge: confirmLarge === true || pendingIntent?.confirmLarge === true,
@@ -544,10 +650,21 @@ export function createWorkspaceTransitions({
       txId: pendingIntent?.txId ?? null,
     };
     if (provision === true) {
-      return {
-        ...(await provisionIntent(session, pendingIntent, txId, prompt, { expectedRevision: expected })),
-        pending: false,
-      };
+      const intent = pendingIntent;
+      try {
+        return {
+          ...(await provisionIntent(session, intent, txId, prompt, {
+            expectedRevision: expected,
+            changes: carryChanges ?? 'ask',
+          })),
+          pending: false,
+        };
+      } catch (error) {
+        // A refused move (uncommitted changes to decide, busy, …) is never
+        // re-armed for the next turn, where nobody could answer it.
+        if (pendingIntent === intent) pendingIntent = priorIntent;
+        throw error;
+      }
     }
     const workspace = session?.id ? currentWorkspace(session) : null;
     return { revision: workspace?.revision ?? 0, workspace, pending: true };
@@ -570,15 +687,35 @@ export function createWorkspaceTransitions({
     if (cleanup !== true || merged.merged !== true) return merged;
     // "Merge and clean up": with autoCleanup on, the merged worktree goes now
     // (a dirty one stays, reported); off, nothing is removed automatically.
+    // The merge is committed: a failed or refused cleanup (dirty, retained
+    // file recovery data, ...) is a cleanup notice, never a merge failure.
     if (worktreeSettings().autoCleanup !== true) {
-      return { ...merged, cleanup: { removed: false, reason: 'auto-cleanup-off' } };
+      return {
+        ...merged,
+        cleanup: { removed: false, reason: 'auto-cleanup-off', message: 'Auto cleanup is off; the worktree is kept.' },
+      };
     }
     try {
       const removed = await removeWorktree({ force: false }, { ownTurn });
       return { ...merged, cleanup: removed.removed, revision: removed.revision, workspace: removed.workspace };
     } catch (error) {
-      if (!isWorktreeError(error, 'WORKTREE_DIRTY') && !isWorktreeError(error, 'WORKTREE_UNMERGED')) throw error;
-      return { ...merged, cleanup: { removed: false, reason: error.code } };
+      // The merge stands: a refused or incomplete cleanup (dirty, unmerged,
+      // retained file recovery data, partly removed, …) is reported, never
+      // thrown, with the workspace as it is now (an incomplete removal already
+      // returned to the project folder).
+      const workspace = currentWorkspace(session);
+      const code = typeof error?.code === 'string' ? error.code : '';
+      return {
+        ...merged,
+        cleanup: {
+          removed: false,
+          reason: code || 'WORKTREE_CLEANUP_FAILED',
+          ...(code ? { code } : {}),
+          message: String(error?.message || error),
+        },
+        revision: workspace.revision,
+        workspace,
+      };
     }
   }
 
@@ -620,6 +757,41 @@ export function createWorkspaceTransitions({
     }
   }
 
+  /**
+   * Move the hosted Lead to another Project folder (session set-project, the
+   * desktop/remote setCwd): the one authority for a Project switch, admitted
+   * like a workspace transition. Refused while a turn runs (`ownTurn`: the
+   * Lead's own tool call tolerates its calling turn), while workers run, and
+   * while the session works in a managed worktree. Serialized with turns and
+   * other workspace changes; the prompt refresh of the Lead and its idle
+   * workers completes (or rolls the switch back) before it resolves. Without
+   * a session (a draft) only the runtime cwd and the selection move.
+   * `classifyByMembership` (the desktop/remote move): a folder outside every
+   * registered Project is classified as a task (cwd-apply).
+   * @returns {Promise<string>} the runtime cwd after the switch
+   */
+  async function switchProject(cwd, { ownTurn = false, classifyByMembership = false } = {}) {
+    const selection = { classifyByMembership: classifyByMembership === true };
+    const session = getSession();
+    if (!session?.id) {
+      applyResolvedCwd(cwd, { persistProjectSelection: true, ...selection });
+      return getCurrentCwd();
+    }
+    const leave = beginWorkspaceTransition(session.id, `project:${newTxId()}`);
+    const journal = [];
+    try {
+      await assertLeadIdle(session, { ownTurn: ownTurn === true, shellJobs: false });
+      if (isWorktreeBound(readSessionWorkspace(session))) throw new Error(WORKTREE_BOUND_SWITCH);
+      await steps.switchProject(session, cwd, journal, selection);
+      return getCurrentCwd();
+    } catch (error) {
+      await undoAll(journal, error);
+      throw error;
+    } finally {
+      leave();
+    }
+  }
+
   async function removeWorktree({ force = false, expectedRevision } = {}, { ownTurn = false } = {}) {
     const expected = validRevision(expectedRevision);
     const session = hostedSession(null);
@@ -636,6 +808,8 @@ export function createWorkspaceTransitions({
     admitTurnWorkspace,
     /** The durable workspace record of the hosted session (null: project folder, never moved). */
     getWorkspace: () => getSession()?.workspace ?? null,
+    /** What the session snapshot publishes (see getLiveWorkspace). */
+    getLiveWorkspace,
     getBranchMenu,
     getProjectBranchMenu: projectBranches.getProjectBranchMenu,
     selectBranch,
@@ -644,6 +818,7 @@ export function createWorkspaceTransitions({
     requestWorktree,
     mergeWorkspace,
     removeWorktree,
+    switchProject,
     listWorktrees,
     pruneWorktrees,
     cleanupDeletedSession,

package/src/standalone/daemon-agent-control.mjs

@@ -68,5 +68,13 @@ export function createCanonicalAgentControl({ getSessionService, getSessionRunti
     return await tool.execute(args, scopedContext);
   }
 
-  return { canonicalAgentTool, execute };
+  /** Graceful shutdown: drain and release the canonical agent's index writers.
+   *  Never builds the tool just to dispose it. */
+  async function dispose() {
+    if (!canonicalAgentToolPromise) return;
+    const tool = await canonicalAgentToolPromise.catch(() => null);
+    await tool?.disposeAsync?.({ settle: true });
+  }
+
+  return { canonicalAgentTool, execute, dispose };
 }

package/src/standalone/daemon-local-session-bridge.mjs

@@ -22,9 +22,22 @@ export function createLocalSessionBridge({ getSessionService, log, pid = process
       return createSessionProtocolClient({
         call(name, args = {}, options = {}) {
           if (closed) throw new Error('daemon-local session client is closed');
-          return getSessionService().handleCall(name, args, {
+          const signal = options?.signal;
+          signal?.throwIfAborted();
+          const result = getSessionService().handleCall(name, args, {
             clientToken,
             ...(options?.callId ? { callId: String(options.callId) } : {}),
+            ...(signal ? { signal } : {}),
+          });
+          if (!signal) return result;
+          // The in-process service has no cancellation of its own: an abort
+          // frees the caller, whose late reply is dropped.
+          return new Promise((resolve, reject) => {
+            const onAbort = () => reject(signal.reason);
+            signal.addEventListener('abort', onAbort, { once: true });
+            Promise.resolve(result)
+              .then(resolve, reject)
+              .finally(() => signal.removeEventListener('abort', onAbort));
           });
         },
         async close(reason = 'local session view closed') {