@yeaft/webchat-agent 1.0.57 → 1.0.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.57",
+  "version": "1.0.59",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -703,6 +703,22 @@ export class Engine {
     this.#config.language = lang;
   }
 
+  /**
+   * Hot-swap runtime managers for a project-bound Session. The ToolRegistry is
+   * shared at the bridge/session layer; these references only decide which
+   * skills are injected and which MCP manager flattened tools call through.
+   *
+   * @param {{ skillManager?: import('./skills.js').SkillManager, mcpManager?: import('./mcp.js').MCPManager }} managers
+   */
+  setRuntimeManagers(managers = {}) {
+    if (Object.prototype.hasOwnProperty.call(managers, 'skillManager')) {
+      this.#skillManager = managers.skillManager || null;
+    }
+    if (Object.prototype.hasOwnProperty.call(managers, 'mcpManager')) {
+      this.#mcpManager = managers.mcpManager || null;
+    }
+  }
+
   /**
    * Unregister a tool.
    *

package/yeaft/session.js

@@ -363,12 +363,9 @@ export async function loadSession(options = {}) {
   }
 
   // ─── 6. Load skills ────────────────────────────────────
-  // Project tier root for skills + MCP project assets. Per-session/per-group
-  // workdirs override at tool-execution time via ToolContext.cwd; for the
-  // SYSTEM-PROMPT skill set and the project MCP servers we use the agent
-  // process cwd, the common case when an agent is launched inside a project
-  // the user wants project-tier assets for. Shared so skills (.claude/skills,
-  // .yeaft/skills) and MCP (.mcp.json) resolve from the same root.
+  // Project tier root for skills + MCP project assets. Per-session workDir
+  // overlays are loaded by web-bridge once it knows the selected Session meta;
+  // the base runtime still uses the agent process cwd for global/default status.
   const projectTierRoot = process.cwd();
 
   let skillManager;

package/yeaft/skills.js

@@ -53,7 +53,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync, mkdirSync, statSync } from 'fs';
-import { join, basename, sep, dirname, resolve } from 'path';
+import { join, basename, sep, dirname, resolve, delimiter } from 'path';
 import { platform, homedir } from 'os';
 import { fileURLToPath } from 'url';
 
@@ -758,19 +758,23 @@ export function createSkillManager(yeaftDir, workDir) {
   const claudeUserDir = home ? join(home, '.claude', 'skills') : null;
   const codexUserDir = home ? join(home, '.codex', 'skills') : null;
   const userDir = join(yeaftDir, 'skills');
-  const claudeProjectDir = workDir ? join(workDir, '.claude', 'skills') : null;
-  const codexProjectDir = workDir ? join(workDir, '.agents', 'skills') : null;
-  const projectDir = workDir ? join(workDir, '.yeaft', 'skills') : null;
-
-  const dirs = [bundled, claudeUserDir, codexUserDir, userDir, claudeProjectDir, codexProjectDir, projectDir].filter(Boolean);
+  const projectRoots = [...new Set(String(workDir || '')
+    .split(delimiter)
+    .map(p => p.trim())
+    .filter(Boolean))];
+  const claudeProjectDirs = projectRoots.map(root => join(root, '.claude', 'skills'));
+  const codexProjectDirs = projectRoots.map(root => join(root, '.agents', 'skills'));
+  const projectDirs = projectRoots.map(root => join(root, '.yeaft', 'skills'));
+
+  const dirs = [bundled, claudeUserDir, codexUserDir, userDir, ...claudeProjectDirs, ...codexProjectDirs, ...projectDirs].filter(Boolean);
   const tierByDir = {};
   if (bundled) tierByDir[bundled] = 'bundled';
   if (claudeUserDir) tierByDir[claudeUserDir] = 'user-claude';
   if (codexUserDir) tierByDir[codexUserDir] = 'user-codex';
   tierByDir[userDir] = 'user';
-  if (claudeProjectDir) tierByDir[claudeProjectDir] = 'project-claude';
-  if (codexProjectDir) tierByDir[codexProjectDir] = 'project-codex';
-  if (projectDir) tierByDir[projectDir] = 'project';
+  for (const dir of claudeProjectDirs) tierByDir[dir] = 'project-claude';
+  for (const dir of codexProjectDirs) tierByDir[dir] = 'project-codex';
+  for (const dir of projectDirs) tierByDir[dir] = 'project';
 
   const ignorePathsByDir = {};
   if (claudeUserDir && bundled && pathIsInside(bundled, claudeUserDir)) {

package/yeaft/web-bridge.js

@@ -18,7 +18,7 @@
  *      ranges removed.
  */
 
-import { join } from 'node:path';
+import { delimiter, join } from 'node:path';
 import { COLLAB_TOOL_POLICY } from './tools/registry.js';
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
@@ -26,7 +26,9 @@ import { DEFAULT_YEAFT_DIR } from './init.js';
 import { buildDreamOutputSnapshot } from './dream/output-snapshot.js';
 import { Engine } from './engine.js';
 import { loadSession } from './session.js';
-import { loadConfig } from './config.js';
+import { loadConfig, loadMCPConfig } from './config.js';
+import { createSkillManager } from './skills.js';
+import { MCPManager } from './mcp.js';
 import { sendToServer } from '../connection/buffer.js';
 import ctx from '../context.js';
 import { hydrateYeaftStatusFromSession } from './status-cache.js';
@@ -79,6 +81,13 @@ const SKILL_COMMAND_PREFIX = 'skill:';
 /** @type {import('./session.js').Session | null} */
 let session = null;
 
+/**
+ * Single-flight runtime boot. History replay must not wait for this promise on
+ * cold load; message send still awaits it through ensureSessionLoaded().
+ * @type {Promise<import('./session.js').Session> | null}
+ */
+let sessionLoadPromise = null;
+
 let threadClassifier = defaultClassifyThread;
 
 function applyLiveLanguage(language) {
@@ -168,20 +177,29 @@ async function sendDreamSnapshotForSession(sessionId, extra = {}) {
 function scheduleYeaftLoadHistoryMetadataReplay(sessionId) {
   const replaySession = session;
   const replayConversationId = yeaftConversationId;
-  setTimeout(() => {
+  setTimeout(async () => {
     try {
       if (!replaySession) return;
       refreshLiveSessionConfig();
-      hydrateYeaftStatusFromSession(replaySession, { reason: 'history_load', emitEvent: true });
+      let projectRuntime = null;
+      if (sessionId) {
+        try {
+          const groupYeaftDir = resolveSessionYeaftDir(ctx.CONFIG?.yeaftDir || DEFAULT_YEAFT_DIR, sessionId);
+          const meta = loadSessionMeta(join(sessionsRoot(groupYeaftDir), sessionId));
+          projectRuntime = await ensureProjectRuntimeForSessionMeta(meta);
+        } catch { /* best-effort project metadata */ }
+      }
+      const status = mergedStatusForProjectRuntime(projectRuntime);
+      hydrateYeaftStatusFromSession({ ...replaySession, status }, { reason: 'history_load', emitEvent: true });
       sendSessionEvent({
         type: 'session_ready',
         conversationId: replayConversationId,
         model: replaySession.config.primaryModel || replaySession.config.model,
         modelEffort: replaySession.config.modelEffort || null,
         availableModels: replaySession.config.availableModels || [],
-        skills: replaySession.status.skills,
-        mcpServers: replaySession.status.mcpServers,
-        tools: replaySession.status.tools,
+        skills: status.skills,
+        mcpServers: status.mcpServers,
+        tools: status.tools,
         yeaftDir: ctx.CONFIG?.yeaftDir || null,
         tasks: replaySession.taskManager ? replaySession.taskManager.listActiveTasks() : [],
       });
@@ -385,6 +403,14 @@ function threadKey(sessionId, vpId, threadId) {
   return `${sessionId}::${vpId}::${threadId || 'main'}`;
 }
 
+function normalizeSessionWorkDir(workDir) {
+  return typeof workDir === 'string' && workDir.trim() ? workDir.trim() : '';
+}
+
+function projectRuntimeKey(workDir) {
+  return normalizeSessionWorkDir(workDir) || '__agent_cwd__';
+}
+
 function createThreadId() {
   return `thr_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
 }
@@ -394,6 +420,62 @@ const RUNNING_THREAD_STATES = new Set(['queued', 'typing', 'thinking', 'streamin
 const vpThreads = new Map();
 /** @type {Map<string, Set<Promise<string|null>>>} */
 const routePromisesByMsgId = new Map();
+/** @type {Map<string, { workDir: string, skillManager: import('./skills.js').SkillManager, mcpManager: import('./mcp.js').MCPManager, mcpStatus: object, mcpConfig: object, status: { skills: number, mcpServers: string[], mcpFailed: object[], mcpSkipped: object[], tools: number } }>} */
+const projectRuntimes = new Map();
+
+function replaceSessionMcpTools(mcpManager) {
+  if (!session?.toolRegistry || typeof session.toolRegistry.replaceMcpTools !== 'function') {
+    return { removed: 0, added: 0, skipped: true };
+  }
+  try {
+    const result = session.toolRegistry.replaceMcpTools(mcpManager, buildMcpFlattenedTools);
+    return { ...result, skipped: false };
+  } catch (err) {
+    console.warn('[Yeaft] hot-swap MCP tools failed:', err?.message || err);
+    return { removed: 0, added: 0, skipped: true, error: err?.message || String(err) };
+  }
+}
+
+function retargetVpEngines({ skillManager, mcpManager }) {
+  for (const eng of vpEngines.values()) {
+    try {
+      eng.setRuntimeManagers?.({ skillManager, mcpManager });
+    } catch { /* best-effort runtime retarget */ }
+  }
+}
+
+function activateBaseRuntime() {
+  const swap = replaceSessionMcpTools(session?.mcpManager);
+  retargetVpEngines({
+    skillManager: session?.skillManager || null,
+    mcpManager: session?.mcpManager || null,
+  });
+  broadcastSkillSlashCommands(session);
+  return swap;
+}
+
+function activateProjectRuntime(runtime) {
+  if (!runtime) return activateBaseRuntime();
+  const swap = replaceSessionMcpTools(runtime.mcpManager);
+  retargetVpEngines({
+    skillManager: runtime.skillManager,
+    mcpManager: runtime.mcpManager,
+  });
+  runtime.status = {
+    ...runtime.status,
+    tools: session?.toolRegistry?.size || runtime.status?.tools || 0,
+  };
+  broadcastSkillSlashCommands(session, [runtime.skillManager]);
+  return swap;
+}
+
+async function shutdownProjectRuntimes() {
+  const runtimes = Array.from(projectRuntimes.values());
+  projectRuntimes.clear();
+  await Promise.all(runtimes.map(async (runtime) => {
+    try { await runtime?.mcpManager?.disconnectAll?.(); } catch { /* best-effort shutdown */ }
+  }));
+}
 
 function getVpThreadMap(sessionId, vpId) {
   const key = vpKey(sessionId, vpId);
@@ -575,7 +657,8 @@ function invalidateGroupContext(sessionId) {
   // Engines are NOT torn down here on purpose. They hold subordinate
   // state (AMS adjustments) that should survive a meta change and a
   // closed sessionHandle — they don't reach the on-disk group meta
-  // directly. They *are* dropped on `resetYeaftSession`.
+  // directly. Project runtime managers are hot-swapped before each turn.
+  // They *are* dropped on `resetYeaftSession`.
 }
 
 /**
@@ -1084,6 +1167,7 @@ export function __testGroupHistory(sessionId) {
  */
 export function __testSetSession(sessionLike) {
   session = sessionLike;
+  sessionLoadPromise = null;
   if (!sessionLike) yeaftConversationId = null;
 }
 
@@ -1703,6 +1787,7 @@ export async function __testDrainVpDrivers() {
  * a half-aborted controller writing to a now-cleared map.
  */
 export async function __testResetVpState() {
+  await shutdownProjectRuntimes();
   for (const ctrl of vpAborts.values()) {
     try { if (!ctrl.signal.aborted) ctrl.abort(); } catch { /* */ }
   }
@@ -1777,23 +1862,110 @@ export function buildSkillSlashCommands(skillManager) {
   return { commands, descriptions };
 }
 
-function broadcastSkillSlashCommands(sessionLike) {
-  const { commands, descriptions } = buildSkillSlashCommands(sessionLike?.skillManager);
-  const slashCommands = [...new Set([...(ctx.slashCommands || []), ...commands])];
-  const slashCommandDescriptions = {
-    ...(ctx.slashCommandDescriptions || {}),
-    ...descriptions,
-  };
+export function buildMergedSkillSlashCommands(skillManagers = []) {
+  const commands = [];
+  const descriptions = {};
+  for (const manager of skillManagers) {
+    const built = buildSkillSlashCommands(manager);
+    for (const cmd of built.commands) commands.push(cmd);
+    Object.assign(descriptions, built.descriptions);
+  }
+  return { commands: [...new Set(commands)].sort((a, b) => a.localeCompare(b)), descriptions };
+}
+
+function broadcastSkillSlashCommands(sessionLike, extraSkillManagers = []) {
+  const managers = [sessionLike?.skillManager, ...extraSkillManagers].filter(Boolean);
+  const { commands, descriptions } = buildMergedSkillSlashCommands(managers);
+  const nonSkillCommands = (ctx.slashCommands || [])
+    .filter(cmd => !(typeof cmd === 'string' && cmd.startsWith(SKILL_COMMAND_PREFIX)));
+  const slashCommands = [...new Set([...nonSkillCommands, ...commands])];
+  const slashCommandDescriptions = Object.fromEntries(
+    Object.entries(ctx.slashCommandDescriptions || {})
+      .filter(([cmd]) => !(typeof cmd === 'string' && cmd.startsWith(SKILL_COMMAND_PREFIX)))
+  );
+  Object.assign(slashCommandDescriptions, descriptions);
   ctx.slashCommands = slashCommands;
   ctx.slashCommandDescriptions = slashCommandDescriptions;
   sendToServer({
     type: 'slash_commands_update',
-    conversationId: '__preload__',
+    agentId: ctx.AGENT_ID || ctx.agentId || null,
+    conversationId: yeaftConversationId || '__preload__',
     slashCommands,
     slashCommandDescriptions,
   });
 }
 
+async function loadProjectRuntime(workDir) {
+  if (!session) return null;
+  const normalizedWorkDir = normalizeSessionWorkDir(workDir);
+  if (!normalizedWorkDir) {
+    activateBaseRuntime();
+    return null;
+  }
+  const key = projectRuntimeKey(normalizedWorkDir);
+  const cached = projectRuntimes.get(key);
+  if (cached) {
+    activateProjectRuntime(cached);
+    return cached;
+  }
+
+  const yeaftDir = ctx.CONFIG?.yeaftDir || session.yeaftDir || DEFAULT_YEAFT_DIR;
+  const skillRoots = normalizedWorkDir && normalizedWorkDir !== process.cwd()
+    ? `${process.cwd()}${delimiter}${normalizedWorkDir}`
+    : normalizedWorkDir;
+  const skillManager = createSkillManager(yeaftDir, skillRoots);
+  const mcpConfig = loadMCPConfig(yeaftDir, undefined, normalizedWorkDir);
+  const mcpManager = new MCPManager();
+  let mcpStatus = { connected: [], failed: [] };
+  if (mcpConfig.servers.length > 0) {
+    mcpStatus = await mcpManager.connectAll(mcpConfig.servers);
+  }
+  const runtime = {
+    workDir: normalizedWorkDir,
+    skillManager,
+    mcpManager,
+    mcpStatus,
+    mcpConfig,
+    status: {
+      skills: skillManager.size,
+      mcpServers: mcpStatus.connected,
+      mcpFailed: mcpStatus.failed,
+      mcpSkipped: mcpConfig.skipped || [],
+      tools: session.toolRegistry?.size || 0,
+    },
+  };
+  projectRuntimes.set(key, runtime);
+  activateProjectRuntime(runtime);
+  return runtime;
+}
+
+async function ensureProjectRuntimeForSessionMeta(sessionMeta) {
+  const workDir = normalizeSessionWorkDir(sessionMeta?.workDir);
+  if (!workDir) {
+    activateBaseRuntime();
+    return null;
+  }
+  try {
+    return await loadProjectRuntime(workDir);
+  } catch (err) {
+    console.warn('[Yeaft] project runtime load failed for %s: %s', workDir, err?.message || err);
+    activateBaseRuntime();
+    return null;
+  }
+}
+
+function mergedStatusForProjectRuntime(runtime) {
+  if (!session?.status || !runtime?.status) return session?.status || { skills: 0, mcpServers: [], tools: 0 };
+  return {
+    ...session.status,
+    skills: Math.max(Number(session.status.skills) || 0, Number(runtime.status.skills) || 0),
+    mcpServers: [...new Set([...(session.status.mcpServers || []), ...(runtime.status.mcpServers || [])])],
+    mcpFailed: [...(session.status.mcpFailed || []), ...(runtime.status.mcpFailed || [])],
+    mcpSkipped: [...(session.status.mcpSkipped || []), ...(runtime.status.mcpSkipped || [])],
+    tools: Math.max(Number(session.status.tools) || 0, Number(runtime.status.tools) || 0),
+  };
+}
+
 /** Send a Yeaft Session metadata event over the legacy-compatible envelope. */
 function sendSessionEvent(event, { sessionId, chatId, vpId, turnId, threadId, perfTraceId } = {}) {
   sendToServer({
@@ -3121,15 +3293,13 @@ export async function handleYeaftSessionSend(msg) {
     return;
   }
 
-  const ensureSessionStart = perfNowMs();
-  await ensureSessionLoaded();
-  traceDuration('session_send.ensure_session_loaded', ensureSessionStart);
-
-  // Open the session. The default `grp_default` no longer self-seeds
-  // here — session creation happens up-front via `handleYeaftCreateSession`,
-  // so a missing dir surfaces a clear error rather than masking it.
+  // Open the session metadata first so a workDir-backed Session can load its
+  // project-tier skills and MCP before the first engine turn. The runtime boot
+  // below uses the same workDir; if metadata is missing we still boot the agent
+  // runtime for a useful error response, then fail on the session open check.
   let sessionHandle = null;
   let sessionRoot = null;
+  let sessionMetaForRuntime = null;
   const openSessionStart = perfNowMs();
   try {
     const groupYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
@@ -3137,6 +3307,7 @@ export async function handleYeaftSessionSend(msg) {
     const dir = join(sessionRoot, sessionId);
     if (existsSync(dir) && loadSessionMeta(dir)) {
       sessionHandle = openSession(sessionRoot, sessionId);
+      sessionMetaForRuntime = sessionHandle.getMeta();
     } else {
       // fix-yeaft-session-server-persistence: the `grp_default` on-the-
       // fly seed used to manufacture a missing session here. That
@@ -3149,9 +3320,14 @@ export async function handleYeaftSessionSend(msg) {
   } catch (err) {
     console.warn('[Yeaft] yeaft_session_chat: session open failed', err?.message || err);
   }
-
   traceDuration('session_send.open_session', openSessionStart, { ok: !!sessionHandle });
 
+  const ensureSessionStart = perfNowMs();
+  await ensureSessionLoaded({ sessionMeta: sessionMetaForRuntime, perfTraceId });
+  await ensureProjectRuntimeForSessionMeta(sessionMetaForRuntime);
+  traceDuration('session_send.ensure_session_loaded', ensureSessionStart);
+
+
   if (!sessionHandle) {
     sendSessionOutputFrame({
       type: 'assistant',
@@ -3498,78 +3674,125 @@ export function buildVpQueryOpts({ vpId, sessionCoordinator, sessionId, envelope
 }
 
 /**
- * Lazy session boot. Idempotent: subsequent calls are no-ops once `session`
- * is set. Emits `session_ready` on first init so the frontend can finalize
- * its handshake.
+ * Lazy session boot. Idempotent: concurrent callers share one in-flight promise.
+ * Emits `session_ready` on first init so the frontend can finalize its handshake.
+ *
+ * @param {{ workDir?: string, sessionId?: string|null, sessionMeta?: object, perfTraceId?: string|null, messageType?: string }} [opts]
+ * @returns {Promise<import('./session.js').Session>}
  */
-async function ensureSessionLoaded() {
-  if (session) return;
+async function ensureSessionLoaded(opts = {}) {
+  if (session) return session;
+  if (sessionLoadPromise) return sessionLoadPromise;
 
-  const yeaftDir = ctx.CONFIG?.yeaftDir;
-  session = await loadSession({
-    ...(yeaftDir && { dir: yeaftDir }),
-    skipMCP: false,
-    skipSkills: false,
-    serverMode: true,
-  });
+  sessionLoadPromise = (async () => {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const normalizedWorkDir = normalizeSessionWorkDir(opts?.workDir || opts?.sessionMeta?.workDir);
+    session = await loadSession({
+      ...(yeaftDir && { dir: yeaftDir }),
+      ...(normalizedWorkDir && { workDir: normalizedWorkDir }),
+      skipMCP: false,
+      skipSkills: false,
+      serverMode: true,
+    });
 
-  installYeaftRuntimeBridge(session);
+    installYeaftRuntimeBridge(session);
 
-  try {
-    if (session.engine && typeof session.engine.setSubAgentEventSink === 'function') {
-      session.engine.setSubAgentEventSink((agentId, evt) => {
-        try {
-          sendSessionEvent({ type: 'sub_agent_event', agentId, payload: evt });
-        } catch { /* ignore */ }
-      });
+    try {
+      if (session.engine && typeof session.engine.setSubAgentEventSink === 'function') {
+        session.engine.setSubAgentEventSink((agentId, evt) => {
+          try {
+            sendSessionEvent({ type: 'sub_agent_event', agentId, payload: evt });
+          } catch { /* ignore */ }
+        });
+      }
+    } catch (err) {
+      console.warn('[Yeaft] setSubAgentEventSink wiring failed:', err?.message || err);
     }
-  } catch (err) {
-    console.warn('[Yeaft] setSubAgentEventSink wiring failed:', err?.message || err);
-  }
 
-  // Bug 8: clean up legacy `.archived-*` group dirs at boot.
-  try {
-    if (yeaftDir) {
-      const removed = purgeArchivedSessions(yeaftDir);
-      if (removed && removed.length > 0) {
-        console.log(`[Yeaft] purged ${removed.length} legacy .archived group dir(s)`);
+    // Bug 8: clean up legacy `.archived-*` group dirs at boot.
+    try {
+      if (yeaftDir) {
+        const removed = purgeArchivedSessions(yeaftDir);
+        if (removed && removed.length > 0) {
+          console.log(`[Yeaft] purged ${removed.length} legacy .archived group dir(s)`);
+        }
       }
+    } catch (err) {
+      console.warn('[Yeaft] purgeArchivedSessions failed:', err?.message || err);
     }
-  } catch (err) {
-    console.warn('[Yeaft] purgeArchivedSessions failed:', err?.message || err);
-  }
 
-  yeaftConversationId = `yeaft-${Date.now()}`;
-  hydrateYeaftStatusFromSession(session, { reason: 'session_ready', emitEvent: true });
-  broadcastSkillSlashCommands(session);
+    ensureYeaftConversationId();
+    const bootProjectRuntime = normalizedWorkDir ? await ensureProjectRuntimeForSessionMeta({ workDir: normalizedWorkDir }) : null;
+    const bootStatus = mergedStatusForProjectRuntime(bootProjectRuntime);
+    hydrateYeaftStatusFromSession({ ...session, status: bootStatus }, { reason: 'session_ready', emitEvent: true });
+    broadcastSkillSlashCommands(session, bootProjectRuntime ? [bootProjectRuntime.skillManager] : []);
 
-  // Per-group history is hydrated lazily on first `getOrCreateSessionHistory`
-  // — there's no global "all conversations" tape any more.
+    // Per-group history is hydrated lazily on first `getOrCreateSessionHistory`
+    // — there's no global "all conversations" tape any more.
+
+    sendSessionEvent({
+      type: 'session_ready',
+      conversationId: yeaftConversationId,
+      model: session.config.primaryModel || session.config.model,
+      modelEffort: session.config.modelEffort || null,
+      availableModels: session.config.availableModels || [],
+      skills: bootStatus.skills,
+      mcpServers: bootStatus.mcpServers,
+      tools: bootStatus.tools,
+      yeaftDir: ctx.CONFIG?.yeaftDir || null,
+      tasks: session.taskManager ? session.taskManager.listActiveTasks() : [],
+    }, opts?.perfTraceId ? { sessionId: opts?.sessionMeta?.id || opts?.sessionId || null, perfTraceId: opts.perfTraceId } : undefined);
+    sendSessionSnapshotBroadcast();
+    // vp-status: rebuild frontend status table from authoritative agent
+    // memory. Sent unconditionally so reconnect/refresh paths get the same
+    // bootstrap as first-load (the broker dedup logic makes a redundant
+    // snapshot harmless).
+    try {
+      getVpStatusBroker().broadcastSnapshot();
+    } catch (err) {
+      console.warn('[Yeaft] vp-status snapshot broadcast failed:', err?.message || err);
+    }
+
+    return session;
+  })();
 
-  sendSessionEvent({
-    type: 'session_ready',
-    conversationId: yeaftConversationId,
-    model: session.config.primaryModel || session.config.model,
-    modelEffort: session.config.modelEffort || null,
-    availableModels: session.config.availableModels || [],
-    skills: session.status.skills,
-    mcpServers: session.status.mcpServers,
-    tools: session.status.tools,
-    yeaftDir: ctx.CONFIG?.yeaftDir || null,
-    tasks: session.taskManager ? session.taskManager.listActiveTasks() : [],
-  });
-  sendSessionSnapshotBroadcast();
-  // vp-status: rebuild frontend status table from authoritative agent
-  // memory. Sent unconditionally so reconnect/refresh paths get the same
-  // bootstrap as first-load (the broker dedup logic makes a redundant
-  // snapshot harmless).
   try {
-    getVpStatusBroker().broadcastSnapshot();
+    return await sessionLoadPromise;
   } catch (err) {
-    console.warn('[Yeaft] vp-status snapshot broadcast failed:', err?.message || err);
+    session = null;
+    throw err;
+  } finally {
+    sessionLoadPromise = null;
   }
 }
 
+function startSessionLoadInBackground({ sessionId = null, sessionMeta = null, perfTraceId = null, traceDuration = null, tracePerf = null, phase = 'history.load_session_runtime' } = {}) {
+  if (session) return null;
+  const start = perfNowMs();
+  const promise = ensureSessionLoaded({ sessionId, sessionMeta, perfTraceId })
+    .then(async (loaded) => {
+      if (typeof traceDuration === 'function') traceDuration(phase, start, { detail: { background: true } });
+      if (sessionId && loaded?.conversationStore) {
+        const hydrateStart = perfNowMs();
+        setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
+        if (typeof traceDuration === 'function') traceDuration('history.hydrate_group_history', hydrateStart, { detail: { background: true } });
+        sendDreamSnapshotForSession(sessionId, { trigger: 'load_history' }).catch(() => null);
+      }
+      return loaded;
+    })
+    .catch((err) => {
+      if (typeof tracePerf === 'function') {
+        tracePerf('history.load_session_runtime_error', {
+          ok: false,
+          detail: { background: true, errorName: err?.name || null, errorMessage: err?.message || String(err) },
+        });
+      }
+      console.warn('[Yeaft] background session load failed:', err?.message || err);
+      return null;
+    });
+  return promise;
+}
+
 /**
  * Wrap {@link runVpTurn} with a hard escalation deadline.
  *
@@ -3795,8 +4018,20 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
         envelope: inboundEnvelope,
         threadId,
       });
+      const projectRuntime = await ensureProjectRuntimeForSessionMeta(sessionCoordinator?.group?.getMeta?.());
 
       vpEngine = getOrCreateVpEngine(sessionId, vpId, threadId);
+      if (projectRuntime) {
+        vpEngine.setRuntimeManagers?.({
+          skillManager: projectRuntime.skillManager,
+          mcpManager: projectRuntime.mcpManager,
+        });
+      } else {
+        vpEngine.setRuntimeManagers?.({
+          skillManager: session?.skillManager || null,
+          mcpManager: session?.mcpManager || null,
+        });
+      }
       if (thread) thread.engine = vpEngine;
 
       const inboundInjectedBy = inboundEnvelope?.msg?.meta?.injectedBy;
@@ -5233,26 +5468,19 @@ export async function handleYeaftLoadHistory(msg) {
     }
     historyAlreadyReplayed = true;
 
-    const bootStart = perfNowMs();
-    session = await loadSession({
-      dir: yeaftDir,
-      skipMCP: false,
-      skipSkills: false,
-      serverMode: true,
-    });
-    traceDuration('history.load_session_runtime', bootStart);
-    installYeaftRuntimeBridge(session);
-
-    // Per-group history hydrates lazily via getOrCreateSessionHistory.
-    // When the load-history call carries a sessionId, force-refresh THAT
-    // group's tape so the next user message sees on-disk state. When
-    // it doesn't (legacy callers), do nothing — the per-group lazy
-    // hydration handles it.
+    let sessionMetaForRuntime = null;
     if (sessionId) {
-      const hydrateStart = perfNowMs();
-      setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
-      traceDuration('history.hydrate_group_history', hydrateStart);
+      try {
+        const groupYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
+        const metaDir = join(sessionsRoot(groupYeaftDir), sessionId);
+        sessionMetaForRuntime = loadSessionMeta(metaDir);
+      } catch { /* best-effort metadata hint */ }
     }
+    // Full runtime boot can be expensive (memory FTS sync, skills, MCP, dream
+    // boot checks). It is not needed to render persisted history, so keep this
+    // request short and let message-send await the same single-flight boot when
+    // the user actually submits a turn.
+    startSessionLoadInBackground({ sessionId, sessionMeta: sessionMetaForRuntime, perfTraceId, traceDuration, tracePerf });
   } else {
     const replayStart = perfNowMs();
     replayHistoryFromStore();
@@ -5260,10 +5488,12 @@ export async function handleYeaftLoadHistory(msg) {
     historyAlreadyReplayed = true;
   }
 
-  if (sessionId) {
+  if (session && sessionId) {
     // Re-entering an existing session with a (possibly new) group filter:
     // re-seed THIS group's history from disk so it doesn't carry stale
-    // in-memory state into the next turn's context.
+    // in-memory state into the next turn's context. Do not mark it hydrated
+    // before the runtime exists; that would cache an empty tape and starve the
+    // next user turn of persisted context.
     const hydrateStart = perfNowMs();
     setGroupHistory(sessionId, hydrateGroupHistory(sessionId));
     traceDuration('history.hydrate_group_history_final', hydrateStart);
@@ -5273,7 +5503,7 @@ export async function handleYeaftLoadHistory(msg) {
   // never make the history response wait for bulky metadata snapshots. The
   // first visible chunk has already been sent above; defer metadata to the next
   // tick so the browser can paint messages before VP/session/dream snapshots.
-  scheduleYeaftLoadHistoryMetadataReplay(sessionId);
+  if (session) scheduleYeaftLoadHistoryMetadataReplay(sessionId);
 
   if (historyAlreadyReplayed) {
     traceDuration('history.handler_total', perfStart, { ok: true });
@@ -5352,6 +5582,7 @@ export async function handleYeaftLoadMoreHistory(msg) {
  * session, then re-initialises so the frontend gets fresh config.
  */
 export async function resetYeaftSession() {
+  await shutdownProjectRuntimes();
   if (currentAbortCtrl && !currentAbortCtrl.signal.aborted) {
     try { currentAbortCtrl.abort(); } catch { /* ignore */ }
   }
@@ -5415,6 +5646,7 @@ export async function resetYeaftSession() {
 
     yeaftConversationId = `yeaft-${Date.now()}`;
     hydrateYeaftStatusFromSession(session, { reason: 'reset', emitEvent: true });
+    broadcastSkillSlashCommands(session);
 
     // Per-group history hydrates lazily via getOrCreateSessionHistory on
     // first read. Nothing to seed here.
@@ -5495,16 +5727,7 @@ function mcpRuntimeSnapshot() {
  * pick up the change.
  */
 function hotSwapMcpTools() {
-  if (!session?.toolRegistry || typeof session.toolRegistry.replaceMcpTools !== 'function') {
-    return { removed: 0, added: 0, skipped: true };
-  }
-  try {
-    const result = session.toolRegistry.replaceMcpTools(session.mcpManager, buildMcpFlattenedTools);
-    return { ...result, skipped: false };
-  } catch (err) {
-    console.warn('[Yeaft] hot-swap MCP tools failed:', err?.message || err);
-    return { removed: 0, added: 0, skipped: true, error: err?.message || String(err) };
-  }
+  return replaceSessionMcpTools(session?.mcpManager);
 }
 
 /**
@@ -5563,7 +5786,7 @@ export async function handleYeaftMcpAdd(msg = {}) {
     }
   }
 
-  const swap = hotSwapMcpTools();
+  const swap = replaceSessionMcpTools(session?.mcpManager);
 
   sendToServer({
     type: 'yeaft_mcp_add_result',
@@ -5600,7 +5823,7 @@ export async function handleYeaftMcpRemove(msg = {}) {
     }
   }
 
-  const swap = hotSwapMcpTools();
+  const swap = replaceSessionMcpTools(session?.mcpManager);
 
   sendToServer({
     type: 'yeaft_mcp_remove_result',
@@ -5658,7 +5881,7 @@ export async function handleYeaftMcpReload(msg = {}) {
     console.warn('[Yeaft] MCP reload failed:', err?.message || err);
   }
 
-  const swap = hotSwapMcpTools();
+  const swap = replaceSessionMcpTools(session?.mcpManager);
 
   sendToServer({
     type: 'yeaft_mcp_reload_result',
@@ -5678,6 +5901,7 @@ export const __testHooks = {
   buildPendingRescueEnvelope,
   setSessionForTest(nextSession) {
     session = nextSession || null;
+    sessionLoadPromise = null;
   },
   resetAbortState() {
     turnAbortCtrls.clear();
@@ -5692,6 +5916,28 @@ export const __testHooks = {
     return getVpStatusBroker().transition(status);
   },
   decorateSessionsWithRuntimeState,
+  async loadProjectRuntime(workDir) {
+    return loadProjectRuntime(workDir);
+  },
+  seedProjectRuntime(workDir, runtime) {
+    const normalizedWorkDir = normalizeSessionWorkDir(workDir);
+    const seeded = {
+      workDir: normalizedWorkDir,
+      skillManager: runtime?.skillManager || { list: () => [] },
+      mcpManager: runtime?.mcpManager || { listTools: () => [], disconnectAll: async () => {} },
+      mcpStatus: runtime?.mcpStatus || { connected: [], failed: [] },
+      mcpConfig: runtime?.mcpConfig || { servers: [], skipped: [] },
+      status: runtime?.status || { skills: 0, mcpServers: [], mcpFailed: [], mcpSkipped: [], tools: 0 },
+    };
+    projectRuntimes.set(projectRuntimeKey(normalizedWorkDir), seeded);
+    return seeded;
+  },
+  async shutdownProjectRuntimes() {
+    return shutdownProjectRuntimes();
+  },
+  projectRuntimeCount() {
+    return projectRuntimes.size;
+  },
   seedQueuedVpTurn({ sessionId = 'session-test', vpId = 'vp-test', threadId = 'main', turnId = 'turn-test' } = {}) {
     const key = threadKey(sessionId, vpId, threadId);
     const inbox = vpInboxes.get(key) || [];