mixdog 1.2.3 → 1.2.4

package/src/session-runtime/tool-policy-refresh.mjs

@@ -4,17 +4,23 @@
 // updated policy.
 import { sessionHasConversationMessages } from '../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import { toSessionWorkflowMeta } from '../runtime/agent/orchestrator/runtime-core/workflow.mjs';
-import { applyDeferredToolSurface, filterDisallowedTools } from '../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
+import {
+  applyDeferredToolSurface,
+  filterDisallowedTools,
+} from '../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
 import { deferredSurfaceModeForLead } from '../runtime/agent/orchestrator/runtime-core/effort.mjs';
 import {
   applyInitialDeferredToolManifestToBp2,
   composeSystemPrompt,
 } from '../runtime/agent/orchestrator/context/collect.mjs';
+import { _buildBaseRules } from '../runtime/agent/orchestrator/session/manager/rules-cache.mjs';
+import { sessionRolePromptFields } from '../runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs';
 import {
-  _buildBaseRules,
-  _buildLeadRules,
-  _buildLeadLanguageContext,
-} from '../runtime/agent/orchestrator/session/manager/rules-cache.mjs';
+  delegationDisabled,
+  honoredSchemaAllowlist,
+} from '../runtime/agent/orchestrator/session/manager/session-tool-surface.mjs';
+import { finalizeSessionToolList } from '../runtime/agent/orchestrator/session/manager/tool-resolution.mjs';
+import { isAgentOwner } from '../runtime/agent/orchestrator/agent-owner.mjs';
 import { unusedModelEditToolName } from '../runtime/shared/edit-tool-dialect.mjs';
 
 function toolNames(list) {
@@ -69,6 +75,7 @@ export function createToolPolicyRefresh({
   getMode,
   getConfig,
   getDataDir,
+  getActiveTurnCount,
   modelStandaloneTools,
   featureDisallowedTools,
   loadCoreMemoryContext,
@@ -78,13 +85,23 @@ export function createToolPolicyRefresh({
 }) {
   // Denied tools leave every surface, then the deferred surface is rebuilt
   // for the lead's current mode.
-  function applyToolDenials(session, denied) {
+  function applyToolDenials(session, denied, schemaAllowedTools, ownerIsAgent) {
     session.disallowedTools = denied;
     session.tools = filterDisallowedTools(session.tools, denied);
     if (Array.isArray(session.deferredToolCatalog)) {
       session.deferredToolCatalog = filterDisallowedTools(session.deferredToolCatalog, denied);
     }
-    applyDeferredToolSurface(session, deferredSurfaceModeForLead(getMode()), modelStandaloneTools(), {
+    const catalogTools = finalizeSessionToolList(modelStandaloneTools(), {
+      schemaAllowedTools,
+      disallowedTools: denied,
+      ownerIsAgent,
+    });
+    session.tools = finalizeSessionToolList(session.tools, {
+      schemaAllowedTools,
+      disallowedTools: denied,
+      ownerIsAgent,
+    });
+    applyDeferredToolSurface(session, deferredSurfaceModeForLead(getMode()), catalogTools, {
       provider: getRoute()?.provider,
     });
     const catalog = Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : [];
@@ -101,16 +118,40 @@ export function createToolPolicyRefresh({
     }
   }
 
+  // A turn is executing from the moment it opens until it settles, even when
+  // its transcript holds only notifications (which are not conversation
+  // content). Its tool surface is frozen for that whole span.
+  function turnInFlight(session) {
+    return (getActiveTurnCount?.() || 0) > 0 || Array.isArray(session.liveTurnMessages);
+  }
+
+  // Admission: the session is still the current one, no turn is executing and
+  // no conversation has started. Checked before staging and again right
+  // before the staged change is applied.
+  function admitsRefresh(session) {
+    return (
+      getSession?.() === session &&
+      !turnInFlight(session) &&
+      !sessionHasConversationMessages(session) &&
+      !sessionHasConversationMessages({ messages: session.liveTurnMessages })
+    );
+  }
+
   async function refreshEmptySessionToolPolicy() {
     invalidatePreSessionToolSurface?.();
     const session = getSession?.();
     if (!session?.id) return { appliedToCurrentSession: true };
-    if (
-      sessionHasConversationMessages(session) ||
-      sessionHasConversationMessages({ messages: session.liveTurnMessages })
-    ) {
-      return { appliedToCurrentSession: false };
-    }
+    if (!admitsRefresh(session)) return { appliedToCurrentSession: false };
+    // Older records contain only compiled prompt text; rebuilding would guess
+    // away custom instructions. Keep that immutable material for every owner.
+    const identity = session.promptIdentity;
+    if (!identity) return { appliedToCurrentSession: false, reason: 'missing-prompt-identity' };
+    const ownerIsAgent = isAgentOwner(session);
+    const schemaAllowedTools = honoredSchemaAllowlist(session.schemaAllowedTools, {
+      ownerIsAgent,
+      agent: identity.agent,
+    });
+    const toolFreeRole = ownerIsAgent && schemaAllowedTools?.length === 0;
 
     const {
       summary: workflow,
@@ -118,34 +159,44 @@ export function createToolPolicyRefresh({
       packContext,
       orchestrationMode,
     } = activeWorkflowContext(getConfig(), getDataDir());
-    const workflowContext = session.owner === 'agent' ? packContext : leadWorkflowContext;
-    const denied = [...featureDisallowedTools(), ...(workflow?.delegatesAgents === false ? ['agent'] : [])]
+    const workflowContext = ownerIsAgent ? packContext : leadWorkflowContext;
+    const denied = [
+      ...session.callerDisallowedTools,
+      ...featureDisallowedTools(),
+      ...(workflow?.delegatesAgents === false ? ['agent'] : []),
+    ]
       .map((name) => String(name || ''))
       .filter(Boolean);
-    session.workflow = toSessionWorkflowMeta(workflow);
-    session.orchestrationMode = orchestrationMode;
-    applyToolDenials(session, denied);
 
-    const allowsAgents = workflow?.delegatesAgents !== false;
-    const baseRules = _buildBaseRules({
-      omitTools: [...denied, unusedModelEditToolName(getRoute()?.model)],
-      allowTools: session.schemaAllowedTools,
-      provider: getRoute()?.provider,
-      model: getRoute()?.model,
-    });
-    const roleRules = _buildLeadRules({ includeLeadBrief: allowsAgents });
+    // Stage: everything below is computed without touching the session, so a
+    // turn that starts during the async rebuild cannot lose tools to it.
+    const baseRules =
+      identity.skipAgentRules || toolFreeRole
+        ? ''
+        : _buildBaseRules({
+            omitTools: [...denied, unusedModelEditToolName(getRoute()?.model)],
+            allowTools: schemaAllowedTools,
+            provider: getRoute()?.provider,
+            model: getRoute()?.model,
+          });
     const coreMemoryContext = await leadCoreMemoryContext();
     const { sessionMarkerCore } = composeSystemPrompt({
-      roleRules,
-      skipRoleCatalog: true,
+      ...sessionRolePromptFields(identity, {
+        ownerIsAgent,
+        toolFreeRole,
+        delegationFree: delegationDisabled(session, ownerIsAgent),
+      }),
+      provider: getRoute()?.provider,
       workflowContext,
       coreMemoryContext,
       // The rebuilt core keeps (or newly applies) the instruction-files setting.
-      instructionFilesContext: loadInstructionFilesContext?.(session) || null,
-      // BP3 rebuild must keep the trailing language block, or a workflow
-      // switch would silently drop the response-language directive.
-      languageContext: _buildLeadLanguageContext(),
+      instructionFilesContext: toolFreeRole ? null : loadInstructionFilesContext?.(session) || null,
     });
+    // Apply: re-check admission after the await, then mutate synchronously.
+    if (!admitsRefresh(session)) return { appliedToCurrentSession: false };
+    session.workflow = toSessionWorkflowMeta(workflow);
+    session.orchestrationMode = orchestrationMode;
+    applyToolDenials(session, denied, schemaAllowedTools, ownerIsAgent);
     rewriteSystemHeading(session, '# Tool Use', baseRules);
     rewriteBp3Core(session, sessionMarkerCore);
     session.updatedAt = Date.now();

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

@@ -3,7 +3,12 @@
  * runtime notifications, and the deferred tool surface (status + selection).
  */
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
-import { toolRow, toolSearchMatches, sortedNamesByMeasuredUsage, selectDeferredTools } from '../../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
+import {
+  toolRow,
+  toolSearchMatches,
+  sortedNamesByMeasuredUsage,
+  selectDeferredTools,
+} from '../../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
 
 function splitToolStatusCounts(rows) {
   const list = Array.isArray(rows) ? rows : [];
@@ -67,6 +72,39 @@ export function createAgentOps(deps) {
     });
   }
 
+  // Explicit user force-release ("Release anyway") of a shell job whose
+  // termination is unconfirmed: drops its workspace hold. The surface has
+  // already asked the user to confirm. The caller session's own holds, and
+  // holds of a closed session whose workspace this session's folder sees.
+  async function releaseShellJob(taskId) {
+    const session = getSession();
+    const { forceReleaseTerminationHold } = await import(
+      '../../runtime/agent/orchestrator/tools/builtin/lib/shell-job-records.mjs'
+    );
+    return forceReleaseTerminationHold(taskId, {
+      callerSessionId: session?.id || null,
+      callerCwd: getCurrentCwd?.() || null,
+    });
+  }
+
+  // This session's live shell jobs (the readout rows), each carrying
+  // `terminationUnconfirmed` when it is held without confirmed termination,
+  // plus held shells a closed session left in a workspace this session sees.
+  async function listShellJobs() {
+    const session = getSession();
+    const { shellJobsStatusFresh, shellJobVisibleFrom } = await import(
+      '../../runtime/shared/statusline/statusline-segments.mjs'
+    );
+    const status = await shellJobsStatusFresh({ clientHostPid: session?.clientHostPid || process.pid });
+    const own = session?.id ? status?.sessions?.[session.id]?.jobs : status?.jobs;
+    const jobs = Array.isArray(own) ? [...own] : [];
+    const cwd = getCurrentCwd?.() || null;
+    for (const job of status?.orphaned || []) {
+      if (shellJobVisibleFrom(job, cwd) && !jobs.some((row) => row.taskId === job.taskId)) jobs.push(job);
+    }
+    return { jobs };
+  }
+
   function onNotification(listener) {
     if (typeof listener !== 'function') return () => {};
     const sessionId = getSession()?.id || getReservedSessionId?.() || '';
@@ -105,5 +143,14 @@ export function createAgentOps(deps) {
     return { ...result, status: toolsStatus() };
   }
 
-  return { agentControl, taskControl, stopShellJob, onNotification, toolsStatus, selectTools };
+  return {
+    agentControl,
+    taskControl,
+    stopShellJob,
+    releaseShellJob,
+    listShellJobs,
+    onNotification,
+    toolsStatus,
+    selectTools,
+  };
 }

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

@@ -3,10 +3,7 @@
  * 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';
+import { askSideQuestion, cancelSideQuestion } from '../../runtime/agent/orchestrator/session/side-question.mjs';
 
 export function createSideQuestionOps({ getSession, getReservedSessionId }) {
   const sessionId = () => getSession()?.id || getReservedSessionId?.() || '';

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

@@ -75,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());
 
@@ -129,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

@@ -86,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?.();
@@ -101,6 +106,7 @@ 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

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/.
@@ -49,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;
@@ -69,28 +56,7 @@ 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);
@@ -129,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

@@ -251,7 +251,10 @@ export function createUsageStatsApi({
       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)))])
+        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');
@@ -114,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 };
 }