mixdog 0.9.22 → 0.9.24

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

@@ -94,7 +94,69 @@ export function createMcpGlue({
     };
   }
 
-  async function connectConfiguredMcp({ reset = false } = {}) {
+  // Connect/disconnect exactly one server in the live registry, leaving all
+  // others untouched. Used by the enable/disable toggle so a single-server
+  // change never triggers a full disconnectAll()/reconnect freeze.
+  async function applyMcpServerConnection(name, enabled) {
+    const target = clean(name);
+    if (!target) return;
+    const { servers, sources } = resolveEffectiveMcpServers();
+    // A project-local `.mcp.json` entry WINS over config for this name, so the
+    // config enable/disable flag doesn't change what's actually connected.
+    // Only act when the effective entry is config-sourced (or absent).
+    if (sources[target] && sources[target] !== 'config') return;
+    // Changing this server's state clears any stale failure record for it.
+    if (Array.isArray(state.mcpFailures)) {
+      state.mcpFailures = state.mcpFailures.filter((row) => row.name !== target);
+    }
+    if (enabled === false) {
+      await mcpClient.disconnectMcpServer?.(target);
+      return;
+    }
+    const cfg = servers[target];
+    if (!cfg) return;
+    // Drop any existing live entry first so connectMcpServers doesn't overwrite
+    // the registry Map entry and leak the old transport/process.
+    await mcpClient.disconnectMcpServer?.(target);
+    try {
+      await mcpClient.connectMcpServers({ [target]: cfg });
+    } catch (error) {
+      const failures = Array.isArray(error?.failures)
+        ? error.failures
+        : [{ name: target, msg: error?.message || String(error) }];
+      state.mcpFailures = [...(state.mcpFailures || []), ...failures];
+    }
+  }
+
+  async function connectConfiguredMcp({ reset = false, only = null, enabled = true } = {}) {
+    // Scoped single-server toggle: non-superseding. It must NEVER cancel a
+    // pending full {reset} (cwd-change/boot). So do not bump the generation;
+    // just wait for any in-flight run, then bail if a newer full reset has
+    // been requested in the meantime. Registering as in-flight makes a later
+    // reset serialize behind us instead of interleaving disconnect/connect.
+    if (only) {
+      // Atomically capture the current generation AND the prior in-flight
+      // promise in the same synchronous step, then chain our op onto it. No
+      // await sits between the capture and the `state.mcpConnectInFlight = run`
+      // assignment, so concurrent {only} calls queue FIFO instead of resuming
+      // together and clobbering the in-flight slot. We never bump the
+      // generation; a {reset} does, so any {only} queued behind a reset sees
+      // the newer generation when its turn comes and bails.
+      const gen = state.mcpConnectGeneration;
+      const prev = state.mcpConnectInFlight;
+      const run = (async () => {
+        if (prev) { try { await prev; } catch { /* prior run's failures already captured */ } }
+        if (gen !== state.mcpConnectGeneration) return;
+        await applyMcpServerConnection(only, enabled);
+      })();
+      state.mcpConnectInFlight = run;
+      try {
+        await run;
+      } finally {
+        if (state.mcpConnectInFlight === run) state.mcpConnectInFlight = null;
+      }
+      return mcpStatus();
+    }
     // Serialize reconnects: boot connect, cwd-change reset, and rapid cwd
     // switches must never interleave their disconnect/connect phases, or an
     // older run finishing after a newer reset could re-add stale servers into
@@ -188,11 +250,41 @@ export function createMcpGlue({
     return { name, config };
   }
 
+  // First-turn gate: await the in-flight INITIAL connect, bounded by the global
+  // startup budget. Boot/UI never call this; only the first ask awaits so
+  // servers that connect within the budget land in THIS request's tool surface.
+  // Resolves (never rejects): a server still connecting after the budget flows
+  // through the existing late-tool deferred announcement path unchanged.
+  async function awaitInitialMcpConnect() {
+    const inFlight = state.mcpConnectInFlight;
+    if (!inFlight) return;
+    let budgetMs = 10000;
+    try {
+      const resolved = mcpClient.resolveMcpStartupTimeoutMs?.({});
+      if (Number.isFinite(resolved)) budgetMs = resolved;
+    } catch { /* fall back to default budget */ }
+    // Swallow the in-flight rejection: failures are already captured in
+    // state.mcpFailures, and this gate must never reject the turn.
+    const settled = Promise.resolve(inFlight).catch(() => {});
+    // Budget disabled (0/off) = no per-server startup timeout, so the connect
+    // promise may never settle; never gate the turn on it — fall back to the
+    // legacy fire-and-forget behavior (late servers use the deferred path).
+    if (!(budgetMs > 0)) return;
+    let timer = null;
+    const budget = new Promise((resolveBudget) => { timer = setTimeout(resolveBudget, budgetMs); });
+    try {
+      await Promise.race([settled, budget]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   return {
     mcpTransportLabel,
     resolveEffectiveMcpServers,
     mcpStatus,
     connectConfiguredMcp,
+    awaitInitialMcpConnect,
     normalizeMcpServerInput,
   };
 }

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

@@ -29,8 +29,56 @@ export function createResourceApi(deps) {
     saveConfigAndAdopt, connectConfiguredMcp, invalidatePreSessionToolSurface,
     recreateCurrentSessionIfReady, normalizeMcpServerInput, mcpStatus,
     skillsStatus, skillContent, addProjectSkill, pluginsStatus, getMemoryModule,
-    reloadFullConfig,
+    reloadFullConfig, getActiveTurnCount,
   } = deps;
+  // Per-server MCP toggle serialization. The synchronous config adopt in
+  // setMcpServerEnabled has already made the intent durable; the heavy
+  // connectConfiguredMcp (process spawn/handshake) + session close/recreate
+  // run here off the toggle's critical path. Rapid re-toggles on one server
+  // update `desired` and ride the in-flight chain so it converges to the last
+  // requested state, closing/recreating the session only once at the end.
+  const mcpToggleChains = new Map(); // name -> { desired, running }
+  // Close/recreate the live session only at a turn boundary: a background
+  // toggle must never abort an in-flight turn. If a turn is active, poll until
+  // it ends, then swap the session so it picks up the new tool surface.
+  function applyMcpToggleRecreate(serverName) {
+    if (typeof getActiveTurnCount === 'function' && getActiveTurnCount() > 0) {
+      const timer = setTimeout(() => applyMcpToggleRecreate(serverName), 250);
+      timer.unref?.();
+      return;
+    }
+    invalidatePreSessionToolSurface();
+    const session = getSession();
+    if (session?.id) mgr.closeSession(session.id, 'cli-mcp-toggle');
+    // Recreate off the critical path (see removeMcpServer notes): the next
+    // on-demand createCurrentSession dedupes onto this in-flight create.
+    void recreateCurrentSessionIfReady().catch((err) => {
+      process.stderr.write(`[mcp] session recreate after toggle failed: ${err?.message || err}\n`);
+    });
+  }
+  function scheduleMcpToggle(serverName, enabled) {
+    const chain = mcpToggleChains.get(serverName) || { desired: enabled, running: null };
+    chain.desired = enabled;
+    mcpToggleChains.set(serverName, chain);
+    if (!chain.running) {
+      chain.running = (async () => {
+        let status;
+        try {
+          let want;
+          do {
+            want = chain.desired;
+            status = await connectConfiguredMcp({ only: serverName, enabled: want });
+          } while (chain.desired !== want);
+          // Turn-safe: defers until any active turn ends (never aborts it).
+          applyMcpToggleRecreate(serverName);
+        } finally {
+          chain.running = null;
+        }
+        return status;
+      })();
+    }
+    return chain.running;
+  }
   return {
     mcpStatus() {
       return mcpStatus();
@@ -78,7 +126,7 @@ export function createResourceApi(deps) {
       await recreateCurrentSessionIfReady();
       return status;
     },
-    async setMcpServerEnabled(name, enabled) {
+    setMcpServerEnabled(name, enabled) {
       const serverName = clean(name);
       if (!serverName) throw new Error('MCP server name is required');
       const nextConfig = { ...getConfig() };
@@ -88,14 +136,20 @@ export function createResourceApi(deps) {
       if (!Object.prototype.hasOwnProperty.call(current, serverName)) {
         throw new Error(`MCP server not configured: ${serverName}`);
       }
+      // A project-local `.mcp.json` entry WINS over config for this name, so a
+      // config enable/disable flag would persist but never change live state.
+      // Surface that to the caller instead of reporting a silent success.
+      const shadowRow = mcpStatus().servers.find((s) => s.name === serverName);
+      if (shadowRow && shadowRow.source === 'project') {
+        throw new Error(`'${serverName}' is defined by project .mcp.json — config toggle has no effect`);
+      }
+      // Adopt + persist config synchronously (fast) so intent is durable, then
+      // hand the heavy connect/close/recreate to the per-server background
+      // chain. Return that chain's promise so callers can settle the picker on
+      // completion, but the store no longer blocks on it.
       current[serverName] = { ...(current[serverName] || {}), enabled: enabled !== false };
       saveConfigAndAdopt({ ...nextConfig, mcpServers: current });
-      const status = await connectConfiguredMcp({ reset: true });
-      invalidatePreSessionToolSurface();
-      const session = getSession();
-      if (session?.id) mgr.closeSession(session.id, 'cli-mcp-toggle');
-      await recreateCurrentSessionIfReady();
-      return status;
+      return scheduleMcpToggle(serverName, enabled !== false);
     },
     skillsStatus() {
       return skillsStatus();

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

@@ -67,6 +67,7 @@ import {
   saveWebhook,
   saveWebhookAuthtoken,
   setBackend,
+  setBackendAsync,
   setScheduleEnabled,
   setWebhookEnabled,
   setWebhookConfig,
@@ -333,6 +334,11 @@ export async function createMixdogSessionRuntime({
   // 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;
   // Last assistant text handed to the transcript writer (via onAssistantText),
   // so the post-turn final-content append can skip an exact duplicate.
   let _lastAppendedAssistant = '';
@@ -599,6 +605,7 @@ export async function createMixdogSessionRuntime({
     resolveEffectiveMcpServers,
     mcpStatus,
     connectConfiguredMcp,
+    awaitInitialMcpConnect,
     normalizeMcpServerInput,
   } = createMcpGlue({
     mcpClient,
@@ -683,7 +690,19 @@ export async function createMixdogSessionRuntime({
     void (async () => {
       await checkForUpdateInternal({ force: true });
       if (autoUpdateEnabled() && updateCheckState.updateAvailable) {
-        await runUpdateNowInternal();
+        const result = await runUpdateNowInternal();
+        // Surface the boot auto-update outcome as a UI-only notice (TUI maps
+        // meta.kind 'update-notice' to a transcript notice, never a
+        // model-visible message). Silent before: installed-but-needs-restart
+        // and failed installs were invisible unless the user opened the
+        // maintenance picker.
+        if (result?.phase === 'installed') {
+          const v = result.version && result.version !== 'unknown'
+            ? `v${result.version}` : (updateCheckState.latestVersion ? `v${updateCheckState.latestVersion}` : 'latest');
+          emitRuntimeNotification(`mixdog ${v} installed — restart to apply.`, { kind: 'update-notice', tone: 'info' });
+        } else if (result?.phase === 'failed') {
+          emitRuntimeNotification(`mixdog auto-update failed: ${result.error || 'unknown error'}`, { kind: 'update-notice', tone: 'warn' });
+        }
       }
     })().catch(() => {});
   }, 0);
@@ -903,6 +922,11 @@ export async function createMixdogSessionRuntime({
         if (msg?.params?.state === 'acquired' && !remoteEnabled) {
           remoteEnabled = true;
           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;
@@ -1001,8 +1025,8 @@ export async function createMixdogSessionRuntime({
         if (!codeGraphMod?.executeCodeGraphTool) throw new Error('code_graph runtime is not available');
         return await codeGraphMod.executeCodeGraphTool(name, args || {}, args?.cwd || callerCwd);
       }
-      if (name === 'tool_search') {
-        return renderToolSearch(args, activeToolSurface(), mode);
+      if (name === 'tool_search' || name === 'load_tool') {
+        return renderToolSearch(args, activeToolSurface(), mode, { mcpStatus });
       }
       if (name === 'explore') {
         const callerSessionId = callerCtx?.callerSessionId || session?.id || null;
@@ -1107,6 +1131,8 @@ export async function createMixdogSessionRuntime({
     flushConfigSave,
     flushBackendSave,
     scheduleBackendSave,
+    scheduleSkillsSave,
+    flushSkillsSave,
     flushOutputStyleSave,
     scheduleOutputStyleSave,
     reloadFullConfig,
@@ -1124,6 +1150,7 @@ export async function createMixdogSessionRuntime({
     cfgMod,
     sharedCfgMod,
     setBackend,
+    setBackendAsync,
     setConfiguredShell,
     normalizeSystemShellConfig,
     normalizeSearchRouteConfig,
@@ -1373,7 +1400,28 @@ export async function createMixdogSessionRuntime({
       session = mgr.createSession(sessionOpts);
       sessionNeedsCwdRefresh = false;
       attachSessionHooks(session, { hooks, hookCommonPayload, getCwd: () => currentCwd });
-      applyDeferredToolSurface(session, deferredSurfaceModeForLead(mode), standaloneTools, { provider: route.provider });
+      // Every-create MCP fold (NO blocking): seed the INITIAL deferred surface +
+      // BP1 manifest from whatever MCP servers are ALREADY 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 initial manifest 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 ? [...standaloneTools, ...connectedMcpTools] : standaloneTools,
+        { 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 });
@@ -1400,6 +1448,9 @@ export async function createMixdogSessionRuntime({
         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;
     })();
 
@@ -1523,6 +1574,63 @@ export async function createMixdogSessionRuntime({
     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.
@@ -1783,6 +1891,7 @@ export async function createMixdogSessionRuntime({
     adoptConfig,
     saveConfigAndAdopt,
     scheduleBackendSave,
+    scheduleSkillsSave,
     cfgMod,
     hasOwn,
     normalizeAutoClearConfig,
@@ -1859,6 +1968,7 @@ export async function createMixdogSessionRuntime({
     statusRoutes,
     channels,
     agentTool,
+    pushTranscriptRebind,
     mcpClient,
     warmupTimers,
     prewarmTimers,
@@ -1896,6 +2006,7 @@ export async function createMixdogSessionRuntime({
     pluginsStatus,
     getMemoryModule,
     reloadFullConfig,
+    getActiveTurnCount: () => activeTurnCount,
   });
   const modelRouteApi = createModelRouteApi({
     getConfig: () => config,
@@ -1978,6 +2089,8 @@ export async function createMixdogSessionRuntime({
     refreshSessionForCwdIfNeeded,
     createCurrentSession,
     ensureRemoteTranscriptWriter,
+    pushTranscriptRebind,
+    flushPendingTranscriptRebind,
     channelsEnabled,
     invokeChannelStart,
     channels,
@@ -1997,6 +2110,7 @@ export async function createMixdogSessionRuntime({
     resolveCwdPath,
     agentStatusState,
     notificationListeners,
+    awaitInitialMcpConnect,
   });
 
   return {

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

@@ -32,6 +32,7 @@ export function isSessionPreviewNoise(text) {
   return !value
     || value.startsWith('<system-reminder>')
     || value.startsWith('</system-reminder>')
+    || isLateToolAnnouncement(value)
     || /^#\s*permission\b/i.test(value)
     || /^permission:\s*/i.test(value)
     || /^cwd:\s*/i.test(value);
@@ -45,6 +46,46 @@ export function cleanSessionPreview(text) {
     .slice(0, 160);
 }
 
+// Stable sentinel carried in every late-tool (deferred MCP) announcement
+// reminder — must stay byte-identical to LATE_TOOL_REMINDER_SENTINEL in
+// src/session-runtime/tool-catalog.mjs. Detection keys on this exact string
+// (never fuzzy matching) so the raw announcement block can be hidden from
+// user-facing surfaces while the model context stays untouched.
+export const LATE_TOOL_ANNOUNCEMENT_SENTINEL = 'connected after this session started';
+
+export function isLateToolAnnouncement(text) {
+  const value = String(text || '');
+  return value.includes(LATE_TOOL_ANNOUNCEMENT_SENTINEL)
+    && /<available-deferred-tools>/i.test(value);
+}
+
+// Derive a muted one-line notice from a late-tool announcement body, e.g.
+// "MCP tools available: UnityMCP (12 tools)". MCP tool entries in the manifest
+// are `- mcp__<server>__<tool>: ...` lines; the server name is the segment
+// after the `mcp__` prefix. Returns '' for non-announcement text.
+export function summarizeLateToolAnnouncement(text) {
+  const value = String(text || '');
+  if (!isLateToolAnnouncement(value)) return '';
+  const block = value.match(/<available-deferred-tools>([\s\S]*?)<\/available-deferred-tools>/i);
+  const body = block ? block[1] : value;
+  const names = [];
+  const lineRe = /^\s*-\s+([A-Za-z0-9_.:-]+)/gm;
+  let m;
+  while ((m = lineRe.exec(body))) names.push(m[1]);
+  const servers = new Set();
+  for (const name of names) {
+    const seg = name.startsWith('mcp__') ? name.slice(5) : name;
+    const server = seg.split('__')[0];
+    if (server) servers.add(server);
+  }
+  const count = names.length;
+  const label = servers.size === 1
+    ? [...servers][0]
+    : (servers.size ? `${servers.size} MCP servers` : 'MCP');
+  if (!count) return `MCP tools available: ${label}`;
+  return `MCP tools available: ${label} (${count} ${count === 1 ? 'tool' : 'tools'})`;
+}
+
 export function clean(value) {
   return String(value ?? '').trim();
 }

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

@@ -6,7 +6,10 @@ import {
   toolSearchMatches,
   sortedNamesByMeasuredUsage,
   selectDeferredTools,
+  reconcileDeferredMcpToolCatalog,
+  refreshInitialDeferredMcpSurface,
 } from './tool-catalog.mjs';
+import { getMcpTools } from '../runtime/agent/orchestrator/mcp/client.mjs';
 
 // Turn execution (ask) + session-manage/tool-surface/agent surfaces. Extracted
 // verbatim from the runtime API object; stateless helpers are imported directly
@@ -22,10 +25,12 @@ export function createSessionTurnApi(deps) {
     getTranscriptWriter, getTwKey, getLastAppendedAssistant, setLastAppendedAssistant,
     scheduleCodeGraphPrewarm, refreshSessionForCwdIfNeeded, createCurrentSession,
     ensureRemoteTranscriptWriter, channelsEnabled, invokeChannelStart, channels,
+    pushTranscriptRebind, flushPendingTranscriptRebind,
     hooks, hookCommonPayload, mgr, notifyFnForSession, bootProfile,
     scheduleProviderWarmup, scheduleProviderModelWarmup, invalidateContextStatusCache,
     agentTool, recreateCurrentSessionIfReady, invalidatePreSessionToolSurface,
     activeToolSurface, applyResolvedCwd, resolveCwdPath, agentStatusState, notificationListeners,
+    awaitInitialMcpConnect,
   } = deps;
   return {
     async ask(prompt, options = {}) {
@@ -46,6 +51,9 @@ export function createSessionTurnApi(deps) {
           setLastAppendedAssistant('');
           const prevKey = getTwKey();
           ensureRemoteTranscriptWriter();
+          // Flush a rebind deferred before the session/writer existed ('acquired'
+          // in lazy mode). One-shot: no-op unless a push was actually deferred.
+          flushPendingTranscriptRebind?.();
           if (getTwKey() && getTwKey() !== prevKey && channelsEnabled() && !envFlag('MIXDOG_DISABLE_CHANNEL_START')) {
             void invokeChannelStart()
               .then(() => {
@@ -56,6 +64,43 @@ export function createSessionTurnApi(deps) {
           }
         }
         const session0 = getSession();
+        if (session0.deferredInitialRefreshPending) {
+          // FIRST TURN of a FRESH session (session-local gate, NOT the
+          // process-wide firstTurnCompleted): an MCP server may have finished its
+          // handshake BETWEEN session-create and this first send. Re-fold the
+          // LIVE registry into the INITIAL deferred surface + BP1
+          // <available-deferred-tools> manifest (sync, in-place, idempotent) and
+          // pre-mark those names announced, so they ship in the initial manifest
+          // instead of a late-tool <system-reminder>. One-shot: cleared before
+          // the fold so a throw still never re-runs it, and a resumed session
+          // (flag unset) skips straight to the late path below.
+          session0.deferredInitialRefreshPending = false;
+          // First-turn gate: give the in-flight INITIAL MCP connect a bounded
+          // chance to finish so servers that connect within the startup budget
+          // land in THIS request's tool surface. Bounded by the same budget —
+          // UI/boot never blocks here; only this first ask waits, and only once.
+          try { await awaitInitialMcpConnect?.(); }
+          catch { /* gate must never break the turn */ }
+          try { refreshInitialDeferredMcpSurface(session0, getMcpTools()); }
+          catch { /* first-turn MCP fold must never break the turn */ }
+        } else {
+          // AFTER FIRST TURN: fold in MCP tools whose servers finished their
+          // handshake after this session was created, and announce the newly
+          // available deferred tool names via ONE appended, persistent
+          // system-reminder (append-only — never rewrites BP1 or touches the
+          // active tool surface, so the prompt-cache prefix stays intact).
+          try {
+            reconcileDeferredMcpToolCatalog(session0, getMcpTools(), {
+              // Deliver the late-tool announcement through the pending-message
+              // queue so it rides inside the next real user turn as a persisted
+              // system-reminder (no synthetic user + '.' assistant pair).
+              enqueue: (text) => (typeof mgr.enqueuePendingMessage === 'function'
+                ? mgr.enqueuePendingMessage(session0.id, text) > 0
+                : false),
+            });
+          }
+          catch { /* MCP delta must never break the turn */ }
+        }
         hooks.emit('turn:start', { sessionId: session0.id, prompt, cwd: getCurrentCwd() });
         // UserPromptSubmit: a hook FAILURE must not block the turn, but blocked===true MUST throw.
         let promptDispatch = null;
@@ -180,6 +225,11 @@ export function createSessionTurnApi(deps) {
         try { agentTool.recoverWorkers?.({ clientHostPid: getSession()?.clientHostPid || process.pid }); } catch {}
       }
       invalidateContextStatusCache();
+      // clearSessionMessages swaps the live session object; the worker binding
+      // + persisted status still reference the pre-clear transcript. Push the
+      // current transcript so outbound forwarding repoints now, not on the next
+      // inbound steal (best-effort, remote-gated inside pushTranscriptRebind).
+      pushTranscriptRebind?.();
       return true;
     },
     // session_manage tool handoff: the engine polls this at turn end and, if

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

@@ -16,6 +16,7 @@ export function createSettingsApi({
   adoptConfig,
   saveConfigAndAdopt,
   scheduleBackendSave,
+  scheduleSkillsSave,
   // normalizers / helpers
   cfgMod,
   hasOwn,
@@ -139,8 +140,14 @@ export function createSettingsApi({
       const names = disabled instanceof Set
         ? [...disabled]
         : (Array.isArray(disabled) ? disabled : []);
-      const nextSkills = cfgMod.patchSkillsDisabled(names);
+      // Adopt in-memory synchronously so getDisabledSkills reflects the new
+      // value on the same tick (matches normalizeSkillsConfig({ disabled })
+      // used by patchSkillsDisabled). Defer the heavy in-lock file RMW through
+      // the skills debounce channel so the settings-toggle key handler does not
+      // hitch on a synchronous disk write.
+      const nextSkills = cfgMod.normalizeSkillsConfig({ disabled: names });
       adoptConfig({ ...getConfig(), skills: nextSkills });
+      scheduleSkillsSave(names);
       return this.getDisabledSkills();
     },
     setProfile(input = {}) {