mixdog 1.2.2 → 1.2.4

package/src/session-runtime/turn/compaction-gate.mjs

@@ -0,0 +1,25 @@
+/**
+ * src/session-runtime/turn/compaction-gate.mjs - serializes a model-scheduled
+ * compaction (session tool) with everything that follows its turn. The
+ * compaction is chained, never left dangling: `after(fn)` wraps a command so it
+ * waits for the compaction in flight, and the compaction itself only runs if
+ * the session it was scheduled for is still the live one.
+ */
+export function createCompactionGate({ getSessionId, compact }) {
+  let tail = Promise.resolve();
+  const run = (sessionId) => {
+    tail = tail
+      .then(() => (getSessionId() === sessionId ? compact() : null))
+      .catch(() => {
+        /* best-effort: a scheduled compaction must never break teardown */
+      });
+    return tail;
+  };
+  const after =
+    (fn) =>
+    async (...args) => {
+      await tail;
+      return fn(...args);
+    };
+  return { run, after };
+}

package/src/session-runtime/turn/session-ops.mjs

@@ -10,7 +10,6 @@ export function createSessionOps(deps) {
   const {
     getSession,
     setSession,
-    getCurrentCwd,
     setMode,
     getActiveTurnCount,
     mgr,
@@ -18,7 +17,7 @@ export function createSessionOps(deps) {
     agentTool,
     invalidatePreSessionToolSurface,
     refreshEmptySessionToolPolicy,
-    applyResolvedCwd,
+    switchProject,
     resolveCwdPath,
     agentStatusState,
     getReservedSessionId,
@@ -122,9 +121,12 @@ export function createSessionOps(deps) {
     return { messageCount: list.length, messages: list.slice(start) };
   }
 
-  function setCwd(path) {
-    applyResolvedCwd(resolveCwdPath(path), { persistProjectSelection: true });
-    return getCurrentCwd();
+  // The desktop/remote Project switch: refused while a turn runs or the
+  // session works in a managed worktree (switchProject); resolves once the
+  // prompt refresh landed. Its target is a registered Project or the task
+  // workspace, classified by desktop membership.
+  async function setCwd(path) {
+    return switchProject(resolveCwdPath(path), { classifyByMembership: true });
   }
 
   return {

package/src/session-runtime/turn/side-question-ops.mjs

@@ -0,0 +1,19 @@
+/**
+ * src/session-runtime/turn/side-question-ops.mjs - /btw side questions on the
+ * runtime's current session. They run beside an in-progress turn and touch no
+ * session state (see orchestrator/session/side-question.mjs).
+ */
+import { askSideQuestion, cancelSideQuestion } from '../../runtime/agent/orchestrator/session/side-question.mjs';
+
+export function createSideQuestionOps({ getSession, getReservedSessionId }) {
+  const sessionId = () => getSession()?.id || getReservedSessionId?.() || '';
+  return {
+    /** @returns {Promise<{ text: string }>} */
+    askSide: (question) => askSideQuestion(sessionId(), question),
+    /** Abort the side question of `targetSessionId` (the session it was
+     *  asked in), or of the current session when omitted. */
+    cancelSide: (targetSessionId) => {
+      cancelSideQuestion(typeof targetSessionId === 'string' && targetSessionId ? targetSessionId : sessionId());
+    },
+  };
+}

package/src/session-runtime/turn/turn-run/ask-callbacks.mjs

@@ -1,4 +1,5 @@
 import { isVisibleStreamProgress } from '../../../runtime/shared/stream-progress.mjs';
+import { toolCallDisplayIdentity } from '../../../runtime/shared/tool-primitives.mjs';
 
 // The askSession callback bridge: caller callbacks pass through, with the
 // transcript, first-visible timing, title release and warmup arming folded in.
@@ -6,10 +7,13 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
   function plannedToolCalls(session0, options) {
     return async (iter, calls) => {
       for (const call of calls || []) {
+        // A bridged call reports the tool it runs; the transcript keeps the wire call.
+        const identity = toolCallDisplayIdentity(call?.name, call?.arguments);
         hooks.emit('tool:planned', {
           sessionId: session0.id,
-          name: call?.name || 'tool',
+          name: identity.name || 'tool',
           callId: call?.id || null,
+          ...(identity.via ? { via: identity.via } : {}),
         });
       }
       if (typeof options.onToolCall === 'function') {
@@ -71,6 +75,8 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
       transcriptMeta: stampCheckpoint(options),
       promptSource: options.promptSource,
       retryFailedTurn: options.retryFailedTurn === true,
+      retryTurnId: options.retryTurnId,
+      retryAttemptId: options.retryAttemptId,
       onTextDelta: options.onTextDelta,
       onTextReset: options.onTextReset,
       onReasoningDelta: options.onReasoningDelta,

package/src/session-runtime/turn/turn-run/turn-prepare.mjs

@@ -23,6 +23,7 @@ export function createTurnPreparation({
   assertSessionAdmission,
   prepareTurnWorkspace,
   admitTurnWorkspace,
+  applyPendingRoute,
 }) {
   const scopedMcpTools = (session) => scopedMcpToolsFor(session, getConfig());
 
@@ -49,9 +50,9 @@ export function createTurnPreparation({
     // Slower servers remain available through the late-tool path; a reconnect
     // in flight gets the same short TTFT grace BEFORE folding the catalog so it
     // cannot hold the provider request. No reconnect in flight → no-op.
-    const awaitGrace = async () => {
+    const awaitGrace = async (options) => {
       try {
-        await turn.awaitTurn(() => turn.timing.awaitMcpGrace());
+        await turn.awaitTurn(() => turn.timing.awaitMcpGrace(options));
       } catch {
         /* gate must never break the turn */
       }
@@ -64,7 +65,12 @@ export function createTurnPreparation({
       // One-shot: cleared before the fold so a throw still never re-runs it,
       // and a resumed session (flag unset) skips straight to the late path.
       session0.deferredInitialRefreshPending = false;
-      await awaitGrace();
+      // A spawned agent runtime owns a fresh MCP scope whose connect starts at
+      // its boot, so the 0 ms default grace would hide every MCP tool from the
+      // agent's first (often only) turn. Agents are not on the user's TTFT
+      // path: wait for the initial connect within the server startup budget.
+      const agentOwned = session0.owner === 'agent' || session0.visibility === 'agent-only';
+      await awaitGrace({ untilConnected: agentOwned });
       try {
         refreshInitialDeferredMcpSurface(session0, scopedMcpTools(session0));
       } catch {
@@ -124,6 +130,9 @@ export function createTurnPreparation({
       throwIfAborted(turn.signal);
       assertSessionAdmission?.();
     }
+    const modelSwitch = applyPendingRoute?.();
+    options.onRouteApplied?.(getSession());
+    if (modelSwitch) options.onModelSwitch?.(modelSwitch);
     ensureSessionTranscriptWriter?.();
     transcript.appendUser(prompt);
     const session0 = getSession();

package/src/session-runtime/turn/turn-run/turn-settle.mjs

@@ -28,6 +28,8 @@ export function createTurnSettlement({
   setFirstTurnCompleted,
   scheduleProviderWarmup,
   scheduleProviderModelWarmup,
+  takePendingCompact,
+  runPendingCompact,
 }) {
   async function completeTurn(turn, session0, result) {
     throwIfAborted(turn.signal);
@@ -84,11 +86,16 @@ export function createTurnSettlement({
     turn.releaseFirstTitle?.();
     turn.emitTiming(turn.timing.status);
     turn.armHeavyRuntimeWarmup('turn-settled');
+    let settleError;
     try {
       await turn.snapshot.finish(turn.signal, turn.awaitTurn);
-    } finally {
-      // The turn no longer works in its checkout: transitions may proceed.
+    } catch (error) {
+      settleError = error;
+    }
+    try {
       turn.releaseWorkspace?.();
+    } catch (error) {
+      settleError = settleError ? new AggregateError([settleError, error], 'Turn cleanup failed.') : error;
     }
     try {
       turn.unregister?.();
@@ -99,6 +106,15 @@ export function createTurnSettlement({
       /* lead pool must never break turn teardown */
     }
     setActiveTurnCount(Math.max(0, getActiveTurnCount() - 1));
+    if (settleError) throw settleError;
+    // A compaction the model scheduled (session tool) runs once the turn is over.
+    // Only while the settled session is still the live one; otherwise it stays
+    // pending for that session and never compacts another. The runner chains
+    // the compaction so the next turn waits on it.
+    const settledId = turn.session0?.id;
+    if (getActiveTurnCount() === 0 && settledId && getSession()?.id === settledId && takePendingCompact?.(settledId)) {
+      runPendingCompact?.(settledId);
+    }
     if (!isFirstTurnCompleted()) {
       setFirstTurnCompleted(true);
       scheduleProviderWarmup();

package/src/session-runtime/turn/turn-run/turn-timing.mjs

@@ -38,11 +38,12 @@ export function createTurnTimingFactory({ getSession, awaitInitialMcpConnect, mc
         /* timing telemetry must never affect a turn */
       }
     };
-    // Give an in-flight MCP connect only a short TTFT grace.
-    timing.awaitMcpGrace = async () => {
+    // Give an in-flight MCP connect only a short TTFT grace. untilConnected
+    // waits for the initial connect bounded only by the server startup budget.
+    timing.awaitMcpGrace = async ({ untilConnected = false } = {}) => {
       const graceStartedAt = performance.now();
       try {
-        await awaitInitialMcpConnect?.(mcpTurnGraceMs);
+        await awaitInitialMcpConnect?.(untilConnected ? undefined : mcpTurnGraceMs);
       } finally {
         timing.mcpWaitMs += performance.now() - graceStartedAt;
       }

package/src/session-runtime/turn/turn-run.mjs

@@ -1,6 +1,5 @@
 /**
- * src/session-runtime/turn/turn-run.mjs - one user turn end to end: viewer
- * forwarding, turn open (abort controller, timing, warmup arming), session
+ * src/session-runtime/turn/turn-run.mjs - one user turn end to end: turn open (abort controller, timing, warmup arming), session
  * preparation (workspace provisioning, then the worktree review snapshot), the
  * askSession callback bridge, and the settlement that always runs. The phases
  * live under turn-run/.
@@ -13,6 +12,7 @@ import { createSnapshotTrackerFactory } from './turn-run/snapshot-tracker.mjs';
 import { createTurnOpener } from './turn-run/turn-open.mjs';
 import { createTurnPreparation } from './turn-run/turn-prepare.mjs';
 import { createAskCallbacks } from './turn-run/ask-callbacks.mjs';
+import { registerNativeWebSearchUsageSink } from '../native-web-search-usage.mjs';
 import { createTurnSettlement } from './turn-run/turn-settle.mjs';
 
 export function createTurnRunner(deps) {
@@ -48,18 +48,6 @@ export function createTurnRunner(deps) {
     deferComputerSessionRelease,
   });
 
-  const enqueueRemoteAttachedPrompt = (prompt) => {
-    const attachedSession = getSession();
-    if (!attachedSession?.remoteAttached || !attachedSession.id) return false;
-    try {
-      // prompt may be a string or { content/text, id } so the submission id
-      // survives spool fallback after a live-share ack miss.
-      return Number(mgr.enqueueRemotePendingMessage?.(attachedSession.id, prompt)) > 0;
-    } catch {
-      return false;
-    }
-  };
-
   function getTurnLiveness() {
     const sessionId = getSession()?.id;
     if (!sessionId || typeof mgr.getSessionProgressSnapshot !== 'function') return null;
@@ -68,41 +56,35 @@ export function createTurnRunner(deps) {
     return { ...snapshot };
   }
 
-  // Remote-attach: this surface is a viewer on a session that another live
-  // process owns. Never run a turn here — persist the prompt into the shared
-  // pending spool; the owner's injection poller submits it as a normal user
-  // turn and this surface refreshes from disk.
-  function forwardAttachedPrompt(attachedSession, prompt, options) {
-    // Carry the submission id into the spool: the owner reuses it for the
-    // queue entry and the settled user row, so the submitting surface's
-    // optimistic bubble is reconciled with the mirrored row.
-    const submissionId = String(options.id || '').trim();
-    const delivered = enqueueRemoteAttachedPrompt(submissionId ? { content: prompt, id: submissionId } : prompt);
-    return {
-      // This branch is only a race-safe fallback for callers that reached
-      // ask() before the live pipe was ready. Never manufacture an
-      // assistant response: the owner's mirrored transcript is authoritative.
-      result: { content: '', remoteAttached: true, delivered },
-      session: attachedSession,
-    };
-  }
-
   async function runTurn(prompt, options) {
-    const attachedSession = getSession();
-    if (attachedSession?.remoteAttached) return forwardAttachedPrompt(attachedSession, prompt, options);
     const turn = openTurn(options);
     try {
       const session0 = await prepareSession(turn, prompt, options);
       const turnContext = await dispatchPromptSubmit(turn, session0, prompt, options);
-      const result = await mgr.askSession(
-        session0.id,
-        prompt,
-        turnContext || null,
-        plannedToolCalls(session0, options),
-        getCurrentCwd(),
-        options.prefetch || null,
-        askCallbacks(turn, session0, options)
-      );
+      const callbacks = askCallbacks(turn, session0, options);
+      // Register only once askSession's session lock is held: the first
+      // provider send of this turn. A turn queued behind another on the same
+      // session id therefore never receives the running turn's search usage.
+      let releaseWebSearchUsage = null;
+      const providerSendStarted = callbacks.onProviderSendStarted;
+      callbacks.onProviderSendStarted = (...args) => {
+        releaseWebSearchUsage ??= registerNativeWebSearchUsageSink(session0.id, options.onNativeWebSearchUsage);
+        return providerSendStarted(...args);
+      };
+      let result;
+      try {
+        result = await mgr.askSession(
+          session0.id,
+          prompt,
+          turnContext || null,
+          plannedToolCalls(session0, options),
+          getCurrentCwd(),
+          options.prefetch || null,
+          callbacks
+        );
+      } finally {
+        releaseWebSearchUsage?.();
+      }
       return await completeTurn(turn, session0, result);
     } catch (error) {
       reportTurnError(turn, error);
@@ -113,7 +95,6 @@ export function createTurnRunner(deps) {
   }
 
   return {
-    enqueueRemoteAttachedPrompt,
     getTurnLiveness,
     ask: (prompt, options = {}) => runWithCwdOverride(getCurrentCwd(), () => runTurn(prompt, options)),
   };

package/src/session-runtime/usage-stats-api.mjs

@@ -82,22 +82,43 @@ function accountsInUse(accountPool) {
   return inUse;
 }
 
-// Every id a session's spend was recorded under: its own, and the per-account
-// provider session each subscription account sent it under before account
-// sends recorded the visible session.
-function sessionUsageIds(sessionId, accountPool) {
-  const ids = [sessionId];
+// Each subscription provider's account ids, read once per request.
+function accountScopes(accountPool) {
+  const scopes = [];
   for (const provider of ACCOUNT_PROVIDERS) {
     try {
-      for (const account of accountPool(provider).accounts)
-        ids.push(accountScopedSessionId(provider, account.id, sessionId));
+      scopes.push([provider, accountPool(provider).accounts.map((account) => account.id)]);
     } catch {
       /* an unreadable pool leaves that provider's older records out */
     }
   }
+  return scopes;
+}
+
+// Every id a session's spend was recorded under: its own, and the per-account
+// provider session each subscription account sent it under before account
+// sends recorded the visible session.
+function sessionUsageIdsFor(scopes, sessionId) {
+  const ids = [sessionId];
+  for (const [provider, accounts] of scopes) {
+    for (const account of accounts) ids.push(accountScopedSessionId(provider, account, sessionId));
+  }
   return ids;
 }
 
+// Other sessions a caller asks about beside its own (the composer island's
+// agent sessions): bounded, distinct, never the caller's own id.
+const MAX_SESSION_USAGE_IDS = 64;
+function otherSessionIds(options, sessionId) {
+  const ids = Array.isArray(options?.sessionIds) ? options.sessionIds : [];
+  const unique = new Set();
+  for (const id of ids) {
+    if (typeof id === 'string' && id && id !== sessionId) unique.add(id);
+    if (unique.size >= MAX_SESSION_USAGE_IDS) break;
+  }
+  return [...unique];
+}
+
 /** `null` = all time. `0` = today. Anything else is a trailing day count. */
 function normalizeDays(value) {
   if (value === null || value === undefined || value === 'all') return null;
@@ -213,15 +234,29 @@ export function createUsageStatsApi({
       return snapshot;
     },
 
-    /** This runtime's session from its first request, compactions included; null before it has one. */
-    async getSessionUsage() {
+    /**
+     * This runtime's session from its first request, compactions included; null before it has one.
+     * `sessionIds` adds the same totals for each named session (the agents it spawned) under
+     * `sessions`, each read by its own id only.
+     */
+    async getSessionUsage(options = {}) {
       const sessionId = getSessionId();
       if (!sessionId) return null;
       const store = ledger();
       if (!store) throw new Error('Usage ledger is unavailable');
       await store.settleWrites();
-      const usage = await store.sessionUsageAsync(sessionUsageIds(sessionId, accountPool));
-      return { sessionId, ...sessionUsageSnapshot(usage) };
+      const scopes = accountScopes(accountPool);
+      const usage = await store.sessionUsageAsync(sessionUsageIdsFor(scopes, sessionId));
+      const result = { sessionId, ...sessionUsageSnapshot(usage) };
+      const others = otherSessionIds(options, sessionId);
+      if (!others.length) return result;
+      const totals = await Promise.all(
+        others.map(async (id) => [
+          id,
+          sessionUsageSnapshot(await store.sessionUsageAsync(sessionUsageIdsFor(scopes, id))),
+        ])
+      );
+      return { ...result, sessions: Object.fromEntries(totals) };
     },
 
     /**

package/src/session-runtime/workflow-agents-api/agent-route.mjs

@@ -6,6 +6,7 @@ import { ensureProviderEnabled } from '../../runtime/agent/orchestrator/runtime-
 import { resolveRouteContextState, selectionFastCapable } from '../route-state.mjs';
 import { canonicalizeAgentRouteStorage, withAgentDisabled } from '../../runtime/shared/agent-route-config.mjs';
 import { agentEditorId } from './shared.mjs';
+import { routeChain, validateRouteChainProviders } from '../../runtime/shared/model-route-chain.mjs';
 
 // Agent route persistence. Route-scope isolation: an agent route owns its
 // model AND its effort/fast, stored in config.agents[<id>]. The shared
@@ -109,7 +110,21 @@ export function createAgentRouteApi(deps) {
     }
     if (!clean(requested.provider)) return clearOverride(id);
     if (!clean(requested.model)) throw new Error('agent route requires provider and model');
-    const routeToSave = normalizeWorkflowRoute(await resolveSelectedRoute(requested, stored));
+    const chain = routeChain({
+      ...requested,
+      fallbacks: hasOwn(requested, 'fallbacks') ? requested.fallbacks : stored.fallbacks,
+    });
+    validateRouteChainProviders(chain);
+    const storedChain = routeChain(stored);
+    const resolved = [];
+    for (const entry of chain) {
+      const previous = storedChain.find(
+        (candidate) => candidate.provider === entry.provider && candidate.model === entry.model
+      );
+      resolved.push(await resolveSelectedRoute(entry, previous || {}));
+    }
+    const [primary, ...fallbacks] = resolved;
+    const routeToSave = normalizeWorkflowRoute({ ...primary, fallbacks });
     if (!routeToSave) throw new Error('agent route requires provider and model');
     // Picking a model is also the "on" switch unless the request keeps it off.
     const nextConfig = withAgentDisabled(getConfig(), id, keepOff);

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

@@ -13,9 +13,11 @@
  * - Each worktree-bound Lead's execution root, which every worker of that Lead
  *   runs in.
  */
-import { worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+import { worktreeError, worktreeRefusal } from '../../runtime/shared/worktrees/contract.mjs';
 import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
 import { isWithin } from '../../runtime/shared/worktrees/paths.mjs';
+import { tryAdmitWorkspaceActivity } from '../../runtime/shared/worktrees/activity-gate.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
 
 /** @type {Map<string, { txId: string, settled: Promise<void> }>} Lead session id → in-flight transition. */
 const transitions = new Map();
@@ -42,8 +44,8 @@ function once(fn) {
   let done = false;
   return () => {
     if (done) return;
-    done = true;
     fn();
+    done = true;
   };
 }
 
@@ -78,21 +80,18 @@ export function beginWorkspaceTransition(sessionId, txId) {
  * 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).
+ * `hold: false` (an external checkout, never lock-blocked) only refuses.
  * @param {string|null} sessionId The changing session; '' / null for a session-less change.
  * @returns {() => void} Release.
  */
-export function holdCheckoutFolder(sessionId, folder) {
+export function holdCheckoutFolder(sessionId, folder, { hold = true } = {}) {
   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 (users.size) throw worktreeRefusal('folder-in-use', { sessions: [...users] });
+  if (!hold) return () => {};
   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',
@@ -145,14 +144,44 @@ function settledOrAborted(promise, signal) {
  */
 export async function admitTurn({ sessionId, cwd, signal }) {
   const id = key(sessionId);
-  for (let blocker = admissionBlocker(id, cwd); blocker; blocker = admissionBlocker(id, cwd)) {
+  for (;;) {
     throwIfAborted(signal);
-    await settledOrAborted(blocker, signal);
+    const blocker = admissionBlocker(id, cwd);
+    if (blocker) {
+      await settledOrAborted(blocker, signal);
+      continue;
+    }
+    const release = tryAdmitWorkspaceActivity(id, cwd());
+    if (!release) {
+      await delay(100, undefined, { signal });
+      continue;
+    }
+    const token = Symbol('turn');
+    const leases = [release];
+    turns.set(token, { sessionId: id, cwd, leases });
+    return once(() => {
+      const errors = [];
+      for (const leave of leases) {
+        try {
+          leave();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      turns.delete(token);
+      if (errors.length) throw new AggregateError(errors, 'Workspace admission could not be released.');
+    });
+  }
+}
+
+/** Keep the old root protected and acquire the destination before an admitted turn moves. */
+export function retainAdmittedTurnWorkspace(sessionId, cwd) {
+  for (const turn of turns.values()) {
+    if (turn.sessionId !== key(sessionId) || turn.cwd() === cwd) continue;
+    const leave = tryAdmitWorkspaceActivity(sessionId, cwd);
+    if (!leave) throw worktreeRefusal('folder-in-use');
+    turn.leases.push(leave);
   }
-  throwIfAborted(signal);
-  const token = Symbol('turn');
-  turns.set(token, { sessionId: id, cwd });
-  return once(() => turns.delete(token));
 }
 
 /**

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

@@ -2,42 +2,32 @@
  * 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.
+ * subfolder Project included): a checkout holds the folder (withProjectFolder)
+ * while git changes it, a merge takes the shared management path.
  */
 import { branchMenuEntries, projectWorkspace, worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+import * as branchManagement from '../../runtime/shared/worktrees/branch-management.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
+ * @param {Function} deps.withManagementFolders The shared admission of every merge and cleanup.
  */
-export function createProjectBranchOps({ backend, inspectProject, findRegisteredProject, withProjectFolder }) {
+export function createProjectBranchOps({
+  backend,
+  inspectProject,
+  findRegisteredProject,
+  withProjectFolder,
+  withManagementFolders,
+}) {
   /** WORKTREE_PROJECT_UNKNOWN unless `projectPath` is a registered Project. */
   async function registeredProject(projectPath) {
     const path = requireText(projectPath, 'projectPath');
@@ -54,12 +44,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,
@@ -112,25 +104,27 @@ export function createProjectBranchOps({ backend, inspectProject, findRegistered
   /**
    * 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.
+   * checked out (WORKTREE_TARGET_MISMATCH). The same guarded path as the
+   * branch-row merge (manageProjectBranch): source and destination validated
+   * and both folders held.
    */
   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 branchManagement.mergeConfirmedTarget(
+      { projectPath: path, branch: requireText(branch, 'branch'), target: requireText(target, 'target') },
+      withManagementFolders
     );
   }
 
-  return { getProjectBranchMenu, selectProjectBranch, mergeProjectBranch };
+  async function inspectProjectBranch({ projectPath, branch } = {}) {
+    const path = await registeredProject(projectPath);
+    return branchManagement.inspectProjectBranch({ projectPath: path, branch: requireText(branch, 'branch') });
+  }
+
+  async function manageProjectBranch(input = {}) {
+    const path = await registeredProject(input.projectPath);
+    return branchManagement.manageProjectBranch({ ...input, projectPath: path }, withManagementFolders);
+  }
+
+  return { getProjectBranchMenu, selectProjectBranch, mergeProjectBranch, inspectProjectBranch, manageProjectBranch };
 }