mixdog 0.9.85 → 0.9.87

package/src/session-runtime/runtime-core.mjs

@@ -1,3 +1,4 @@
+import { createSessionLifecycle } from './session-lifecycle.mjs';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { performance } from 'node:perf_hooks';
@@ -41,7 +42,10 @@ import {
   setLocalProvider,
 } from '../standalone/provider-admin.mjs';
 import { createUsageDashboard } from '../standalone/usage-dashboard.mjs';
-import { fetchOAuthUsageSnapshot } from '../runtime/agent/orchestrator/providers/oauth-usage.mjs';
+import {
+  consumeOpenAICodexResetCredit,
+  fetchOAuthUsageSnapshot,
+} from '../runtime/agent/orchestrator/providers/oauth-usage.mjs';
 import {
   getModelMetadataSync,
   warmCatalogsInBackground,
@@ -246,6 +250,7 @@ import { createToolSurface } from './tool-surface.mjs';
 import { readRuntimeTunables } from './runtime-tunables.mjs';
 import { createSessionTurnApi } from './session-turn-api.mjs';
 import { providerInitCacheKey } from './provider-init-key.mjs';
+import { createRoutePreparationGate } from './route-preparation.mjs';
 import {
   RUNTIME,
   SEARCH_RUNTIME,
@@ -319,28 +324,22 @@ export async function createMixdogSessionRuntime({
   remote = false,
   desktopSession: initialDesktopSession = null,
 } = {}) {
-  let desktopSession = initialDesktopSession;
+  // Shared mutable runtime state, promoted from closure `let`s so extracted
+  // modules can read/write live values through one reference.
+  const rt = {};
+  rt.desktopSession = initialDesktopSession;
   bootProfile('session-runtime:start', { provider, model, toolMode, cwd });
-  let remoteEnabled = remote === true;
-  // Transient marker: an AUTO start (config/delayed autoStart) has forked the
-  // worker to ATTEMPT a claim-if-vacant but has NOT asserted remote for this
-  // session yet. remoteEnabled flips only if the worker reports it acquired the
-  // seat (the 'acquired' notification). Lets the deferred start chain proceed
-  // past its remoteEnabled guards without prematurely showing this session as
-  // remote (single-holder: a live owner must not be stolen by autoStart).
-  let remoteClaimPending = false;
-  // SESSION-SCOPED remote (user decision): the session that toggled remote
-  // OWNS the channel relay. Other sessions' turns never rebind or relay; a
-  // dead/replaced owner (clear, delete) hands the seat to the next current
-  // session that asks.
-  let remoteSessionId = null;
+  rt.remoteEnabled = remote === true;
+  // SESSION-SCOPED Remote is manual-only. Explicit ON selects/overrides; no
+  // registration, turn, session death, or process death transfers ownership.
+  rt.remoteSessionId = null;
   // Desktop/TUI Remote toggles are desired-state transitions. Serialize the
   // daemon deactivate/detach and reconnect/activate chains so an OFF that is
   // still stopping can never tear down the worker created by the following ON.
   const remoteTransitions = createRemoteTransitionQueue();
   // Last assistant text handed to the transcript writer (via onAssistantText),
   // so the post-turn final-content append can skip an exact duplicate.
-  let _lastAppendedAssistant = '';
+  rt._lastAppendedAssistant = '';
   process.env.MIXDOG_QUIET_SESSION_LOG ??= '1';
   const standaloneStartedAt = performance.now();
   ensureStandaloneEnvironment({
@@ -349,11 +348,11 @@ export async function createMixdogSessionRuntime({
   });
   bootProfile('standalone-env:ready', { ms: (performance.now() - standaloneStartedAt).toFixed(1) });
   const keychainPrewarmPromise = keychain.prewarmSecrets();
-  let keychainPrewarmWaitDone = false;
-  let keychainPrewarmWaitPromise = null;
+  rt.keychainPrewarmWaitDone = false;
+  rt.keychainPrewarmWaitPromise = null;
   function awaitKeychainPrewarm() {
-    if (keychainPrewarmWaitDone) return Promise.resolve();
-    keychainPrewarmWaitPromise ??= (async () => {
+    if (rt.keychainPrewarmWaitDone) return Promise.resolve();
+    rt.keychainPrewarmWaitPromise ??= (async () => {
       let timeoutId;
       const deadline = new Promise((resolveDeadline) => {
         timeoutId = setTimeout(resolveDeadline, KEYCHAIN_PREWARM_WAIT_MS);
@@ -363,14 +362,19 @@ export async function createMixdogSessionRuntime({
         await Promise.race([keychainPrewarmPromise, deadline]);
       } finally {
         clearTimeout(timeoutId);
-        keychainPrewarmWaitDone = true;
+        rt.keychainPrewarmWaitDone = true;
       }
     // Invoked here: the assignment used to store the async FUNCTION, so every
     // `await awaitKeychainPrewarm()` resolved instantly (awaiting a function is
     // a no-op) and callers silently skipped the wait they asked for.
     })();
-    return keychainPrewarmWaitPromise;
+    return rt.keychainPrewarmWaitPromise;
   }
+  const routePreparation = createRoutePreparationGate({
+    onError: (error) => bootProfile('route-preparation:failed', {
+      error: error?.message || String(error),
+    }),
+  });
 
   const importsStartedAt = performance.now();
   const [
@@ -416,22 +420,22 @@ export async function createMixdogSessionRuntime({
     dataDir: pluginDataDir,
     cwd,
   });
-  let memoryModPromise = null;
-  let searchModPromise = null;
-  let codeGraphModPromise = null;
+  rt.memoryModPromise = null;
+  rt.searchModPromise = null;
+  rt.codeGraphModPromise = null;
 
   // Memory module is always-on. `memoryEnabled()` is kept as a thin alias that
   // now always returns true (callers/compaction helpers still reference it);
   // the user-facing toggle is `recap` (background cycles only), read via
   // recapEnabled(config).
   const memoryEnabled = () => true;
-  const recapEnabledFn = () => recapEnabled(config, true);
-  const channelsEnabled = () => moduleEnabled(config, 'channels', true);
+  const recapEnabledFn = () => recapEnabled(rt.config, true);
+  const channelsEnabled = () => moduleEnabled(rt.config, 'channels', true);
 
   async function getMemoryModule() {
     const startedAt = performance.now();
-    memoryModPromise ??= Promise.resolve(memoryRuntime);
-    const mod = await memoryModPromise;
+    rt.memoryModPromise ??= Promise.resolve(memoryRuntime);
+    const mod = await rt.memoryModPromise;
     if (typeof mod?.init === 'function') {
       await mod.init();
     }
@@ -441,16 +445,16 @@ export async function createMixdogSessionRuntime({
 
   async function getSearchModule() {
     const startedAt = performance.now();
-    searchModPromise ??= import(SEARCH_RUNTIME);
-    const mod = await searchModPromise;
+    rt.searchModPromise ??= import(SEARCH_RUNTIME);
+    const mod = await rt.searchModPromise;
     bootProfile('search-runtime:ready', { ms: (performance.now() - startedAt).toFixed(1) });
     return mod;
   }
 
   async function getCodeGraphModule() {
     const startedAt = performance.now();
-    codeGraphModPromise ??= import(CODE_GRAPH_RUNTIME);
-    const mod = await codeGraphModPromise;
+    rt.codeGraphModPromise ??= import(CODE_GRAPH_RUNTIME);
+    const mod = await rt.codeGraphModPromise;
     bootProfile('code-graph-runtime:ready', { ms: (performance.now() - startedAt).toFixed(1) });
     return mod;
   }
@@ -459,7 +463,7 @@ export async function createMixdogSessionRuntime({
     const leadRoute = normalizeWorkflowRoute(routeLike);
     if (!leadRoute) return null;
 
-    const nextConfig = { ...(config || {}) };
+    const nextConfig = { ...(rt.config || {}) };
     nextConfig.presets = upsertWorkflowPreset(nextConfig.presets, 'lead', leadRoute);
     nextConfig.workflowRoutes = {
       ...(nextConfig.workflowRoutes || {}),
@@ -486,21 +490,21 @@ export async function createMixdogSessionRuntime({
   }
 
   const configStartedAt = performance.now();
-  let config = cfgMod.loadConfig({ secrets: false });
-  setConfiguredShell(normalizeSystemShellConfig(config.shell).command);
-  let configHasSecrets = false;
-  let route = resolveRoute(config, { provider, model });
-  let searchRoute = normalizeSearchRouteConfig(config.searchRoute);
+  rt.config = cfgMod.loadConfig({ secrets: false });
+  setConfiguredShell(normalizeSystemShellConfig(rt.config.shell).command);
+  rt.configHasSecrets = false;
+  rt.route = resolveRoute(rt.config, { provider, model });
+  rt.searchRoute = normalizeSearchRouteConfig(rt.config.searchRoute);
   bootProfile('config:ready', { ms: (performance.now() - configStartedAt).toFixed(1) });
-  let mode = normalizeToolMode(toolMode);
-  let session = null;
-  let sessionCreatePromise = null;
-  let currentCwd = cwd;
-  let sessionNeedsCwdRefresh = false;
+  rt.mode = normalizeToolMode(toolMode);
+  rt.session = null;
+  rt.sessionCreatePromise = null;
+  rt.currentCwd = cwd;
+  rt.sessionNeedsCwdRefresh = false;
   // session_manage tool: reset request scheduled by the model mid-turn,
   // consumed by the TUI engine at turn end ('clear' | 'compact_clear').
-  let pendingSessionReset = null;
-  let closeRequested = false;
+  rt.pendingSessionReset = null;
+  rt.closeRequested = false;
   const warmupTimers = {
     providerSetupWarmupTimer: null,
     providerWarmupTimer: null,
@@ -521,8 +525,8 @@ export async function createMixdogSessionRuntime({
     codeGraphPrewarmQueuedCwd: '',
     channelStartPromise: null,
   };
-  let activeTurnCount = 0;
-  let firstTurnCompleted = false;
+  rt.activeTurnCount = 0;
+  rt.firstTurnCompleted = false;
   function hookTranscriptPath(sessionId) {
     const id = clean(sessionId);
     if (!id || !/^[A-Za-z0-9_-]+$/.test(id)) return null;
@@ -530,15 +534,15 @@ export async function createMixdogSessionRuntime({
     return join(dataDir, 'sessions', `${id}.json`);
   }
   function hookEffortPayload() {
-    const level = clean(route.effectiveEffort || route.effort);
+    const level = clean(rt.route.effectiveEffort || rt.route.effort);
     return level ? { level: level.toLowerCase() } : undefined;
   }
   function hookCommonPayload(extra = {}) {
-    const sid = clean(extra.session_id || extra.sessionId || session?.id);
+    const sid = clean(extra.session_id || extra.sessionId || rt.session?.id);
     return {
       ...(sid ? { session_id: sid, transcript_path: hookTranscriptPath(sid) } : {}),
-      cwd: currentCwd,
-      permission_mode: session?.permissionMode || 'default',
+      cwd: rt.currentCwd,
+      permission_mode: rt.session?.permissionMode || 'default',
       ...(hookEffortPayload() ? { effort: hookEffortPayload() } : {}),
       ...extra,
     };
@@ -563,7 +567,7 @@ export async function createMixdogSessionRuntime({
     modelCatalogWarmupEnabled,
     codeGraphPrewarmLazy,
   } = readRuntimeTunables();
-  let codeGraphFirstTurnPrewarmDone = false;
+  rt.codeGraphFirstTurnPrewarmDone = false;
   const modelMetaByRoute = new Map();
   const notificationListeners = new Set();
   // Remote seat listeners (TUI): fired when remote mode flips outside a direct
@@ -588,11 +592,11 @@ export async function createMixdogSessionRuntime({
     providerSetupPromise: null,
   };
   const providerInitPromises = new Map();
-  let startupProviderCatalogRefreshStarted = false;
+  rt.startupProviderCatalogRefreshStarted = false;
   // True while the boot-time provider-catalog refresh is in flight: warming a
   // model cache it is about to invalidate only burns the load twice.
-  let startupProviderCatalogRefreshPending = false;
-  let lastProjectMcpKey = null;
+  rt.startupProviderCatalogRefreshPending = false;
+  rt.lastProjectMcpKey = null;
   // MCP connect state, owned here so teardown/reconnect paths still observe it;
   // the mcp-glue factory mutates this object in place (see createMcpGlue).
   const mcpState = {
@@ -611,15 +615,15 @@ export async function createMixdogSessionRuntime({
     normalizeMcpServerInput,
   } = createMcpGlue({
     mcpClient,
-    getConfig: () => config,
-    getCurrentCwd: () => currentCwd,
-    getDesktopSession: () => desktopSession,
-    setDesktopSession: (v) => { desktopSession = v; },
+    getConfig: () => rt.config,
+    getCurrentCwd: () => rt.currentCwd,
+    getDesktopSession: () => rt.desktopSession,
+    setDesktopSession: (v) => { rt.desktopSession = v; },
     state: mcpState,
   });
   const hooksStartedAt = performance.now();
   const hooks = createStandaloneHookBus({ dataDir: cfgMod.getPluginData() });
-  hooks.emit('runtime:start', { cwd: currentCwd, provider: route.provider, model: route.model, toolMode: mode });
+  hooks.emit('runtime:start', { cwd: rt.currentCwd, provider: rt.route.provider, model: rt.route.model, toolMode: rt.mode });
   bootProfile('hooks:ready', { ms: (performance.now() - hooksStartedAt).toFixed(1) });
 
   // Self-update: registry check + background staging live in self-update.mjs;
@@ -627,7 +631,7 @@ export async function createMixdogSessionRuntime({
   // boot check is deferred past this constructor so a hanging registry request
   // can never delay session boot.
   const selfUpdate = createSelfUpdateController({
-    getConfig: () => config,
+    getConfig: () => rt.config,
     getDataDir: () => cfgMod.getPluginData?.() || STANDALONE_DATA_DIR,
     emitNotification: (...a) => emitRuntimeNotification(...a),
   });
@@ -650,7 +654,7 @@ export async function createMixdogSessionRuntime({
     skillContent,
     skillToolContent,
     addProjectSkill,
-  } = createSkillsApi({ contextMod, getCwd: () => currentCwd });
+  } = createSkillsApi({ contextMod, getCwd: () => rt.currentCwd });
 
   // cwd resolution/apply + plugins-status + core-memory context. Extracted to
   // session-runtime/cwd-plugins.mjs; the facade keeps ownership of the mutable
@@ -664,17 +668,17 @@ export async function createMixdogSessionRuntime({
     pluginsStatus,
     loadCoreMemoryContext,
   } = createCwdPlugins({
-    getCurrentCwd: () => currentCwd,
-    setCurrentCwd: (next) => { currentCwd = next; },
-    getConfig: () => config,
-    getSession: () => session,
-    getRoute: () => route,
-    getLastProjectMcpKey: () => lastProjectMcpKey,
-    setLastProjectMcpKey: (next) => { lastProjectMcpKey = next; },
+    getCurrentCwd: () => rt.currentCwd,
+    setCurrentCwd: (next) => { rt.currentCwd = next; },
+    getConfig: () => rt.config,
+    getSession: () => rt.session,
+    getRoute: () => rt.route,
+    getLastProjectMcpKey: () => rt.lastProjectMcpKey,
+    setLastProjectMcpKey: (next) => { rt.lastProjectMcpKey = next; },
     isCodeGraphPrewarmLazy: () => codeGraphPrewarmLazy,
-    isCodeGraphFirstTurnPrewarmDone: () => codeGraphFirstTurnPrewarmDone,
+    isCodeGraphFirstTurnPrewarmDone: () => rt.codeGraphFirstTurnPrewarmDone,
     getCodeGraphPrewarmDelayMs: () => codeGraphPrewarmDelayMs,
-    setSessionNeedsCwdRefresh: (next) => { sessionNeedsCwdRefresh = next; },
+    setSessionNeedsCwdRefresh: (next) => { rt.sessionNeedsCwdRefresh = next; },
     connectConfiguredMcp,
     invalidatePreSessionToolSurface: (...a) => invalidatePreSessionToolSurface(...a),
     scheduleCodeGraphPrewarm: (...a) => scheduleCodeGraphPrewarm(...a),
@@ -706,7 +710,7 @@ export async function createMixdogSessionRuntime({
     dataDir: cfgMod.getPluginData(),
     cwd,
     awaitKeychainPrewarm,
-    isKeychainPrewarmReady: () => keychainPrewarmWaitDone,
+    isKeychainPrewarmReady: () => rt.keychainPrewarmWaitDone,
     // SubagentStart/SubagentStop: bridge internal worker spawn/finish to the
     // standard hook bus. agent_type is passed top-level via hookCommonPayload
     // (added to hook-bus buildEventPayload passthrough). Best-effort.
@@ -723,7 +727,7 @@ export async function createMixdogSessionRuntime({
   bootProfile('agent:ready', { ms: (performance.now() - agentToolStartedAt).toFixed(1) });
   const agentStatusState = () => {
     try {
-      const status = agentTool.getStatus?.({ clientHostPid: session?.clientHostPid || process.pid }) || {};
+      const status = agentTool.getStatus?.({ clientHostPid: rt.session?.clientHostPid || process.pid }) || {};
       return {
         agentWorkers: Array.isArray(status.workers) ? status.workers : [],
         agentJobs: Array.isArray(status.jobs) ? status.jobs : [],
@@ -744,28 +748,10 @@ export async function createMixdogSessionRuntime({
       // newer remote session. Drop remote mode entirely on this session (no
       // handover, no retry) and tell UI listeners so the indicator updates.
       if (msg?.method === 'notifications/mixdog/remote') {
-        // Any acquire/supersede verdict resolves an in-flight auto claim attempt.
-        remoteClaimPending = false;
-        if (msg?.params?.state === 'superseded' && remoteEnabled) {
+        if (msg?.params?.state === 'superseded' && rt.remoteEnabled) {
           stopRemote('superseded-by-newer-remote-session');
           emitRemoteStateChange(false, 'superseded');
         }
-        // Symmetric acquire: the worker took the bridge seat (boot make-before-
-        // break or activate). Flip remote ON via the same side-state a user
-        // /remote toggles — remoteEnabled + transcript writer — but WITHOUT
-        // re-invoking channel start (the worker is already running; startRemote
-        // would re-fork/activate). Idempotent: no-op when already enabled.
-        if (msg?.params?.state === 'acquired' && !remoteEnabled) {
-          remoteEnabled = true;
-          if (!remoteSessionId) remoteSessionId = session?.id || null;
-          ensureRemoteTranscriptWriter();
-          // Auto-acquire: the worker restored yesterday's transcript from
-          // persisted status and we just created the CURRENT writer. Push the
-          // repoint now instead of waiting for the next inbound parent-chain
-          // steal, so outbound forwarding never tails a stale transcript.
-          pushTranscriptRebind();
-          emitRemoteStateChange(true, 'acquired');
-        }
         return;
       }
       if (msg?.method !== 'notifications/claude/channel') return;
@@ -774,8 +760,8 @@ export async function createMixdogSessionRuntime({
       const content = channelNotificationModelContent(params);
       if (!content) return;
       const { handled } = emitRuntimeNotification(content, meta);
-      if (!handled && session?.id && shouldMirrorChannelNotificationToPending(meta)) {
-        try { mgr.enqueuePendingMessage(session.id, content); } catch {}
+      if (!handled && rt.session?.id && shouldMirrorChannelNotificationToPending(meta)) {
+        try { mgr.enqueuePendingMessage(rt.session.id, content); } catch {}
       }
     },
   });
@@ -811,12 +797,12 @@ export async function createMixdogSessionRuntime({
     applyPreSessionToolSelection,
   } = createToolSurface({
     mgr,
-    mode,
+    mode: rt.mode,
     standaloneTools,
     agentToolNames,
-    getSession: () => session,
-    getRoute: () => route,
-    getConfig: () => config,
+    getSession: () => rt.session,
+    getRoute: () => rt.route,
+    getConfig: () => rt.config,
     cfgMod,
     loadWorkflowPack,
     activeWorkflowId,
@@ -824,20 +810,20 @@ export async function createMixdogSessionRuntime({
   });
 
   const { contextStatus: computeContextStatus, invalidateContextStatusCache } = createContextStatus({
-    getSession: () => session,
-    getRoute: () => route,
-    getCurrentCwd: () => currentCwd,
-    getMode: () => mode,
+    getSession: () => rt.session,
+    getRoute: () => rt.route,
+    getCurrentCwd: () => rt.currentCwd,
+    getMode: () => rt.mode,
   });
   internalTools.setInternalToolsProvider({
     tools: [...standaloneTools, ...searchRuntimeTools.filter((tool) => tool?.public === false)],
     executor: async (name, args, callerCtx = {}) => {
-      const callerCwd = callerCtx?.callerCwd || currentCwd;
+      const callerCwd = callerCtx?.callerCwd || rt.currentCwd;
       if (name === 'search' || name === 'web_fetch' || name === 'local_fetch' || name === 'image_fetch') {
         return dispatchSearchRuntimeTool(name, args, callerCtx, {
           getSearchModule,
-          getCurrentCwd: () => currentCwd,
-          getSession: () => session,
+          getCurrentCwd: () => rt.currentCwd,
+          getSession: () => rt.session,
           notifyFnForSession,
           runNativeWebSearch,
         });
@@ -848,7 +834,7 @@ export async function createMixdogSessionRuntime({
         return await memoryMod.handleToolCall(
           name,
           memoryToolArgsForCaller(args, callerCwd),
-          callerCtx?.signal || session?.controller?.signal || null,
+          callerCtx?.signal || rt.session?.controller?.signal || null,
         );
       }
       if (name === 'code_graph') {
@@ -857,20 +843,20 @@ export async function createMixdogSessionRuntime({
         return await codeGraphMod.executeCodeGraphTool(name, args || {}, args?.cwd || callerCwd);
       }
       if (name === 'tool_search' || name === 'load_tool') {
-        return renderToolSearch(args, activeToolSurface(), mode, { mcpStatus });
+        return renderToolSearch(args, activeToolSurface(), rt.mode, { mcpStatus });
       }
       if (name === 'explore') {
-        const callerSessionId = callerCtx?.callerSessionId || session?.id || null;
+        const callerSessionId = callerCtx?.callerSessionId || rt.session?.id || null;
         return await runExplore(args || {}, {
           callerCwd: args?.cwd ? resolveCwdPath(args.cwd) : callerCwd,
           callerSessionId,
           routingSessionId: callerSessionId,
-          clientHostPid: callerCtx?.clientHostPid || session?.clientHostPid || process.pid,
+          clientHostPid: callerCtx?.clientHostPid || rt.session?.clientHostPid || process.pid,
           notifyFn: notifyFnForSession(callerSessionId),
           // Cascade caller cancellation (ESC / owner abort) into the explore
           // fan-out so every child dispatch tears down immediately — same
           // signal the adjacent native search already forwards.
-          signal: callerCtx?.signal || session?.controller?.signal,
+          signal: callerCtx?.signal || rt.session?.controller?.signal,
         });
       }
       if (name === 'cwd') {
@@ -880,17 +866,17 @@ export async function createMixdogSessionRuntime({
         } else if (action !== 'get') {
           throw new Error(`cwd: unknown action "${action}"`);
         }
-        return JSON.stringify({ cwd: currentCwd, sessionId: session?.id || null }, null, 2);
+        return JSON.stringify({ cwd: rt.currentCwd, sessionId: rt.session?.id || null }, null, 2);
       }
       if (name === 'session_manage') {
         // Lead/owner sessions only: an agent worker resetting its own
         // transcript mid-task would corrupt the delegation contract, and it
         // must never reach the owner conversation either.
         const callerSessionId = callerCtx?.callerSessionId || null;
-        if (callerSessionId && session?.id && callerSessionId !== session.id) {
+        if (callerSessionId && rt.session?.id && callerSessionId !== rt.session.id) {
           throw new Error('session_manage: only the lead session may reset the conversation');
         }
-        if (!session?.id) throw new Error('session_manage: no active session');
+        if (!rt.session?.id) throw new Error('session_manage: no active session');
         const action = clean(args?.action).toLowerCase();
         if (action !== 'clear' && action !== 'compact_clear') {
           throw new Error(`session_manage: unknown action "${action}" (use clear | compact_clear)`);
@@ -900,7 +886,7 @@ export async function createMixdogSessionRuntime({
         // boundary the idle auto-clear uses).
         // Pin to the current session id so a resume/new-session between
         // scheduling and consumption can never clear the wrong conversation.
-        pendingSessionReset = { action, sessionId: session.id };
+        rt.pendingSessionReset = { action, sessionId: rt.session.id };
         return action === 'clear'
           ? 'Session reset scheduled: full clear will run when this turn ends. All prior context will be gone.'
           : 'Session reset scheduled: the conversation will be summarized (compact) and cleared when this turn ends; key context carries forward in the summary.';
@@ -909,12 +895,12 @@ export async function createMixdogSessionRuntime({
         return skillToolContent(args?.name);
       }
       if (name === 'agent') {
-        const callerSessionId = callerCtx?.callerSessionId || session?.id || null;
+        const callerSessionId = callerCtx?.callerSessionId || rt.session?.id || null;
         return await agentTool.execute(args, {
           callerCwd,
           invocationSource: 'model-tool',
           callerSessionId,
-          clientHostPid: callerCtx?.clientHostPid || session?.clientHostPid || process.pid,
+          clientHostPid: callerCtx?.clientHostPid || rt.session?.clientHostPid || process.pid,
           signal: callerCtx?.signal,
           notifyFn: notifyFnForSession(callerSessionId),
         });
@@ -927,7 +913,7 @@ export async function createMixdogSessionRuntime({
     },
   });
   internalTools.markBootReady?.();
-  try { lastProjectMcpKey = resolve(currentCwd) + '\u0000' + JSON.stringify(readProjectMcpServers(currentCwd)); } catch { lastProjectMcpKey = null; }
+  try { rt.lastProjectMcpKey = resolve(rt.currentCwd) + '\u0000' + JSON.stringify(readProjectMcpServers(rt.currentCwd)); } catch { rt.lastProjectMcpKey = null; }
   void connectConfiguredMcp()
     .then((status) => bootProfile('mcp:ready', {
       connected: Number(status?.connectedCount || 0),
@@ -976,13 +962,13 @@ export async function createMixdogSessionRuntime({
     displayConfig,
     ensureConfigForRouteProvider,
   } = createConfigLifecycle({
-    getConfig: () => config,
-    setConfig: (next) => { config = next; },
-    getSearchRoute: () => searchRoute,
-    setSearchRoute: (next) => { searchRoute = next; },
-    getConfigHasSecrets: () => configHasSecrets,
-    setConfigHasSecrets: (next) => { configHasSecrets = next; },
-    getRoute: () => route,
+    getConfig: () => rt.config,
+    setConfig: (next) => { rt.config = next; },
+    getSearchRoute: () => rt.searchRoute,
+    setSearchRoute: (next) => { rt.searchRoute = next; },
+    getConfigHasSecrets: () => rt.configHasSecrets,
+    setConfigHasSecrets: (next) => { rt.configHasSecrets = next; },
+    getRoute: () => rt.route,
     cfgMod,
     sharedCfgMod,
     setBackend,
@@ -997,7 +983,7 @@ export async function createMixdogSessionRuntime({
     STANDALONE_DATA_DIR,
   });
 
-  async function ensureProvidersReady(providerConfig = config.providers || {}) {
+  async function ensureProvidersReady(providerConfig = rt.config.providers || {}) {
     await awaitKeychainPrewarm();
     const initKey = providerInitCacheKey(providerConfig);
     const existing = providerInitPromises.get(initKey);
@@ -1017,16 +1003,16 @@ export async function createMixdogSessionRuntime({
       if (providerInitPromises.get(initKey) === providerInitPromise) providerInitPromises.delete(initKey);
       throw error;
     }
-    if (!startupProviderCatalogRefreshStarted && !closeRequested) {
-      startupProviderCatalogRefreshStarted = true;
-      startupProviderCatalogRefreshPending = true;
+    if (!rt.startupProviderCatalogRefreshStarted && !rt.closeRequested) {
+      rt.startupProviderCatalogRefreshStarted = true;
+      rt.startupProviderCatalogRefreshPending = true;
       try {
         void Promise.resolve(reg.refreshProviderCatalogsOnStartup())
           .then(() => {
             // Fresh catalog rows invalidate model-derived caches, but the
             // already initialized provider registry remains valid.
             invalidateProviderCaches({ preserveProviderInit: true });
-            startupProviderCatalogRefreshPending = false;
+            rt.startupProviderCatalogRefreshPending = false;
             // Secrets-aware: a no-secrets rewarm bumps the load sequence and
             // is never adopted, so it discarded the in-flight authoritative
             // load and left the picker cache empty — every later consumer then
@@ -1035,12 +1021,12 @@ export async function createMixdogSessionRuntime({
             bootProfile('provider-catalogs:refresh-ready');
           })
           .catch((error) => {
-            startupProviderCatalogRefreshPending = false;
+            rt.startupProviderCatalogRefreshPending = false;
             bootProfile('provider-catalogs:refresh-failed', { error: error?.message || String(error) });
           });
         bootProfile('provider-catalogs:refresh-started');
       } catch (error) {
-        startupProviderCatalogRefreshPending = false;
+        rt.startupProviderCatalogRefreshPending = false;
         bootProfile('provider-catalogs:refresh-failed', { error: error?.message || String(error) });
       }
     }
@@ -1051,11 +1037,11 @@ export async function createMixdogSessionRuntime({
     currentMainSearchModelMeta,
     runNativeWebSearch,
   } = createNativeSearch({
-    getRoute: () => route,
-    getSearchRoute: () => searchRoute,
-    setSearchRoute: (next) => { searchRoute = next; },
-    getConfig: () => config,
-    getSession: () => session,
+    getRoute: () => rt.route,
+    getSearchRoute: () => rt.searchRoute,
+    setSearchRoute: (next) => { rt.searchRoute = next; },
+    getConfig: () => rt.config,
+    getSession: () => rt.session,
     getReg: () => reg,
     ensureFullConfig,
     awaitKeychainPrewarm,
@@ -1072,23 +1058,25 @@ export async function createMixdogSessionRuntime({
   // cachedProviderSetup(quick) may nudge scheduleProviderSetupWarmup on a cold
   // quick-cache fill. Thread it by reference so the scheduler is reachable once
   // it exists (a pre-scheduler quick fill simply skips the warmup nudge).
-  let scheduleProviderSetupWarmupRef = () => {};
+  rt.scheduleProviderSetupWarmupRef = () => {};
   const {
     refreshStatuslineUsageSnapshot,
     cachedProviderSetup,
     hasProviderSetupCached,
     getUsageDashboard,
+    consumeCodexRateLimitResetCredit,
   } = createProviderUsage({
     caches: providerUsageCaches,
-    getConfig: () => config,
+    getConfig: () => rt.config,
     getReg: () => reg,
     displayConfig,
     providerSetup,
     createUsageDashboard,
     fetchOAuthUsageSnapshot,
-    isCloseRequested: () => closeRequested,
+    consumeOpenAICodexResetCredit,
+    isCloseRequested: () => rt.closeRequested,
     getProviderSetupWarmupTimer: () => warmupTimers.providerSetupWarmupTimer,
-    scheduleProviderSetupWarmup: (delayMs) => scheduleProviderSetupWarmupRef(delayMs),
+    scheduleProviderSetupWarmup: (delayMs) => rt.scheduleProviderSetupWarmupRef(delayMs),
   });
 
   // Holder filled after createQuickModelRows resolves; provider-models and
@@ -1100,7 +1088,7 @@ export async function createMixdogSessionRuntime({
   // lookupModelMeta may fire scheduleProviderModelWarmup on a cache miss. Thread
   // it by reference so the scheduler is called once it exists (miss handling is
   // best-effort; a pre-scheduler miss simply skips the warmup nudge).
-  let scheduleProviderModelWarmupRef = () => {};
+  rt.scheduleProviderModelWarmupRef = () => {};
   const {
     modelMetaKey,
     lookupModelMeta,
@@ -1113,8 +1101,8 @@ export async function createMixdogSessionRuntime({
   } = createProviderModels({
     caches: providerModelCaches,
     modelMetaByRoute,
-    getRoute: () => route,
-    getConfig: () => config,
+    getRoute: () => rt.route,
+    getConfig: () => rt.config,
     getReg: () => reg,
     searchCapableFor,
     sortProviderModelsRaw,
@@ -1125,7 +1113,7 @@ export async function createMixdogSessionRuntime({
     awaitKeychainPrewarm,
     ensureProvidersReady,
     bootProfile,
-    scheduleProviderModelWarmup: () => scheduleProviderModelWarmupRef(),
+    scheduleProviderModelWarmup: () => rt.scheduleProviderModelWarmupRef(),
     quickHelpers: providerModelQuickHelpers,
   });
 
@@ -1136,8 +1124,8 @@ export async function createMixdogSessionRuntime({
     searchModelsFromRows,
     searchRowsWithDefault,
   } = createQuickModelRows({
-    getRoute: () => route,
-    getSearchRoute: () => searchRoute,
+    getRoute: () => rt.route,
+    getSearchRoute: () => rt.searchRoute,
     displayConfig,
     providerModelCacheRow,
     providerModelsFromCacheRows,
@@ -1158,289 +1146,71 @@ export async function createMixdogSessionRuntime({
     searchRowsWithDefault,
   });
 
-  async function resolveMissingRouteModelForFirstTurn() {
-    if (routeHasModel()) return route;
-    const models = await collectProviderModels();
-    const picked = models[0] || null;
-    if (!picked) {
-      throw new Error('No provider models available. Open /providers to sign in, then /model to choose a model.');
-    }
-    route = {
-      ...route,
-      provider: picked.provider,
-      model: picked.id,
-      preset: null,
-    };
-    return route;
-  }
-
-  async function refreshRouteEffort(modelMetaOverride = null) {
-    await ensureProvidersReady(ensureProviderEnabled(config, route.provider));
-    const modelMeta = modelMetaOverride || await lookupModelMeta(route.provider, route.model);
-    const requested = hasOwn(route, 'effort') ? route.effort : (route.preset?.effort || null);
-    const effectiveEffort = coerceEffortFor(route.provider, modelMeta, requested);
-    const fastCapable = fastCapableFor(route.provider, modelMeta);
-    // Carry the catalog display name onto the route so the statusline shows a
-    // human label (e.g. "Claude Fable 5") for preset-less direct models instead
-    // of the raw id. `name` is only trusted when it differs from the raw model
-    // id (some providers echo the id as `name`), so it can't clobber a better
-    // already-resolved label. Falls back to existing route.modelDisplay, then unset.
-    const metaName = clean(modelMeta?.name);
-    const modelDisplay = clean(modelMeta?.display) || clean(modelMeta?.displayName)
-      || (metaName && metaName !== clean(route.model) ? metaName : '')
-      || clean(route.modelDisplay);
-    route = {
-      ...route,
-      fast: fastCapable ? route.fast === true : false,
-      fastCapable,
-      effectiveEffort,
-      effortOptions: effortItemsFor(route.provider, modelMeta, effectiveEffort),
-      ...(modelDisplay ? { modelDisplay } : {}),
-    };
-    return route;
-  }
-
-  function routeHasModel() {
-    return !!clean(route?.model);
-  }
-
-  function requireModelRoute() {
-    if (routeHasModel()) return;
-    throw new Error('No model configured. Open /providers to sign in, then /model to choose a model.');
-  }
-
-  async function recreateCurrentSessionIfReady() {
-    if (!routeHasModel()) {
-      session = null;
-      return null;
-    }
-    return await createCurrentSession();
-  }
-
-  async function createCurrentSession(reason = 'demand') {
-    if (sessionCreatePromise) return await sessionCreatePromise;
-    if (session?.id && !sessionNeedsCwdRefresh) {
-      const liveSession = mgr.getSession(session.id);
-      if (liveSession && liveSession.closed !== true && liveSession.status !== 'closed') {
-        session = liveSession;
-        return session;
-      }
-      session = null;
-    }
-
-    const startedAt = performance.now();
-    bootProfile('session:create:start', { mode, reason });
-    const promise = (async () => {
-      // Demand-only: this starts only after the user submits (unless an
-      // explicitly enabled prewarm caller asks for a session). Core-memory
-      // startup does not depend on keychain/provider readiness, so overlap the
-      // two cold paths instead of paying their bounded waits serially.
-      const coreMemoryContextPromise = loadCoreMemoryContext();
-      await awaitKeychainPrewarm();
-      ensureConfigForRouteProvider();
-      await resolveMissingRouteModelForFirstTurn();
-      requireModelRoute();
-      bootProfile('session:create:route-ready', { ms: (performance.now() - startedAt).toFixed(1) });
-      // Route effort waits on provider readiness while the already-started
-      // memory load continues independently.
-      const [, coreMemoryContext] = await Promise.all([
-        refreshRouteEffort(),
-        coreMemoryContextPromise,
-      ]);
-      bootProfile('session:create:effort-ready', { ms: (performance.now() - startedAt).toFixed(1) });
-      const providerImpl = reg.getProvider(route.provider);
-      if (!providerImpl) {
-        throw new Error(`Provider "${route.provider}" is not configured.`);
-      }
-      bootProfile('session:create:provider-ready', { ms: (performance.now() - startedAt).toFixed(1) });
-      if (closeRequested) throw new Error('runtime is closing');
-      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
-      // Load the active WORKFLOW.md pack once for both summary + context block.
-      const { summary: workflow, context: workflowContext } = activeWorkflowContext(config, dataDir);
-      const sessionOpts = {
-        provider: route.provider,
-        model: route.model,
-        preset: route.preset || undefined,
-        tools: toolSpecForMode(mode),
-        owner: 'cli',
-        agent: 'lead',
-        lane: 'cli',
-        sourceType: 'lead',
-        sourceName: 'main',
-        clientHostPid: process.pid,
-        disallowedTools: LEAD_DISALLOWED_TOOLS,
-        cwd: currentCwd,
-        ...(desktopSession && typeof desktopSession === 'object' ? { desktopSession } : {}),
-        coreMemoryContext,
-        workflow,
-        workflowContext,
-        fast: route.fast === true,
-        compaction: config.compaction && typeof config.compaction === 'object'
-          ? normalizeCompactionConfig(config.compaction, { memoryEnabled: memoryEnabled() })
-          : undefined,
-      };
-      if (hasOwn(route, 'effort') || route.effectiveEffort) {
-        sessionOpts.effort = route.effectiveEffort || null;
-      }
-      session = mgr.createSession(sessionOpts);
-      sessionNeedsCwdRefresh = false;
-      attachSessionHooks(session, { hooks, hookCommonPayload, getCwd: () => currentCwd });
-      // Every-create MCP fold (NO blocking): seed the INITIAL provider-visible
-      // surface (and native BP1 manifest) from MCP servers connected at create
-      // time. There is no await — a boot connect still mid-handshake is caught on
-      // the first user turn by refreshInitialDeferredMcpSurface (session-turn-api),
-      // which re-folds the live registry into the first-turn surface before the
-      // prompt renders. This fold keeps recreate paths (cwd change with MCP
-      // already connected) seeding their manifest instead of re-announcing late.
-      let connectedMcpTools = [];
-      try { connectedMcpTools = mcpClient.getMcpTools?.() || []; }
-      catch { connectedMcpTools = []; }
-      applyDeferredToolSurface(
-        session,
-        deferredSurfaceModeForLead(mode),
-        connectedMcpTools.length ? [...modelStandaloneTools(), ...connectedMcpTools] : modelStandaloneTools(),
-        { provider: route.provider },
-      );
-      // Session-local one-shot: mark this FRESH session eligible for the
-      // first-turn deferred-surface refresh (session-turn-api). A resumed
-      // session (prior transcript) is NEVER marked, so its already-baked BP1 is
-      // never rebuilt or re-announced — the gate is per-session, not the
-      // process-wide firstTurnCompleted.
-      session.deferredInitialRefreshPending = !/resume/i.test(String(reason || ''));
-      applyPreSessionToolSelection();
-      writeStatuslineRoute(statusRoutes, session, route);
-      hooks.emit('session:create', { sessionId: session.id, provider: route.provider, model: route.model, toolMode: mode, cwd: currentCwd });
-      // SessionStart: bridge to the standard project hook bus. Best-effort;
-      // a hook error must never break session creation. additionalContext is
-      // injected before the first user turn as a system-reminder context pair.
-      try {
-        const startSource = /resume/i.test(String(reason || ''))
-          ? 'resume'
-          : (/clear/i.test(String(reason || '')) ? 'clear' : 'startup');
-        const startDispatch = await hooks.dispatch('SessionStart', hookCommonPayload({ session_id: session.id, source: startSource, model: route.model }));
-        const startContext = Array.isArray(startDispatch?.additionalContext)
-          ? startDispatch.additionalContext.join('\n\n')
-          : String(startDispatch?.additionalContext || '');
-        if (startContext.trim()) {
-          session.messages.push({ role: 'user', content: `<system-reminder>\n# SessionStart Hook Context\n${startContext.trim()}\n</system-reminder>` });
-          session.messages.push({ role: 'assistant', content: '.' });
-          session.updatedAt = Date.now();
-        }
-      } catch { /* best-effort: never break session create */ }
-      bootProfile('session:create:ready', {
-        ms: (performance.now() - startedAt).toFixed(1),
-        reason,
-        tools: Array.isArray(session.tools) ? session.tools.length : 0,
-        catalog: Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog.length : 0,
-      });
-      // A rebind push may have been deferred (e.g. 'acquired' landed before this
-      // session existed). The writer is now bindable — flush it exactly once.
-      flushPendingTranscriptRebind();
-      return session;
-    })();
-
-    sessionCreatePromise = promise;
-    try {
-      return await promise;
-    } finally {
-      if (sessionCreatePromise === promise) sessionCreatePromise = null;
-    }
-  }
-
+  // Route resolution + createCurrentSession: session-lifecycle.mjs.
   const {
+    resolveMissingRouteModelForFirstTurn,
     scheduleProviderWarmup,
     scheduleProviderSetupWarmup,
     scheduleProviderModelWarmup,
     scheduleModelCatalogWarmup,
     scheduleStatuslineUsageWarmup,
     scheduleStatuslineUsageRefresh,
-  } = createWarmupSchedulers({
-    timers: warmupTimers,
-    bootProfile,
-    getRoute: () => route,
-    getConfig: () => config,
-    isCloseRequested: () => closeRequested,
-    getActiveTurnCount: () => activeTurnCount,
-    getSessionCreatePromise: () => sessionCreatePromise,
-    getProviderModelsCache: () => providerModelCaches.providerModelsCache,
-    getProviderModelsPromise: () => providerModelCaches.providerModelsPromise,
-    reloadFullConfig,
-    ensureConfigForRouteProvider,
-    awaitKeychainPrewarm,
-    ensureProvidersReady,
-    ensureProviderEnabled,
-    refreshStatuslineUsageSnapshot,
-    warmProviderModelCache,
-    cachedProviderSetup,
-    warmCatalogsInBackground,
-    isFirstTurnCompleted: () => firstTurnCompleted,
-    isCatalogRefreshPending: () => startupProviderCatalogRefreshPending,
-    envFlag,
-    delays: {
-      providerWarmupDelayMs,
-      providerSetupWarmupDelayMs,
-      providerModelWarmupDelayMs,
-      modelCatalogWarmupDelayMs,
-      statuslineUsageWarmupDelayMs,
-      statuslineUsageRefreshDelayMs,
-      backgroundBusyRetryMs,
-    },
-    flags: {
-      providerWarmupEnabled,
-      modelPrefetchEnabled,
-      modelCatalogWarmupEnabled,
-    },
-  });
-  scheduleProviderModelWarmupRef = scheduleProviderModelWarmup;
-  scheduleProviderSetupWarmupRef = scheduleProviderSetupWarmup;
-
-  const {
     scheduleCodeGraphPrewarm,
     scheduleLeadSessionPrewarm,
+    scheduleToolRuntimeWarmup,
     invokeChannelStart,
     scheduleChannelStart,
-  } = createPrewarmSchedulers({
-    timers: prewarmTimers,
-    bootProfile,
-    getCurrentCwd: () => currentCwd,
-    isCloseRequested: () => closeRequested,
-    getActiveTurnCount: () => activeTurnCount,
-    getSessionCreatePromise: () => sessionCreatePromise,
-    getSession: () => session,
-    isRemoteEnabled: () => remoteEnabled,
-    channelsEnabled,
-    hasActiveAutomation,
-    getCodeGraphModule,
+    refreshRouteEffort,
+    routeHasModel,
+    requireModelRoute,
+    recreateCurrentSessionIfReady,
     createCurrentSession,
-    channels,
-    envFlag,
-    delays: {
-      codeGraphPrewarmDelayMs,
-      channelStartDelayMs,
-      sessionPrewarmDelayMs,
-      backgroundBusyRetryMs,
-    },
-    flags: {
-      codeGraphPrewarmEnabled,
-      sessionPrewarmEnabled,
-    },
-    state: prewarmState,
-  });
-
-  // Remote transcript binding + worker rebind pushes live in
-  // remote-transcript.mjs; the facade injects the mutable session/cwd/remote
-  // state it needs.
-  const remoteTranscript = createRemoteTranscript({
-    getSession: () => session,
-    getCwd: () => currentCwd,
-    isRemoteEnabled: () => remoteEnabled,
-    getRemoteSessionId: () => remoteSessionId,
-    setRemoteSessionId: (next) => { remoteSessionId = next; },
-    isCloseRequested: () => closeRequested,
+    remoteTranscript,
+  } = createSessionLifecycle({
+    rt,
+    collectProviderModels,
+    ensureProvidersReady,
+    lookupModelMeta,
+    mgr,
+    loadCoreMemoryContext,
+    awaitKeychainPrewarm,
+    ensureConfigForRouteProvider,
+    reg,
+    cfgMod,
+    activeWorkflowContext,
+    memoryEnabled,
+    hooks,
+    hookCommonPayload,
+    mcpClient,
+    modelStandaloneTools,
+    applyPreSessionToolSelection,
+    statusRoutes,
+    warmupTimers,
+    providerModelCaches,
+    reloadFullConfig,
+    refreshStatuslineUsageSnapshot,
+    warmProviderModelCache,
+    cachedProviderSetup,
+    providerWarmupDelayMs,
+    providerSetupWarmupDelayMs,
+    providerModelWarmupDelayMs,
+    modelCatalogWarmupDelayMs,
+    statuslineUsageWarmupDelayMs,
+    statuslineUsageRefreshDelayMs,
+    backgroundBusyRetryMs,
+    providerWarmupEnabled,
+    modelPrefetchEnabled,
+    modelCatalogWarmupEnabled,
+    prewarmTimers,
     channelsEnabled,
+    getCodeGraphModule,
     channels,
-    mgr,
-    bootProfile,
+    codeGraphPrewarmDelayMs,
+    channelStartDelayMs,
+    sessionPrewarmDelayMs,
+    codeGraphPrewarmEnabled,
+    sessionPrewarmEnabled,
+    prewarmState,
   });
   const ensureRemoteTranscriptWriter = () => remoteTranscript.ensureRemoteTranscriptWriter();
   const pushTranscriptRebind = () => remoteTranscript.pushTranscriptRebind();
@@ -1449,14 +1219,12 @@ export async function createMixdogSessionRuntime({
   // Remote (channel relay) claim/release/stop live in remote-control.mjs; the
   // facade injects the mutable session + remote state they mutate.
   const remoteControl = createRemoteControl({
-    getSession: () => session,
-    isRemoteEnabled: () => remoteEnabled,
-    setRemoteEnabled: (next) => { remoteEnabled = next; },
-    getRemoteSessionId: () => remoteSessionId,
-    setRemoteSessionId: (next) => { remoteSessionId = next; },
-    isRemoteClaimPending: () => remoteClaimPending,
-    setRemoteClaimPending: (next) => { remoteClaimPending = next; },
-    isCloseRequested: () => closeRequested,
+    getSession: () => rt.session,
+    isRemoteEnabled: () => rt.remoteEnabled,
+    setRemoteEnabled: (next) => { rt.remoteEnabled = next; },
+    getRemoteSessionId: () => rt.remoteSessionId,
+    setRemoteSessionId: (next) => { rt.remoteSessionId = next; },
+    isCloseRequested: () => rt.closeRequested,
     clearChannelStartTimer: () => {
       if (prewarmTimers.channelStartTimer) {
         clearTimeout(prewarmTimers.channelStartTimer);
@@ -1482,7 +1250,7 @@ export async function createMixdogSessionRuntime({
   const stopRemote = (reason) => remoteControl.stopRemote(reason);
 
   function isRemoteEnabled() {
-    return remoteEnabled;
+    return rt.remoteEnabled;
   }
 
   function withTeardownDeadline(promise, ms, fallback = false) {
@@ -1504,6 +1272,7 @@ export async function createMixdogSessionRuntime({
     codeGraphPrewarm: codeGraphPrewarmEnabled,
   });
   scheduleLeadSessionPrewarm();
+  scheduleToolRuntimeWarmup();
   // Lazy mode (default): skip the startup prewarm entirely; the first turn
   // triggers it instead (see ask()). Eager mode keeps the old startup schedule.
   if (!codeGraphPrewarmLazy) {
@@ -1523,32 +1292,7 @@ export async function createMixdogSessionRuntime({
   // Channels are opt-in: only boot the worker when this session started in (or
   // was toggled into) remote mode. Non-remote sessions never contend for the
   // channel; see startRemote()/stopRemote() and the `/remote` toggle.
-  // `remote.autoStart` in mixdog-config.json makes terminal sessions attempt a
-  // remote claim at boot. Desktop sessions are explicit-only: opening the app
-  // must never claim or spawn the channel bridge until its Remote button is
-  // pressed, while the shared owner-state watcher still reflects a terminal
-  // that already owns it.
-  // The flag lives in the TOP-LEVEL `remote` section of mixdog-config.json
-  // (sibling of agent/ui/channels), not inside the agent section that
-  // cfgMod.loadConfig returns — read it via the shared whole-file reader.
-  // `config?.remote?.autoStart` is kept for back-compat with agent-section
-  // placement.
-  // `remote` (from `mixdog --remote`) is EXPLICIT force-takeover. Config
-  // `remote.autoStart` is AUTO: it must claim the seat ONLY if no live owner
-  // exists (claim-if-vacant) and back off silently otherwise — so it does NOT
-  // set remoteEnabled up front (that would assert remote before the claim is
-  // known to have won). Track it as a separate deferred auto request; the
-  // worker's acquire notification flips remoteEnabled if/when it wins the seat.
-  let remoteAutoStartRequested = false;
-  if (!remoteEnabled && !desktopSession) {
-    try {
-      if (config?.remote?.autoStart === true
-        || sharedCfgMod?.readSection?.('remote')?.autoStart === true) {
-        remoteAutoStartRequested = true;
-      }
-    } catch { /* unreadable config never blocks boot */ }
-  }
-  // Boot-time remote start (autoStart or --remote) is DEFERRED past the TUI's
+  // A manual `mixdog --remote` request is deferred past the TUI's
   // first frame. startRemote() front-loads heavy work — memory daemon fork
   // (PG + forced ONNX embed warmup in the child), eager session create, and
   // the channel-worker fork — and running it inline here interleaves that
@@ -1557,29 +1301,25 @@ export async function createMixdogSessionRuntime({
   // early /remote (startRemote clears it), stopRemote(), and close() all
   // cancel it through the existing clearTimeout paths. Runtime /remote calls
   // still start immediately (user-initiated, UI already painted).
-  if (remoteEnabled || remoteAutoStartRequested) {
-    const remoteStartIntent = remoteEnabled ? 'explicit' : 'auto';
-    bootProfile('channels:autostart-deferred', { delayMs: remoteAutoStartDelayMs, intent: remoteStartIntent });
+  if (rt.remoteEnabled) {
+    bootProfile('channels:manual-start-deferred', { delayMs: remoteAutoStartDelayMs });
     prewarmTimers.channelStartTimer = setTimeout(() => {
       prewarmTimers.channelStartTimer = null;
-      if (closeRequested) return;
-      // Explicit: a /remote-off before the timer clears remoteEnabled — skip.
-      // Auto: always attempt (claim-if-vacant is safe when a live owner exists).
-      if (remoteStartIntent === 'explicit' && !remoteEnabled) return;
-      startRemote({ intent: remoteStartIntent });
+      if (rt.closeRequested || !rt.remoteEnabled) return;
+      startRemote();
     }, remoteAutoStartDelayMs);
     prewarmTimers.channelStartTimer.unref?.();
   } else {
     // Automation decoupling (user decision): enabled schedules/webhooks boot
     // the worker on their own — no remote flag, no remote.autoStart, and no
-    // messaging backend. A later explicit/auto Remote claim promotes the same
+    // messaging backend. A later explicit Remote ON promotes the same
     // daemon without restarting schedules or webhooks.
     prewarmTimers.channelStartTimer = setTimeout(() => {
       prewarmTimers.channelStartTimer = null;
-      if (closeRequested || remoteEnabled) return;
+      if (rt.closeRequested || rt.remoteEnabled) return;
       void hasActiveAutomation()
         .then((active) => {
-          if (!active || closeRequested || remoteEnabled) return;
+          if (!active || rt.closeRequested || rt.remoteEnabled) return;
           bootProfile('channels:automation-autostart');
           void invokeChannelStart();
         })
@@ -1593,10 +1333,10 @@ export async function createMixdogSessionRuntime({
   // token save/forget, setBackend). Extracted to session-runtime/settings-api.mjs
   // and SPREAD into the API object below so the external surface is unchanged.
   const settingsApi = createSettingsApi({
-    getConfig: () => config,
-    getRoute: () => route,
-    getSession: () => session,
-    getRemoteEnabled: () => remoteEnabled,
+    getConfig: () => rt.config,
+    getRoute: () => rt.route,
+    getSession: () => rt.session,
+    getRemoteEnabled: () => rt.remoteEnabled,
     adoptConfig,
     saveConfigAndAdopt,
     scheduleBackendSave,
@@ -1655,35 +1395,36 @@ export async function createMixdogSessionRuntime({
   });
   const providerAuthApi = createProviderAuthApi({
     cfgMod,
-    getConfig: () => config,
+    getConfig: () => rt.config,
     saveConfigAndAdopt,
     displayConfig,
     reloadFullConfig,
     awaitKeychainPrewarm,
-    isKeychainPrewarmReady: () => keychainPrewarmWaitDone,
+    isKeychainPrewarmReady: () => rt.keychainPrewarmWaitDone,
     hasProviderSetupCached,
     invalidateProviderCaches,
     warmProviderModelCache,
-    refreshProviderCatalogs: () => ensureProvidersReady(config.providers || {}).then(() => reg.refreshCatalogs()),
+    refreshProviderCatalogs: () => ensureProvidersReady(rt.config.providers || {}).then(() => reg.refreshCatalogs()),
     cachedProviderSetup,
     getUsageDashboard,
+    consumeCodexRateLimitResetCredit,
     collectProviderModels,
   });
   const mediaApi = createMediaApi();
   const lifecycleApi = createLifecycleApi({
-    getSession: () => session,
-    setSession: (v) => { session = v; },
-    getRoute: () => route,
-    setRoute: (v) => { route = v; },
-    getConfig: () => config,
-    getMode: () => mode,
-    getCurrentCwd: () => currentCwd,
-    getDesktopSession: () => desktopSession,
-    setDesktopSession: (v) => { desktopSession = v; },
-    setCloseRequested: (v) => { closeRequested = v; },
-    getMemoryModPromise: () => memoryModPromise,
-    setMemoryModPromise: (v) => { memoryModPromise = v; },
-    setSessionNeedsCwdRefresh: (v) => { sessionNeedsCwdRefresh = v; },
+    getSession: () => rt.session,
+    setSession: (v) => { rt.session = v; },
+    getRoute: () => rt.route,
+    setRoute: (v) => { rt.route = v; },
+    getConfig: () => rt.config,
+    getMode: () => rt.mode,
+    getCurrentCwd: () => rt.currentCwd,
+    getDesktopSession: () => rt.desktopSession,
+    setDesktopSession: (v) => { rt.desktopSession = v; },
+    setCloseRequested: (v) => { rt.closeRequested = v; },
+    getMemoryModPromise: () => rt.memoryModPromise,
+    setMemoryModPromise: (v) => { rt.memoryModPromise = v; },
+    setSessionNeedsCwdRefresh: (v) => { rt.sessionNeedsCwdRefresh = v; },
     hooks,
     hookCommonPayload,
     mgr,
@@ -1707,15 +1448,17 @@ export async function createMixdogSessionRuntime({
     applyResolvedCwd,
     resolveRoute,
     applyDeferredToolSurface,
+    beginRoutePreparation: (task) => routePreparation.start(task),
+    clearRoutePreparation: () => routePreparation.clear(),
     // Live getter: cwd-refresh session rebuilds must re-evaluate the
     // workflow's agent-tool gate, not reuse the boot-time array.
     getStandaloneTools: modelStandaloneTools,
-    desktopSession,
+    desktopSession: rt.desktopSession,
   });
   const resourceApi = createResourceApi({
-    getConfig: () => config,
-    getSession: () => session,
-    getCurrentCwd: () => currentCwd,
+    getConfig: () => rt.config,
+    getSession: () => rt.session,
+    getCurrentCwd: () => rt.currentCwd,
     cfgMod,
     mgr,
     hooks,
@@ -1733,17 +1476,17 @@ export async function createMixdogSessionRuntime({
     getMemoryModule,
     reloadFullConfig,
     awaitKeychainPrewarm,
-    getActiveTurnCount: () => activeTurnCount,
+    getActiveTurnCount: () => rt.activeTurnCount,
   });
   const modelRouteApi = createModelRouteApi({
-    getConfig: () => config,
-    getRoute: () => route,
-    setRouteState: (v) => { route = v; },
-    getSession: () => session,
-    setSession: (v) => { session = v; },
-    getConfigHasSecrets: () => configHasSecrets,
-    getSearchRouteState: () => searchRoute,
-    setSearchRouteState: (v) => { searchRoute = v; },
+    getConfig: () => rt.config,
+    getRoute: () => rt.route,
+    setRouteState: (v) => { rt.route = v; },
+    getSession: () => rt.session,
+    setSession: (v) => { rt.session = v; },
+    getConfigHasSecrets: () => rt.configHasSecrets,
+    getSearchRouteState: () => rt.searchRoute,
+    setSearchRouteState: (v) => { rt.searchRoute = v; },
     cfgMod,
     reg,
     mgr,
@@ -1768,12 +1511,12 @@ export async function createMixdogSessionRuntime({
     collectSearchProviderModels,
   });
   const workflowAgentsApi = createWorkflowAgentsApi({
-    getConfig: () => config,
-    getRoute: () => route,
-    setRouteState: (v) => { route = v; },
-    getSession: () => session,
-    setSession: (v) => { session = v; },
-    getConfigHasSecrets: () => configHasSecrets,
+    getConfig: () => rt.config,
+    getRoute: () => rt.route,
+    setRouteState: (v) => { rt.route = v; },
+    getSession: () => rt.session,
+    setSession: (v) => { rt.session = v; },
+    getConfigHasSecrets: () => rt.configHasSecrets,
     cfgMod,
     reg,
     mgr,
@@ -1799,26 +1542,26 @@ export async function createMixdogSessionRuntime({
     invalidateContextStatusCache,
   });
   const sessionTurnApi = createSessionTurnApi({
-    getSession: () => session,
-    setSession: (v) => { session = v; },
-    getCurrentCwd: () => currentCwd,
-    getMode: () => mode,
-    setMode: (v) => { mode = v; },
-    getActiveTurnCount: () => activeTurnCount,
-    setActiveTurnCount: (v) => { activeTurnCount = v; },
-    isFirstTurnCompleted: () => firstTurnCompleted,
-    setFirstTurnCompleted: (v) => { firstTurnCompleted = v; },
-    getCodeGraphFirstTurnPrewarmDone: () => codeGraphFirstTurnPrewarmDone,
-    setCodeGraphFirstTurnPrewarmDone: (v) => { codeGraphFirstTurnPrewarmDone = v; },
+    getSession: () => rt.session,
+    setSession: (v) => { rt.session = v; },
+    getCurrentCwd: () => rt.currentCwd,
+    getMode: () => rt.mode,
+    setMode: (v) => { rt.mode = v; },
+    getActiveTurnCount: () => rt.activeTurnCount,
+    setActiveTurnCount: (v) => { rt.activeTurnCount = v; },
+    isFirstTurnCompleted: () => rt.firstTurnCompleted,
+    setFirstTurnCompleted: (v) => { rt.firstTurnCompleted = v; },
+    getCodeGraphFirstTurnPrewarmDone: () => rt.codeGraphFirstTurnPrewarmDone,
+    setCodeGraphFirstTurnPrewarmDone: (v) => { rt.codeGraphFirstTurnPrewarmDone = v; },
     codeGraphPrewarmLazy,
-    getRemoteEnabled: () => remoteEnabled,
-    getCloseRequested: () => closeRequested,
-    getPendingSessionReset: () => pendingSessionReset,
-    setPendingSessionReset: (v) => { pendingSessionReset = v; },
+    getRemoteEnabled: () => rt.remoteEnabled,
+    getCloseRequested: () => rt.closeRequested,
+    getPendingSessionReset: () => rt.pendingSessionReset,
+    setPendingSessionReset: (v) => { rt.pendingSessionReset = v; },
     getTranscriptWriter: () => remoteTranscript.transcriptWriter,
     getTwKey: () => remoteTranscript.transcriptKey,
-    getLastAppendedAssistant: () => _lastAppendedAssistant,
-    setLastAppendedAssistant: (v) => { _lastAppendedAssistant = v; },
+    getLastAppendedAssistant: () => rt._lastAppendedAssistant,
+    setLastAppendedAssistant: (v) => { rt._lastAppendedAssistant = v; },
     scheduleCodeGraphPrewarm,
     refreshSessionForCwdIfNeeded,
     createCurrentSession,
@@ -1846,6 +1589,7 @@ export async function createMixdogSessionRuntime({
     notificationListeners,
     remoteStateListeners,
     awaitInitialMcpConnect,
+    awaitRoutePreparation: () => routePreparation.wait(),
   });
 
   return {
@@ -1855,55 +1599,55 @@ export async function createMixdogSessionRuntime({
     ...mediaApi,
     // Turn-scoped attributed review: child apply_patch diffs for this Lead turn.
     // Lead patches are read from its transcript by the renderer.
-    getTurnReviewDiff: () => getTurnSnapshotReviewDiff(currentCwd, session?.id),
+    getTurnReviewDiff: () => getTurnSnapshotReviewDiff(rt.currentCwd, rt.session?.id),
     get id() {
-      return session?.id || null;
+      return rt.session?.id || null;
     },
     get provider() {
-      return route.provider;
+      return rt.route.provider;
     },
     get model() {
-      return route.model;
+      return rt.route.model;
     },
     get effort() {
-      return route.effectiveEffort || route.effort || route.preset?.effort || null;
+      return rt.route.effectiveEffort || rt.route.effort || rt.route.preset?.effort || null;
     },
     get fast() {
-      return route.fast === true;
+      return rt.route.fast === true;
     },
     get fastCapable() {
-      return route.fastCapable === true;
+      return rt.route.fastCapable === true;
     },
     get effortOptions() {
-      return route.effortOptions || [];
+      return rt.route.effortOptions || [];
     },
     get contextWindow() {
-      return session?.contextWindow || null;
+      return rt.session?.contextWindow || null;
     },
     get rawContextWindow() {
-      return session?.rawContextWindow || session?.contextWindow || null;
+      return rt.session?.rawContextWindow || rt.session?.contextWindow || null;
     },
     get effectiveContextWindowPercent() {
-      return session?.effectiveContextWindowPercent || null;
+      return rt.session?.effectiveContextWindowPercent || null;
     },
     get toolMode() {
-      return mode;
+      return rt.mode;
     },
     get autoClear() {
       return this.getAutoClear();
     },
     get systemShell() {
-      return normalizeSystemShellConfig(config.shell);
+      return normalizeSystemShellConfig(rt.config.shell);
     },
     get searchRoute() {
-      searchRoute = normalizeSearchRouteConfig(config.searchRoute) || normalizeSearchRouteConfig(searchRoute);
-      return searchRoute;
+      rt.searchRoute = normalizeSearchRouteConfig(rt.config.searchRoute) || normalizeSearchRouteConfig(rt.searchRoute);
+      return rt.searchRoute;
     },
     get workflow() {
       const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
-      const active = activeWorkflowSummary(config, dataDir);
-      if (session?.workflow && typeof session.workflow === 'object') {
-        const current = workflowSummary(session.workflow);
+      const active = activeWorkflowSummary(rt.config, dataDir);
+      if (rt.session?.workflow && typeof rt.session.workflow === 'object') {
+        const current = workflowSummary(rt.session.workflow);
         return current?.id && active?.id && current.id !== active.id
           ? { ...active, currentSession: current, appliedToCurrentSession: false }
           : active;
@@ -1914,10 +1658,10 @@ export async function createMixdogSessionRuntime({
       return getOutputStyleStatusCached().current;
     },
     get cwd() {
-      return currentCwd;
+      return rt.currentCwd;
     },
     get session() {
-      return session;
+      return rt.session;
     },
     contextStatus() {
       // Prefer the in-flight working transcript while a turn is running so the
@@ -1942,17 +1686,11 @@ export async function createMixdogSessionRuntime({
     },
     // Session-scoped remote: the owning session id (null when off/unassigned).
     getRemoteSessionId() {
-      return remoteSessionId;
+      return rt.remoteSessionId;
     },
-    // Move the relay seat to the CURRENT session (last-wins within this
-    // engine): rebind the transcript writer + forwarder without restarting
-    // the worker. No-op when remote is off or no session exists.
+    // Back-compat alias for an explicit manual ON in the current session.
     claimRemoteForCurrentSession() {
-      if (!remoteEnabled || !session?.id) return false;
-      remoteSessionId = session.id;
-      ensureRemoteTranscriptWriter();
-      pushTranscriptRebind();
-      return true;
+      return startRemote();
     },
     // Subscribe to non-user-initiated remote flips (seat superseded). Returns
     // an unsubscribe function. TUI uses this to sync its Remote indicator and
@@ -1963,7 +1701,7 @@ export async function createMixdogSessionRuntime({
       return () => remoteStateListeners.delete(listener);
     },
     get clientHostPid() {
-      return session?.clientHostPid || process.pid;
+      return rt.session?.clientHostPid || process.pid;
     },
     ...lifecycleApi,
     ...resourceApi,