mixdog 0.9.23 → 0.9.25

package/src/runtime/shared/user-data-guard.mjs

@@ -8,6 +8,13 @@ import {
   statSync,
   writeFileSync,
 } from 'fs';
+import {
+  copyFile as copyFileP,
+  mkdir as mkdirP,
+  readdir as readdirP,
+  rm as rmP,
+  stat as statP,
+} from 'fs/promises';
 import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
@@ -158,6 +165,65 @@ export function backupUserData(dataDir, reason = 'snapshot') {
   return { dir: copied.length > 0 ? backupDir : null, copied };
 }
 
+// ── Async backup variant (fs.promises) ──────────────────────────────
+// Byte-for-byte the same policy/skip guards/prune behavior as backupUserData,
+// but every filesystem op yields via fs.promises so a debounced config flush
+// on the UI event loop never blocks on the copy tree or the prune sweep.
+async function copyTreeAsync(src, dst, copied) {
+  const st = await statP(src);
+  if (st.isDirectory()) {
+    for (const name of await readdirP(src)) {
+      await copyTreeAsync(join(src, name), join(dst, name), copied);
+    }
+    return;
+  }
+  if (!st.isFile()) return;
+  await mkdirP(dirname(dst), { recursive: true });
+  await copyFileP(src, dst);
+  copied.push(dst);
+}
+
+async function pruneBackupsAsync(keep = 40) {
+  let entries = [];
+  try {
+    entries = (await readdirP(getBackupRoot(), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort()
+      .reverse();
+  } catch {
+    return;
+  }
+  for (const name of entries.slice(keep)) {
+    try { await rmP(join(getBackupRoot(), name), { recursive: true, force: true }); } catch {}
+  }
+}
+
+export async function backupUserDataAsync(dataDir, reason = 'snapshot') {
+  if (process.env.MIXDOG_SKIP_USER_DATA_BACKUP === '1' || process.env.MIXDOG_SKIP_USER_DATA_BACKUP === 'true') {
+    return { dir: null, copied: [] };
+  }
+  if (!dataDir || !existsSync(dataDir)) return { dir: null, copied: [] };
+  const backupDir = join(getBackupRoot(), `${stamp()}-${safeReason(reason)}`);
+  const copied = [];
+  for (const rel of USER_DATA_FILES) {
+    const src = join(dataDir, rel);
+    if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
+  }
+  for (const rel of USER_DATA_DIRS) {
+    const src = join(dataDir, rel);
+    if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
+  }
+  if (copied.length > 0) {
+    markUserDataInitialized(dataDir);
+    await pruneBackupsAsync();
+    if (process.env.MIXDOG_SETUP_QUIET !== '1') {
+      process.stderr.write(`[user-data-backup] ${reason}: copied ${copied.length} file(s) to ${backupDir}\n`);
+    }
+  }
+  return { dir: copied.length > 0 ? backupDir : null, copied };
+}
+
 export function shouldSeedMissingUserData(dataDir, rel) {
   if (!dataDir) return true;
   if (existsSync(join(dataDir, rel))) {

package/src/session-runtime/config-lifecycle.mjs

@@ -31,6 +31,7 @@ export function createConfigLifecycle({
   cfgMod,
   sharedCfgMod,
   setBackend,
+  setBackendAsync,
   setConfiguredShell,
   normalizeSystemShellConfig,
   normalizeSearchRouteConfig,
@@ -90,8 +91,61 @@ export function createConfigLifecycle({
   }
 
   // --- debounced config save --------------------------------------------------
+  // Coexistence strategy (sync vs async flush):
+  //  * The debounce TIMER fires the ASYNC flush (async lock wait + async icacls
+  //    + async backup + async atomic write) so a toggle never blocks the UI
+  //    event loop.
+  //  * Per-channel serialization: each channel keeps ONE in-flight promise tail;
+  //    a new async flush chains after it so flushes never interleave. The pending
+  //    payload is re-read at write time (identity guard), so a burst collapses to
+  //    the last writer without dropping a newer toggle.
+  //  * The SYNC flush is retained for reloadFullConfig/teardown (they need the
+  //    write durable before continuing). It nulls the pending payload and writes
+  //    synchronously; that sync write takes the SAME cross-process lock file as
+  //    any in-flight async write, so it serializes AFTER it (lock contention),
+  //    and the async loop's identity guard then finds a null/superseded payload
+  //    and does not rewrite — never a revert, and no double-write except a rare
+  //    idempotent same-content window if a sync flush lands mid async disk-write.
   let pendingConfigToSave = null;
   let configSaveTimer = null;
+  let configFlushInFlight = null;
+
+  async function runConfigFlushAsync() {
+    // Drain config, then skills, and RE-CHECK config. A config snapshot queued
+    // after the skills patch may carry a stale snapshot.skills (the snapshot
+    // captured an older config object ref, before the skills toggle replaced it)
+    // that would overwrite the just-patched skills.disabled. Looping until BOTH
+    // channels are quiescent keeps the skills patch the last writer relative to
+    // EVERY pending/queued config snapshot.
+    do {
+      let configFailed = false;
+      while (pendingConfigToSave !== null) {
+        const snapshot = pendingConfigToSave;
+        try {
+          await cfgMod.saveConfigAsync(snapshot);
+        } catch (err) {
+          process.stderr.write(`[config] async saveConfig failed: ${err?.message || err}\n`);
+          // Keep the payload: a failed write must not drop the pending change.
+          configFailed = true;
+          break;
+        }
+        if (pendingConfigToSave === snapshot) pendingConfigToSave = null;
+      }
+      // Ordering invariant: skills.disabled patch lands AFTER the config save.
+      await flushSkillsSaveAsync();
+      if (configFailed) break; // avoid a hot spin on a persistently failing write
+    } while (pendingConfigToSave !== null);
+  }
+
+  function flushConfigSaveAsync() {
+    if (configSaveTimer) { clearTimeout(configSaveTimer); configSaveTimer = null; }
+    const start = () => runConfigFlushAsync();
+    const p = configFlushInFlight ? configFlushInFlight.then(start, start) : start();
+    configFlushInFlight = p;
+    const clear = () => { if (configFlushInFlight === p) configFlushInFlight = null; };
+    p.then(clear, clear);
+    return p;
+  }
 
   function flushConfigSave() {
     if (configSaveTimer) {
@@ -100,9 +154,13 @@ export function createConfigLifecycle({
     }
     if (pendingConfigToSave !== null) {
       const snapshot = pendingConfigToSave;
-      pendingConfigToSave = null;
       try {
         cfgMod.saveConfig(snapshot);
+        // Clear ONLY after a durable write. saveConfig blocks on the same
+        // cross-process lock an async flush may hold, so it serializes after it;
+        // if it still fails (e.g. lock timeout) we keep the payload so a later
+        // flush / reloadFullConfig retries instead of reverting to stale disk.
+        if (pendingConfigToSave === snapshot) pendingConfigToSave = null;
       } catch (err) {
         process.stderr.write(`[config] debounced saveConfig failed: ${err?.message || err}\n`);
       }
@@ -126,7 +184,7 @@ export function createConfigLifecycle({
     // disk write after CONFIG_SAVE_DEBOUNCE_MS of quiet.
     pendingConfigToSave = getConfig();
     if (configSaveTimer) clearTimeout(configSaveTimer);
-    configSaveTimer = setTimeout(flushConfigSave, CONFIG_SAVE_DEBOUNCE_MS);
+    configSaveTimer = setTimeout(() => { flushConfigSaveAsync(); }, CONFIG_SAVE_DEBOUNCE_MS);
     configSaveTimer.unref?.();
     return adopted;
   }
@@ -134,6 +192,31 @@ export function createConfigLifecycle({
   // --- debounced backend switch ----------------------------------------------
   let pendingBackendName = null;
   let backendSaveTimer = null;
+  let backendFlushInFlight = null;
+
+  async function runBackendFlushAsync() {
+    while (pendingBackendName !== null) {
+      const name = pendingBackendName;
+      try {
+        await setBackendAsync(name);
+      } catch (err) {
+        process.stderr.write(`[channels] async setBackend failed: ${err?.message || err}\n`);
+        if (pendingBackendName === name) pendingBackendName = null;
+        break;
+      }
+      if (pendingBackendName === name) pendingBackendName = null;
+    }
+  }
+
+  function flushBackendSaveAsync() {
+    if (backendSaveTimer) { clearTimeout(backendSaveTimer); backendSaveTimer = null; }
+    const start = () => runBackendFlushAsync();
+    const p = backendFlushInFlight ? backendFlushInFlight.then(start, start) : start();
+    backendFlushInFlight = p;
+    const clear = () => { if (backendFlushInFlight === p) backendFlushInFlight = null; };
+    p.then(clear, clear);
+    return p;
+  }
 
   function flushBackendSave() {
     if (backendSaveTimer) {
@@ -153,7 +236,7 @@ export function createConfigLifecycle({
   function scheduleBackendSave(name) {
     pendingBackendName = name;
     if (backendSaveTimer) clearTimeout(backendSaveTimer);
-    backendSaveTimer = setTimeout(flushBackendSave, CONFIG_SAVE_DEBOUNCE_MS);
+    backendSaveTimer = setTimeout(() => { flushBackendSaveAsync(); }, CONFIG_SAVE_DEBOUNCE_MS);
     backendSaveTimer.unref?.();
   }
 
@@ -163,6 +246,31 @@ export function createConfigLifecycle({
   // burst of settings-toggle key presses collapses into one disk write.
   let pendingSkillsNames = null;
   let skillsSaveTimer = null;
+  let skillsFlushInFlight = null;
+
+  async function runSkillsFlushAsync() {
+    while (pendingSkillsNames !== null) {
+      const names = pendingSkillsNames;
+      try {
+        await cfgMod.patchSkillsDisabledAsync(names);
+      } catch (err) {
+        process.stderr.write(`[config] async patchSkillsDisabled failed: ${err?.message || err}\n`);
+        if (pendingSkillsNames === names) pendingSkillsNames = null;
+        break;
+      }
+      if (pendingSkillsNames === names) pendingSkillsNames = null;
+    }
+  }
+
+  function flushSkillsSaveAsync() {
+    if (skillsSaveTimer) { clearTimeout(skillsSaveTimer); skillsSaveTimer = null; }
+    const start = () => runSkillsFlushAsync();
+    const p = skillsFlushInFlight ? skillsFlushInFlight.then(start, start) : start();
+    skillsFlushInFlight = p;
+    const clear = () => { if (skillsFlushInFlight === p) skillsFlushInFlight = null; };
+    p.then(clear, clear);
+    return p;
+  }
 
   function flushSkillsSave() {
     if (skillsSaveTimer) {
@@ -182,13 +290,50 @@ export function createConfigLifecycle({
   function scheduleSkillsSave(names) {
     pendingSkillsNames = names;
     if (skillsSaveTimer) clearTimeout(skillsSaveTimer);
-    skillsSaveTimer = setTimeout(flushSkillsSave, CONFIG_SAVE_DEBOUNCE_MS);
+    skillsSaveTimer = setTimeout(() => { flushSkillsSaveAsync(); }, CONFIG_SAVE_DEBOUNCE_MS);
     skillsSaveTimer.unref?.();
   }
 
   // --- debounced top-level outputStyle persist -------------------------------
   let pendingOutputStyleId = null;
   let outputStyleSaveTimer = null;
+  let outputStyleFlushInFlight = null;
+
+  function outputStyleUpdater(styleId) {
+    return (root) => {
+      const next = { ...(root || {}), outputStyle: styleId };
+      if (next.agent && typeof next.agent === 'object' && !Array.isArray(next.agent)) {
+        const agent = { ...next.agent };
+        delete agent.outputStyle;
+        next.agent = agent;
+      }
+      return next;
+    };
+  }
+
+  async function runOutputStyleFlushAsync() {
+    while (pendingOutputStyleId !== null) {
+      const styleId = pendingOutputStyleId;
+      try {
+        await sharedCfgMod.updateConfigAsync(outputStyleUpdater(styleId));
+      } catch (err) {
+        process.stderr.write(`[config] async outputStyle save failed: ${err?.message || err}\n`);
+        if (pendingOutputStyleId === styleId) pendingOutputStyleId = null;
+        break;
+      }
+      if (pendingOutputStyleId === styleId) pendingOutputStyleId = null;
+    }
+  }
+
+  function flushOutputStyleSaveAsync() {
+    if (outputStyleSaveTimer) { clearTimeout(outputStyleSaveTimer); outputStyleSaveTimer = null; }
+    const start = () => runOutputStyleFlushAsync();
+    const p = outputStyleFlushInFlight ? outputStyleFlushInFlight.then(start, start) : start();
+    outputStyleFlushInFlight = p;
+    const clear = () => { if (outputStyleFlushInFlight === p) outputStyleFlushInFlight = null; };
+    p.then(clear, clear);
+    return p;
+  }
 
   function flushOutputStyleSave() {
     if (outputStyleSaveTimer) {
@@ -199,15 +344,7 @@ export function createConfigLifecycle({
     const styleId = pendingOutputStyleId;
     pendingOutputStyleId = null;
     try {
-      sharedCfgMod.updateConfig((root) => {
-        const next = { ...(root || {}), outputStyle: styleId };
-        if (next.agent && typeof next.agent === 'object' && !Array.isArray(next.agent)) {
-          const agent = { ...next.agent };
-          delete agent.outputStyle;
-          next.agent = agent;
-        }
-        return next;
-      });
+      sharedCfgMod.updateConfig(outputStyleUpdater(styleId));
     } catch (err) {
       process.stderr.write(`[config] debounced outputStyle save failed: ${err?.message || err}\n`);
     }
@@ -216,7 +353,7 @@ export function createConfigLifecycle({
   function scheduleOutputStyleSave(styleId) {
     pendingOutputStyleId = styleId;
     if (outputStyleSaveTimer) clearTimeout(outputStyleSaveTimer);
-    outputStyleSaveTimer = setTimeout(flushOutputStyleSave, CONFIG_SAVE_DEBOUNCE_MS);
+    outputStyleSaveTimer = setTimeout(() => { flushOutputStyleSaveAsync(); }, CONFIG_SAVE_DEBOUNCE_MS);
     outputStyleSaveTimer.unref?.();
   }
 
@@ -227,7 +364,30 @@ export function createConfigLifecycle({
     // subsequent adopt preserves) that change instead of reverting to a stale
     // on-disk snapshot.
     flushConfigSave();
-    return adoptConfig(cfgMod.loadConfig(), { hasSecrets: true });
+    const loaded = cfgMod.loadConfig();
+    if (pendingConfigToSave !== null) {
+      // The debounced write could not land (e.g. lock timeout), so on-disk is
+      // stale. Prefer the freshest in-memory state and re-overlay the keychain
+      // provider secrets that only the disk load carries, so a failed flush
+      // never reverts the user's latest change.
+      const current = getConfig();
+      const merged = { ...loaded, ...current, providers: { ...(current.providers || {}) } };
+      for (const [name, val] of Object.entries(loaded.providers || {})) {
+        if (val && val.apiKey) {
+          // Match loadConfig's keychain overlay: apiKey ⇒ enabled:true, UNLESS
+          // the in-memory pending state EXPLICITLY disabled this provider (a
+          // genuine newer user change that must not be reverted).
+          const explicitlyDisabled = current.providers?.[name]?.enabled === false;
+          merged.providers[name] = {
+            ...(merged.providers[name] || {}),
+            apiKey: val.apiKey,
+            enabled: explicitlyDisabled ? false : true,
+          };
+        }
+      }
+      return adoptConfig(merged, { hasSecrets: true });
+    }
+    return adoptConfig(loaded, { hasSecrets: true });
   }
 
   function ensureFullConfig() {

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

@@ -250,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/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);
@@ -1131,6 +1150,7 @@ export async function createMixdogSessionRuntime({
     cfgMod,
     sharedCfgMod,
     setBackend,
+    setBackendAsync,
     setConfiguredShell,
     normalizeSystemShellConfig,
     normalizeSearchRouteConfig,
@@ -1380,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 });
@@ -1407,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;
     })();
 
@@ -1538,17 +1582,55 @@ export async function createMixdogSessionRuntime({
   // failure must never throw into the lead paths that call this.
   function pushTranscriptRebind() {
     if (!remoteEnabled) return;
-    if (!ensureRemoteTranscriptWriter()) 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()) return;
+    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((error) => bootProfile('channels:rebind-push-failed', { error: error?.message || String(error) }));
+      void channels.execute('rebind_current_transcript', { transcriptPath }).catch(onError);
     } catch (error) {
-      bootProfile('channels:rebind-push-failed', { error: error?.message || String(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.
@@ -2008,6 +2090,7 @@ export async function createMixdogSessionRuntime({
     createCurrentSession,
     ensureRemoteTranscriptWriter,
     pushTranscriptRebind,
+    flushPendingTranscriptRebind,
     channelsEnabled,
     invokeChannelStart,
     channels,
@@ -2027,6 +2110,7 @@ export async function createMixdogSessionRuntime({
     resolveCwdPath,
     agentStatusState,
     notificationListeners,
+    awaitInitialMcpConnect,
   });
 
   return {

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

@@ -7,6 +7,7 @@ import {
   sortedNamesByMeasuredUsage,
   selectDeferredTools,
   reconcileDeferredMcpToolCatalog,
+  refreshInitialDeferredMcpSurface,
 } from './tool-catalog.mjs';
 import { getMcpTools } from '../runtime/agent/orchestrator/mcp/client.mjs';
 
@@ -24,11 +25,12 @@ export function createSessionTurnApi(deps) {
     getTranscriptWriter, getTwKey, getLastAppendedAssistant, setLastAppendedAssistant,
     scheduleCodeGraphPrewarm, refreshSessionForCwdIfNeeded, createCurrentSession,
     ensureRemoteTranscriptWriter, channelsEnabled, invokeChannelStart, channels,
-    pushTranscriptRebind,
+    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 = {}) {
@@ -49,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(() => {
@@ -59,22 +64,43 @@ export function createSessionTurnApi(deps) {
           }
         }
         const session0 = getSession();
-        // Turn-boundary snapshot: 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),
-          });
+        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 */ }
         }
-        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;