mixdog 1.3.0 → 1.3.2

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

@@ -1,125 +1,14 @@
 // Refresh the empty Lead session's model-facing tool surface and BP1/BP3
 // layers after workflow or search/memory settings change. Conversation
 // sessions keep their frozen schema; the next new session picks up the
-// updated policy. The one exception is a workflow switch made in the session
-// itself (switchSessionWorkflow), which rebuilds that conversation's policy.
+// updated policy. The exceptions are a workflow or orchestration mode switch
+// made in the session itself (switchSessionWorkflow,
+// switchSessionOrchestrationMode), which that conversation takes as an overlay.
 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 { 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 {
-  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 {
-  AGENT_MODE,
-  isRoutineSource,
-  resolveSessionMode,
-  sessionModeOf,
-} from '../runtime/agent/orchestrator/session/agent-mode.mjs';
-import { unusedModelEditToolName } from '../runtime/shared/edit-tool-dialect.mjs';
-import { MIXY_AGENT_ID } from '../runtime/agent/orchestrator/session/agent-home.mjs';
-import {
-  refreshSessionBp3Environment,
-  withPresentedWorkspaceSlices,
-} from '../runtime/agent/orchestrator/session/manager/prompt-utils.mjs';
-import { stageWorkflowSwitchNotice } from '../runtime/agent/orchestrator/session/manager/workflow-switch-notice.mjs';
-import { markToolSurfaceMigrated } from '../runtime/agent/orchestrator/session/loop/tool-exposure-migration.mjs';
-import { agentProfileRevision, leadRosterRevision } from '../runtime/agent/orchestrator/context/role-instructions.mjs';
-import { recordTranscriptBoundary } from './model-route/set-route.mjs';
-
-const WORKFLOW_SWITCH_BUSY = 'The session is running a turn; wait for it to finish.';
-const AGENT_PROFILE_INTENT = 'agent_profile';
-
-function toolNames(list) {
-  return (Array.isArray(list) ? list : [])
-    .map((item) => (typeof item === 'string' ? item : item?.name))
-    .filter(Boolean);
-}
-
-function replaceMessageContent(messages, target, content) {
-  const index = messages.indexOf(target);
-  if (index < 0) return false;
-  messages[index] = { ...target, content };
-  return true;
-}
-
-function rewriteSystemHeading(session, heading, nextContent) {
-  if (!nextContent) return;
-  const messages = Array.isArray(session.messages) ? session.messages : [];
-  const target = messages.find(
-    (message) =>
-      message?.role === 'system' && typeof message.content === 'string' && message.content.startsWith(heading)
-  );
-  if (target) replaceMessageContent(messages, target, nextContent);
-}
-
-function bp3Message(session) {
-  const messages = Array.isArray(session.messages) ? session.messages : [];
-  return (
-    messages.find((message) => message?.role === 'system' && message.cacheTier === 'tier3') ||
-    messages.find(
-      (message) =>
-        message?.role === 'system' &&
-        typeof message.content === 'string' &&
-        message.content.startsWith('# Active Workflow:')
-    )
-  );
-}
-
-// The BP3 core the session's prompt carries now (split layout: the whole
-// tier3 block; combined: the stored core beside the environment).
-function presentedBp3Core(session) {
-  return session.bp3EnvSplit === true ? bp3Message(session)?.content : session.bp3CoreContext;
-}
-
-function rewriteBp3Core(session, nextCore) {
-  const messages = Array.isArray(session.messages) ? session.messages : [];
-  const bp3 = bp3Message(session);
-  if (!bp3 || typeof bp3.content !== 'string') return;
-  if (session.bp3EnvSplit === true) {
-    // Split layout: the environment lives in its own cacheTier:'env' system
-    // block — the tier3 block carries the core only.
-    replaceMessageContent(messages, bp3, nextCore || '');
-    session.bp3CoreContext = nextCore || '';
-    return;
-  }
-  const env = session.bp3EnvironmentContext || '';
-  replaceMessageContent(messages, bp3, [nextCore, env].filter((part) => String(part || '').trim()).join('\n\n---\n\n'));
-  session.bp3CoreContext = nextCore || '';
-}
-
-// A Lead's workflow slices (orchestration, agent and contact catalogs) for its
-// mode, Mixy's with the contacts.
-function leadPartsFor(session, leadPromptParts) {
-  return leadPromptParts({
-    agentMode: sessionModeOf(session) === AGENT_MODE,
-    mixy: resolveSessionMode({ session }).agentId === MIXY_AGENT_ID,
-  });
-}
-
-// A conversation keeps its `# Session` block: the legacy combined layout
-// rebuilds the tier3 block from the new core (rooted where it was).
-function rewriteConversationBp3Core(session, nextCore) {
-  if (session.bp3EnvSplit !== true && typeof session.bp3CoreContext === 'string') {
-    const previous = session.bp3CoreContext;
-    session.bp3CoreContext = nextCore;
-    if (refreshSessionBp3Environment(session, session.cwd)) return;
-    session.bp3CoreContext = previous;
-  }
-  rewriteBp3Core(session, nextCore);
-}
+import { createAgentProfileFold } from './tool-policy/agent-profile-fold.mjs';
+import { createPolicyStage } from './tool-policy/policy-stage.mjs';
+import { createSessionSwitches } from './tool-policy/session-switches.mjs';
+import { rewriteBp3Core } from './tool-policy/surface-helpers.mjs';
 
 export function createToolPolicyRefresh({
   getSession,
@@ -134,41 +23,18 @@ export function createToolPolicyRefresh({
   loadInstructionFilesContext,
   activeWorkflowContext,
   invalidatePreSessionToolSurface,
+  persistSession,
 }) {
-  // Denied tools leave every surface, then the deferred surface is rebuilt
-  // for the lead's current mode.
-  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);
-    }
-    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 : [];
-    const active = new Set(toolNames(session.tools).concat(toolNames(session.deferredCallableTools)));
-    const pool = catalog.map((tool) => String(tool?.name || '')).filter((name) => name && !active.has(name));
-    applyInitialDeferredToolManifestToBp2(session, pool, { rebuild: true });
-  }
-
-  async function leadCoreMemoryContext() {
-    try {
-      return await loadCoreMemoryContext();
-    } catch {
-      return '';
-    }
-  }
+  const { liveDeniedTools, stagePolicy, applyPolicy } = createPolicyStage({
+    getRoute,
+    getMode,
+    getDataDir,
+    modelStandaloneTools,
+    featureDisallowedTools,
+    loadCoreMemoryContext,
+    loadInstructionFilesContext,
+    activeWorkflowContext,
+  });
 
   // A turn is executing from the moment it opens until it settles, even when
   // its transcript holds only notifications (which are not conversation
@@ -189,84 +55,6 @@ export function createToolPolicyRefresh({
     );
   }
 
-  // The policy `config` gives `session`, computed without touching the
-  // session, so a turn that starts during the async rebuild cannot lose tools
-  // to it. `conversation`: the rebuilt BP3 core keeps the instruction files
-  // and core memory the prompt presents now (withPresentedWorkspaceSlices).
-  async function stagePolicy(session, identity, config, { conversation = false } = {}) {
-    const ownerIsAgent = isAgentOwner(session);
-    const schemaAllowedTools = honoredSchemaAllowlist(session.schemaAllowedTools, {
-      ownerIsAgent,
-      agent: identity.agent,
-    });
-    const toolFreeRole = ownerIsAgent && schemaAllowedTools?.length === 0;
-
-    const {
-      summary: workflow,
-      leadPromptParts,
-      packContext: workflowContext,
-      orchestrationMode,
-    } = activeWorkflowContext(config, getDataDir());
-    const sessionMode = sessionModeOf(session);
-    const agentMode = sessionMode === AGENT_MODE;
-    const leadWorkflowParts = ownerIsAgent ? {} : leadPartsFor(session, leadPromptParts);
-    const denied = [
-      ...session.callerDisallowedTools,
-      ...featureDisallowedTools(),
-      ...(workflow?.delegatesAgents === false ? ['agent'] : []),
-    ]
-      .map((name) => String(name || ''))
-      .filter(Boolean);
-
-    const baseRules =
-      identity.skipAgentRules || toolFreeRole
-        ? ''
-        : _buildBaseRules({
-            omitTools: [...denied, unusedModelEditToolName(getRoute()?.model)],
-            allowTools: schemaAllowedTools,
-            provider: getRoute()?.provider,
-            model: getRoute()?.model,
-          });
-    const coreMemoryContext = conversation ? '' : await leadCoreMemoryContext();
-    const { sessionMarkerCore } = composeSystemPrompt({
-      ...sessionRolePromptFields(identity, {
-        ownerIsAgent,
-        toolFreeRole,
-        delegationFree: delegationDisabled(session, ownerIsAgent),
-        sessionMode,
-        routine: isRoutineSource(session.sourceType),
-      }),
-      provider: getRoute()?.provider,
-      workflowContext,
-      ...leadWorkflowParts,
-      coreMemoryContext,
-      // The rebuilt core keeps (or newly applies) the instruction-files
-      // setting; agent mode carries none.
-      instructionFilesContext:
-        conversation || toolFreeRole || agentMode ? null : loadInstructionFilesContext?.(session) || null,
-    });
-    return {
-      workflow,
-      orchestrationMode,
-      sessionMode,
-      denied,
-      schemaAllowedTools,
-      ownerIsAgent,
-      baseRules,
-      core: conversation ? withPresentedWorkspaceSlices(session, sessionMarkerCore) : sessionMarkerCore,
-    };
-  }
-
-  // Apply a staged policy synchronously; the BP3 core is the caller's.
-  function applyPolicy(session, staged) {
-    session.workflow = toSessionWorkflowMeta(staged.workflow);
-    session.orchestrationMode = staged.orchestrationMode;
-    session.sessionMode = staged.sessionMode;
-    applyToolDenials(session, staged.denied, staged.schemaAllowedTools, staged.ownerIsAgent);
-    rewriteSystemHeading(session, '# Tool Use', staged.baseRules);
-    session.updatedAt = Date.now();
-  }
-
   async function refreshEmptySessionToolPolicy() {
     invalidatePreSessionToolSurface?.();
     const session = getSession?.();
@@ -284,133 +72,34 @@ export function createToolPolicyRefresh({
     return { appliedToCurrentSession: true };
   }
 
-  /**
-   * Switch the current coding session's workflow mid-conversation (the
-   * composer's workflow selector): its prompt (BP3 core and `# Tool Use`) and
-   * tool/delegation surface are rebuilt now for `workflowId` with the current
-   * orchestration mode and agents, so its next turn runs on them, and that
-   * turn carries a one-time notice (manager/workflow-switch-notice.mjs). The
-   * provider prompt cache is rebuilt once. Refused while a turn runs, like a
-   * working-folder change. The configured workflow (the default for new
-   * sessions) is the caller's and stays as it is.
-   *
-   * Running work is untouched: agents and workers the session started under
-   * the old workflow are separate sessions with their own prompts and tools,
-   * so they keep running as they are (unlike a working-folder change, running
-   * agents never refuse this); only delegation made from the next turn on
-   * uses the new surface.
-   *
-   * Returns null when the session has no conversation (the caller applies the
-   * configured workflow to an empty session as before), else
-   * `{ appliedToCurrentSession: true, workflow, workflowSwitch }` where
-   * `workflowSwitch` is the transcript boundary (null when unchanged).
-   */
-  async function switchSessionWorkflow(workflowId) {
-    const session = getSession?.();
-    if (!session?.id) return null;
-    const conversation = () =>
-      sessionHasConversationMessages(session) || sessionHasConversationMessages({ messages: session.liveTurnMessages });
-    if (!conversation()) return null;
-    if (isAgentOwner(session) || sessionModeOf(session) === AGENT_MODE) {
-      throw new Error('Only a coding session has a workflow.');
-    }
-    const identity = session.promptIdentity;
-    if (!identity) throw new Error('This session is too old to switch its workflow; start a new task.');
-    const busy = () => getSession?.() !== session || turnInFlight(session);
-    if (busy()) throw new Error(WORKFLOW_SWITCH_BUSY);
-    const config = getConfig();
-    const staged = await stagePolicy(
-      session,
-      identity,
-      { ...config, workflow: { ...(config?.workflow || {}), active: workflowId } },
-      { conversation: true }
-    );
-    if (busy()) throw new Error(WORKFLOW_SWITCH_BUSY);
-    const before = session.workflow;
-    const from = before?.id ? before : null;
-    applyPolicy(session, staged);
-    rewriteConversationBp3Core(session, staged.core);
-    // The request prefix changed: drop provider replay state and the context
-    // baseline, and tag the next send's expected cache break.
-    markToolSurfaceMigrated(session, 'workflow_switch');
-    stageWorkflowSwitchNotice(session, from, session.workflow);
-    let workflowSwitch = null;
-    if (from?.id !== session.workflow.id) {
-      workflowSwitch = {
-        fromId: from?.id || '',
-        from: from?.name || from?.id || '',
-        toId: session.workflow.id,
-        to: session.workflow.name,
-        at: Date.now(),
-      };
-      recordTranscriptBoundary(session, 'workflowSwitches', workflowSwitch, (entry) => entry?.at === workflowSwitch.at);
-    }
-    return { appliedToCurrentSession: true, workflow: session.workflow, workflowSwitch };
-  }
-
-  // An agent profile edit that met a running turn: the next turn applies it.
-  let agentProfilePending = false;
-
-  /**
-   * Bring a Lead session's prompt to the saved bots — its own agent's
-   * persona, AGENT.md and name, and the bot roster its catalogs list — after
-   * a bot was saved, created, renamed, archived or restored
-   * (agent-profile-changes.mjs), on resume, or at the start of the turn after
-   * one that ran through the change (`trigger`: 'save' | 'resume' | 'turn').
-   * Two stamps (agentProfileRevision, agentRosterRevision) tell whether
-   * anything it embeds changed; a delegated worker keeps its prompt. The core
-   * is rebuilt like a workflow switch's (the session's own workflow, the
-   * workspace slices the model was told) and replaces the stored one, so the
-   * next turn sends it with one provider cache break; nothing is re-read per
-   * turn. Tools are untouched. Returns true when the prompt changed.
-   */
-  async function refreshAgentProfile({ trigger = 'save' } = {}) {
-    const session = getSession?.();
-    const identity = session?.promptIdentity;
-    const agent = identity?.agent;
-    if (!session?.id || !agent || isAgentOwner(session)) return false;
-    const revision = agentProfileRevision(agent);
-    const config = getConfig();
-    const workflowId = session.workflow?.id;
-    const workflowConfig = workflowId
-      ? { ...config, workflow: { ...(config?.workflow || {}), active: workflowId } }
-      : config;
-    const roster = leadRosterRevision(
-      leadPartsFor(session, activeWorkflowContext(workflowConfig, getDataDir()).leadPromptParts)
-    );
-    if (session.agentProfileRevision === revision && session.agentRosterRevision === roster) return false;
-    // A coding session from before profile stamps keeps its prompt when it
-    // is reopened; a saved edit still reaches it.
-    if (session.agentProfileRevision === undefined && trigger === 'resume' && sessionModeOf(session) !== AGENT_MODE) {
-      return false;
-    }
-    // At a turn's start its own turn is the one counted; nothing runs yet.
-    const busy = () => getSession?.() !== session || (trigger !== 'turn' && turnInFlight(session));
-    if (busy()) {
-      agentProfilePending = true;
-      return false;
-    }
-    const staged = await stagePolicy(session, identity, workflowConfig, { conversation: true });
-    if (busy()) {
-      agentProfilePending = true;
-      return false;
-    }
-    session.agentProfileRevision = revision;
-    session.agentRosterRevision = roster;
-    session.updatedAt = Date.now();
-    if (staged.core === presentedBp3Core(session)) return false;
-    rewriteConversationBp3Core(session, staged.core);
-    // The request prefix changed: one cache break, tagged on the next send.
-    markToolSurfaceMigrated(session, AGENT_PROFILE_INTENT);
-    return true;
-  }
-
-  /** Turn start: apply an edit that arrived while the previous turn ran. */
-  async function applyPendingAgentProfile() {
-    if (!agentProfilePending) return false;
-    agentProfilePending = false;
-    return refreshAgentProfile({ trigger: 'turn' });
-  }
+  const switches = createSessionSwitches({
+    getSession,
+    getConfig,
+    getDataDir,
+    modelStandaloneTools,
+    activeWorkflowContext,
+    persistSession,
+    liveDeniedTools,
+    turnInFlight,
+  });
+  const profile = createAgentProfileFold({
+    getSession,
+    getConfig,
+    getDataDir,
+    modelStandaloneTools,
+    activeWorkflowContext,
+    liveDeniedTools,
+    stagePolicy,
+    applyPolicy,
+    turnInFlight,
+  });
 
-  return { refreshEmptySessionToolPolicy, switchSessionWorkflow, refreshAgentProfile, applyPendingAgentProfile };
+  return {
+    refreshEmptySessionToolPolicy,
+    switchSessionWorkflow: switches.switchSessionWorkflow,
+    switchSessionOrchestrationMode: switches.switchSessionOrchestrationMode,
+    applyPendingSessionSwitches: switches.applyPendingSessionSwitches,
+    refreshAgentProfile: profile.refreshAgentProfile,
+    applyPendingAgentProfile: profile.applyPendingAgentProfile,
+  };
 }

package/src/session-runtime/tool-surface.mjs

@@ -15,6 +15,7 @@ import {
   filterModelToolsForProfile,
 } from '../runtime/agent/orchestrator/runtime-core/tool-profile.mjs';
 import { workflowDisallowsAgentTool } from '../runtime/agent/orchestrator/runtime-core/workflow.mjs';
+import { promptWorkflowOf } from '../runtime/agent/orchestrator/session/manager/workflow-switch-notice.mjs';
 import { configuredOrchestrationMode } from '../runtime/shared/orchestration.mjs';
 
 export function createToolSurface({
@@ -35,12 +36,13 @@ export function createToolSurface({
 }) {
   let preSessionSurface = null;
 
-  // A live session keeps its frozen capability; a new session uses current
-  // agents. Solo still offers the tool (deferred) for explicit user requests.
+  // A live session keeps its frozen capability (the workflow its prompt was
+  // built with, even after a mid-conversation switch); a new session uses
+  // current agents. Solo still offers the tool (deferred) for explicit user requests.
   function workflowAllowsAgents() {
     const session = getSession();
     if (session?.id || session?.workflow || session?.orchestrationMode) {
-      return !workflowDisallowsAgentTool(session?.workflow);
+      return !workflowDisallowsAgentTool(promptWorkflowOf(session));
     }
     return (delegatableAgentIds?.(getConfig(), cfgMod.getPluginData?.() || dataDir).length ?? 1) > 0;
   }

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

@@ -5,11 +5,75 @@ import {
 } from '../../../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
 import { throwIfAborted } from '../../../runtime/shared/abort-race.mjs';
 
+function scheduleFirstTitle(sessionTitles, session0, prompt) {
+  let resolve = null;
+  const after = new Promise((done) => {
+    resolve = done;
+  });
+  const release = () => {
+    if (!resolve) return;
+    const done = resolve;
+    resolve = null;
+    done();
+  };
+  try {
+    sessionTitles?.scheduleFirst(session0, prompt, { after });
+  } catch {
+    /* title fallback stays the preview */
+  }
+  return release;
+}
+
+async function foldMcpSurface(turn, session0, scopedMcpTools) {
+  // 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 (options) => {
+    try {
+      await turn.awaitTurn(() => turn.timing.awaitMcpGrace(options));
+    } catch {
+      /* gate must never break the turn */
+    }
+  };
+  if (session0.deferredInitialRefreshPending) {
+    // FIRST TURN of a FRESH session (session-local gate, NOT the process-wide
+    // firstTurnCompleted): an MCP server may have finished its handshake
+    // BETWEEN session-create and this first send. Re-fold the LIVE registry
+    // into the INITIAL provider-visible surface (sync, in-place, idempotent).
+    // 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;
+    // 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 {
+      /* first-turn MCP fold must never break the turn */
+    }
+    return;
+  }
+  await awaitGrace();
+  try {
+    // Persist a typed world-state delta on the session. askSession attaches
+    // it to THIS real prompt; reconciliation itself never enqueues a
+    // follow-up turn.
+    reconcileDeferredMcpToolCatalog(session0, scopedMcpTools(session0));
+  } catch {
+    /* MCP delta must never break the turn */
+  }
+}
+
 // Session preparation before askSession: route readiness, session creation,
 // transcript user row, first title, the MCP surface fold, and the
 // UserPromptSubmit hook.
 export function createTurnPreparation({
   getSession,
+  setSession,
+  mgr,
   getCurrentCwd,
   awaitRoutePreparation,
   createCurrentSession,
@@ -25,86 +89,9 @@ export function createTurnPreparation({
   admitTurnWorkspace,
   applyPendingRoute,
   applyPendingAgentProfile,
+  applyPendingSessionSwitches,
 }) {
-  const scopedMcpTools = (session) => scopedMcpToolsFor(session, getConfig());
-
-  function scheduleFirstTitle(session0, prompt) {
-    let resolve = null;
-    const after = new Promise((done) => {
-      resolve = done;
-    });
-    const release = () => {
-      if (!resolve) return;
-      const done = resolve;
-      resolve = null;
-      done();
-    };
-    try {
-      sessionTitles?.scheduleFirst(session0, prompt, { after });
-    } catch {
-      /* title fallback stays the preview */
-    }
-    return release;
-  }
-
-  async function foldMcpSurface(turn, session0) {
-    // 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 (options) => {
-      try {
-        await turn.awaitTurn(() => turn.timing.awaitMcpGrace(options));
-      } catch {
-        /* gate must never break the turn */
-      }
-    };
-    if (session0.deferredInitialRefreshPending) {
-      // FIRST TURN of a FRESH session (session-local gate, NOT the process-wide
-      // firstTurnCompleted): an MCP server may have finished its handshake
-      // BETWEEN session-create and this first send. Re-fold the LIVE registry
-      // into the INITIAL provider-visible surface (sync, in-place, idempotent).
-      // 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;
-      // 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 {
-        /* first-turn MCP fold must never break the turn */
-      }
-      return;
-    }
-    await awaitGrace();
-    try {
-      // Persist a typed world-state delta on the session. askSession attaches
-      // it to THIS real prompt; reconciliation itself never enqueues a
-      // follow-up turn.
-      reconcileDeferredMcpToolCatalog(session0, scopedMcpTools(session0));
-    } catch {
-      /* MCP delta must never break the turn */
-    }
-  }
-
-  // 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, options = {}) {
-    // A closing/closed addressed runtime admits no turn (checked again after
-    // every await that could have outlived a close).
-    assertSessionAdmission?.();
-    await turn.awaitTurn(() => awaitRoutePreparation?.());
-    assertSessionAdmission?.();
-    turn.timing.routeWaitMs = performance.now() - turn.routeStartedAt;
-    if (!getSession()?.id) {
-      await turn.awaitTurn(() => createCurrentSession('turn', { signal: turn.signal }));
-    }
-    throwIfAborted(turn.signal);
-    assertSessionAdmission?.();
+  async function admitWorkspace(turn, prompt, options) {
     // 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
@@ -131,11 +118,42 @@ export function createTurnPreparation({
       throwIfAborted(turn.signal);
       assertSessionAdmission?.();
     }
+  }
+
+  // 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, options = {}) {
+    // A closing/closed addressed runtime admits no turn (checked again after
+    // every await that could have outlived a close).
+    assertSessionAdmission?.();
+    await turn.awaitTurn(() => awaitRoutePreparation?.());
+    assertSessionAdmission?.();
+    turn.timing.routeWaitMs = performance.now() - turn.routeStartedAt;
+    if (!getSession()?.id) {
+      await turn.awaitTurn(() => createCurrentSession('turn', { signal: turn.signal }));
+    }
+    throwIfAborted(turn.signal);
+    assertSessionAdmission?.();
+    // askSession runs the turn on the session the store serves for this id.
+    // While this runtime idled, the store's idle sweep may have released the
+    // snapshot it holds, and the store then serves a fresh parse of the file:
+    // preparing the turn on the held copy would leave its one-shot work (the
+    // first-turn MCP fold, its flag) undone on the turn's session, which then
+    // rewrites the prompt it already sent on the next turn. Prepare the turn
+    // on the session it runs on (as completeTurn adopts it afterwards).
+    const stored = mgr.getSession(getSession().id);
+    if (stored && stored !== getSession()) setSession(stored);
+    await admitWorkspace(turn, prompt, options);
     const modelSwitch = applyPendingRoute?.();
+    // An orchestration mode or workflow chosen while the previous turn ran
+    // applies from this one (before a cold-cache fold can take it in).
+    const sessionSwitches = applyPendingSessionSwitches?.();
     // An agent profile saved while the previous turn ran applies from this one.
     await applyPendingAgentProfile?.();
     options.onRouteApplied?.(getSession());
     if (modelSwitch) options.onModelSwitch?.(modelSwitch);
+    if (sessionSwitches) options.onSessionSwitches?.(sessionSwitches);
     ensureSessionTranscriptWriter?.();
     transcript.appendUser(prompt);
     const session0 = getSession();
@@ -144,8 +162,8 @@ export function createTurnPreparation({
     // preparation. Worker apply_patch diffs bind to this generation and cannot
     // leak into the next turn/session.
     turn.snapshot.start(session0?.id);
-    turn.releaseFirstTitle = scheduleFirstTitle(session0, prompt);
-    await foldMcpSurface(turn, session0);
+    turn.releaseFirstTitle = scheduleFirstTitle(sessionTitles, session0, prompt);
+    await foldMcpSurface(turn, session0, (session) => scopedMcpToolsFor(session, getConfig()));
     hooks.emit('turn:start', { sessionId: session0.id, prompt, cwd: getCurrentCwd() });
     try {
       agentTool?.upsertLeadSession?.(session0, {