@moretea-labs/forge 1.6.0 → 1.7.0

package/src/cli/mcp/tool-capability-cache.ts

@@ -13,7 +13,7 @@ export interface ToolDefinitionCacheOptions {
   maxEntriesPerSession?: number;
 }
 
-const CORE_TOOL_NAMES = new Set(['rh_context', 'rh_access', 'work_submit', 'work_get', 'work_list', 'controller_ready']);
+const CORE_TOOL_NAMES = new Set(['rh_context', 'rh_access', 'rh_work', 'rh_status', 'rh_inbox']);
 
 export function controllerCapabilityGroupForTool(name: string): ControllerCapabilityGroup {
   if (CORE_TOOL_NAMES.has(name)) return 'core';

package/src/cli/mcp/toolset-selection.ts

@@ -8,7 +8,7 @@ export interface ControllerToolsetSelection {
 }
 
 export function normalizeConfiguredMcpToolset(value: unknown): McpToolset | undefined {
-  return value === 'core' || value === 'advanced' || value === 'full' ? value : undefined;
+  return value === 'facade' || value === 'core' || value === 'advanced' || value === 'full' ? value : undefined;
 }
 
 /** Persisted Core and Advanced are compatibility-equivalent stable profiles. */

package/src/cli/mcp/toolset.ts

@@ -17,7 +17,7 @@ import type { McpToolset } from './types';
 import { forgeToolSurfaceFingerprint } from '../controller/runtime-config';
 
 export type ToolExposureClass = 'facade' | 'advanced' | 'internal' | 'compatibility';
-export type ControllerToolProfile = 'core' | 'advanced' | 'full';
+export type ControllerToolProfile = 'facade' | 'core' | 'advanced' | 'full';
 
 export interface ControllerToolInventoryEntry {
   name: string;
@@ -48,6 +48,22 @@ export interface ControllerExposureSnapshot {
   ready: boolean;
 }
 
+/**
+ * Cached schema/readiness projection for hot paths that do not need access
+ * policy or a per-tool inventory. Status uses this rather than rebuilding a
+ * complete controller exposure response on every read.
+ */
+export interface ControllerToolSurfaceStatus {
+  expectedToolNames: string[];
+  actualToolNames: string[];
+  missingToolNames: string[];
+  unexpectedToolNames: string[];
+  duplicateToolNames: string[];
+  fingerprint: string;
+  schemaStableAcrossAccessModes: true;
+  ready: boolean;
+}
+
 /**
  * Core and Advanced expose the same bounded default ChatGPT surface
  * (DEFAULT_CONTROLLER_TOOL_NAMES). Full remains the exhaustive compatibility
@@ -84,7 +100,7 @@ function pruneStaticExposureCache(): void {
 }
 
 export function normalizeMcpToolset(value: unknown): McpToolset {
-  if (value === 'full' || value === 'advanced' || value === 'core') return value;
+  if (value === 'full' || value === 'advanced' || value === 'core' || value === 'facade') return value;
   return 'advanced';
 }
 
@@ -97,6 +113,7 @@ export function controllerToolNamesForToolset(
   _ctx?: MultiRepositoryMcpToolContext,
 ): readonly string[] | null {
   if (toolset === 'full') return null;
+  if (toolset === 'facade') return PREFERRED_FACADE_TOOL_NAMES;
   return DEFAULT_CONTROLLER_TOOL_NAMES;
 }
 
@@ -158,13 +175,19 @@ function staticExposureCacheKey(ctx: MultiRepositoryMcpToolContext): string {
 function buildStaticControllerExposureSnapshot(
   ctx: MultiRepositoryMcpToolContext,
 ): StaticControllerExposureSnapshot {
-  const rawDefinitions = runtimeToolDefinitions.concat(
+  const currentDefinitions = runtimeToolDefinitions.concat(
     executionToolDefinitions,
     processToolDefinitions,
     accessToolDefinitions,
     repositoryToolDefinitions,
-    buildMultiRepositoryToolDefinitions(ctx),
   );
+  const rawDefinitions = ctx.toolset === 'full'
+    ? currentDefinitions.concat(
+      buildMultiRepositoryToolDefinitions(ctx).filter(
+        (legacy) => !currentDefinitions.some((current) => current.name === legacy.name),
+      ),
+    )
+    : currentDefinitions;
   const unique = uniqueDefinitions(rawDefinitions);
   const allowed = controllerToolNamesForToolset(ctx.toolset, ctx);
   const expectedToolNames = allowed === null
@@ -226,7 +249,7 @@ function capabilityForToolName(name: string): string {
 }
 
 function profileForToolset(toolset: McpToolset): ControllerToolProfile {
-  return toolset === 'full' ? 'full' : toolset === 'core' ? 'core' : 'advanced';
+  return toolset === 'full' ? 'full' : toolset === 'facade' ? 'facade' : toolset === 'core' ? 'core' : 'advanced';
 }
 
 export function controllerToolInventory(
@@ -263,6 +286,20 @@ export function controllerExposureSnapshot(ctx: MultiRepositoryMcpToolContext):
   };
 }
 
+export function controllerToolSurfaceStatus(ctx: MultiRepositoryMcpToolContext): ControllerToolSurfaceStatus {
+  const snapshot = staticControllerExposureSnapshot(ctx);
+  return {
+    expectedToolNames: snapshot.expectedToolNames,
+    actualToolNames: snapshot.actualToolNames,
+    missingToolNames: snapshot.missingToolNames,
+    unexpectedToolNames: snapshot.unexpectedToolNames,
+    duplicateToolNames: snapshot.duplicateToolNames,
+    fingerprint: snapshot.fingerprint,
+    schemaStableAcrossAccessModes: snapshot.schemaStableAcrossAccessModes,
+    ready: snapshot.ready,
+  };
+}
+
 export function controllerExposedToolNames(ctx: MultiRepositoryMcpToolContext): string[] {
   return controllerExposureSnapshot(ctx).actualToolNames;
 }

package/src/cli/mcp/transports/http.ts

@@ -11,9 +11,11 @@ import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/share
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
   buildMultiRepositoryToolDefinitions,
+  createCanonicalRuntimeProxy,
   createMcpToolContext,
   createForgeMcpServerFromContext,
   readCanonicalRuntimeToolSchema,
+  type CanonicalRuntimeProxy,
   type CanonicalRuntimeToolSchema,
   type McpServerOptions,
 } from '../server';
@@ -36,6 +38,7 @@ import {
   controllerExposureSnapshot,
 } from '../toolset';
 import { readForgeRuntimeStatus } from '../../../runtime/control-plane/runtime-status-client';
+import { invalidateExecutionSession } from '../../../runtime/control-plane/execution/session-store';
 import { runtimeIdentitySnapshot } from '../../../runtime/gateway/mcp/runtime-tools';
 import { projectionBlocksReadiness, readRepositoryProjectionSnapshot } from '../../../runtime/projections/materialized-view';
 import { readRuntimeGeneration } from '../../../runtime/control-plane/runtime-generation';
@@ -194,6 +197,14 @@ export async function resolveMcpSessionCurrentFingerprint(
   return await loadRuntimeFingerprint?.();
 }
 
+export function isMcpToolsListRequest(body: unknown): boolean {
+  const messages = Array.isArray(body) ? body : [body];
+  return messages.length > 0 && messages.every((message) => {
+    if (!message || typeof message !== 'object') return false;
+    return (message as { method?: unknown }).method === 'tools/list';
+  });
+}
+
 function toolCallOutsideSessionSchema(body: unknown, toolNames: readonly string[] | undefined): boolean {
   if (!toolNames) return false;
   const messages = Array.isArray(body) ? body : [body];
@@ -620,6 +631,11 @@ function requireMcpHttpAuth(
   resourcePath = '/mcp',
 ) {
   return (req: Request, res: Response, next: NextFunction) => {
+    if (mode === 'none') {
+      next();
+      return;
+    }
+
     if (mode === 'bearer') {
       if (!isAuthorizedMcpHttpRequest(req, bearerToken)) {
         sendBearerUnauthorized(res, bearerToken ? 'Missing or invalid Authorization header' : 'Bearer token is not configured', Boolean(bearerToken));
@@ -666,7 +682,7 @@ function positiveIntegerEnv(name: string, fallback: number): number {
 }
 
 const MAX_MCP_SESSIONS = positiveIntegerEnv('FORGE_MCP_MAX_SESSIONS', 64);
-const MAX_MCP_SESSIONS_PER_PRINCIPAL = positiveIntegerEnv('FORGE_MCP_MAX_SESSIONS_PER_PRINCIPAL', 8);
+const MAX_MCP_SESSIONS_PER_PRINCIPAL = positiveIntegerEnv('FORGE_MCP_MAX_SESSIONS_PER_PRINCIPAL', MAX_MCP_SESSIONS);
 const MAX_INITIALIZING_SESSIONS = positiveIntegerEnv('FORGE_MCP_MAX_INITIALIZING_SESSIONS', 8);
 const MAX_POSTS_PER_SESSION = positiveIntegerEnv('FORGE_MCP_MAX_POSTS_PER_SESSION', 4);
 const MAX_ACTIVE_POSTS = positiveIntegerEnv('FORGE_MCP_MAX_ACTIVE_POSTS', 32);
@@ -687,6 +703,7 @@ async function handleMcpPost(
   route: McpSessionRoute,
   currentToolSurfaceFingerprint: () => string | undefined,
   resolveRuntimeSchema?: (context: McpToolContext) => Promise<CanonicalRuntimeToolSchema | undefined>,
+  sharedRuntimeProxy?: CanonicalRuntimeProxy,
 ): Promise<void> {
   let body: unknown;
   try {
@@ -713,7 +730,15 @@ async function handleMcpPost(
     if (stats.initializing >= MAX_INITIALIZING_SESSIONS || stats.activePosts >= MAX_ACTIVE_POSTS) {
       stats.rejectedOverload += 1;
       res.setHeader('retry-after', '1');
-      res.status(503).json({ error: 'server_busy', message: 'Too many MCP sessions are initializing; retry shortly' });
+      res.status(503).json({
+        error: 'server_busy',
+        code: 'MCP_SERVER_BUSY',
+        message: 'Too many MCP sessions are initializing; retry shortly',
+        recoverable: true,
+        retryable: true,
+        sessionPreserved: true,
+        action: 'retry',
+      });
       return;
     }
     stats.initializing += 1;
@@ -733,7 +758,15 @@ async function handleMcpPost(
       if (!reservationId) {
         stats.rejectedOverload += 1;
         res.setHeader('retry-after', '1');
-        res.status(503).json({ error: 'session_capacity', message: 'All MCP sessions are executing active work; retry shortly' });
+        res.status(503).json({
+          error: 'session_capacity',
+          code: 'MCP_SESSION_CAPACITY',
+          message: 'All MCP sessions are executing active requests; retry shortly',
+          recoverable: true,
+          retryable: true,
+          sessionPreserved: true,
+          action: 'retry',
+        });
         return;
       }
       const sessionContext = createMcpToolContext({
@@ -741,7 +774,7 @@ async function handleMcpPost(
         sessionId: `mcp_${randomUUID().replace(/-/g, '')}`,
         principalId,
       });
-      const runtimeSchema = await resolveRuntimeSchema?.(sessionContext);
+      let runtimeSchema = await resolveRuntimeSchema?.(sessionContext);
       let server: ReturnType<typeof createForgeMcpServerFromContext> | undefined;
       transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
@@ -756,6 +789,21 @@ async function handleMcpPost(
             toolSurfaceFingerprint: runtimeSchema?.fingerprint ?? currentToolSurfaceFingerprint(),
             toolNames: runtimeSchema?.toolNames,
             notifyToolListChanged: async () => { await server?.sendToolListChanged(); },
+            ...(runtimeSchema && resolveRuntimeSchema
+              ? {
+                  refreshToolSurface: async () => {
+                    const refreshed = await resolveRuntimeSchema(sessionContext);
+                    if (!refreshed || !runtimeSchema) return undefined;
+                    runtimeSchema.definitions = refreshed.definitions;
+                    runtimeSchema.toolNames = refreshed.toolNames;
+                    runtimeSchema.fingerprint = refreshed.fingerprint;
+                    return {
+                      toolSurfaceFingerprint: refreshed.fingerprint,
+                      toolNames: refreshed.toolNames,
+                    };
+                  },
+                }
+              : {}),
           });
           initializedSessionId = newSessionId;
         },
@@ -763,7 +811,7 @@ async function handleMcpPost(
       transport.onclose = () => {
         if (transport?.sessionId) registry.detach(transport.sessionId);
       };
-      server = createForgeMcpServerFromContext(sessionContext, runtimeSchema);
+      server = createForgeMcpServerFromContext(sessionContext, runtimeSchema, sharedRuntimeProxy);
       await server.connect(transport);
       await transport.handleRequest(req, res, body);
     } finally {
@@ -794,6 +842,17 @@ async function handleMcpPost(
             : undefined,
         );
         if (!mcpSessionToolSurfaceFingerprintIsCurrent(managed.toolSurfaceFingerprint, currentFingerprint)) {
+          // Standard MCP hot refresh: allow an explicitly requested tools/list
+          // to replace the live session's mutable Runtime schema snapshot. Hosts
+          // that ignore list_changed and call directly still hit the reset fence.
+          if (isMcpToolsListRequest(body)) {
+            const refreshed = await registry.refreshToolSurface(sessionId);
+            if (refreshed
+              && (!currentFingerprint || refreshed.toolSurfaceFingerprint === currentFingerprint)) {
+              await managed.transport.handleRequest(req, res, body);
+              return;
+            }
+          }
           // Keep the transport/session alive long enough for the host to observe
           // the recoverable reset and issue a replacement initialize request.
           // The initialize path explicitly supersedes this session afterward.
@@ -877,10 +936,15 @@ async function handleMcpDelete(req: Request, res: Response, registry: HttpSessio
 export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const host = opts.host ?? '127.0.0.1';
   const port = opts.port ?? 8765;
-  const repoRoot = resolveMcpRepoRoot(opts.repo ?? '.');
   const controllerHome = resolveControllerHome(opts.controllerHome);
-  const serviceConfig = loadMcpServiceLocalConfig(controllerHome, repoRoot);
+  const serviceConfig = loadMcpServiceLocalConfig(controllerHome);
   const profile = opts.profile ?? serviceConfig?.profile ?? 'controller';
+  // A controller Gateway can serve registered repositories without selecting
+  // one at startup. Do not turn its launchd working directory into an
+  // implicit repository, especially for package Runtime snapshots.
+  const repoRoot = profile === 'controller' && !opts.repo?.trim()
+    ? undefined
+    : resolveMcpRepoRoot(opts.repo ?? '.');
   const authMode = parseMcpHttpAuthMode(opts.auth ?? serviceConfig?.auth?.mode);
   const authToken = opts.authToken ?? readMcpServiceBearerToken(controllerHome, repoRoot);
   const oauthPassphrase = authMode === 'oauth'
@@ -902,6 +966,17 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
     streamLeaseMs: MCP_STREAM_LEASE_MS,
     absoluteLifetimeMs: MCP_SESSION_ABSOLUTE_LIFETIME_MS,
     activePostStallMs: MCP_ACTIVE_POST_STALL_MS,
+    onSessionClosed: (session, reason) => {
+      const context = session.toolContext;
+      if (!('controllerHome' in context) || typeof context.controllerHome !== 'string') return;
+      const executionSessionId = typeof context.sessionId === 'string' ? context.sessionId.trim() : '';
+      if (!executionSessionId) return;
+      invalidateExecutionSession(
+        context.controllerHome,
+        executionSessionId,
+        `mcp_transport_${reason}`,
+      );
+    },
   });
   const runtimeStats: McpRuntimeStats = { initializing: 0, activePosts: 0, rejectedOverload: 0 };
   const toolContext = createMcpToolContext({ ...opts, repo: repoRoot, controllerHome, profile });
@@ -917,6 +992,9 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
     devRunnerMaxTimeoutMs: opts.devRunnerMaxTimeoutMs,
   };
   const runtimeControllerHome = 'controllerHome' in toolContext ? toolContext.controllerHome : undefined;
+  const sharedRuntimeProxy = runtimeControllerHome && 'controllerHome' in toolContext && !toolContext.runtimeSourceRoot
+    ? createCanonicalRuntimeProxy(toolContext)
+    : undefined;
   const currentRuntimeGeneration = () => runtimeControllerHome ? readRuntimeGeneration(runtimeControllerHome) : undefined;
   const currentRuntimeToolSurfaceFingerprint = () => runtimeControllerHome
     ? readRuntimeStatusSnapshot(runtimeControllerHome)?.toolSurfaceFingerprint
@@ -941,7 +1019,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const resolveRuntimeSchema = runtimeControllerHome
     ? async (context: McpToolContext): Promise<CanonicalRuntimeToolSchema | undefined> => {
       if (!('controllerHome' in context)) return undefined;
-      return await readCanonicalRuntimeToolSchema(context);
+      return await readCanonicalRuntimeToolSchema(context, sharedRuntimeProxy);
     }
     : undefined;
   const localControllerConfig = {
@@ -953,7 +1031,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const toolSurface = toolContext.policy.profile === 'controller' ? FORGE_TOOL_SURFACE : `${toolContext.policy.profile}-legacy-v1`;
   const toolSurfaceSchemaVersion = toolContext.policy.profile === 'controller' ? FORGE_MCP_SCHEMA_VERSION : 1;
   const forgeVersion = FORGE_VERSION;
-  const repoId = toolContext.policy.profile === 'controller' ? undefined : repositoryIdentity(repoRoot);
+  const repoId = toolContext.policy.profile === 'controller' || !repoRoot ? undefined : repositoryIdentity(repoRoot);
   const startedAt = new Date().toISOString();
   const localOrigin = `http://${host === '::' || host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
   const advertisedOrigin = configuredPublicOrigin ?? localOrigin;
@@ -1027,7 +1105,11 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
         defaultTimeoutMs: toolContext.policy.execution.runnerTimeoutMs,
         maxTimeoutMs: toolContext.policy.execution.runnerMaxTimeoutMs,
       },
-      auth: authMode === 'oauth' ? (oauthPassphrase ? 'oauth' : 'missing') : (authToken ? 'required' : 'missing'),
+      auth: authMode === 'oauth'
+        ? (oauthPassphrase ? 'oauth' : 'missing')
+        : authMode === 'bearer'
+          ? (authToken ? 'required' : 'missing')
+          : 'none',
       mcpEndpoint: `${advertisedOrigin}/mcp`,
       // Grok now completes standard OAuth dynamic registration + PKCE on the
       // canonical MCP resource. Keep /mcp-grok below only as a legacy alias.
@@ -1216,7 +1298,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   // Primary MCP path: OAuth (or bearer when --auth bearer). Unchanged for ChatGPT.
   app.use('/mcp', setMcpResponseHeaders);
   app.post('/mcp', requireMcpHttpAuth(authMode, authToken, oauthProvider, configuredPublicOrigin), express.raw({ type: '*/*', limit: '1mb' }), (req, res) => {
-    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema).catch((error: unknown) => {
+    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema, sharedRuntimeProxy).catch((error: unknown) => {
       if (!res.headersSent) sendMcpRequestError(res, error);
     });
   });
@@ -1234,7 +1316,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   // Legacy Grok OAuth resource. New Grok connectors should use canonical /mcp.
   app.use('/mcp-grok', setMcpResponseHeaders);
   app.post('/mcp-grok', requireMcpHttpAuth(authMode, authToken, oauthProvider, configuredPublicOrigin, '/mcp-grok'), express.raw({ type: '*/*', limit: '1mb' }), (req, res) => {
-    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp-grok', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema).catch((error: unknown) => {
+    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp-grok', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema, sharedRuntimeProxy).catch((error: unknown) => {
       if (!res.headersSent) sendMcpRequestError(res, error);
     });
   });
@@ -1252,7 +1334,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   // Bearer-only MCP path for clients that can send Authorization headers. Never advertises OAuth resource_metadata.
   app.use('/mcp-bearer', setMcpResponseHeaders);
   app.post('/mcp-bearer', requireMcpHttpAuth('bearer', authToken, null, configuredPublicOrigin), express.raw({ type: '*/*', limit: '1mb' }), (req, res) => {
-    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp-bearer', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema).catch((error: unknown) => {
+    handleMcpPost(req, res, baseOptions, sessionRegistry, runtimeStats, '/mcp-bearer', currentRuntimeToolSurfaceFingerprint, resolveRuntimeSchema, sharedRuntimeProxy).catch((error: unknown) => {
       if (!res.headersSent) sendMcpRequestError(res, error);
     });
   });
@@ -1284,12 +1366,17 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
     if (toolSurfaceNotificationTimer) clearTimeout(toolSurfaceNotificationTimer);
     runtimeStatusWatcher?.close();
     void sessionRegistry.closeAll('shutdown');
+    void sharedRuntimeProxy?.close();
   });
 
   await new Promise<void>((resolve) => {
     httpServer.once('listening', resolve);
   });
-  const authLabel = authMode === 'oauth' ? (oauthPassphrase ? 'oauth' : 'oauth-missing') : (authToken ? 'bearer' : 'missing');
+  const authLabel = authMode === 'oauth'
+    ? (oauthPassphrase ? 'oauth' : 'oauth-missing')
+    : authMode === 'bearer'
+      ? (authToken ? 'bearer' : 'missing')
+      : 'none';
   console.error(
     `forge mcp http listening on http://${host}:${port}/mcp (auth: ${authLabel}), http://${host}:${port}/mcp-grok (auth: ${authLabel}), and http://${host}:${port}/mcp-bearer (auth: bearer)`,
   );

package/src/cli/mcp/transports/session-registry.ts

@@ -18,6 +18,11 @@ export interface ClosableMcpTransport {
   close(): Promise<void> | void;
 }
 
+export interface McpToolSurfaceRefresh {
+  toolSurfaceFingerprint: string;
+  toolNames?: string[];
+}
+
 export interface ManagedMcpSession<
   TTransport extends ClosableMcpTransport = ClosableMcpTransport,
   TContext = unknown,
@@ -33,6 +38,8 @@ export interface ManagedMcpSession<
   toolNames?: string[];
   /** Standard MCP tools/list_changed notification bound to this session's connected Server. */
   notifyToolListChanged?: () => Promise<void> | void;
+  /** Refreshes the mutable Runtime schema snapshot backing this live MCP session. */
+  refreshToolSurface?: () => Promise<McpToolSurfaceRefresh | undefined>;
   lastNotifiedToolSurfaceFingerprint?: string;
   createdAt: number;
   lastActivityAt: number;
@@ -72,7 +79,10 @@ export interface McpSessionSnapshot {
   closed: McpSessionCloseCounters;
 }
 
-export interface McpSessionRegistryOptions {
+export interface McpSessionRegistryOptions<
+  TTransport extends ClosableMcpTransport = ClosableMcpTransport,
+  TContext = unknown,
+> {
   maximumSessions?: number;
   maximumSessionsPerPrincipal?: number;
   idleTtlMs?: number;
@@ -80,6 +90,7 @@ export interface McpSessionRegistryOptions {
   absoluteLifetimeMs?: number;
   activePostStallMs?: number;
   now?: () => number;
+  onSessionClosed?: (session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason) => void;
 }
 
 interface RegisterMcpSession<TTransport extends ClosableMcpTransport, TContext> {
@@ -92,6 +103,7 @@ interface RegisterMcpSession<TTransport extends ClosableMcpTransport, TContext>
   toolSurfaceFingerprint?: string;
   toolNames?: string[];
   notifyToolListChanged?: () => Promise<void> | void;
+  refreshToolSurface?: () => Promise<McpToolSurfaceRefresh | undefined>;
   initialPost?: boolean;
 }
 
@@ -161,12 +173,13 @@ export class McpSessionRegistry<
   private readonly absoluteLifetimeMs: number;
   private readonly activePostStallMs: number;
   private readonly now: () => number;
+  private readonly onSessionClosed?: (session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason) => void;
   private readonly closeCounters = emptyCloseCounters();
   private readonly initializeReservations = new Map<string, InitializeReservation>();
   private admissionQueue: Promise<void> = Promise.resolve();
   private nextReservationId = 0;
 
-  constructor(options: McpSessionRegistryOptions = {}) {
+  constructor(options: McpSessionRegistryOptions<TTransport, TContext> = {}) {
     this.maximumSessions = positiveInteger(options.maximumSessions, DEFAULT_MAXIMUM_SESSIONS);
     this.maximumSessionsPerPrincipal = Math.min(
       this.maximumSessions,
@@ -177,6 +190,7 @@ export class McpSessionRegistry<
     this.absoluteLifetimeMs = positiveInteger(options.absoluteLifetimeMs, DEFAULT_ABSOLUTE_LIFETIME_MS);
     this.activePostStallMs = positiveInteger(options.activePostStallMs, DEFAULT_ACTIVE_POST_STALL_MS);
     this.now = options.now ?? Date.now;
+    this.onSessionClosed = options.onSessionClosed;
   }
 
   get size(): number {
@@ -230,6 +244,18 @@ export class McpSessionRegistry<
     return notified;
   }
 
+  async refreshToolSurface(sessionId: string): Promise<McpToolSurfaceRefresh | undefined> {
+    const session = this.sessions.get(sessionId);
+    if (!session?.refreshToolSurface) return undefined;
+    const refreshed = await session.refreshToolSurface();
+    if (!refreshed?.toolSurfaceFingerprint) return undefined;
+    session.toolSurfaceFingerprint = refreshed.toolSurfaceFingerprint;
+    session.toolNames = refreshed.toolNames;
+    session.lastNotifiedToolSurfaceFingerprint = refreshed.toolSurfaceFingerprint;
+    session.lastActivityAt = this.now();
+    return refreshed;
+  }
+
   beginPost(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
     const session = this.sessions.get(sessionId);
     if (!session) return undefined;
@@ -274,9 +300,11 @@ export class McpSessionRegistry<
   detach(sessionId: string, reason: McpSessionCloseReason = 'transport_close'): boolean {
     const session = this.sessions.get(sessionId);
     if (!session) return false;
+    const closeReason = session.pendingCloseReason ?? reason;
     this.sessions.delete(sessionId);
     clearSessionCachesForSession(sessionId);
-    this.incrementCloseCounter(session.pendingCloseReason ?? reason);
+    this.incrementCloseCounter(closeReason);
+    this.observeSessionClosed(session, closeReason);
     return true;
   }
 
@@ -287,6 +315,7 @@ export class McpSessionRegistry<
     clearSessionCachesForSession(sessionId);
     session.pendingCloseReason = reason;
     this.incrementCloseCounter(reason);
+    this.observeSessionClosed(session, reason);
     try {
       await session.transport.close();
     } catch {
@@ -296,6 +325,15 @@ export class McpSessionRegistry<
     return true;
   }
 
+  private observeSessionClosed(session: ManagedMcpSession<TTransport, TContext>, reason: McpSessionCloseReason): void {
+    try {
+      this.onSessionClosed?.(session, reason);
+    } catch {
+      // Session close must remain available even if liveness evidence cannot be recorded.
+      // The controller lease then expires normally instead of being released unsafely.
+    }
+  }
+
   async reserveForInitialize(request: InitializeCapacityRequest): Promise<string | undefined> {
     return await this.withAdmissionLock(async () => {
       await this.prune();
@@ -382,7 +420,7 @@ export class McpSessionRegistry<
     const reservations = [...this.initializeReservations.values()];
     const activePosts = sessions.reduce((count, session) => count + session.inFlightPosts, 0) + reservations.length;
     const activeStreams = sessions.reduce((count, session) => count + session.inFlightGets, 0);
-    const evictable = sessions.filter((session) => session.inFlightPosts === 0).length;
+    const evictable = sessions.filter((session) => session.inFlightPosts === 0 && session.inFlightGets === 0).length;
     const reserved = reservations.length;
     const protectedCount = sessions.length - evictable + reserved;
     const capacityAvailable = Math.max(0, this.maximumSessions - sessions.length - reserved);
@@ -437,7 +475,7 @@ export class McpSessionRegistry<
     predicate: (session: ManagedMcpSession<TTransport, TContext>) => boolean = () => true,
   ): ManagedMcpSession<TTransport, TContext>[] {
     return [...this.sessions.values()]
-      .filter((session) => session.inFlightPosts === 0 && predicate(session))
+      .filter((session) => session.inFlightPosts === 0 && session.inFlightGets === 0 && predicate(session))
       .sort((left, right) => {
         const leftAge = left.streamOpenedAt ?? left.lastActivityAt;
         const rightAge = right.streamOpenedAt ?? right.lastActivityAt;

package/src/cli/mcp/types.ts

@@ -2,11 +2,11 @@ export type McpProfileName = 'planner' | 'executor' | 'orchestrator' | 'controll
 export type McpPathIntent = 'read' | 'write';
 export type McpAgentRunnerName = 'codex' | 'claude';
 /** Controller MCP tools/list exposure profile.
- * - core (default): facade + repository bootstrap/selection only
- * - advanced: supervised controller surface (former large core set)
+ * - facade: explicit five-tool ChatGPT orchestration surface
+ * - core/advanced (default compatibility labels): bounded stable controller surface
  * - full: compatibility mode — all legacy + runtime tools
  */
-export type McpToolset = 'core' | 'advanced' | 'full';
+export type McpToolset = 'facade' | 'core' | 'advanced' | 'full';
 
 export interface McpPolicy {
   profile: McpProfileName;