mixdog 0.9.68 → 0.9.70

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

@@ -1,7 +1,6 @@
 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';
-import httpMod from 'node:http';
 import keychain from '../lib/keychain-cjs.cjs';
 import './hitch-profile.mjs';
 import { ensureStandaloneEnvironment } from '../standalone/seeds.mjs';
@@ -11,15 +10,13 @@ import { EXPLORE_TOOL, runExplore } from '../standalone/explore-tool.mjs';
 import { createStandaloneChannelWorker } from '../standalone/channel-worker.mjs';
 import { createStandaloneMemoryRuntime } from '../standalone/memory-runtime-proxy.mjs';
 import { createStandaloneHookBus } from '../standalone/hook-bus.mjs';
+import { createRemoteTransitionQueue } from './remote-transition-queue.mjs';
 import { writeLastSessionCwd } from '../runtime/shared/user-cwd.mjs';
 import { cancelBackgroundTasks } from '../runtime/shared/background-tasks.mjs';
 import { createTranscriptWriter } from '../runtime/shared/transcript-writer.mjs';
 import { mixdogHome } from '../runtime/shared/plugin-paths.mjs';
 import { checkLatestVersion, localPackageVersion, isDevInstall } from '../runtime/shared/update-checker.mjs';
 import { spawnStagedInstall, runStagedInstall, isStagedComplete } from '../runtime/shared/staged-update.mjs';
-import {
-  modelVisibleToolCompletionMessage,
-} from '../runtime/shared/tool-execution-contract.mjs';
 import {
   channelNotificationModelContent,
   shouldMirrorChannelNotificationToPending,
@@ -30,12 +27,6 @@ import {
 } from '../runtime/shared/markdown-frontmatter.mjs';
 import { setConfiguredShell } from '../runtime/agent/orchestrator/tools/builtin/shell-runtime.mjs';
 import { hasUserConversationMessage } from '../runtime/agent/orchestrator/session/manager/prompt-utils.mjs';
-import { markCompletionEntry } from '../runtime/agent/orchestrator/session/manager/pending-messages.mjs';
-import {
-  recordDeliveredCompletion,
-  isDeliveredCompletion,
-  logDuplicateSkip,
-} from '../runtime/agent/orchestrator/session/manager/delivered-completions.mjs';
 import {
   beginOAuthProviderLogin,
   forgetProviderAuth,
@@ -236,15 +227,23 @@ import { createCwdPlugins } from './cwd-plugins.mjs';
 import { createSettingsApi } from './settings-api.mjs';
 import { createProviderModels } from './provider-models.mjs';
 import { createProviderUsage } from './provider-usage.mjs';
-import { envFlag, envPresent, envDelayMs } from './env.mjs';
+import { envFlag } from './env.mjs';
 import { bootProfile, profiledImport } from './boot-profile.mjs';
 import { createChannelConfigApi } from './channel-config-api.mjs';
+import { createMediaApi } from './media-api.mjs';
 import { createProviderAuthApi } from './provider-auth-api.mjs';
 import { createContextStatus } from './context-status.mjs';
 import { createLifecycleApi } from './lifecycle-api.mjs';
 import { createResourceApi } from './resource-api.mjs';
 import { createModelRouteApi } from './model-route-api.mjs';
 import { createWorkflowAgentsApi } from './workflow-agents-api.mjs';
+import { createSelfUpdateController } from './self-update.mjs';
+import { createSkillsApi } from './skills-api.mjs';
+import { createRemoteTranscript } from './remote-transcript.mjs';
+import { createRemoteControl } from './remote-control.mjs';
+import { createNotificationBus } from './notification-bus.mjs';
+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 {
@@ -297,6 +296,7 @@ const {
   workflowSummary,
   activeWorkflowSummary,
   loadAgentDefinition,
+  listCustomAgentIds,
   workflowContextBlock,
   activeWorkflowContext,
 } = createWorkflowHelpers({
@@ -334,15 +334,10 @@ export async function createMixdogSessionRuntime({
   // dead/replaced owner (clear, delete) hands the seat to the next current
   // session that asks.
   let remoteSessionId = null;
-  // Remote-mode transcript writer (Discord outbound). Lazily created per
-  // session.id + cwd inside ask(); only active while remoteEnabled.
-  let _transcriptWriter = null;
-  let _twKey = '';
-  // One-shot: an 'acquired' verdict (or other rebind trigger) landed before a
-  // session/writer existed, so the rebind push could not fire. Set true when a
-  // push is deferred; the next session-create / turn-start flushes it exactly
-  // once so the daemon forwarder always ends bound to THIS session's transcript.
-  let _pendingRebind = false;
+  // 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 = '';
@@ -370,6 +365,9 @@ export async function createMixdogSessionRuntime({
         clearTimeout(timeoutId);
         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;
   }
@@ -545,50 +543,26 @@ export async function createMixdogSessionRuntime({
       ...extra,
     };
   }
-  const sessionPrewarmDelayMs = envDelayMs('MIXDOG_SESSION_PREWARM_DELAY_MS', 50, { min: 0, max: 10_000 });
-  const providerSetupWarmupDelayMs = envDelayMs('MIXDOG_PROVIDER_SETUP_WARMUP_DELAY_MS', 300, { min: 0, max: 60_000 });
-  const modelCatalogWarmupDelayMs = envDelayMs('MIXDOG_MODEL_CATALOG_WARMUP_DELAY_MS', 200, { min: 0, max: 60_000 });
-  const providerWarmupDelayMs = envDelayMs('MIXDOG_PROVIDER_WARMUP_DELAY_MS', 1_500, { min: 0, max: 60_000 });
-  // Background model-catalog prefetch delay. Kept short so the first `/model`
-  // open finds a warm cache instead of paying a cold full network load. The
-  // work is async + unref'd, so short-lived detached runtimes still exit
-  // cleanly without waiting on it. Operators can raise it via env if a
-  // detached runtime must avoid the /models round-trip entirely.
-  const providerModelWarmupDelayMs = envDelayMs('MIXDOG_PROVIDER_MODEL_WARMUP_DELAY_MS', 2_000, { min: 0, max: 120_000 });
-  const codeGraphPrewarmDelayMs = envDelayMs('MIXDOG_CODE_GRAPH_PREWARM_DELAY_MS', 250, { min: 0, max: 60_000 });
-  const statuslineUsageWarmupDelayMs = envDelayMs('MIXDOG_STATUSLINE_USAGE_WARMUP_DELAY_MS', 800, { min: 0, max: 60_000 });
-  // Idle keep-alive: re-fetch usage before the statusline's 10-min staleness cut
-  // (LIVE_USAGE_SNAPSHOT_MAX_AGE_MS) so the usage segment does not disappear
-  // while the session sits idle with no turns to trigger a refresh.
-  const statuslineUsageRefreshDelayMs = envDelayMs('MIXDOG_STATUSLINE_USAGE_REFRESH_MS', 240_000, { min: 30_000, max: 540_000 });
-  const channelStartDelayMs = envDelayMs('MIXDOG_CHANNEL_START_DELAY_MS', 10_000, { min: 0, max: 120_000 });
-  const backgroundBusyRetryMs = envDelayMs('MIXDOG_BACKGROUND_BUSY_RETRY_MS', 1_000, { min: 50, max: 10_000 });
-  const sessionPrewarmEnabled = !envFlag('MIXDOG_DISABLE_SESSION_PREWARM')
-    && (envFlag('MIXDOG_ENABLE_SESSION_PREWARM') || envPresent('MIXDOG_SESSION_PREWARM_DELAY_MS'));
-  const providerWarmupEnabled = !envFlag('MIXDOG_DISABLE_PROVIDER_WARMUP')
-    && (
-      envFlag('MIXDOG_ENABLE_PROVIDER_WARMUP')
-      || envFlag('MIXDOG_PROVIDER_WARMUP_BEFORE_FIRST_TURN')
-      || envPresent('MIXDOG_PROVIDER_WARMUP_DELAY_MS')
-      || envPresent('MIXDOG_PROVIDER_MODEL_WARMUP_DELAY_MS')
-    );
-  // Boot-time model-catalog prefetch is intentionally decoupled from the
-  // heavier providerWarmupEnabled gate (which stays opt-in for provider
-  // *init* side effects). Fetching the model list in the background after a
-  // short delay is cheap, fire-and-forget, and unref'd, so it is ON by
-  // default — otherwise the FIRST `/model` open always paid a cold full
-  // network load. Operators can still disable it explicitly.
-  const modelPrefetchEnabled = !envFlag('MIXDOG_DISABLE_PROVIDER_WARMUP')
-    && !envFlag('MIXDOG_DISABLE_MODEL_PREFETCH');
-  const codeGraphPrewarmEnabled = !envFlag('MIXDOG_DISABLE_CODE_GRAPH_PREWARM');
-  const modelCatalogWarmupEnabled = !envFlag('MIXDOG_DISABLE_MODEL_CATALOG_WARMUP');
-  // Lazy code-graph prewarm (default ON): do NOT prewarm at startup / on cwd
-  // change — that fired ~250ms after the first frame and, in a large tree,
-  // burned a worker (and felt like a freeze) before the user did anything.
-  // Instead prewarm ONCE on the first real turn, when a code lookup is actually
-  // imminent. Operators who want the old eager behavior can set
-  // MIXDOG_CODE_GRAPH_PREWARM_EAGER=1.
-  const codeGraphPrewarmLazy = codeGraphPrewarmEnabled && !envFlag('MIXDOG_CODE_GRAPH_PREWARM_EAGER');
+  // Env-tunable boot delays and feature gates: runtime-tunables.mjs.
+  const {
+    sessionPrewarmDelayMs,
+    providerSetupWarmupDelayMs,
+    modelCatalogWarmupDelayMs,
+    providerWarmupDelayMs,
+    providerModelWarmupDelayMs,
+    codeGraphPrewarmDelayMs,
+    statuslineUsageWarmupDelayMs,
+    statuslineUsageRefreshDelayMs,
+    channelStartDelayMs,
+    backgroundBusyRetryMs,
+    remoteAutoStartDelayMs,
+    sessionPrewarmEnabled,
+    providerWarmupEnabled,
+    modelPrefetchEnabled,
+    codeGraphPrewarmEnabled,
+    modelCatalogWarmupEnabled,
+    codeGraphPrewarmLazy,
+  } = readRuntimeTunables();
   let codeGraphFirstTurnPrewarmDone = false;
   const modelMetaByRoute = new Map();
   const notificationListeners = new Set();
@@ -615,6 +589,9 @@ export async function createMixdogSessionRuntime({
   };
   const providerInitPromises = new Map();
   let 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;
   // MCP connect state, owned here so teardown/reconnect paths still observe it;
   // the mcp-glue factory mutates this object in place (see createMcpGlue).
@@ -640,251 +617,40 @@ export async function createMixdogSessionRuntime({
     setDesktopSession: (v) => { desktopSession = v; },
     state: mcpState,
   });
-  let preSessionToolSurface = null;
   const hooksStartedAt = performance.now();
   const hooks = createStandaloneHookBus({ dataDir: cfgMod.getPluginData() });
   hooks.emit('runtime:start', { cwd: currentCwd, provider: route.provider, model: route.model, toolMode: mode });
   bootProfile('hooks:ready', { ms: (performance.now() - hooksStartedAt).toFixed(1) });
 
-  // ---------------------------------------------------------------------
-  // Self-update (npm registry version check + optional auto-install).
-  // updateCheckState mirrors the last-known checkLatestVersion() result;
-  // updateProcessState tracks the in-flight install lifecycle so the TUI can
-  // poll getUpdateStatus() instead of needing a push/event channel. Both are
-  // purely in-memory (per runtime instance) — the on-disk cache lives inside
-  // update-checker.mjs and is what actually enforces the 24h TTL.
-  let updateCheckState = {
-    currentVersion: null,
-    latestVersion: null,
-    updateAvailable: false,
-    lastCheckedAt: 0,
-  };
-  // phase: 'idle' | 'checking' | 'installing' | 'installed' | 'failed'
-  let updateProcessState = { phase: 'idle', version: null, error: null };
-  // Boot detects an available update and STAGES it in the background (a hidden,
-  // detached npm install into ~/.mixdog/data/staging/<ver>). The staged package
-  // is swapped into the global dir on the next clean launch (cli.mjs
-  // pre-import), never while a session is live — so npm never overwrites the
-  // .mjs files node currently holds (the old shutdown `npm install -g` did, and
-  // caused Windows TAR_ENTRY_ERROR / ENOENT). The live-session refcount that a
-  // concurrent launch consults to defer its swap is registered earlier, in
-  // cli.mjs (pre-import), so this process is visible before any runtime loads.
-
-  function autoUpdateEnabled() {
-    return config?.update?.auto !== false;
-  }
-
-  async function checkForUpdateInternal({ force = false } = {}) {
-    if (updateProcessState.phase !== 'installing') updateProcessState.phase = 'checking';
-    try {
-      const result = await checkLatestVersion({ force, dataDir: cfgMod.getPluginData?.() || STANDALONE_DATA_DIR });
-      updateCheckState = {
-        currentVersion: result.currentVersion,
-        latestVersion: result.latestVersion,
-        updateAvailable: result.updateAvailable,
-        lastCheckedAt: result.lastCheckedAt,
-      };
-    } catch {
-      // checkLatestVersion() is already silent-safe; this catch is belt-and-
-      // braces so a boot-time call can never crash the runtime.
-    } finally {
-      if (updateProcessState.phase === 'checking') updateProcessState.phase = 'idle';
-    }
-    return updateCheckState;
-  }
-
-  async function runUpdateNowInternal() {
-    if (updateProcessState.phase === 'installing') {
-      return { ...updateProcessState, alreadyInstalling: true, error: 'update already in progress' };
-    }
-    if (isDevInstall()) {
-      updateProcessState = { phase: 'failed', version: null, error: 'dev install — update skipped' };
-      return updateProcessState;
-    }
-    const ver = updateCheckState.latestVersion;
-    if (!ver || !updateCheckState.updateAvailable) {
-      updateProcessState = { phase: 'idle', version: null, error: null };
-      return { ...updateProcessState, error: 'no update available' };
-    }
-    // "Update now" stages the new version (verified, self-contained) rather than
-    // installing over the live global dir; the swap applies on the next launch.
-    // phase 'installed' here means "staged & ready — restart to apply".
-    updateProcessState = { phase: 'installing', version: ver, error: null };
-    try {
-      const result = await runStagedInstall(ver);
-      if (result?.ok) {
-        updateProcessState = { phase: 'installed', version: result.version || ver, error: null };
-      } else {
-        updateProcessState = { phase: 'failed', version: null, error: result?.error || 'update failed' };
-      }
-    } catch (err) {
-      updateProcessState = { phase: 'failed', version: null, error: err?.message || String(err) };
-    }
-    return updateProcessState;
-  }
-
-  // Non-blocking boot hook: fires after the runtime object below is fully
-  // constructed (setTimeout(0) defers past the synchronous return), so a
-  // slow/hanging registry request can never delay session boot. The check
-  // ALWAYS runs (populates updateCheckState for the maintenance picker), but
-  // when an update is available it kicks off a hidden BACKGROUND staging
-  // install (spawnStagedInstall) into ~/.mixdog/data/staging/<ver>. The actual
-  // swap into the global dir happens on the next clean launch (cli.mjs
-  // pre-import), so npm never overwrites files this live process holds.
-  // force:true — always hit the registry at boot (the 24h disk cache went
-  // stale-visible: it kept reporting an older "latest" than the installed
-  // version). checkLatestVersion() still falls back to the cache offline.
-  // isDevInstall() gate: a git checkout / clone (or non-node_modules install)
-  // must never self-update — staging + swap would fight the working tree.
-  const updateBootTimer = setTimeout(() => {
-    void (async () => {
-      await checkForUpdateInternal({ force: true });
-      if (!(autoUpdateEnabled() && !isDevInstall() && updateCheckState.updateAvailable)) return;
-      const ver = updateCheckState.latestVersion;
-      if (!ver) return;
-      // The notice fires ONLY once staging has completed (a ready-to-apply
-      // package sits on disk) — never upfront — so the user sees no "update
-      // available / installs on quit" nag while the background stage runs
-      // silently. The wording lives in the notice surface (notification-plan):
-      // this emit only carries meta.version. TUI maps meta.kind 'update-notice'
-      // to a transient notice, never a model-visible message; tone 'info' =
-      // non-urgent, applies on the next launch.
-      const announceReady = () => {
-        emitRuntimeNotification('update ready', { kind: 'update-notice', version: ver, tone: 'info' });
-      };
-      // Already staged in a prior session → announce immediately.
-      if (isStagedComplete(ver)) { announceReady(); return; }
-      try { spawnStagedInstall(ver); } catch { /* best-effort background stage */ }
-      // Poll for staging completion, then announce once. The interval is
-      // unref'd so it never holds the process open, and gives up silently
-      // after the cap — the next launch retries.
-      const POLL_MS = 3_000;
-      const MAX_MS = 10 * 60 * 1000;
-      const startedAt = Date.now();
-      const poll = setInterval(() => {
-        if (isStagedComplete(ver)) {
-          clearInterval(poll);
-          announceReady();
-        } else if (Date.now() - startedAt > MAX_MS) {
-          clearInterval(poll);
-        }
-      }, POLL_MS);
-      poll.unref?.();
-    })().catch(() => {});
-  }, 0);
-  updateBootTimer.unref?.();
-
-  function emitRuntimeNotification(content, meta = {}) {
-    const text = String(content || '').trim();
-    if (!text) return { handled: false, modelVisibleDelivered: false };
-    const event = { content: text, meta: meta && typeof meta === 'object' ? meta : {} };
-    let handled = false;
-    for (const listener of [...notificationListeners]) {
-      try {
-        if (listener(event) === true) handled = true;
-      } catch {}
-    }
-    // EXPLICIT model-visible-delivery ack: only the TUI execution-ui path sets
-    // event.modelVisibleDelivered when it enqueues the model-visible completion
-    // body into the active loop. A generic display-only / API listener that
-    // returns true does NOT set it, so `handled` alone must never be read as
-    // "the model saw the body".
-    const modelVisibleDelivered = event.modelVisibleDelivered === true;
-    return { handled, modelVisibleDelivered };
-  }
+  // Self-update: registry check + background staging live in self-update.mjs;
+  // the facade only wires config/data-dir/notification access into it. The
+  // boot check is deferred past this constructor so a hanging registry request
+  // can never delay session boot.
+  const selfUpdate = createSelfUpdateController({
+    getConfig: () => config,
+    getDataDir: () => cfgMod.getPluginData?.() || STANDALONE_DATA_DIR,
+    emitNotification: (...a) => emitRuntimeNotification(...a),
+  });
+  const autoUpdateEnabled = () => selfUpdate.autoUpdateEnabled();
+  const checkForUpdateInternal = (...a) => selfUpdate.checkForUpdate(...a);
+  const runUpdateNowInternal = (...a) => selfUpdate.runUpdateNow();
+  selfUpdate.startBootCheck();
 
-  function notifyFnForSession(callerSessionId) {
-    return (text, meta = {}) => {
-      const { handled: handledByRuntimeListener, modelVisibleDelivered } = emitRuntimeNotification(text, meta);
-      let enqueued = false;
-      // Model-visible delivery ack (TUI execution-ui only): register this
-      // completion in the process-local delivered registry so a racing enqueue
-      // on another path (background reconcile/fallback/notify) within THIS
-      // process is skipped instead of double-injecting the same body next turn.
-      if (modelVisibleDelivered) {
-        try {
-          const deliveredVisible = modelVisibleToolCompletionMessage(text, meta);
-          recordDeliveredCompletion({ executionId: meta?.execution_id, text: deliveredVisible });
-        } catch {}
-      }
-      // TUI sessions consume raw execution notifications for UI/task cards via
-      // onNotification, but those raw envelopes are internal-only in pending
-      // drain. The TUI execution-ui path injects the model-visible twin of a
-      // terminal completion into the active loop and acks with
-      // modelVisibleDelivered, so mirroring it into the pending queue would
-      // double-inject the same completion — skip only on that EXPLICIT ack. A
-      // generic display-only / API listener returning true is NOT an ack: the
-      // mirror stays as the sole model-visible delivery.
-      if (shouldMirrorCompletionToPendingQueue({
-        callerSessionId,
-        modelVisibleDelivered,
-        hasEnqueue: typeof mgr.enqueuePendingMessage === 'function',
-        text,
-        meta,
-      })) {
-        try {
-          const visible = modelVisibleToolCompletionMessage(text, meta);
-          // Terminal completion (gated by shouldPersistModelVisibleToolCompletion)
-          // → tag so drain discards it on resume rather than replaying out-of-order.
-          if (visible) {
-            if (isDeliveredCompletion({ executionId: meta?.execution_id, text: visible })) {
-              // Already delivered+ACKed on the TUI path → suppress the mirror but
-              // report DELIVERED so the caller marks it notified and never retries.
-              logDuplicateSkip('mirror', { executionId: meta?.execution_id, text: visible });
-              enqueued = true;
-            } else {
-              enqueued = mgr.enqueuePendingMessage(callerSessionId, markCompletionEntry(visible)) > 0;
-            }
-          }
-        } catch {}
-      }
-      // Headless/API listeners may exist but not consume the event; preserve
-      // the old fallback for non-terminal notifications only when unhandled.
-      if (!enqueued && !handledByRuntimeListener && callerSessionId
-        && typeof mgr.enqueuePendingMessage === 'function') {
-        try {
-          const visible = modelVisibleToolCompletionMessage(text, meta);
-          // modelVisibleToolCompletionMessage only returns non-empty for a
-          // persistable terminal completion, so this fallback is a completion
-          // too → tag it (genuine non-completion notifications yield '' above).
-          if (visible) {
-            if (isDeliveredCompletion({ executionId: meta?.execution_id, text: visible })) {
-              // Already delivered+ACKed on the TUI path → suppress the fallback
-              // enqueue but report DELIVERED so the caller stops retrying.
-              logDuplicateSkip('fallback', { executionId: meta?.execution_id, text: visible });
-              enqueued = true;
-            } else {
-              enqueued = mgr.enqueuePendingMessage(callerSessionId, markCompletionEntry(visible)) > 0;
-            }
-          }
-        } catch {}
-      }
-      return enqueued || handledByRuntimeListener;
-    };
-  }
+  // Notification fan-out (listener broadcast + pending-queue mirroring of
+  // terminal completions) lives in notification-bus.mjs.
+  const { emitRuntimeNotification, notifyFnForSession } = createNotificationBus({
+    listeners: notificationListeners,
+    mgr,
+  });
 
-  function skillsStatus() {
-    const skills = typeof contextMod.collectSkillsCached === 'function'
-      ? contextMod.collectSkillsCached(currentCwd)
-      : [];
-    const norm = (value) => String(value || '').replace(/\\/g, '/').toLowerCase();
-    const cwdNorm = norm(currentCwd);
-    const sourceForSkill = (filePath) => {
-      const path = norm(filePath);
-      if (cwdNorm && path.startsWith(`${cwdNorm}/.mixdog/skills/`)) return 'project';
-      return 'skill';
-    };
-    return {
-      cwd: currentCwd,
-      count: skills.length,
-      skills: skills.map((skill) => ({
-        name: skill.name,
-        description: skill.description || '',
-        filePath: skill.filePath || null,
-        source: sourceForSkill(skill.filePath),
-      })),
-    };
-  }
+  // Skill listing/loading/creation lives in skills-api.mjs; the facade only
+  // supplies the mutable cwd and the context module.
+  const {
+    skillsStatus,
+    skillContent,
+    skillToolContent,
+    addProjectSkill,
+  } = createSkillsApi({ contextMod, getCwd: () => currentCwd });
 
   // cwd resolution/apply + plugins-status + core-memory context. Extracted to
   // session-runtime/cwd-plugins.mjs; the facade keeps ownership of the mutable
@@ -932,52 +698,6 @@ export async function createMixdogSessionRuntime({
     STANDALONE_DATA_DIR,
   });
 
-  function skillContent(name) {
-    const res = typeof contextMod.loadSkillResource === 'function'
-      ? contextMod.loadSkillResource(name, currentCwd)
-      : null;
-    if (!res) throw new Error(`skill not found: ${name}`);
-    return { name, content: res.content, dir: res.dir };
-  }
-
-  function skillToolContent(name) {
-    if (typeof contextMod.isSkillDisabled === 'function' && contextMod.isSkillDisabled(name)) {
-      const label = String(name || '').trim() || 'skill';
-      return `Error: skill "${label}" is disabled`;
-    }
-    const skill = skillContent(name);
-    // Return the general tool envelope so the main/Lead session behaves the
-    // same as agent-loop sessions: the model-visible tool_result is the short
-    // stub (`Loaded skill: <name>`) and the full SKILL.md body is delivered
-    // ONCE as a separate injected role:'user' message (newMessages). The
-    // envelope passes through internal-tools._normalize untouched (it preserves
-    // __toolEnvelope objects), and the agent loop's central normalizeToolEnvelope
-    // splits it into stub + injected user body.
-    return contextMod.buildSkillToolEnvelope(skill.name, skill.content, skill.dir);
-  }
-
-  function addProjectSkill(input = {}) {
-    const name = clean(input.name).replace(/[^a-zA-Z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
-    if (!name) throw new Error('skill name is required');
-    const dir = join(currentCwd, '.mixdog', 'skills', name);
-    const filePath = join(dir, 'SKILL.md');
-    if (existsSync(filePath)) throw new Error(`skill already exists: ${name}`);
-    const description = clean(input.description) || 'Project skill.';
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(filePath, [
-      '---',
-      `name: ${name}`,
-      `description: ${description}`,
-      '---',
-      '',
-      '# Instructions',
-      '',
-      'Describe when and how to use this skill.',
-      '',
-    ].join('\n'), 'utf8');
-    return { name, filePath };
-  }
-
   const agentToolStartedAt = performance.now();
   const agentTool = createStandaloneAgent({
     cfgMod,
@@ -1082,25 +802,26 @@ export async function createMixdogSessionRuntime({
   // schema-visible tool that policy always rejects is a guaranteed error turn
   // (user-reported in Solo). Names derive from the live agent tool defs.
   const agentToolNames = new Set(agentTool.tools.map((tool) => String(tool?.name || '')).filter(Boolean));
-  function workflowAllowsAgents() {
-    try {
-      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
-      const pack = loadWorkflowPack(dataDir, activeWorkflowId(config));
-      if (!pack || pack.agentsConfigured !== true) return true;
-      return Array.isArray(pack.agents) && pack.agents.length > 0;
-    } catch {
-      return true;
-    }
-  }
-  function modelStandaloneTools() {
-    return workflowAllowsAgents()
-      ? standaloneTools
-      : standaloneTools.filter((tool) => !agentToolNames.has(String(tool?.name || '')));
-  }
-
-  function invalidatePreSessionToolSurface() {
-    preSessionToolSurface = null;
-  }
+  // Lead tool surface (workflow-gated agent tool, pre-session preview, deferred
+  // replay) lives in tool-surface.mjs.
+  const {
+    modelStandaloneTools,
+    invalidatePreSessionToolSurface,
+    activeToolSurface,
+    applyPreSessionToolSelection,
+  } = createToolSurface({
+    mgr,
+    mode,
+    standaloneTools,
+    agentToolNames,
+    getSession: () => session,
+    getRoute: () => route,
+    getConfig: () => config,
+    cfgMod,
+    loadWorkflowPack,
+    activeWorkflowId,
+    dataDir: STANDALONE_DATA_DIR,
+  });
 
   const { contextStatus: computeContextStatus, invalidateContextStatusCache } = createContextStatus({
     getSession: () => session,
@@ -1108,34 +829,6 @@ export async function createMixdogSessionRuntime({
     getCurrentCwd: () => currentCwd,
     getMode: () => mode,
   });
-
-  function buildPreSessionToolSurface() {
-    const previewTools = typeof mgr.previewSessionTools === 'function'
-      ? mgr.previewSessionTools(toolSpecForMode(mode), [])
-      : [];
-    const tools = filterDisallowedTools(previewTools, LEAD_DISALLOWED_TOOLS);
-    const surface = { tools: Array.isArray(tools) ? tools.slice() : [] };
-    applyDeferredToolSurface(surface, deferredSurfaceModeForLead(mode), modelStandaloneTools(), { provider: route.provider });
-    return surface;
-  }
-
-  function activeToolSurface() {
-    if (session) return session;
-    preSessionToolSurface ??= buildPreSessionToolSurface();
-    return preSessionToolSurface;
-  }
-
-  function applyPreSessionToolSelection() {
-    if (!session || !preSessionToolSurface) return;
-    const selected = Array.isArray(preSessionToolSurface.deferredSelectedTools)
-      ? preSessionToolSurface.deferredSelectedTools
-      : [];
-    const discovered = Array.isArray(preSessionToolSurface.deferredDiscoveredTools)
-      ? preSessionToolSurface.deferredDiscoveredTools
-      : [];
-    const replay = [...new Set([...selected, ...discovered])];
-    if (replay.length) selectDeferredTools(session, replay, deferredSurfaceModeForLead(mode));
-  }
   internalTools.setInternalToolsProvider({
     tools: [...standaloneTools, ...searchRuntimeTools.filter((tool) => tool?.public === false)],
     executor: async (name, args, callerCtx = {}) => {
@@ -1322,20 +1015,28 @@ export async function createMixdogSessionRuntime({
     }
     if (!startupProviderCatalogRefreshStarted && !closeRequested) {
       startupProviderCatalogRefreshStarted = true;
+      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 });
-            warmProviderModelCache();
+            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
+            // paid a full catalog load (measured ~560ms each).
+            warmProviderModelCache({ loadSecrets: true });
             bootProfile('provider-catalogs:refresh-ready');
           })
           .catch((error) => {
+            startupProviderCatalogRefreshPending = false;
             bootProfile('provider-catalogs:refresh-failed', { error: error?.message || String(error) });
           });
         bootProfile('provider-catalogs:refresh-started');
       } catch (error) {
+        startupProviderCatalogRefreshPending = false;
         bootProfile('provider-catalogs:refresh-failed', { error: error?.message || String(error) });
       }
     }
@@ -1371,6 +1072,7 @@ export async function createMixdogSessionRuntime({
   const {
     refreshStatuslineUsageSnapshot,
     cachedProviderSetup,
+    hasProviderSetupCached,
     getUsageDashboard,
   } = createProviderUsage({
     caches: providerUsageCaches,
@@ -1665,6 +1367,7 @@ export async function createMixdogSessionRuntime({
     cachedProviderSetup,
     warmCatalogsInBackground,
     isFirstTurnCompleted: () => firstTurnCompleted,
+    isCatalogRefreshPending: () => startupProviderCatalogRefreshPending,
     envFlag,
     delays: {
       providerWarmupDelayMs,
@@ -1717,313 +1420,59 @@ export async function createMixdogSessionRuntime({
     state: prewarmState,
   });
 
-  // Eagerly create/refresh the remote transcript writer for the CURRENT
-  // session + cwd, publish the session record, and ensure the transcript
-  // file exists on disk. Called from startRemote() (so the channel worker's
-  // activate-time discovery finds THIS session immediately instead of
-  // waiting for the first turn) and from ask() at turn start. Returns true
-  // when a writer is bound.
-  function ensureRemoteTranscriptWriter() {
-    if (!remoteEnabled || !session?.id) return false;
-    // Owner gate: late adopt covers lazy create (owner unknown at /remote
-    // time); a live owner blocks every other session; a dead owner (cleared
-    // or deleted session) hands the relay to the current session.
-    if (!remoteSessionId) {
-      remoteSessionId = session.id;
-    } else if (session.id !== remoteSessionId) {
-      const owner = mgr.getSession(remoteSessionId);
-      if (owner && owner.closed !== true && owner.status !== 'closed') return false;
-      remoteSessionId = session.id;
-    }
-    const twKey = `${session.id}\u0000${currentCwd}`;
-    if (_twKey !== twKey) {
-      try {
-        _transcriptWriter = createTranscriptWriter({
-          mixdogHome: mixdogHome(),
-          sessionId: session.id,
-          cwd: currentCwd,
-          pid: process.pid,
-        });
-        _transcriptWriter.writeSessionRecord();
-        _twKey = twKey;
-      } catch (error) {
-        process.stderr.write(`mixdog: transcript-writer: init failed: ${error?.message || error}\n`);
-        _transcriptWriter = null;
-        _twKey = '';
-        return false;
-      }
-    } else {
-      // Same binding — refresh updatedAt so worker-side discovery keeps
-      // ranking this session as the live parent-chain candidate.
-      try { _transcriptWriter?.writeSessionRecord(); } catch {}
-    }
-    try { _transcriptWriter?.ensureTranscriptFile(); }
-    catch (error) { process.stderr.write(`mixdog: transcript-writer: ensureTranscriptFile failed: ${error?.message || error}\n`); }
-    return _transcriptWriter != null;
-  }
-
-  // Push the CURRENT transcript path to the channel worker so outbound
-  // forwarding repoints immediately at the moments the binding can go stale
-  // (auto-acquire, newSession/resume, clear) instead of waiting for the next
-  // inbound parent-chain steal. Best-effort: ensures the writer, then fires
-  // the dedicated idempotent worker op — a missing/not-ready worker or a bind
-  // failure must never throw into the lead paths that call this.
-  function pushTranscriptRebind() {
-    if (!remoteEnabled) return;
-    // Writer not bindable yet (e.g. 'acquired' before the session exists in
-    // lazy mode): defer instead of silently dropping the push. flushPending-
-    // TranscriptRebind() re-fires this exactly once when the writer is ready.
-    if (!ensureRemoteTranscriptWriter()) { _pendingRebind = true; return; }
-    const transcriptPath = _transcriptWriter?.transcriptPath;
-    if (!transcriptPath || !channelsEnabled()) { _pendingRebind = true; return; }
-    _pendingRebind = false;
-    executeTranscriptRebind(transcriptPath, 1);
-  }
-
-  // Fire the idempotent worker op with bounded retry. A rejected/throwing
-  // channels.execute retries a few times with short backoff; the final failure
-  // surfaces one stderr line (not only the env-gated bootProfile) so a lost
-  // rebind is diagnosable by default. Best-effort throughout — never throws
-  // into the lead paths that call pushTranscriptRebind().
-  function executeTranscriptRebind(transcriptPath, attempt) {
-    const maxAttempts = 3;
-    const onError = (error) => {
-      const detail = error?.message || String(error);
-      bootProfile('channels:rebind-push-failed', { attempt, error: detail });
-      if (attempt < maxAttempts && remoteEnabled && !closeRequested) {
-        const timer = setTimeout(() => {
-          // Abort the retry chain silently if remote was dropped or the writer
-          // moved on (supersede→re-acquire, newSession/clear): re-firing the
-          // captured path would rebind forwarding back to a stale transcript.
-          if (!remoteEnabled || !channelsEnabled()) return;
-          if (_transcriptWriter?.transcriptPath !== transcriptPath) return;
-          executeTranscriptRebind(transcriptPath, attempt + 1);
-        }, 150 * attempt);
-        timer.unref?.();
-      } else {
-        process.stderr.write(`mixdog: channels: rebind_current_transcript failed after ${attempt} attempt(s): ${detail}\n`);
-      }
-    };
-    try {
-      void channels.execute('rebind_current_transcript', { transcriptPath }).catch(onError);
-    } catch (error) {
-      onError(error);
-    }
-  }
-
-  // Re-fire a deferred rebind exactly once, after a session/writer becomes
-  // available (session create or turn start). No-op unless a push was deferred,
-  // so no unconditional rebind fires per turn for already-bound sessions.
-  function flushPendingTranscriptRebind() {
-    if (!_pendingRebind || !remoteEnabled) return;
-    pushTranscriptRebind();
-  }
-
-  // Remote (Discord channel) mode is opt-in per session. Only a session that
-  // explicitly enables remote — via `mixdog --remote` or the runtime toggle —
-  // boots the channel worker and contends for channel ownership.
-  // startRemote() is FORCE-TAKEOVER: it always (re)claims the bridge seat and
-  // rebinds output forwarding to this session, even when the worker is
-  // already running (e.g. `/remote` re-issued after another session took the
-  // seat, or to re-pin forwarding onto the current transcript).
-  function startRemote(options = {}) {
-    const intent = options?.intent === 'auto' ? 'auto' : 'explicit';
-    // Claim intent reaches the worker's boot claim via MIXDOG_REMOTE_INTENT
-    // (last-wins for explicit, claim-if-vacant for auto). It is set transiently
-    // around the worker fork below (see invokeChannelStart) and restored right
-    // after — NOT here on the shared process.env — so unrelated children forked
-    // during the boot window never inherit a stale intent.
-    if (intent === 'auto') {
-      // Auto-start (config/delayed): do NOT flip this session to remote up
-      // front. Boot the worker to ATTEMPT a claim-if-vacant; remoteEnabled is
-      // set only when the worker reports it actually acquired the seat (the
-      // 'acquired' notification). A live owner already holding the seat makes
-      // the worker back off silently and this session stays non-remote.
-      remoteClaimPending = true;
-    } else {
-      remoteEnabled = true;
-      // Explicit toggle: the CURRENT session owns the relay (lazy create
-      // adopts inside ensureRemoteTranscriptWriter when no session exists yet).
-      remoteSessionId = session?.id || null;
-    }
-    // Boot the memory daemon eagerly. The channels worker forwards
-    // transcript ingests/entries to the memory HTTP service, whose port is
-    // published to active-instance.json by getMemoryModule().init(). Without
-    // this, memory only starts on the first turn's getMemoryModule() call —
-    // so early channel traffic finds no memory_port and gets buffered (or,
-    // pre-drainer, silently dropped). Runs BEFORE channel claim so the port is
-    // racing to be live by the time the worker sends its first ingest.
-    //
-    // Not fire-and-forget: init() only resolves the module handle, so a bare
-    // getMemoryModule() could return before /health reports ok — leaving early
-    // ingests to hit a not-yet-listening port. Await the proxy start() and then
-    // poll /health with a bounded retry so the daemon is provably reachable
-    // (or logged failed) rather than assumed-up. Still non-blocking to the
-    // caller: the whole probe is detached, but it internally awaits readiness.
-    void (async () => {
-      try {
-        // Yield one event-loop tick before the heavy chain below (module
-        // resolve, daemon fork/health-poll) starts, so Ink's next render
-        // (scheduled via setImmediate/timers) and any queued keypress
-        // events get a turn first instead of being starved by this
-        // detached chain's synchronous setup work.
-        await new Promise((r) => setImmediate(r));
-        const mod = await getMemoryModule();
-        const started = typeof mod?.start === 'function' ? await mod.start() : null;
-        const port = started?.port;
-        if (!port) { bootProfile('channels:memory-eager-init-failed', { error: 'no port from start()' }); return; }
-        for (let i = 0; i < 30; i++) {
-          try {
-            const ok = await new Promise((res) => {
-              const req = httpMod.request({ hostname: '127.0.0.1', port, path: '/health', timeout: 1500 }, (r) => {
-                let d = ''; r.on('data', (c) => { d += c; }); r.on('end', () => {
-                  try { res(JSON.parse(d)?.status === 'ok'); } catch { res(false); }
-                });
-              });
-              req.on('error', () => res(false));
-              req.on('timeout', () => { req.destroy(); res(false); });
-              req.end();
-            });
-            if (ok) { bootProfile('channels:memory-eager-init-ready', { port }); return; }
-          } catch {}
-          await new Promise((r) => setTimeout(r, 500));
-        }
-        bootProfile('channels:memory-eager-init-failed', { error: `health not ok after retries (port ${port})` });
-      } catch (error) {
-        bootProfile('channels:memory-eager-init-failed', { error: error?.message || String(error) });
-      }
-    })();
-    // Publish this session's record + transcript file BEFORE the worker's
-    // activate-time discovery polls, so output forwarding binds to this
-    // terminal session immediately instead of waiting for the first turn.
-    // No-op when the session has not been created yet (lazy mode); that
-    // case is covered by the turn-start rebind in ask().
-    ensureRemoteTranscriptWriter();
-    if (envFlag('MIXDOG_DISABLE_CHANNEL_START')) {
-      bootProfile('channels:start-skipped');
-      return true;
-    }
-    if (closeRequested) return true;
-    if (prewarmTimers.channelStartTimer) {
-      clearTimeout(prewarmTimers.channelStartTimer);
-      prewarmTimers.channelStartTimer = null;
-    }
-    bootProfile('channels:start-scheduled', { delayMs: 0, immediate: true });
-    void (async () => {
-      // Channels-module toggle gates MESSAGING only: automation (schedules/
-      // webhooks) still boots the worker — its backend runs headless when
-      // messaging is off or unconfigured (see channels/lib/config.mjs).
-      if (!channelsEnabled() && !(await hasActiveAutomation().catch(() => false))) {
-        bootProfile('channels:start-disabled');
-        remoteClaimPending = false;
-        return;
-      }
-      // A backend switch may still be pending or writing asynchronously. Drain
-      // it before the worker reads config; never race it with a sync lock wait.
-      try { await flushBackendSave(); } catch {}
-      // Yield before the createCurrentSession/transcript/fork chain below —
-      // same rationale as the memory-eager-init yield above: this detached
-      // chain runs synchronous config/fs work (createCurrentSession, backend
-      // flush, transcript writer) back-to-back, and without a tick break it
-      // can run ahead of Ink's queued render/input handling.
-      await new Promise((r) => setImmediate(r));
-      // Immediate-occupancy guarantee: make sure a session + transcript
-      // exist BEFORE the worker boots — a freshly-forked worker claims and
-      // runs transcript discovery inside its own start(), so publishing the
-      // session record/file first lets that very first discovery pass bind
-      // output forwarding to THIS terminal instead of a persisted/stale
-      // neighbour. Lazy mode means the session may not exist yet at /remote
-      // time; create it here (idempotent — reuses a live session, joins an
-      // in-flight create). On create failure we still claim: that matches
-      // the pre-eager behavior (bind resolves on the first turn's rebind).
-      try { await createCurrentSession('remote-start'); }
-      catch (error) { bootProfile('channels:remote-session-create-failed', { error: error?.message || String(error) }); }
-      ensureRemoteTranscriptWriter();
-      // Re-check after the awaits above: stopRemote()/superseded or runtime
-      // close may have landed mid-chain — do not boot/claim for a session
-      // that already turned remote off.
-      if ((!remoteEnabled && !remoteClaimPending) || closeRequested) { remoteClaimPending = false; return; }
-      // Set the fork-inherited intent immediately before the worker fork (the
-      // fork reads process.env synchronously inside invokeChannelStart) and
-      // restore the prior value the instant it resolves, so the pollution
-      // window is just this fork rather than the whole boot chain.
-      const _prevIntent = process.env.MIXDOG_REMOTE_INTENT;
-      try {
-        process.env.MIXDOG_REMOTE_INTENT = intent;
-        await invokeChannelStart();
-      } finally {
-        if (_prevIntent === undefined) delete process.env.MIXDOG_REMOTE_INTENT;
-        else process.env.MIXDOG_REMOTE_INTENT = _prevIntent;
-      }
-      if ((!remoteEnabled && !remoteClaimPending) || closeRequested) { remoteClaimPending = false; return; }
-      // Explicit claims are unconditional. Auto-start dispatches the same
-      // activation as claim-if-vacant so it can promote an existing
-      // automation-only daemon without stealing a live remote owner.
-      await channels.execute('activate_channel_bridge', {
-        active: true,
-        claimIfVacant: intent === 'auto',
-        sessionId: session?.id || remoteSessionId || null,
-        transcriptPath: _transcriptWriter?.transcriptPath || null,
-      });
-      // Claim attempt dispatched; the worker's acquire/supersede notification
-      // now owns the remoteEnabled transition. Drop the transient marker.
-      remoteClaimPending = false;
-    })().catch((error) => {
-      remoteClaimPending = false;
-      if (remoteEnabled) {
-        remoteEnabled = false;
-        remoteSessionId = null;
-        channels.stop('remote-claim-failed').catch(() => {});
-        emitRemoteStateChange(false, 'claim-failed');
-      }
-      bootProfile('channels:claim-failed', { error: error?.message || String(error) });
-    });
-    return true;
-  }
+  // 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,
+    channelsEnabled,
+    channels,
+    mgr,
+    bootProfile,
+  });
+  const ensureRemoteTranscriptWriter = () => remoteTranscript.ensureRemoteTranscriptWriter();
+  const pushTranscriptRebind = () => remoteTranscript.pushTranscriptRebind();
+  const flushPendingTranscriptRebind = () => remoteTranscript.flushPendingTranscriptRebind();
 
-  // Explicit user OFF is a desired-state command, not a toggle retry. Ask the
-  // daemon to deactivate the machine-global bridge before detaching this
-  // client; the call runs in the background so the UI never waits through a
-  // daemon spawn/reconnect window. Repeated releases remain idempotent.
-  function releaseRemote(reason) {
-    const releasingSessionId = remoteSessionId || session?.id || null;
-    remoteEnabled = false;
-    remoteSessionId = null;
-    remoteClaimPending = false;
-    if (prewarmTimers.channelStartTimer) {
-      clearTimeout(prewarmTimers.channelStartTimer);
-      prewarmTimers.channelStartTimer = null;
-    }
-    void (async () => {
-      try {
-        await channels.execute('activate_channel_bridge', {
-          active: false,
-          sessionId: releasingSessionId,
-        });
-      } catch (error) {
-        bootProfile('channels:release-failed', { error: error?.message || String(error) });
-        emitRemoteStateChange(false, 'release-failed');
-      } finally {
-        await channels.stop(reason || 'remote-disabled').catch(() => {});
+  // 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,
+    clearChannelStartTimer: () => {
+      if (prewarmTimers.channelStartTimer) {
+        clearTimeout(prewarmTimers.channelStartTimer);
+        prewarmTimers.channelStartTimer = null;
       }
-    })();
-    return false;
-  }
-
-  function stopRemote(reason) {
-    remoteEnabled = false;
-    remoteSessionId = null;
-    // A pending auto-claim is abandoned by an explicit stop/supersede.
-    remoteClaimPending = false;
-    // Cancel any pending deferred start so it can't fire after remote is off.
-    if (prewarmTimers.channelStartTimer) { clearTimeout(prewarmTimers.channelStartTimer); prewarmTimers.channelStartTimer = null; }
-    // Route /remote-off and supersede through a WAITING stop: the runtime keeps
-    // running, so we don't block on it (no await), but the waiting path runs the
-    // full SIGTERM -> taskkill /T /F escalation ladder to guarantee the worker
-    // dies rather than lingering as a zombie holding the bridge seat.
-    channels.stop(reason || 'remote-disabled').catch(() => {});
-    return true;
-  }
+    },
+    remoteTransitions,
+    channels,
+    channelsEnabled,
+    hasActiveAutomation,
+    flushBackendSave,
+    invokeChannelStart,
+    createCurrentSession,
+    ensureRemoteTranscriptWriter,
+    getTranscriptPath: () => remoteTranscript.transcriptWriter?.transcriptPath || null,
+    emitRemoteStateChange,
+    getMemoryModule,
+    bootProfile,
+    envFlag,
+  });
+  const startRemote = (options) => remoteControl.startRemote(options);
+  const releaseRemote = (reason) => remoteControl.releaseRemote(reason);
+  const stopRemote = (reason) => remoteControl.stopRemote(reason);
 
   function isRemoteEnabled() {
     return remoteEnabled;
@@ -2101,7 +1550,6 @@ 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).
-  const remoteAutoStartDelayMs = envDelayMs('MIXDOG_REMOTE_AUTOSTART_DELAY_MS', 1_500, { min: 0, max: 60_000 });
   if (remoteEnabled || remoteAutoStartRequested) {
     const remoteStartIntent = remoteEnabled ? 'explicit' : 'auto';
     bootProfile('channels:autostart-deferred', { delayMs: remoteAutoStartDelayMs, intent: remoteStartIntent });
@@ -2166,8 +1614,8 @@ export async function createMixdogSessionRuntime({
     recapEnabledFn,
     channelsEnabled,
     autoUpdateEnabled,
-    getUpdateCheckState: () => updateCheckState,
-    getUpdateProcessState: () => updateProcessState,
+    getUpdateCheckState: () => selfUpdate.getCheckState(),
+    getUpdateProcessState: () => selfUpdate.getProcessState(),
     invalidateContextStatusCache: (...a) => invalidateContextStatusCache(...a),
     invalidatePreSessionToolSurface: (...a) => invalidatePreSessionToolSurface(...a),
     scheduleChannelStart: (...a) => scheduleChannelStart(...a),
@@ -2196,6 +1644,7 @@ export async function createMixdogSessionRuntime({
     // Automation saved mid-session boots the worker (claim-if-vacant) even
     // though the boot-time autostart window has already passed.
     ensureAutomationRuntime: () => scheduleChannelStart(0),
+    awaitKeychainPrewarm,
   });
   const providerAuthApi = createProviderAuthApi({
     cfgMod,
@@ -2204,6 +1653,8 @@ export async function createMixdogSessionRuntime({
     displayConfig,
     reloadFullConfig,
     awaitKeychainPrewarm,
+    isKeychainPrewarmReady: () => keychainPrewarmWaitDone,
+    hasProviderSetupCached,
     invalidateProviderCaches,
     warmProviderModelCache,
     refreshProviderCatalogs: () => ensureProvidersReady(config.providers || {}).then(() => reg.refreshCatalogs()),
@@ -2211,6 +1662,7 @@ export async function createMixdogSessionRuntime({
     getUsageDashboard,
     collectProviderModels,
   });
+  const mediaApi = createMediaApi();
   const lifecycleApi = createLifecycleApi({
     getSession: () => session,
     setSession: (v) => { session = v; },
@@ -2327,6 +1779,7 @@ export async function createMixdogSessionRuntime({
     displayConfig,
     agentRouteFromConfig,
     loadAgentDefinition,
+    listCustomAgentIds,
     activeWorkflowId,
     listWorkflowPacks,
     loadWorkflowPack,
@@ -2355,8 +1808,8 @@ export async function createMixdogSessionRuntime({
     getCloseRequested: () => closeRequested,
     getPendingSessionReset: () => pendingSessionReset,
     setPendingSessionReset: (v) => { pendingSessionReset = v; },
-    getTranscriptWriter: () => _transcriptWriter,
-    getTwKey: () => _twKey,
+    getTranscriptWriter: () => remoteTranscript.transcriptWriter,
+    getTwKey: () => remoteTranscript.transcriptKey,
     getLastAppendedAssistant: () => _lastAppendedAssistant,
     setLastAppendedAssistant: (v) => { _lastAppendedAssistant = v; },
     scheduleCodeGraphPrewarm,
@@ -2392,6 +1845,7 @@ export async function createMixdogSessionRuntime({
     ...settingsApi,
     ...channelConfigApi,
     ...providerAuthApi,
+    ...mediaApi,
     // Turn-scoped worktree diff (shadow snapshot): everything changed since
     // the current turn's base tree, regardless of which agent/process wrote it.
     getTurnReviewDiff: () => getTurnSnapshotReviewDiff(currentCwd, session?.id),