mixdog 1.1.2 → 1.2.0

package/src/session-runtime/setup-tool/tool-defs.mjs

@@ -6,6 +6,7 @@ import {
 } from './settings-contract.mjs';
 import { MEDIA_KINDS } from '../../runtime/media/tool-defs.mjs';
 import { INSTRUCTION_FILES_MODES } from '../../runtime/shared/instruction-files-mode.mjs';
+import { WORKTREE_NEW_TASK_DEFAULTS } from '../../runtime/shared/worktrees/settings.mjs';
 
 /** Built-in `setup` tool: the model's handle on a Mixdog user's persisted
  *  configuration. The description is a contract only; how to use each action
@@ -31,6 +32,7 @@ export const SETUP_STATUS_DOMAINS = Object.freeze([
   'plugins',
   'update',
   'onboarding',
+  'worktree',
   ...SETUP_EXTENDED_DOMAINS,
 ]);
 
@@ -100,7 +102,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   save_mcp_server: 'server',
   remove_mcp_server: 'name',
   set_mcp_enabled: 'name enabled',
-  reconnect_mcp: '',
+  reconnect_mcp: 'name?',
   set_disabled_skills: 'skills',
   set_extension_scope: 'kind name projects',
   add_plugin: 'source',
@@ -108,6 +110,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   set_plugin_enabled: 'name enabled',
   remove_plugin: 'name',
   enable_plugin_mcp: 'name',
+  set_worktree_settings: 'worktree',
   ...SETUP_EXTENDED_ACTION_FIELDS,
 });
 
@@ -122,6 +125,7 @@ export const SETUP_BUILTIN_TOGGLE_FEATURES = Object.freeze([
   'browser',
   'computer',
   'voice',
+  'visualize',
 ]);
 
 const ROUTE_SCHEMA = {
@@ -136,6 +140,11 @@ const ROUTE_SCHEMA = {
     // A typed enum is unrepresentable on Gemini; the bounds project everywhere
     // and the executor rejects values that are not a multiple of 10.
     contextPercent: { type: 'integer', minimum: 10, maximum: 100, description: 'A multiple of 10.' },
+    contextTokens: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Exact context window in tokens; overrides contextPercent, clamped to 10%-100% of the model window.',
+    },
     disabled: {
       type: 'boolean',
       description: 'Agent routes only: true disables without losing the route; false re-enables.',
@@ -176,7 +185,7 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         route: {
           ...ROUTE_SCHEMA,
           description:
-            'Partial route update; omitted fields are preserved. Agent or Web Search provider "" restores Main inheritance. contextPercent applies to Main and agent routes only.',
+            'Partial route update; omitted fields are preserved. Agent or Web Search provider "" restores Main inheritance. contextPercent and contextTokens apply to Main and agent routes only.',
         },
         agent: { type: 'string', description: 'set_agent_route: agent id.' },
         workflow: { type: 'string', description: 'set_workflow: pack id.' },
@@ -222,7 +231,7 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         },
         name: {
           type: 'string',
-          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; else MCP/plugin/provider id.`,
+          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; reconnect_mcp: optional MCP server name (omit for all); else MCP/plugin/provider id.`,
         },
         accountId: {
           type: 'string',
@@ -320,6 +329,25 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           items: { type: 'string', minLength: 1, pattern: '\\S' },
           description: 'set_extension_scope: required project roots; [] = every project.',
         },
+        worktree: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            newTaskDefault: {
+              type: 'string',
+              enum: [...WORKTREE_NEW_TASK_DEFAULTS],
+              description: 'branch = new tasks use the current branch (default); worktree = a new worktree.',
+            },
+            branchPrefix: { type: 'string', description: 'Ref prefix ending with "/"; default "mixdog/".' },
+            sizeWarnBytes: {
+              type: 'integer',
+              minimum: 0,
+              description: 'Repository size that asks for confirmation first; 0 never asks.',
+            },
+            autoCleanup: { type: 'boolean', description: 'Remove clean, merged worktrees when their task ends.' },
+          },
+          description: 'set_worktree_settings: only the given fields change.',
+        },
         ...SETUP_EXTENDED_PROPERTIES,
       },
     },

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

@@ -56,6 +56,17 @@ export function createAgentOps(deps) {
     });
   }
 
+  // Stop one background shell job of THIS session through the task tool's
+  // cancel path; the answer is structured so a surface never parses text.
+  async function stopShellJob(taskId) {
+    const session = getSession();
+    const { stopBackgroundShellJob } = await import('../../runtime/agent/orchestrator/tools/builtin/task-tool.mjs');
+    return stopBackgroundShellJob(taskId, {
+      callerSessionId: session?.id || null,
+      clientHostPid: session?.clientHostPid || process.pid,
+    });
+  }
+
   function onNotification(listener) {
     if (typeof listener !== 'function') return () => {};
     const sessionId = getSession()?.id || getReservedSessionId?.() || '';
@@ -94,5 +105,5 @@ export function createAgentOps(deps) {
     return { ...result, status: toolsStatus() };
   }
 
-  return { agentControl, taskControl, onNotification, toolsStatus, selectTools };
+  return { agentControl, taskControl, stopShellJob, onNotification, toolsStatus, selectTools };
 }

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

@@ -55,18 +55,28 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
     };
   }
 
+  // The turn's change-record key rides the caller's transcript metadata (in
+  // place: the stream stamps assistantAt on this same object), so the
+  // persisted user row and completion carry it across restore.
+  function stampCheckpoint(options) {
+    const meta = options.transcriptMeta;
+    const checkpointId = String(options.id || '').trim();
+    if (checkpointId && meta && typeof meta === 'object') meta.checkpointId = checkpointId;
+    return meta;
+  }
+
   function askCallbacks(turn, session0, options) {
     return {
       beforeToolExecution: () => turn.snapshot.promise || Promise.resolve(),
-      transcriptMeta: options.transcriptMeta,
+      transcriptMeta: stampCheckpoint(options),
       promptSource: options.promptSource,
       retryFailedTurn: options.retryFailedTurn === true,
       onTextDelta: options.onTextDelta,
       onTextReset: options.onTextReset,
       onReasoningDelta: options.onReasoningDelta,
-      onAssistantText: (text) => {
+      onAssistantText: (text, detail) => {
         transcript.appendAssistantText(text);
-        return options.onAssistantText?.(text);
+        return options.onAssistantText?.(text, detail);
       },
       onUsageDelta: options.onUsageDelta,
       onAssistantToolCallObserved: options.onAssistantToolCallObserved,

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

@@ -1,25 +1,21 @@
 import { settleWithin } from '../../../runtime/shared/abort-race.mjs';
 
-// Worktree snapshot for the turn review. Captured immediately, but never on
-// the first-token critical path: every actual tool execution joins the same
-// promise, so shell/apply_patch cannot mutate the worktree before the baseline.
+// Worktree snapshot for the turn review. Captured as soon as the turn's
+// workspace is final (after any lazy worktree provisioning, so the baseline is
+// taken in the root the turn runs in), but never on the first-token critical
+// path: every actual tool execution joins the same promise, so
+// shell/apply_patch cannot mutate the worktree before the baseline.
 export function createSnapshotTrackerFactory({
   getCurrentCwd,
   beginTurnSnapshotForTurn,
-  cancelTurnSnapshotForTurn,
   completeTurnSnapshotForTurn,
   turnCleanupSettleMs,
 }) {
   return function createSnapshotTracker(options) {
+    // `promise` resolves to the turn token beginTurnSnapshot returns
+    // (`{ generation, checkpointId }`), or undefined when nothing began.
     const tracker = { sessionId: null, promise: null };
-    // A completion wake continues the user turn whose review already exists;
-    // aborting the wake seals that review instead of discarding it.
     const continueTurn = options.continueTurn === true;
-    const cancel = () => {
-      try {
-        cancelTurnSnapshotForTurn(tracker.sessionId);
-      } catch {}
-    };
     tracker.start = (sessionId) => {
       const id = typeof sessionId === 'string' ? sessionId.trim() : '';
       if (!id || (tracker.promise && tracker.sessionId === id)) return;
@@ -36,19 +32,28 @@ export function createSnapshotTrackerFactory({
         .catch(() => undefined);
     };
     tracker.finish = async (signal, awaitTurn) => {
+      // A turn refused before its workspace was final never began a review.
+      if (!tracker.promise) return;
+      // Captured now: a later start (or the next turn) cannot redirect this seal.
+      const sessionId = tracker.sessionId;
+      const started = Promise.resolve(tracker.promise);
       if (signal.aborted && !continueTurn) {
-        cancel();
-        void Promise.resolve(tracker.promise).catch(() => {});
+        // A cancelled turn keeps its edits as a change record. Sealing waits
+        // for the snapshot start, never for the abort's settlement, and only
+        // seals the generation this turn began: delayed cleanup cannot seal
+        // a newer turn.
+        void started
+          .then((token) => (token ? completeTurnSnapshotForTurn(sessionId, token) : undefined))
+          .catch(() => {});
         return;
       }
-      const cleanup = Promise.resolve(tracker.promise).then(() => completeTurnSnapshotForTurn(tracker.sessionId));
+      const cleanup = started.then((token) => completeTurnSnapshotForTurn(sessionId, token));
       cleanup.catch(() => {});
       try {
         await awaitTurn(() => settleWithin(cleanup, turnCleanupSettleMs));
       } catch {
         /* optional review cleanup never overrides turn settlement */
       }
-      if (signal.aborted && !continueTurn) cancel();
     };
     return tracker;
   };

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

@@ -1,13 +1,11 @@
 import { runAbortable } from '../../../runtime/shared/abort-race.mjs';
 
 // Opens one turn: abort controller registration, timing, the worktree
-// snapshot tracker, the active-turn count and the one-shot heavy-runtime
-// warmup arm.
+// snapshot tracker (started by session preparation once the turn's workspace
+// is final), the active-turn count and the one-shot heavy-runtime warmup arm.
 export function createTurnOpener({
   createTiming,
   createSnapshot,
-  getSession,
-  getReservedSessionId,
   registerActiveTurnController,
   getActiveTurnCount,
   setActiveTurnCount,
@@ -41,7 +39,6 @@ export function createTurnOpener({
     const signal = controller.signal;
     const snapshot = createSnapshot(options);
     const routeStartedAt = performance.now();
-    snapshot.start(getSession()?.id || getReservedSessionId?.());
     setActiveTurnCount(getActiveTurnCount() + 1);
     return {
       signal,
@@ -54,6 +51,8 @@ export function createTurnOpener({
       armHeavyRuntimeWarmup: heavyRuntimeWarmupArm(),
       session0: null,
       releaseFirstTitle: null,
+      /** Set by turn admission (admitTurnWorkspace); released by settleTurn. */
+      releaseWorkspace: null,
       startedAt: Date.now(),
     };
   };

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

@@ -21,6 +21,8 @@ export function createTurnPreparation({
   agentTool,
   getConfig,
   assertSessionAdmission,
+  prepareTurnWorkspace,
+  admitTurnWorkspace,
 }) {
   const scopedMcpTools = (session) => scopedMcpToolsFor(session, getConfig());
 
@@ -84,7 +86,7 @@ export function createTurnPreparation({
   // Historical-session resume publishes its transcript immediately while
   // provider/model metadata initializes in the background. Only the next
   // actual turn waits, guaranteeing that it cannot run on a stale route.
-  async function prepareSession(turn, prompt) {
+  async function prepareSession(turn, prompt, options = {}) {
     // A closing/closed addressed runtime admits no turn (checked again after
     // every await that could have outlived a close).
     assertSessionAdmission?.();
@@ -96,6 +98,32 @@ export function createTurnPreparation({
     }
     throwIfAborted(turn.signal);
     assertSessionAdmission?.();
+    // Turn admission: waits while this session's workspace transitions or
+    // another session changes the checkout this session works in, then holds
+    // the turn registered (released by settleTurn) so no checkout changes
+    // under it.
+    if (typeof admitTurnWorkspace === 'function') {
+      turn.releaseWorkspace = await admitTurnWorkspace({ signal: turn.signal });
+      throwIfAborted(turn.signal);
+      assertSessionAdmission?.();
+    }
+    // Workspace gate: a session in recovery refuses the turn, and a pending
+    // worktree intent is provisioned and applied (cwd, record, prompt context)
+    // BEFORE the user row, the review snapshot, hooks, the provider and any
+    // worker spawn. The submission id is the provisioning transaction id, so a
+    // retried or duplicate send reuses the same worktree.
+    if (typeof prepareTurnWorkspace === 'function') {
+      await turn.awaitTurn(() =>
+        prepareTurnWorkspace({
+          submissionId: String(options.id || '').trim(),
+          prompt,
+          signal: turn.signal,
+          confirmLarge: options.confirmLarge === true,
+        })
+      );
+      throwIfAborted(turn.signal);
+      assertSessionAdmission?.();
+    }
     ensureSessionTranscriptWriter?.();
     transcript.appendUser(prompt);
     const session0 = getSession();

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

@@ -84,7 +84,12 @@ export function createTurnSettlement({
     turn.releaseFirstTitle?.();
     turn.emitTiming(turn.timing.status);
     turn.armHeavyRuntimeWarmup('turn-settled');
-    await turn.snapshot.finish(turn.signal, turn.awaitTurn);
+    try {
+      await turn.snapshot.finish(turn.signal, turn.awaitTurn);
+    } finally {
+      // The turn no longer works in its checkout: transitions may proceed.
+      turn.releaseWorkspace?.();
+    }
     try {
       turn.unregister?.();
     } catch {}

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

@@ -1,10 +1,11 @@
 /**
  * src/session-runtime/turn/turn-run.mjs - one user turn end to end: viewer
- * forwarding, turn open (abort controller, timing, worktree snapshot, warmup
- * arming), session preparation, the askSession callback bridge, and the
- * settlement that always runs. The phases live under turn-run/.
+ * forwarding, 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/.
  */
-import { beginTurnSnapshot, cancelTurnSnapshot, completeTurnSnapshot } from '../../runtime/shared/turn-snapshot.mjs';
+import { beginTurnSnapshot, completeTurnSnapshot } from '../../runtime/shared/turn-snapshot.mjs';
 import { runWithCwdOverride } from '../../runtime/shared/user-cwd.mjs';
 import { createTurnTranscript } from './turn-run/transcript.mjs';
 import { createTurnTimingFactory } from './turn-run/turn-timing.mjs';
@@ -23,7 +24,6 @@ export function createTurnRunner(deps) {
     endComputerExecution = async () => false,
     deferComputerSessionRelease = () => false,
     beginTurnSnapshotForTurn = beginTurnSnapshot,
-    cancelTurnSnapshotForTurn = cancelTurnSnapshot,
     completeTurnSnapshotForTurn = completeTurnSnapshot,
     turnCleanupSettleMs = 2_000,
     getConfig = () => null,
@@ -35,7 +35,6 @@ export function createTurnRunner(deps) {
     createSnapshot: createSnapshotTrackerFactory({
       getCurrentCwd,
       beginTurnSnapshotForTurn,
-      cancelTurnSnapshotForTurn,
       completeTurnSnapshotForTurn,
       turnCleanupSettleMs,
     }),
@@ -93,7 +92,7 @@ export function createTurnRunner(deps) {
     if (attachedSession?.remoteAttached) return forwardAttachedPrompt(attachedSession, prompt, options);
     const turn = openTurn(options);
     try {
-      const session0 = await prepareSession(turn, prompt);
+      const session0 = await prepareSession(turn, prompt, options);
       const turnContext = await dispatchPromptSubmit(turn, session0, prompt, options);
       const result = await mgr.askSession(
         session0.id,

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

@@ -3,7 +3,7 @@ import { hasOwn } from '../../runtime/shared/object.mjs';
 import { isHiddenAgent } from '../../runtime/agent/orchestrator/internal-agents.mjs';
 import { normalizeWorkflowRoute } from '../../runtime/agent/orchestrator/runtime-core/workflow.mjs';
 import { ensureProviderEnabled } from '../../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
-import { selectionFastCapable } from '../route-state.mjs';
+import { resolveRouteContextState, selectionFastCapable } from '../route-state.mjs';
 import { canonicalizeAgentRouteStorage, withAgentDisabled } from '../../runtime/shared/agent-route-config.mjs';
 import { agentEditorId } from './shared.mjs';
 
@@ -43,19 +43,31 @@ export function createAgentRouteApi(deps) {
       clean(selectedRoute.provider) === clean(stored.provider) && clean(selectedRoute.model) === clean(stored.model);
     const inheritedEffort = sameModel ? stored.effort || null : null;
     const inheritedModelParameters = sameModel ? stored.modelParameters || {} : {};
-    const inheritedContextPercent = sameModel ? stored.contextPercent : undefined;
+    // A requested percent replaces the stored exact window and requested
+    // tokens replace the stored percent.
+    const requestsPercent = requested.contextPercent !== undefined;
+    const requestsTokens = requested.contextTokens !== undefined;
+    const inheritedContextPercent = sameModel && !requestsTokens ? stored.contextPercent : undefined;
+    const inheritedContextTokens = sameModel && !requestsPercent ? stored.contextTokens : undefined;
     selectedRoute = {
       ...selectedRoute,
       effort: requested.effort !== undefined ? selectedRoute.effort : inheritedEffort,
       fast: requested.fast !== undefined ? selectedRoute.fast === true : sameModel && stored.fast === true,
+      // Main's modelSettings bucket must not decide an agent's Auto effort.
+      autoEffort:
+        requested.autoEffort !== undefined ? requested.autoEffort !== false : !sameModel || stored.autoEffort !== false,
       modelParameters:
         requested.modelParameters !== undefined ? selectedRoute.modelParameters : inheritedModelParameters,
       // resolveRoute reads contextPercent from Main's modelSettings bucket;
       // an agent route owns its own.
-      contextPercent: requested.contextPercent !== undefined ? requested.contextPercent : inheritedContextPercent,
+      contextPercent: requestsPercent ? requested.contextPercent : inheritedContextPercent,
+      contextTokens: requestsTokens ? requested.contextTokens : inheritedContextTokens,
     };
     await ensureProvidersReady(ensureProviderEnabled(getConfig(), selectedRoute.provider));
     const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model);
+    // Stored clamped, and not at all at the default window, as for Main.
+    const contextState = resolveRouteContextState(selectedRoute, modelMeta);
+    if (contextState.contextDefaultPercent !== undefined) selectedRoute.contextTokens = contextState.contextTokens;
     const fastCapable = selectionFastCapable(
       selectedRoute.provider,
       modelMeta,

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;
+}