mixdog 1.3.0 → 1.3.2

package/src/session-runtime/mcp-glue/connect.mjs

@@ -3,7 +3,9 @@
 // connect. All mutable progress lives on the caller-owned `state`.
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import { envFlag } from '../../runtime/shared/env.mjs';
+import { awaitInitialConnect } from './initial-connect-gate.mjs';
 import { ensurePluginServerData } from './plugin-servers.mjs';
+import { createServerConnection } from './server-connection.mjs';
 
 export function createMcpConnect({
   mcpClient,
@@ -29,58 +31,100 @@ export function createMcpConnect({
   // Answer it with the redirect URL pasted from the browser.
   const completeMcpLogin = (name, callbackUrl) => mcpClient.completeMcpLogin(clean(name), callbackUrl, scopeOptions());
 
-  // Connect/disconnect exactly one server in the live registry, leaving all
-  // others untouched. Used by the enable/disable toggle so a single-server
-  // change never triggers a full disconnectAll()/reconnect freeze. Only an
-  // explicit sign-in passes `login` ({ openBrowser }): every other connect is
-  // non-interactive and reports a server that needs one as sign-in required.
-  async function applyMcpServerConnection(name, enabled, servers = resolveEffectiveMcpServers().servers, login = null) {
-    const target = clean(name);
-    if (!target) return;
-    // Changing this server's state clears any stale failure record for it.
-    if (Array.isArray(state.mcpFailures)) {
-      state.mcpFailures = state.mcpFailures.filter((row) => row.name !== target);
-    }
-    const cfg = servers[target];
-    if (enabled === false || !cfg || cfg.enabled === false) {
-      applied().delete(target);
-      await mcpClient.disconnectMcpServer?.(target, scopeOptions());
-      return;
+  const { applyMcpServerConnection, reconcileServers } = createServerConnection({
+    mcpClient,
+    state,
+    resolveEffectiveMcpServers,
+    getMcpScopeId,
+    scopeOptions,
+    applied,
+    fingerprint,
+    syncScopeRoot,
+  });
+
+  // Wait for a prior run (its failures were already captured in state).
+  async function settled(prior) {
+    if (!prior) return;
+    try {
+      await prior;
+    } catch {
+      /* prior run's failures already captured */
     }
-    applied().set(target, fingerprint(cfg));
-    // Close-then-connect as one generation-guarded op: a shutdown landing
-    // between the close and the connect never resurrects the server.
+  }
+
+  // Register `run` as the in-flight connect so a later reset serializes
+  // behind it instead of interleaving disconnect/connect.
+  async function trackInFlight(run) {
+    state.mcpConnectInFlight = run;
     try {
-      ensurePluginServerData(cfg);
-      await mcpClient.reconnectSingleMcpServer(
-        getMcpScopeId(),
-        target,
-        cfg,
-        login ? { interactive: true, openBrowser: login.openBrowser } : {}
-      );
-    } catch (error) {
-      const failure = { name: target, msg: error?.message || String(error) };
-      if (error?.authRequired) failure.authRequired = true;
-      const failures = Array.isArray(error?.failures) ? error.failures : [failure];
-      state.mcpFailures = [...(state.mcpFailures || []), ...failures];
+      await run;
+    } finally {
+      if (state.mcpConnectInFlight === run) state.mcpConnectInFlight = null;
     }
   }
 
-  // Bring the registry in line with the effective set: drop servers that are
-  // gone or disabled, (re)connect servers that are new or whose resolved
-  // config changed; untouched servers keep their connection.
-  async function reconcileServers() {
-    syncScopeRoot();
-    const { servers } = resolveEffectiveMcpServers();
-    const known = applied();
-    const drops = [...known.keys()].filter((name) => !servers[name] || servers[name].enabled === false);
-    const connects = Object.entries(servers)
-      .filter(([name, cfg]) => cfg?.enabled !== false && known.get(name) !== fingerprint(cfg))
-      .map(([name]) => name);
-    await Promise.allSettled([
-      ...drops.map((name) => applyMcpServerConnection(name, false, servers)),
-      ...connects.map((name) => applyMcpServerConnection(name, true, servers)),
-    ]);
+  // Scoped single-server toggle (or reconcile): non-superseding. It must NEVER
+  // cancel a pending full {reset} (cwd-change/boot). So do not bump the
+  // generation; just wait for any in-flight run, then bail if a newer full
+  // reset has been requested in the meantime.
+  async function connectScoped({ only, enabled, reconcile, login }) {
+    // A disable/remove must not wait out an interactive login of the
+    // connect it queues behind: cancel that login first.
+    if (only && enabled === false) cancelMcpLogin(only);
+    // Atomically capture the current generation AND the prior in-flight
+    // promise in the same synchronous step, then chain our op onto it. No
+    // await sits between the capture and the `state.mcpConnectInFlight = run`
+    // assignment, so concurrent {only} calls queue FIFO instead of resuming
+    // together and clobbering the in-flight slot. We never bump the
+    // generation; a {reset} does, so any {only} queued behind a reset sees
+    // the newer generation when its turn comes and bails.
+    const gen = state.mcpConnectGeneration;
+    const prev = state.mcpConnectInFlight;
+    await trackInFlight(
+      (async () => {
+        await settled(prev);
+        if (gen !== state.mcpConnectGeneration) return;
+        if (reconcile) await reconcileServers();
+        else await applyMcpServerConnection(only, enabled, undefined, login);
+      })()
+    );
+  }
+
+  // Serialize reconnects: boot connect, cwd-change reset, and rapid cwd
+  // switches must never interleave their disconnect/connect phases, or an
+  // older run finishing after a newer reset could re-add stale servers into
+  // the shared client registry. Approach: a generation token + a single
+  // in-flight promise. Each call bumps the generation, waits for any prior
+  // run to finish, then bails if a newer call has superseded it — leaving the
+  // latest requested effective-server-set in the registry.
+  async function connectAll({ reset }) {
+    const gen = ++state.mcpConnectGeneration;
+    await settled(state.mcpConnectInFlight);
+    if (gen !== state.mcpConnectGeneration) return;
+    await trackInFlight(
+      (async () => {
+        if (reset) {
+          await mcpClient.disconnectAll?.(scopeOptions());
+          applied().clear();
+        }
+        state.mcpFailures = [];
+        syncScopeRoot();
+        const { servers } = resolveEffectiveMcpServers();
+        for (const [name, cfg] of Object.entries(servers)) {
+          if (cfg?.enabled === false) applied().delete(name);
+          else applied().set(name, fingerprint(cfg));
+        }
+        if (Object.keys(servers).length === 0) return;
+        try {
+          for (const cfg of Object.values(servers)) if (cfg?.enabled !== false) ensurePluginServerData(cfg);
+          await mcpClient.connectMcpServers(servers, scopeOptions());
+        } catch (error) {
+          state.mcpFailures = Array.isArray(error?.failures)
+            ? error.failures
+            : [{ name: 'mcp', msg: error?.message || String(error) }];
+        }
+      })()
+    );
   }
 
   async function connectConfiguredMcp({
@@ -98,146 +142,16 @@ export function createMcpConnect({
       else await mcpClient.disconnectAll?.(scopeOptions());
       return mcpStatus();
     }
-    // Scoped single-server toggle: non-superseding. It must NEVER cancel a
-    // pending full {reset} (cwd-change/boot). So do not bump the generation;
-    // just wait for any in-flight run, then bail if a newer full reset has
-    // been requested in the meantime. Registering as in-flight makes a later
-    // reset serialize behind us instead of interleaving disconnect/connect.
-    if (only || reconcile) {
-      // A disable/remove must not wait out an interactive login of the
-      // connect it queues behind: cancel that login first.
-      if (only && enabled === false) cancelMcpLogin(only);
-      // Atomically capture the current generation AND the prior in-flight
-      // promise in the same synchronous step, then chain our op onto it. No
-      // await sits between the capture and the `state.mcpConnectInFlight = run`
-      // assignment, so concurrent {only} calls queue FIFO instead of resuming
-      // together and clobbering the in-flight slot. We never bump the
-      // generation; a {reset} does, so any {only} queued behind a reset sees
-      // the newer generation when its turn comes and bails.
-      const gen = state.mcpConnectGeneration;
-      const prev = state.mcpConnectInFlight;
-      const run = (async () => {
-        if (prev) {
-          try {
-            await prev;
-          } catch {
-            /* prior run's failures already captured */
-          }
-        }
-        if (gen !== state.mcpConnectGeneration) return;
-        if (reconcile) await reconcileServers();
-        else await applyMcpServerConnection(only, enabled, undefined, login);
-      })();
-      state.mcpConnectInFlight = run;
-      try {
-        await run;
-      } finally {
-        if (state.mcpConnectInFlight === run) state.mcpConnectInFlight = null;
-      }
-      return mcpStatus();
-    }
-    // Serialize reconnects: boot connect, cwd-change reset, and rapid cwd
-    // switches must never interleave their disconnect/connect phases, or an
-    // older run finishing after a newer reset could re-add stale servers into
-    // the shared client registry. Approach: a generation token + a single
-    // in-flight promise. Each call bumps the generation, waits for any prior
-    // run to finish, then bails if a newer call has superseded it — leaving the
-    // latest requested effective-server-set in the registry.
-    const gen = ++state.mcpConnectGeneration;
-    if (state.mcpConnectInFlight) {
-      try {
-        await state.mcpConnectInFlight;
-      } catch {
-        /* prior run's failures already captured */
-      }
-    }
-    if (gen !== state.mcpConnectGeneration) return mcpStatus();
-    const run = (async () => {
-      if (reset) {
-        await mcpClient.disconnectAll?.(scopeOptions());
-        applied().clear();
-      }
-      state.mcpFailures = [];
-      syncScopeRoot();
-      const { servers } = resolveEffectiveMcpServers();
-      for (const [name, cfg] of Object.entries(servers)) {
-        if (cfg?.enabled === false) applied().delete(name);
-        else applied().set(name, fingerprint(cfg));
-      }
-      if (Object.keys(servers).length === 0) return;
-      try {
-        for (const cfg of Object.values(servers)) if (cfg?.enabled !== false) ensurePluginServerData(cfg);
-        await mcpClient.connectMcpServers(servers, scopeOptions());
-      } catch (error) {
-        state.mcpFailures = Array.isArray(error?.failures)
-          ? error.failures
-          : [{ name: 'mcp', msg: error?.message || String(error) }];
-      }
-    })();
-    state.mcpConnectInFlight = run;
-    try {
-      await run;
-    } finally {
-      if (state.mcpConnectInFlight === run) state.mcpConnectInFlight = null;
-    }
+    if (only || reconcile) await connectScoped({ only, enabled, reconcile, login });
+    else await connectAll({ reset });
     return mcpStatus();
   }
 
-  // Turn gate: await the in-flight INITIAL connect, bounded by both the global
-  // server startup budget and the caller's TTFT grace. A server still
-  // connecting after the grace flows through the existing late-tool deferred
-  // announcement path unchanged.
-  async function awaitInitialMcpConnect(maxWaitMs = undefined) {
-    const inFlight = state.mcpConnectInFlight;
-    if (!inFlight) return;
-    let budgetMs = 10000;
-    try {
-      // The gate must outlast the slowest enabled server's own startup budget;
-      // a server with its budget disabled (0) means the connect may never
-      // settle, so the whole gate is disabled (handled below).
-      const configs = Object.values(resolveEffectiveMcpServers().servers).filter((cfg) => cfg?.enabled !== false);
-      const budgets = (configs.length > 0 ? configs : [{}])
-        .map((cfg) => mcpClient.resolveMcpStartupTimeoutMs?.(cfg))
-        .filter((value) => Number.isFinite(value));
-      if (budgets.length > 0) budgetMs = budgets.includes(0) ? 0 : Math.max(...budgets);
-    } catch {
-      /* fall back to default budget */
-    }
-    if (maxWaitMs !== null && maxWaitMs !== undefined) {
-      const requestedMaxWaitMs = Number(maxWaitMs);
-      if (Number.isFinite(requestedMaxWaitMs) && requestedMaxWaitMs >= 0) {
-        budgetMs = Math.min(budgetMs, requestedMaxWaitMs);
-      }
-    }
-    // Budget disabled (0/off) = no per-server startup timeout, so the connect
-    // promise may never settle; never gate the turn on it — fall back to the
-    // legacy fire-and-forget behavior (late servers use the deferred path).
-    if (!(budgetMs > 0)) return;
-    let timer = null;
-    let expired = false;
-    const budget = new Promise((resolveBudget) => {
-      timer = setTimeout(() => {
-        expired = true;
-        resolveBudget();
-      }, budgetMs);
-    });
-    try {
-      // Follow replacement connects (a reconnect queued behind the captured
-      // run installs a new in-flight promise) inside ONE fixed deadline.
-      // Failures are already captured in state.mcpFailures, so rejections are
-      // swallowed: this gate must never reject the turn.
-      let current = inFlight;
-      while (current && !expired) {
-        await Promise.race([Promise.resolve(current).catch(() => {}), budget]);
-        if (expired) break;
-        // Let a queued reconnect install its promise before re-checking.
-        await Promise.race([new Promise((resolveTick) => setImmediate(resolveTick)), budget]);
-        current = state.mcpConnectInFlight;
-      }
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-  }
-
-  return { connectConfiguredMcp, awaitInitialMcpConnect, cancelMcpLogin, completeMcpLogin };
+  return {
+    connectConfiguredMcp,
+    awaitInitialMcpConnect: (maxWaitMs) =>
+      awaitInitialConnect({ state, mcpClient, resolveEffectiveMcpServers }, maxWaitMs),
+    cancelMcpLogin,
+    completeMcpLogin,
+  };
 }

package/src/session-runtime/mcp-glue/initial-connect-gate.mjs

@@ -0,0 +1,57 @@
+// The turn gate on the initial MCP connect: a bounded wait, never a rejection.
+
+// Turn gate: await the in-flight INITIAL connect, bounded by both the global
+// server startup budget and the caller's TTFT grace. A server still
+// connecting after the grace flows through the existing late-tool deferred
+// announcement path unchanged.
+export async function awaitInitialConnect({ state, mcpClient, resolveEffectiveMcpServers }, maxWaitMs = undefined) {
+  const inFlight = state.mcpConnectInFlight;
+  if (!inFlight) return;
+  let budgetMs = 10000;
+  try {
+    // The gate must outlast the slowest enabled server's own startup budget;
+    // a server with its budget disabled (0) means the connect may never
+    // settle, so the whole gate is disabled (handled below).
+    const configs = Object.values(resolveEffectiveMcpServers().servers).filter((cfg) => cfg?.enabled !== false);
+    const budgets = (configs.length > 0 ? configs : [{}])
+      .map((cfg) => mcpClient.resolveMcpStartupTimeoutMs?.(cfg))
+      .filter((value) => Number.isFinite(value));
+    if (budgets.length > 0) budgetMs = budgets.includes(0) ? 0 : Math.max(...budgets);
+  } catch {
+    /* fall back to default budget */
+  }
+  if (maxWaitMs !== null && maxWaitMs !== undefined) {
+    const requestedMaxWaitMs = Number(maxWaitMs);
+    if (Number.isFinite(requestedMaxWaitMs) && requestedMaxWaitMs >= 0) {
+      budgetMs = Math.min(budgetMs, requestedMaxWaitMs);
+    }
+  }
+  // Budget disabled (0/off) = no per-server startup timeout, so the connect
+  // promise may never settle; never gate the turn on it — fall back to the
+  // legacy fire-and-forget behavior (late servers use the deferred path).
+  if (!(budgetMs > 0)) return;
+  let timer = null;
+  let expired = false;
+  const budget = new Promise((resolveBudget) => {
+    timer = setTimeout(() => {
+      expired = true;
+      resolveBudget();
+    }, budgetMs);
+  });
+  try {
+    // Follow replacement connects (a reconnect queued behind the captured
+    // run installs a new in-flight promise) inside ONE fixed deadline.
+    // Failures are already captured in state.mcpFailures, so rejections are
+    // swallowed: this gate must never reject the turn.
+    let current = inFlight;
+    while (current && !expired) {
+      await Promise.race([Promise.resolve(current).catch(() => {}), budget]);
+      if (expired) break;
+      // Let a queued reconnect install its promise before re-checking.
+      await Promise.race([new Promise((resolveTick) => setImmediate(resolveTick)), budget]);
+      current = state.mcpConnectInFlight;
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/session-runtime/mcp-glue/server-connection.mjs

@@ -0,0 +1,71 @@
+// Connecting, disconnecting and reconciling individual MCP servers in the live
+// registry. The caller (connect.mjs) owns the serialization and the shared state.
+import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
+import { ensurePluginServerData } from './plugin-servers.mjs';
+
+export function createServerConnection({
+  mcpClient,
+  state,
+  resolveEffectiveMcpServers,
+  getMcpScopeId,
+  scopeOptions,
+  applied,
+  fingerprint,
+  syncScopeRoot,
+}) {
+  // Connect/disconnect exactly one server in the live registry, leaving all
+  // others untouched. Used by the enable/disable toggle so a single-server
+  // change never triggers a full disconnectAll()/reconnect freeze. Only an
+  // explicit sign-in passes `login` ({ openBrowser }): every other connect is
+  // non-interactive and reports a server that needs one as sign-in required.
+  async function applyMcpServerConnection(name, enabled, servers = resolveEffectiveMcpServers().servers, login = null) {
+    const target = clean(name);
+    if (!target) return;
+    // Changing this server's state clears any stale failure record for it.
+    if (Array.isArray(state.mcpFailures)) {
+      state.mcpFailures = state.mcpFailures.filter((row) => row.name !== target);
+    }
+    const cfg = servers[target];
+    if (enabled === false || !cfg || cfg.enabled === false) {
+      applied().delete(target);
+      await mcpClient.disconnectMcpServer?.(target, scopeOptions());
+      return;
+    }
+    applied().set(target, fingerprint(cfg));
+    // Close-then-connect as one generation-guarded op: a shutdown landing
+    // between the close and the connect never resurrects the server.
+    try {
+      ensurePluginServerData(cfg);
+      await mcpClient.reconnectSingleMcpServer(
+        getMcpScopeId(),
+        target,
+        cfg,
+        login ? { interactive: true, openBrowser: login.openBrowser } : {}
+      );
+    } catch (error) {
+      const failure = { name: target, msg: error?.message || String(error) };
+      if (error?.authRequired) failure.authRequired = true;
+      const failures = Array.isArray(error?.failures) ? error.failures : [failure];
+      state.mcpFailures = [...(state.mcpFailures || []), ...failures];
+    }
+  }
+
+  // Bring the registry in line with the effective set: drop servers that are
+  // gone or disabled, (re)connect servers that are new or whose resolved
+  // config changed; untouched servers keep their connection.
+  async function reconcileServers() {
+    syncScopeRoot();
+    const { servers } = resolveEffectiveMcpServers();
+    const known = applied();
+    const drops = [...known.keys()].filter((name) => !servers[name] || servers[name].enabled === false);
+    const connects = Object.entries(servers)
+      .filter(([name, cfg]) => cfg?.enabled !== false && known.get(name) !== fingerprint(cfg))
+      .map(([name]) => name);
+    await Promise.allSettled([
+      ...drops.map((name) => applyMcpServerConnection(name, false, servers)),
+      ...connects.map((name) => applyMcpServerConnection(name, true, servers)),
+    ]);
+  }
+
+  return { applyMcpServerConnection, reconcileServers };
+}

package/src/session-runtime/media-api.mjs

@@ -41,8 +41,11 @@ export function createMediaApi() {
       });
       return { status: await module.getVoiceStatus(), error };
     },
-    async listMediaLanes() {
-      return (await lanes()).listMediaLanes();
+    // `budgetMs` (Studio) caps the per-lane catalog wait; slower lanes come
+    // back `catalogPending`. Capped so a caller cannot park the call.
+    async listMediaLanes(options) {
+      const budgetMs = Math.min(30_000, Math.max(0, Math.trunc(Number(options?.budgetMs) || 0)));
+      return (await lanes()).listMediaLanes({ budgetMs });
     },
     // The Studio's current selection is the runtime's default: a tool call
     // that omits lane/model follows it. Studio pushes on every settled change.

package/src/session-runtime/model-route/route-persist.mjs

@@ -35,7 +35,7 @@ export function createRoutePersistence(deps) {
         hasSecrets: getConfigHasSecrets(),
       });
     },
-    persistAdoptedModelSettings(route, { keepMainModel } = {}) {
+    persistAdoptedModelSettings(route, { keepMainModel, onlyIfAbsent = false } = {}) {
       // saveModelSettings is in-memory only. persistLeadRoute debounce-writes
       // the adopted config (including modelSettings). If the lead preset cannot
       // be normalized, still debounce-persist so effort/fast are not memory-only.
@@ -43,7 +43,7 @@ export function createRoutePersistence(deps) {
         keepMainModel === true ||
         (keepMainModel !== false && tunesNonMainModel(getRoute(), route, resolveRoute(getConfig(), {})))
           ? null
-          : persistLeadRoute(route);
+          : persistLeadRoute(route, { onlyIfAbsent });
       if (!leadRoute) saveConfigAndAdopt(getConfig());
       return leadRoute;
     },

package/src/session-runtime/model-route/route-tuning.mjs

@@ -10,7 +10,13 @@ export function createRouteTuning(deps, persist) {
   const { getConfig, getRoute, setRouteState, resolveRoute, lookupModelMeta, refreshRouteEffort } = deps;
 
   /** Save the live route's modelSettings, re-resolve through the lead preset
-   *  when one exists, refresh effort and tune the current session. */
+   *  when one exists, refresh effort and tune the current session.
+   *
+   *  This is not a Main-model write and needs no compare-and-set: it persists
+   *  the LIVE route (read after every await), and only when that route's model
+   *  is already the Main model (persistAdoptedModelSettings: tunesNonMainModel),
+   *  so the lead preset's model is rewritten with itself and never changes. A
+   *  live route without a model normalizes to nothing and writes no preset. */
   async function commitRouteTuning(fastCapable, modelMeta) {
     persist.saveRouteModelSettings(getRoute(), fastCapable);
     const leadRoute = persist.persistAdoptedModelSettings(getRoute());
@@ -61,7 +67,10 @@ export function createRouteTuning(deps, persist) {
     },
     async setEffort(value) {
       const normalized = normalizeEffortInput(value);
-      setRouteState({ ...getRoute(), effort: normalized });
+      // An explicit level is the user's choice for this route: Auto effort
+      // would replace it on the next turn (its base is fixed), so the pick
+      // turns the route's Auto off until it is switched back on.
+      setRouteState({ ...getRoute(), effort: normalized, ...(normalized ? { autoEffort: false } : {}) });
       const modelMeta = await lookupModelMeta(getRoute().provider, getRoute().model);
       const fastCapable = selectionFastCapable(getRoute().provider, modelMeta, normalized, getRoute().modelParameters);
       await commitRouteTuning(fastCapable, modelMeta);

package/src/session-runtime/model-route/set-route.mjs

@@ -24,6 +24,11 @@ import {
 } from '../../runtime/agent/orchestrator/runtime-core/session-route-policy.mjs';
 import { rebuildToolSurfaceForProviderWithMigration } from '../../runtime/agent/orchestrator/session/loop/tool-exposure-migration.mjs';
 import { UNOWNED_LEASE, openRouteLease } from './route-ownership.mjs';
+import { resolveSessionMode } from '../../runtime/agent/orchestrator/session/agent-mode.mjs';
+import { ownerRouteFallbacks } from '../../runtime/agent/orchestrator/session/manager/owner-route-fallbacks.mjs';
+import { normalizeWorkflowRoute } from '../../runtime/agent/orchestrator/runtime-core/workflow.mjs';
+import { routeChain, validateRouteChainProviders } from '../../runtime/shared/model-route-chain.mjs';
+import { resolveChainEntry } from '../workflow-agents-api/agent-route.mjs';
 
 /** The request, completed from the live route where the caller left gaps. */
 function completeRequest(deps, next) {
@@ -105,6 +110,32 @@ async function recreateEmptySession(deps, lease) {
   if (closed) await createCurrentSession('model-switch-empty');
 }
 
+/** The fallback chain a Lead-class session follows on `route`: its owner's chain
+ *  while the route is the owner's primary model, none otherwise (see
+ *  owner-route-fallbacks.mjs). Nothing for an agent's session, which keeps its own. */
+export function sessionRouteFallbackFields(deps, session, route) {
+  const { mode, agentId } = resolveSessionMode({ session });
+  if (!agentId) return {};
+  return {
+    routeFallbacks: ownerRouteFallbacks({
+      sessionMode: mode,
+      agentId,
+      provider: route.provider,
+      model: route.model,
+      config: deps.getConfig(),
+    }),
+  };
+}
+
+/** A same-model selection (a bot profile saved with new fallbacks) restarts the
+ *  addressed session's chain when the owner's chain no longer matches it. */
+function refreshSessionFallbacks(deps, session) {
+  const fields = sessionRouteFallbackFields(deps, session, deps.getRoute());
+  if (!fields.routeFallbacks) return;
+  if (JSON.stringify(fields.routeFallbacks) === JSON.stringify(session.routeFallbacks || [])) return;
+  deps.mgr.updateSessionRoute?.(session.id, fields, { session });
+}
+
 /** Rewrite the addressed empty session to the route it was asked to run on. */
 function updateSessionInPlace(deps, session, updateOptions) {
   const { getRoute, getSession, setSession, mgr, statusRoutes } = deps;
@@ -119,6 +150,7 @@ function updateSessionInPlace(deps, session, updateOptions) {
     contextPercent: route.contextPercent,
     contextTokens: route.contextTokens || null,
     selectedContextWindow: route.selectedContextWindow || null,
+    ...sessionRouteFallbackFields(deps, session, route),
   };
   const updated = mgr.updateSessionRoute?.(session.id, fields, updateOptions);
   if (updated) setSession(updated);
@@ -183,6 +215,27 @@ function switchSessionInPlace(deps, session) {
   return recorded ? boundary : null;
 }
 
+/** The Lead's fallback models after this selection, checked like an agent's
+ *  chain (leaf routes, distinct providers): an explicit list replaces the
+ *  stored one ([] clears it), a selection without one keeps it. */
+async function leadFallbackChain(deps, next, primary) {
+  const storedPreset = findPreset(deps.getConfig(), workflowPresetId('lead'));
+  const requested = hasOwn(next || {}, 'fallbacks') ? next.fallbacks : storedPreset?.fallbacks;
+  if (!Array.isArray(requested) || !requested.length) return [];
+  const chain = routeChain({ provider: primary.provider, model: primary.model, fallbacks: requested });
+  validateRouteChainProviders(chain);
+  const storedChain = routeChain(storedPreset || {});
+  // Each entry goes through the agents' normalizer (fast clamp, context window).
+  const resolved = [];
+  for (const entry of chain.slice(1)) {
+    const previous = storedChain.find((c) => c.provider === entry.provider && c.model === entry.model);
+    resolved.push(await resolveChainEntry(deps, entry, previous || {}));
+  }
+  return (
+    normalizeWorkflowRoute({ provider: primary.provider, model: primary.model, fallbacks: resolved })?.fallbacks || []
+  );
+}
+
 /** Validate, persist and adopt the requested route as the runtime's route. */
 async function adoptRoute(deps, persist, next, options, lease) {
   const {
@@ -195,9 +248,29 @@ async function adoptRoute(deps, persist, next, options, lease) {
     scheduleStatuslineUsageRefresh,
   } = deps;
   const { selectedRoute, fastCapable, modelMeta } = await resolveSelectedRoute(deps, next);
+  // The Lead's fallback chain travels with an explicit main-model choice only
+  // (the Lead editor, the setup tool); a session's own pick never touches it.
+  const persistedRoute =
+    options?.keepMainModel === false && options?.sessionOnly !== true
+      ? { ...selectedRoute, fallbacks: await leadFallbackChain(deps, next, selectedRoute) }
+      : selectedRoute;
+  // The Lead route a conditional fill wrote, until the file confirms it.
+  let filled = null;
   // Provider readiness may outlast the session the selection was made for.
   const adopted = lease.run(
     () => {
+      // Compare-and-set: a route that already has a model (picked while this
+      // selection was resolving) is never replaced. Checked synchronously with
+      // the adopt below, so nothing can set a route in between. A Lead route
+      // another process persisted may not have reached this runtime yet (the
+      // change notification is debounced): the config is re-read from disk
+      // right here, which adopts it and fills the empty route, and that route
+      // is the winner this selection answers with.
+      if (options?.onlyIfEmpty === true) {
+        if (clean(getRoute()?.model)) return false;
+        deps.reloadFullConfig?.();
+        if (clean(getRoute()?.model)) return false;
+      }
       if (options?.sessionOnly === true) {
         // An agent child's route belongs to that session alone: the shared
         // modelSettings bucket (saved effort/Fast per model) and the main
@@ -208,9 +281,11 @@ async function adoptRoute(deps, persist, next, options, lease) {
         // The main model changes only on an explicit main-model choice
         // (keepMainModel: false, e.g. the setup tool); every other selection
         // — the session surface's model pick, an heir — keeps it.
-        const leadRoute = persist.persistAdoptedModelSettings(selectedRoute, {
+        const leadRoute = persist.persistAdoptedModelSettings(persistedRoute, {
           keepMainModel: options?.keepMainModel !== false,
+          onlyIfAbsent: options?.onlyIfEmpty === true,
         });
+        filled = leadRoute;
         setRouteState(resolveRoute(getConfig(), leadRoute ? { model: workflowPresetId('lead') } : selectedRoute));
       }
       return true;
@@ -218,9 +293,13 @@ async function adoptRoute(deps, persist, next, options, lease) {
     () => false
   );
   if (!adopted) return false;
+  // A conditional fill reaches the file only while no Lead route is stored
+  // there (judged under the config file lock). When another process wrote one
+  // after the re-read above, the file's route replaces the fill in the runtime.
+  const replaced = filled && (await deps.confirmLeadFill?.(filled)) === true;
   // The refresh completes against the route just adopted and only while the
   // selection still owns it.
-  await refreshRouteEffort(modelMeta, getRoute(), null, lease);
+  await refreshRouteEffort(replaced ? null : modelMeta, getRoute(), null, lease);
   return lease.run(
     () => {
       refreshStatuslineUsageSnapshot(getRoute());
@@ -320,6 +399,7 @@ export function createSetRoute(deps, persist) {
         return modelSwitch ? { ...getRoute(), modelSwitch } : getRoute();
       }
       persist.applySessionTuning();
+      refreshSessionFallbacks(deps, session);
       return getRoute();
     }
     // An addressed runtime keeps its durable id: the empty session is updated