release: v2.7.246 lazy MCP deferred startup semantics

Author: robertpelloni

CHANGELOG.md

@@ -4,6 +4,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.7.246] — 2026-03-16
+
+- changed(core/mcp): `packages/core/src/MCPServer.ts` now honors lifecycle lazy-session mode during startup and skips eager `warmAdvertisedServers()` preconnects when lazy mode is enabled, preventing downstream MCP binaries from auto-spawning at boot.
+- changed(core/startup-status): `packages/core/src/routers/startupStatus.ts` + `packages/core/src/routers/systemProcedures.ts` now treat resident always-on warmup as optional in lazy mode, so startup readiness reflects deferred-on-demand MCP behavior instead of requiring preconnected always-on runtimes.
+- test(core/startup-status): `packages/core/src/routers/startupStatus.test.ts` adds regression coverage for lazy-mode readiness semantics.
+- test(validation): revalidated targeted startup-status suite and strict TypeScript gates (`vitest startupStatus`, `CORE_TSC_OK`, `WEB_TSC_OK`).
+
 ## [2.7.245] — 2026-03-16
 
 - changed(web/billing): `apps/web/src/app/dashboard/billing/page.tsx` adds fallback-history triage controls for **cause** and **task** filtering, including dynamic facet counts and scoped-result rendering.

VERSION

@@ -1 +1 @@
-2.7.245
+2.7.246

VERSION.md

@@ -1 +1 @@
-# Borg Project Version: 2.7.245
+# Borg Project Version: 2.7.246

packages/core/src/MCPServer.ts

@@ -159,6 +159,7 @@ import { createCouncilTools } from "./mcp/tools/council_tools.js";
 import { NativeSessionMetaTools } from "./mcp/NativeSessionMetaTools.js";
 import { jsonConfigProvider } from './services/config/JsonConfigProvider.js';
 import { configImportService } from './services/config-import.service.js';
+import { mcpServerPool } from './services/mcp-server-pool.service.js';
 import {
     applyBridgeClientHello,
     buildBridgeManifest,
@@ -3138,7 +3139,12 @@ export class MCPServer {
                     })),
                     source: inventory.source,
                 });
-                this.mcpAggregator.warmAdvertisedServers();
+                const { lazySessionMode } = mcpServerPool.getLifecycleModes();
+                if (lazySessionMode) {
+                    mcpServerDebugLog('[MCPServer] Lazy MCP session mode enabled; skipping eager advertised-server warmup.');
+                } else {
+                    this.mcpAggregator.warmAdvertisedServers();
+                }
             })
             .catch(e => console.error("[MCPServer] Aggregator Init Failed:", e));
 

packages/core/src/routers/startupStatus.test.ts

@@ -767,4 +767,80 @@ describe('buildStartupStatusSnapshot', () => {
             ready: false,
         }));
     });
+
+    it('treats resident always-on warmup as optional when lazy MCP sessions are enabled', async () => {
+        const snapshot = await buildStartupStatusSnapshot({
+            mcpServer: {
+                memoryManager: {},
+                isMemoryInitialized: true,
+                getBridgeStatus: () => ({
+                    ready: true,
+                    clientCount: 0,
+                    clients: [],
+                    supportedCapabilities: [],
+                    supportedHookPhases: [],
+                }),
+            },
+            aggregator: {
+                getInitializationStatus: () => ({
+                    inProgress: false,
+                    initialized: true,
+                    connectedClientCount: 0,
+                    configuredServerCount: 4,
+                }),
+            },
+            agentMemory: {},
+            browserService: {},
+            browserStatus: { active: false, pageCount: 0, pageIds: [] },
+            sessionSupervisor: {
+                getRestoreStatus: () => ({
+                    lastRestoreAt: 1_700_000_000_000,
+                    restoredSessionCount: 0,
+                    autoResumeCount: 0,
+                }),
+            },
+            sessionCount: 0,
+            mcpConfigService: {
+                getStatus: () => ({
+                    inProgress: false,
+                    lastCompletedAt: 1_700_000_000_000,
+                    lastSuccessAt: 1_700_000_000_000,
+                    lastServerCount: 4,
+                    lastToolCount: 16,
+                }),
+            },
+            liveServerCount: 0,
+            residentLiveServerCount: 0,
+            warmingServerCount: 0,
+            failedWarmupServerCount: 0,
+            lazySessionMode: true,
+            persistedServerCount: 4,
+            persistedToolCount: 16,
+            persistedAlwaysOnServerCount: 2,
+            persistedAlwaysOnToolCount: 6,
+            executionEnvironment: {
+                ready: true,
+                preferredShellId: 'pwsh',
+                preferredShellLabel: 'PowerShell 7',
+                shellCount: 1,
+                verifiedShellCount: 1,
+                toolCount: 2,
+                verifiedToolCount: 2,
+                harnessCount: 1,
+                verifiedHarnessCount: 1,
+                supportsPowerShell: true,
+                supportsPosixShell: false,
+                notes: ['Prefer PowerShell 7.'],
+            },
+        });
+
+        expect(snapshot.ready).toBe(true);
+        expect(snapshot.checks.mcpAggregator.liveReady).toBe(true);
+        expect(snapshot.checks.mcpAggregator.residentReady).toBe(true);
+        expect(snapshot.blockingReasons).not.toEqual(
+            expect.arrayContaining([
+                expect.objectContaining({ code: 'mcp_resident_runtime_not_ready' }),
+            ]),
+        );
+    });
 });

packages/core/src/routers/startupStatus.ts

@@ -79,6 +79,7 @@ type StartupStatusInput = {
     residentLiveServerCount?: number;
     warmingServerCount?: number;
     failedWarmupServerCount?: number;
+    lazySessionMode?: boolean;
     persistedServerCount: number;
     persistedToolCount: number;
     persistedAlwaysOnServerCount: number;
@@ -130,6 +131,7 @@ export async function buildStartupStatusSnapshot(input: StartupStatusInput) {
         residentLiveServerCount = 0,
         warmingServerCount = 0,
         failedWarmupServerCount = 0,
+        lazySessionMode = false,
         persistedServerCount,
         persistedToolCount,
         persistedAlwaysOnServerCount,
@@ -190,12 +192,14 @@ export async function buildStartupStatusSnapshot(input: StartupStatusInput) {
     );
     const aggregatorReady = Boolean(aggregatorStatus?.initialized);
     const liveReady = mcpReady && aggregatorReady;
-    const residentReady = liveReady && residentLiveServerCount >= advertisedAlwaysOnServerCount;
+    const residentReady = lazySessionMode
+        ? liveReady
+        : liveReady && residentLiveServerCount >= advertisedAlwaysOnServerCount;
     const mcpWarmupInProgress = Boolean(
         aggregatorStatus?.inProgress
         || configSyncStatus?.inProgress
         || warmingServerCount > 0
-        || (inventoryReady && configuredServerCount > 0 && liveServerCount < configuredServerCount),
+        || (!lazySessionMode && inventoryReady && configuredServerCount > 0 && liveServerCount < configuredServerCount),
     );
     const executionReady = Boolean(executionEnvironment?.ready);
     const claudeMemEnabled = Boolean(claudeMem?.enabled);
@@ -221,7 +225,7 @@ export async function buildStartupStatusSnapshot(input: StartupStatusInput) {
         });
     }
 
-    if (!residentReady) {
+    if (!residentReady && !lazySessionMode) {
         const residentTarget = persistedAlwaysOnServerCount;
         const residentConnected = residentLiveServerCount;
         blockingReasons.push({

packages/core/src/routers/systemProcedures.ts

@@ -18,6 +18,7 @@ import { detectLocalExecutionEnvironment } from '../services/execution-environme
 import { getCachedToolInventory } from '../mcp/cachedToolInventory.js';
 import { readClaudeMemStoreStatus } from './memoryRouter.claude-mem.js';
 import { summarizeCachedInventory } from './startupInventorySummary.js';
+import { mcpServerPool } from '../services/mcp-server-pool.service.js';
 import type { MemoryPipelineSummary } from '../services/memory/MemoryManager.js';
 
 const EXECUTION_ENV_CACHE_TTL_MS = Number(process.env.BORG_EXECUTION_ENV_CACHE_TTL_MS ?? 30_000);
@@ -98,6 +99,7 @@ export const systemProcedures = {
         ).length;
         const warmingServerCount = runtimeServers.filter((server) => server.warmupStatus === 'scheduled' || server.warmupStatus === 'warming').length;
         const failedWarmupServerCount = runtimeServers.filter((server) => server.warmupStatus === 'failed').length;
+        const lifecycleModes = mcpServerPool.getLifecycleModes();
 
         const cachedInventorySummary = summarizeCachedInventory(cachedInventory);
 
@@ -132,6 +134,7 @@ export const systemProcedures = {
             residentLiveServerCount,
             warmingServerCount,
             failedWarmupServerCount,
+            lazySessionMode: lifecycleModes.lazySessionMode,
             persistedServerCount,
             persistedToolCount,
             persistedAlwaysOnServerCount,