@moretea-labs/forge 1.6.0 → 1.7.0

package/src/cli/mcp/server.ts

@@ -23,8 +23,9 @@ import { randomUUID } from 'crypto';
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import { observeRuntimeStatus } from '../../runtime/root/status';
+import { readRuntimeReleaseAuthority } from '../../runtime/root/release-store';
 import { getRuntimeWriteClaim } from '../../runtime/root/write-fence';
-import { recordMcpIncident, recordMcpTiming } from '../../runtime/diagnostics/mcp-timing';
+import { recordMcpIncident, recordMcpTiming, type McpTimingTrace } from '../../runtime/diagnostics/mcp-timing';
 import { FORGE_VERSION, forgeToolSurfaceFingerprint } from '../controller/runtime-config';
 
 export type { McpServerOptions } from './multi-repository';
@@ -84,6 +85,7 @@ function tracedResult(
   value: CallToolResult | undefined,
   traceId: string,
   requestId: string,
+  serverTiming?: { startedAt: string; durationMs: number },
 ): CallToolResult | undefined {
   if (!value || !value.structuredContent || typeof value.structuredContent !== 'object' || Array.isArray(value.structuredContent)) return value;
   const originalStructuredContent = value.structuredContent as Record<string, unknown>;
@@ -95,6 +97,7 @@ function tracedResult(
         : {}),
       traceId,
       requestId,
+      ...(serverTiming ? { serverStartedAt: serverTiming.startedAt, serverDurationMs: serverTiming.durationMs } : {}),
     },
   };
   return {
@@ -111,7 +114,7 @@ async function traceControllerMcpRequest(
   name: string,
   args: Record<string, unknown>,
   rpcId: string | number | undefined,
-  handler: (requestId: string) => Promise<CallToolResult>,
+  handler: (requestId: string, traceId: string, phaseTimings: Partial<McpTimingTrace>) => Promise<CallToolResult>,
 ): Promise<CallToolResult> {
   const startedAtWall = new Date().toISOString();
   const startedAt = performance.now();
@@ -120,8 +123,9 @@ async function traceControllerMcpRequest(
   let outcome: 'ok' | 'error' | 'exception' = 'ok';
   let errorCode: string | undefined;
   let executionIdentity: ReturnType<typeof timingIdentity> = {};
+  const phaseTimings: Partial<McpTimingTrace> = {};
   try {
-    const value = await handler(requestId);
+    const value = await handler(requestId, traceId, phaseTimings);
     executionIdentity = timingIdentity(value);
     if (value?.isError) {
       outcome = 'error';
@@ -148,7 +152,8 @@ async function traceControllerMcpRequest(
         });
       }
     }
-    return tracedResult(value, traceId, requestId) as CallToolResult;
+    const serverDurationMs = Math.round((performance.now() - startedAt) * 100) / 100;
+    return tracedResult(value, traceId, requestId, { startedAt: startedAtWall, durationMs: serverDurationMs }) as CallToolResult;
   } catch (error) {
     outcome = 'exception';
     errorCode = 'MCP_REQUEST_EXCEPTION';
@@ -173,6 +178,7 @@ async function traceControllerMcpRequest(
       outcome,
       ...(errorCode ? { errorCode } : {}),
       ...executionIdentity,
+      ...phaseTimings,
       totalToolDurationMs: Math.round((performance.now() - startedAt) * 100) / 100,
     });
   }
@@ -189,8 +195,7 @@ export function createMcpToolContext(opts: McpServerOptions): ServerToolContext
   return createMultiRepositoryToolContext({ ...opts, repo });
 }
 
-function canonicalRuntimeEndpoint(ctx: MultiRepositoryMcpToolContext): URL {
-  const endpoint = observeRuntimeStatus(ctx.controllerHome).snapshot?.endpoint;
+function canonicalRuntimeEndpoint(endpoint: string | undefined): URL {
   if (!endpoint) throw new Error('CANONICAL_RUNTIME_ENDPOINT_UNAVAILABLE');
   const url = new URL(endpoint);
   const host = url.hostname.replace(/^\[|\]$/g, '');
@@ -207,161 +212,576 @@ function canonicalRuntimeToken(ctx: MultiRepositoryMcpToolContext): string {
   return token;
 }
 
-const CANONICAL_RUNTIME_MCP_TIMEOUT_MS = 5_000;
+export const CANONICAL_RUNTIME_CONNECT_TIMEOUT_MS = 5_000;
+/**
+ * The loopback connection should fail fast, but a valid Canonical Runtime tool
+ * call may legitimately outlive five seconds (for example Work finalization).
+ * Do not let the thin Public Gateway report a false timeout while authoritative
+ * work continues successfully behind it.
+ */
+export const CANONICAL_RUNTIME_TOOL_CALL_TIMEOUT_MS = 120_000;
+export const CANONICAL_RUNTIME_HANDOFF_WAIT_MS = 20_000;
+export const CANONICAL_RUNTIME_HANDOFF_RETRY_INTERVAL_MS = 150;
+const CANONICAL_RUNTIME_HANDOFF_SIGNAL_TTL_MS = 90_000;
 
-async function withCanonicalRuntimeClient<T>(
-  ctx: MultiRepositoryMcpToolContext,
-  action: (client: Client) => Promise<T>,
+export interface CanonicalRuntimeReleaseHandoffObservation {
+  authorityReleaseId?: string;
+  authorityCommittedAt?: string;
+  runtimeReleaseId?: string;
+  runtimeRunning: boolean;
+  runtimeReady: boolean;
+  runtimeStartedAt?: string;
+  runtimeUpdatedAt?: string;
+  recoveryActivationInProgress?: boolean;
+  nowMs: number;
+}
+
+function timestampIsRecent(value: string | undefined, nowMs: number, maxAgeMs: number): boolean {
+  if (!value) return false;
+  const observedAt = Date.parse(value);
+  if (!Number.isFinite(observedAt)) return false;
+  const ageMs = nowMs - observedAt;
+  return ageMs >= -5_000 && ageMs <= maxAgeMs;
+}
+
+/**
+ * Recognize only a bounded whole-Runtime release handoff. An old dead Runtime
+ * must not keep the public Gateway waiting forever, so every transition signal
+ * is time-bounded. This is observability, never release authority.
+ */
+export function canonicalRuntimeReleaseHandoffInProgress(
+  input: CanonicalRuntimeReleaseHandoffObservation,
+): boolean {
+  if (!input.authorityReleaseId) return false;
+  const sameRelease = input.runtimeReleaseId === input.authorityReleaseId;
+  const authorityRecent = timestampIsRecent(
+    input.authorityCommittedAt,
+    input.nowMs,
+    CANONICAL_RUNTIME_HANDOFF_SIGNAL_TTL_MS,
+  );
+
+  // The release authority switches only after the old Runtime has completely
+  // stopped. Until the new Runtime publishes matching status, this mismatch is
+  // the strongest handoff signal. Missing status is equivalent to mismatch only
+  // while the authority commit is recent.
+  if (!sameRelease && authorityRecent) return true;
+
+  // The new Runtime owns the target release but has not completed scheduler +
+  // MCP end-to-end readiness yet.
+  if (sameRelease && input.runtimeRunning && !input.runtimeReady) {
+    return timestampIsRecent(
+      input.runtimeStartedAt ?? input.runtimeUpdatedAt,
+      input.nowMs,
+      CANONICAL_RUNTIME_HANDOFF_SIGNAL_TTL_MS,
+    );
+  }
+
+  // Bridge the intentional bootout -> authority-publish gap only while the
+  // standalone Recovery transaction explicitly owns the activation lock. A
+  // freshly crashed Runtime without that lock is an outage and stays fail-fast.
+  if (sameRelease && !input.runtimeRunning) {
+    return input.recoveryActivationInProgress === true;
+  }
+
+  return false;
+}
+
+export interface CanonicalRuntimeHandoffWaitResult {
+  waited: boolean;
+  settled: boolean;
+  observations: number;
+}
+
+export async function waitForCanonicalRuntimeReleaseHandoff(
+  handoffInProgress: () => boolean,
+  options: {
+    maxWaitMs?: number;
+    intervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+  } = {},
+): Promise<CanonicalRuntimeHandoffWaitResult> {
+  const maxWaitMs = Math.max(0, options.maxWaitMs ?? CANONICAL_RUNTIME_HANDOFF_WAIT_MS);
+  const intervalMs = Math.max(1, options.intervalMs ?? CANONICAL_RUNTIME_HANDOFF_RETRY_INTERVAL_MS);
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  let observations = 1;
+  if (!handoffInProgress()) return { waited: false, settled: true, observations };
+  const deadline = now() + maxWaitMs;
+  let waited = false;
+  while (now() < deadline) {
+    waited = true;
+    await sleep(Math.min(intervalMs, Math.max(1, deadline - now())));
+    observations += 1;
+    if (!handoffInProgress()) return { waited, settled: true, observations };
+  }
+  observations += 1;
+  return { waited, settled: !handoffInProgress(), observations };
+}
+
+export async function retryCanonicalRuntimeConnectDuringHandoff<T>(
+  connect: () => Promise<T>,
+  handoffInProgress: () => boolean,
+  options: Parameters<typeof waitForCanonicalRuntimeReleaseHandoff>[1] = {},
 ): Promise<T> {
-  const abort = new AbortController();
-  const timeout = setTimeout(() => abort.abort(new Error('CANONICAL_RUNTIME_TIMEOUT')), CANONICAL_RUNTIME_MCP_TIMEOUT_MS);
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${canonicalRuntimeToken(ctx)}`,
-  };
-  if (ctx.principalId?.trim()) headers['x-forge-forwarded-principal-id'] = ctx.principalId.trim();
-  if (ctx.sessionId?.trim()) headers['x-forge-forwarded-session-id'] = ctx.sessionId.trim();
-  const transport = new StreamableHTTPClientTransport(canonicalRuntimeEndpoint(ctx), {
-    requestInit: { headers, signal: abort.signal },
-  });
-  const client = new Client({ name: 'forge-public-gateway-proxy', version: '1.0.0' });
+  const initialWait = await waitForCanonicalRuntimeReleaseHandoff(handoffInProgress, options);
+  if (initialWait.waited && !initialWait.settled) {
+    // Preserve the ordinary connect failure shape after the bounded handoff
+    // window rather than manufacturing a new proxy-only error.
+    return await connect();
+  }
   try {
-    await client.connect(transport);
-    return await action(client);
-  } finally {
-    clearTimeout(timeout);
-    await client.close().catch(() => undefined);
+    return await connect();
+  } catch (error) {
+    // Retrying is safe only because connect() has not dispatched a tool call.
+    // Once client.callTool() begins, callers must never use this helper.
+    if (!handoffInProgress()) throw error;
+    const waited = await waitForCanonicalRuntimeReleaseHandoff(handoffInProgress, options);
+    if (!waited.settled) throw error;
+    return await connect();
   }
 }
 
-/**
- * The public Gateway has no schema cache authority. It obtains each Connector
- * session's schema from the Runtime that will execute its calls.
- */
-export async function readCanonicalRuntimeToolSchema(
-  ctx: MultiRepositoryMcpToolContext,
-): Promise<CanonicalRuntimeToolSchema> {
-  const response = await withCanonicalRuntimeClient(ctx, async (client) => await client.listTools());
-  const definitions = response.tools as Tool[];
-  const toolNames = definitions
-    .map((tool) => tool.name)
-    .filter((name): name is string => typeof name === 'string' && name.length > 0)
-    .sort();
+function recoveryRuntimeReleaseActivationInProgress(controllerHome: string): boolean {
+  try {
+    const lock = JSON.parse(readFileSync(join(controllerHome, 'recovery', 'locks', 'operation.lock'), 'utf8')) as {
+      action?: string;
+      acquiredAt?: string;
+    };
+    if (lock.action !== 'activate_runtime_release' && lock.action !== 'stage_and_activate_runtime_release') return false;
+    return timestampIsRecent(lock.acquiredAt, Date.now(), CANONICAL_RUNTIME_HANDOFF_SIGNAL_TTL_MS);
+  } catch {
+    return false;
+  }
+}
+
+function canonicalRuntimeReleaseHandoffActive(controllerHome: string): boolean {
+  const runtime = observeRuntimeStatus(controllerHome);
+  if (runtime.running && runtime.ready) return false;
+  const authority = readRuntimeReleaseAuthority(controllerHome);
+  return canonicalRuntimeReleaseHandoffInProgress({
+    authorityReleaseId: authority?.active.releaseId,
+    authorityCommittedAt: authority?.committedAt,
+    runtimeReleaseId: runtime.snapshot?.releaseId,
+    runtimeRunning: runtime.running,
+    runtimeReady: runtime.ready,
+    runtimeStartedAt: runtime.snapshot?.startedAt,
+    runtimeUpdatedAt: runtime.snapshot?.updatedAt,
+    recoveryActivationInProgress: recoveryRuntimeReleaseActivationInProgress(controllerHome),
+    nowMs: Date.now(),
+  });
+}
+
+
+const CANONICAL_RUNTIME_FORWARD_META_KEY = 'forgeRuntimeForwarding';
+
+type ForwardedControllerType = NonNullable<McpToolContext['controllerType']>;
+
+interface CanonicalRuntimeForwardingIdentity {
+  principalId?: string;
+  sessionId?: string;
+  controllerType?: ForwardedControllerType;
+}
+
+function boundedForwardedIdentity(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim();
+  return normalized ? normalized.slice(0, 512) : undefined;
+}
+
+export function canonicalRuntimeForwardingIdentity(meta: unknown): CanonicalRuntimeForwardingIdentity {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return {};
+  const envelope = (meta as Record<string, unknown>)[CANONICAL_RUNTIME_FORWARD_META_KEY];
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) return {};
+  const record = envelope as Record<string, unknown>;
+  const controllerType = boundedForwardedIdentity(record.controllerType);
   return {
-    definitions,
-    toolNames,
-    fingerprint: forgeToolSurfaceFingerprint(definitions),
+    principalId: boundedForwardedIdentity(record.principalId),
+    sessionId: boundedForwardedIdentity(record.sessionId),
+    ...(controllerType && ['chatgpt', 'codex', 'claude', 'grok', 'human'].includes(controllerType)
+      ? { controllerType: controllerType as ForwardedControllerType }
+      : {}),
   };
 }
 
-interface CanonicalRuntimeProxyIdentity {
+function canonicalRuntimeForwardingMeta(ctx: MultiRepositoryMcpToolContext): Record<string, unknown> {
+  return {
+    [CANONICAL_RUNTIME_FORWARD_META_KEY]: {
+      ...(ctx.principalId?.trim() ? { principalId: ctx.principalId.trim() } : {}),
+      ...(ctx.sessionId?.trim() ? { sessionId: ctx.sessionId.trim() } : {}),
+      ...(ctx.controllerType ? { controllerType: ctx.controllerType } : {}),
+    },
+  };
+}
+
+function canonicalRuntimeRequestContext(baseContext: ServerToolContext, meta: unknown): ServerToolContext {
+  if (!isMultiRepositoryContext(baseContext) || !baseContext.runtimeSourceRoot) return baseContext;
+  const forwarded = canonicalRuntimeForwardingIdentity(meta);
+  return {
+    ...baseContext,
+    ...(forwarded.principalId ? { principalId: forwarded.principalId } : {}),
+    ...(forwarded.sessionId ? { sessionId: forwarded.sessionId } : {}),
+    ...(forwarded.controllerType ? { controllerType: forwarded.controllerType } : {}),
+  };
+}
+
+export interface CanonicalRuntimeProxyIdentity {
   endpoint: URL;
   token: string;
-  principalId: string;
-  sessionId: string;
+  runtimeInstanceId: string;
 }
 
 function canonicalRuntimeProxyIdentity(ctx: MultiRepositoryMcpToolContext): CanonicalRuntimeProxyIdentity {
+  const snapshot = observeRuntimeStatus(ctx.controllerHome).snapshot;
+  if (!snapshot?.runtimeInstanceId) throw new Error('CANONICAL_RUNTIME_IDENTITY_UNAVAILABLE');
   return {
-    endpoint: canonicalRuntimeEndpoint(ctx),
+    endpoint: canonicalRuntimeEndpoint(snapshot.endpoint),
     token: canonicalRuntimeToken(ctx),
-    principalId: ctx.principalId?.trim() ?? '',
-    sessionId: ctx.sessionId?.trim() ?? '',
+    runtimeInstanceId: snapshot.runtimeInstanceId,
   };
 }
 
-function sameCanonicalRuntimeProxyIdentity(
+export function sameCanonicalRuntimeProxyIdentity(
   left: CanonicalRuntimeProxyIdentity,
   right: CanonicalRuntimeProxyIdentity,
 ): boolean {
   return left.endpoint.href === right.endpoint.href
     && left.token === right.token
-    && left.principalId === right.principalId
-    && left.sessionId === right.sessionId;
+    && left.runtimeInstanceId === right.runtimeInstanceId;
 }
 
-function createCanonicalRuntimeProxy(ctx: MultiRepositoryMcpToolContext): {
-  callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
-  close: () => Promise<void>;
-} {
-  let current: { identity: CanonicalRuntimeProxyIdentity; client: Client } | undefined;
-  let connecting: Promise<{ identity: CanonicalRuntimeProxyIdentity; client: Client }> | undefined;
+export interface CanonicalRuntimeProxy {
+  listTools(): Promise<{ tools: Tool[] }>;
+  callTool(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>, timing?: MutableGatewayProxyTiming): Promise<CallToolResult>;
+  close(): Promise<void>;
+}
+
+/**
+ * The public Gateway has no schema cache authority. It obtains each Connector
+ * session's schema from the Runtime that will execute its calls. When the HTTP
+ * Gateway owns a shared proxy, discovery and tool calls reuse the same loopback
+ * MCP session instead of paying an initialize/connect round trip per outer
+ * Connector session.
+ */
+export async function readCanonicalRuntimeToolSchema(
+  ctx: MultiRepositoryMcpToolContext,
+  sharedProxy?: CanonicalRuntimeProxy,
+): Promise<CanonicalRuntimeToolSchema> {
+  const proxy = sharedProxy ?? createCanonicalRuntimeProxy(ctx);
+  try {
+    const response = await proxy.listTools();
+    const definitions = response.tools as Tool[];
+    const toolNames = definitions
+      .map((tool) => tool.name)
+      .filter((name): name is string => typeof name === 'string' && name.length > 0)
+      .sort();
+    return {
+      definitions,
+      toolNames,
+      fingerprint: forgeToolSurfaceFingerprint(definitions),
+    };
+  } finally {
+    if (!sharedProxy) await proxy.close();
+  }
+}
+
+type GatewayProxyTiming = Pick<McpTimingTrace,
+  | 'gatewayProxyResolveMs'
+  | 'gatewayProxyConnectMs'
+  | 'gatewayProxyCallMs'
+  | 'gatewayProxyCanonicalDispatchLagMs'
+  | 'gatewayProxyCanonicalDurationMs'
+  | 'gatewayProxyReturnMs'
+  | 'gatewayProxyConnectionState'
+>;
+
+type MutableGatewayProxyTiming = Partial<GatewayProxyTiming>;
+
+function roundedMs(value: number): number {
+  return Math.round(Math.max(0, value) * 100) / 100;
+}
+
+export function deriveCanonicalForwardingTiming(input: {
+  gatewayCallStartedAtMs: number;
+  gatewayCallDurationMs: number;
+  response: CallToolResult;
+}): Pick<GatewayProxyTiming, 'gatewayProxyCanonicalDispatchLagMs' | 'gatewayProxyCanonicalDurationMs' | 'gatewayProxyReturnMs'> {
+  const structured = input.response.structuredContent;
+  const responseMeta = structured && typeof structured === 'object' && !Array.isArray(structured)
+    && (structured as Record<string, unknown>).responseMeta
+    && typeof (structured as Record<string, unknown>).responseMeta === 'object'
+    ? (structured as Record<string, unknown>).responseMeta as Record<string, unknown>
+    : undefined;
+  const canonicalStartedAt = typeof responseMeta?.serverStartedAt === 'string'
+    ? Date.parse(responseMeta.serverStartedAt)
+    : Number.NaN;
+  const canonicalDurationMs = typeof responseMeta?.serverDurationMs === 'number'
+    ? responseMeta.serverDurationMs
+    : Number.NaN;
+  if (!Number.isFinite(canonicalStartedAt) || !Number.isFinite(canonicalDurationMs)) return {};
+  const dispatchLagMs = roundedMs(canonicalStartedAt - input.gatewayCallStartedAtMs);
+  const boundedCanonicalDurationMs = roundedMs(canonicalDurationMs);
+  return {
+    gatewayProxyCanonicalDispatchLagMs: dispatchLagMs,
+    gatewayProxyCanonicalDurationMs: boundedCanonicalDurationMs,
+    gatewayProxyReturnMs: roundedMs(input.gatewayCallDurationMs - dispatchLagMs - boundedCanonicalDurationMs),
+  };
+}
+
+export const DEFAULT_CANONICAL_RUNTIME_PROXY_LANES = 8;
+export const MAX_CANONICAL_RUNTIME_PROXY_LANES = 16;
+
+export function canonicalRuntimeProxyLaneLimit(raw = process.env.FORGE_CANONICAL_RUNTIME_PROXY_LANES): number {
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) return DEFAULT_CANONICAL_RUNTIME_PROXY_LANES;
+  return Math.min(parsed, MAX_CANONICAL_RUNTIME_PROXY_LANES);
+}
+
+export type CanonicalRuntimeLaneClass = 'interactive' | 'wait';
+
+export interface CanonicalRuntimeLaneScheduler {
+  acquire(laneClass?: CanonicalRuntimeLaneClass): Promise<number>;
+  release(laneId: number): void;
+  close(): void;
+  size(): number;
+}
+
+export const RESERVED_INTERACTIVE_CANONICAL_RUNTIME_PROXY_LANES = 2;
+
+/**
+ * Lease one inner Runtime MCP session exclusively to each in-flight request.
+ * Long process_wait calls are capped below total capacity so they can never
+ * consume every lane. Interactive waiters are handed released lanes first.
+ */
+export function createCanonicalRuntimeLaneScheduler(maxLanes = canonicalRuntimeProxyLaneLimit()): CanonicalRuntimeLaneScheduler {
+  const boundedMax = Math.max(1, Math.min(Math.trunc(maxLanes), MAX_CANONICAL_RUNTIME_PROXY_LANES));
+  const maxWaitLanes = boundedMax <= RESERVED_INTERACTIVE_CANONICAL_RUNTIME_PROXY_LANES
+    ? Math.max(1, boundedMax - 1)
+    : boundedMax - RESERVED_INTERACTIVE_CANONICAL_RUNTIME_PROXY_LANES;
+  const idle: number[] = [];
+  const waiters: Array<{ laneClass: CanonicalRuntimeLaneClass; resolve: (laneId: number) => void; reject: (error: Error) => void }> = [];
+  const activeClasses = new Map<number, CanonicalRuntimeLaneClass>();
+  let waitLaneCount = 0;
+  let laneCount = 0;
+  let closed = false;
+
+  const activate = (laneId: number, laneClass: CanonicalRuntimeLaneClass): number => {
+    activeClasses.set(laneId, laneClass);
+    if (laneClass === 'wait') waitLaneCount += 1;
+    return laneId;
+  };
+
+  const nextEligibleWaiterIndex = (): number => {
+    const interactiveIndex = waiters.findIndex((waiter) => waiter.laneClass === 'interactive');
+    if (interactiveIndex >= 0) return interactiveIndex;
+    return waitLaneCount < maxWaitLanes ? waiters.findIndex((waiter) => waiter.laneClass === 'wait') : -1;
+  };
+
+  return {
+    async acquire(laneClass: CanonicalRuntimeLaneClass = 'interactive'): Promise<number> {
+      if (closed) throw new Error('CANONICAL_RUNTIME_PROXY_CLOSED');
+      if (laneClass === 'wait' && waitLaneCount >= maxWaitLanes) {
+        return await new Promise<number>((resolve, reject) => waiters.push({ laneClass, resolve, reject }));
+      }
+      const available = idle.shift();
+      if (available !== undefined) return activate(available, laneClass);
+      if (laneCount < boundedMax) return activate(laneCount++, laneClass);
+      return await new Promise<number>((resolve, reject) => waiters.push({ laneClass, resolve, reject }));
+    },
+    release(laneId: number): void {
+      if (closed) return;
+      const previousClass = activeClasses.get(laneId);
+      activeClasses.delete(laneId);
+      if (previousClass === 'wait') waitLaneCount = Math.max(0, waitLaneCount - 1);
+      const waiterIndex = nextEligibleWaiterIndex();
+      if (waiterIndex >= 0) {
+        const [waiter] = waiters.splice(waiterIndex, 1);
+        waiter.resolve(activate(laneId, waiter.laneClass));
+        return;
+      }
+      idle.push(laneId);
+    },
+    close(): void {
+      if (closed) return;
+      closed = true;
+      const error = new Error('CANONICAL_RUNTIME_PROXY_CLOSED');
+      for (const waiter of waiters.splice(0)) waiter.reject(error);
+      activeClasses.clear();
+      idle.length = 0;
+    },
+    size(): number {
+      return laneCount;
+    },
+  };
+}
+
+interface CanonicalRuntimeProxyLane {
+  current?: { identity: CanonicalRuntimeProxyIdentity; client: Client };
+  connecting?: Promise<{ identity: CanonicalRuntimeProxyIdentity; client: Client }>;
+}
+
+export function createCanonicalRuntimeProxy(ctx: MultiRepositoryMcpToolContext): CanonicalRuntimeProxy {
+  const scheduler = createCanonicalRuntimeLaneScheduler();
+  const lanes = new Map<number, CanonicalRuntimeProxyLane>();
+  let closed = false;
 
-  const closeCurrent = async (expectedClient?: Client): Promise<void> => {
-    if (!current || (expectedClient && current.client !== expectedClient)) return;
-    const closing = current.client;
-    current = undefined;
+  const laneState = (laneId: number): CanonicalRuntimeProxyLane => {
+    const existing = lanes.get(laneId);
+    if (existing) return existing;
+    const created: CanonicalRuntimeProxyLane = {};
+    lanes.set(laneId, created);
+    return created;
+  };
+
+  const closeLane = async (laneId: number, expectedClient?: Client): Promise<void> => {
+    const lane = lanes.get(laneId);
+    if (!lane) return;
+    if (lane.connecting) {
+      await lane.connecting.catch(() => undefined);
+      lane.connecting = undefined;
+    }
+    if (!lane.current || (expectedClient && lane.current.client !== expectedClient)) return;
+    const closing = lane.current.client;
+    lane.current = undefined;
     await closing.close().catch(() => undefined);
   };
 
+  const closeAllLanes = async (): Promise<void> => {
+    await Promise.all(Array.from(lanes.keys()).map(async (laneId) => await closeLane(laneId)));
+  };
+
   const connect = async (identity: CanonicalRuntimeProxyIdentity): Promise<{ identity: CanonicalRuntimeProxyIdentity; client: Client }> => {
-    const abort = new AbortController();
-    const timeout = setTimeout(() => abort.abort(new Error('CANONICAL_RUNTIME_TIMEOUT')), CANONICAL_RUNTIME_MCP_TIMEOUT_MS);
-    const headers: Record<string, string> = {
-      Authorization: `Bearer ${identity.token}`,
+    const connectOnce = async (): Promise<{ identity: CanonicalRuntimeProxyIdentity; client: Client }> => {
+      const abort = new AbortController();
+      const timeout = setTimeout(() => abort.abort(new Error('CANONICAL_RUNTIME_TIMEOUT')), CANONICAL_RUNTIME_CONNECT_TIMEOUT_MS);
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${identity.token}`,
+      };
+      const transport = new StreamableHTTPClientTransport(identity.endpoint, {
+        requestInit: { headers, signal: abort.signal },
+      });
+      const client = new Client({ name: 'forge-public-gateway-proxy', version: '1.0.0' });
+      try {
+        await client.connect(transport);
+        return { identity, client };
+      } catch (error) {
+        await client.close().catch(() => undefined);
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
     };
-    if (identity.principalId) headers['x-forge-forwarded-principal-id'] = identity.principalId;
-    if (identity.sessionId) headers['x-forge-forwarded-session-id'] = identity.sessionId;
-    const transport = new StreamableHTTPClientTransport(identity.endpoint, {
-      requestInit: { headers, signal: abort.signal },
-    });
-    const client = new Client({ name: 'forge-public-gateway-proxy', version: '1.0.0' });
-    try {
-      await client.connect(transport);
-      return { identity, client };
-    } catch (error) {
-      await client.close().catch(() => undefined);
-      throw error;
-    } finally {
-      clearTimeout(timeout);
-    }
+    return await retryCanonicalRuntimeConnectDuringHandoff(
+      connectOnce,
+      () => canonicalRuntimeReleaseHandoffActive(ctx.controllerHome),
+    );
   };
 
-  const clientForCurrentRuntime = async (): Promise<Client> => {
+  const clientForCurrentRuntime = async (laneId: number, timing: MutableGatewayProxyTiming): Promise<Client> => {
+    const lane = laneState(laneId);
+    const resolveStarted = performance.now();
     const identity = canonicalRuntimeProxyIdentity(ctx);
-    if (current && sameCanonicalRuntimeProxyIdentity(current.identity, identity)) return current.client;
+    timing.gatewayProxyResolveMs = roundedMs(performance.now() - resolveStarted);
+    if (lane.current && sameCanonicalRuntimeProxyIdentity(lane.current.identity, identity)) {
+      timing.gatewayProxyConnectionState = 'reused';
+      timing.gatewayProxyConnectMs = 0;
+      return lane.current.client;
+    }
 
-    if (connecting) {
-      const pending = await connecting;
-      if (sameCanonicalRuntimeProxyIdentity(pending.identity, identity)) return pending.client;
+    if (lane.connecting) {
+      const connectStarted = performance.now();
+      const pending = await lane.connecting;
+      timing.gatewayProxyConnectMs = roundedMs(performance.now() - connectStarted);
+      if (sameCanonicalRuntimeProxyIdentity(pending.identity, identity)) {
+        timing.gatewayProxyConnectionState = 'coalesced_connect';
+        return pending.client;
+      }
     }
 
-    await closeCurrent();
-    connecting = connect(identity);
+    const reconnect = Boolean(lane.current);
+    await closeLane(laneId);
+    const connectStarted = performance.now();
+    lane.connecting = connect(identity);
     try {
-      current = await connecting;
-      return current.client;
+      lane.current = await lane.connecting;
+      timing.gatewayProxyConnectMs = roundedMs(performance.now() - connectStarted);
+      timing.gatewayProxyConnectionState = reconnect ? 'identity_reconnect' : 'cold_connect';
+      return lane.current.client;
     } finally {
-      connecting = undefined;
+      lane.connecting = undefined;
+    }
+  };
+
+  const prepareLane = async (
+    timing: MutableGatewayProxyTiming,
+    laneClass: CanonicalRuntimeLaneClass = 'interactive',
+  ): Promise<{ laneId: number; client: Client }> => {
+    if (closed) throw new Error('CANONICAL_RUNTIME_PROXY_CLOSED');
+    const handoff = await waitForCanonicalRuntimeReleaseHandoff(
+      () => canonicalRuntimeReleaseHandoffActive(ctx.controllerHome),
+    );
+    if (handoff.waited) await closeAllLanes();
+    const laneId = await scheduler.acquire(laneClass);
+    try {
+      return { laneId, client: await clientForCurrentRuntime(laneId, timing) };
+    } catch (error) {
+      scheduler.release(laneId);
+      throw error;
     }
   };
 
   return {
-    async callTool(name, args) {
-      const client = await clientForCurrentRuntime();
+    async listTools() {
+      const { laneId, client } = await prepareLane({});
+      try {
+        return await client.listTools() as { tools: Tool[] };
+      } catch (error) {
+        await closeLane(laneId, client);
+        throw error;
+      } finally {
+        scheduler.release(laneId);
+      }
+    },
+    async callTool(callerContext, name, args, timing = {}) {
+      const { laneId, client } = await prepareLane(timing, name === 'process_wait' ? 'wait' : 'interactive');
+      const gatewayCallStartedAtMs = Date.now();
+      const callStarted = performance.now();
       try {
         // The outer Connector session is already bound to the Canonical Runtime
         // schema and fenced by the Runtime-published fingerprint before dispatch.
-        // Re-listing tools here creates a second discovery round trip for every
-        // tool call without strengthening that fence.
+        // Caller identity stays request-scoped while the inner MCP lane is reused.
         const response = await client.callTool(
-          { name, arguments: args },
+          {
+            name,
+            arguments: args,
+            _meta: canonicalRuntimeForwardingMeta(callerContext),
+          } as Parameters<Client['callTool']>[0],
           undefined,
-          { timeout: CANONICAL_RUNTIME_MCP_TIMEOUT_MS },
+          { timeout: CANONICAL_RUNTIME_TOOL_CALL_TIMEOUT_MS },
         );
-        return response as unknown as CallToolResult;
+        const result = response as unknown as CallToolResult;
+        timing.gatewayProxyCallMs = roundedMs(performance.now() - callStarted);
+        Object.assign(timing, deriveCanonicalForwardingTiming({
+          gatewayCallStartedAtMs,
+          gatewayCallDurationMs: timing.gatewayProxyCallMs,
+          response: result,
+        }));
+        return result;
       } catch (error) {
-        // A Runtime restart, token rotation, or broken HTTP session must never
-        // poison later calls. The next request reconnects against fresh identity.
-        await closeCurrent(client);
+        timing.gatewayProxyCallMs = roundedMs(performance.now() - callStarted);
+        // Poison only the failed lane. Other hot lanes remain available so one
+        // Runtime/session failure cannot collapse the whole Gateway proxy pool.
+        await closeLane(laneId, client);
         throw error;
+      } finally {
+        scheduler.release(laneId);
       }
     },
     async close() {
-      if (connecting) {
-        await connecting.catch(() => undefined);
-        connecting = undefined;
-      }
-      await closeCurrent();
+      if (closed) return;
+      closed = true;
+      scheduler.close();
+      await closeAllLanes();
     },
   };
 }
@@ -388,16 +808,18 @@ function toolSurfaceMismatchResult(): CallToolResult {
 export function createForgeMcpServerFromContext(
   baseContext: ServerToolContext,
   runtimeSchema?: CanonicalRuntimeToolSchema,
+  sharedRuntimeProxy?: CanonicalRuntimeProxy,
 ): Server {
   const server = new Server(
     { name: 'forge-mcp', version: FORGE_VERSION },
     { capabilities: { tools: { listChanged: true } }, instructions: mcpServerInstructions(baseContext.policy.profile) },
   );
+  const ownsRuntimeProxy = isMultiRepositoryContext(baseContext) && !getRuntimeWriteClaim() && !sharedRuntimeProxy;
   const runtimeProxy = isMultiRepositoryContext(baseContext) && !getRuntimeWriteClaim()
-    ? createCanonicalRuntimeProxy(baseContext)
+    ? sharedRuntimeProxy ?? createCanonicalRuntimeProxy(baseContext)
     : undefined;
   server.onclose = () => {
-    void runtimeProxy?.close();
+    if (ownsRuntimeProxy) void runtimeProxy?.close();
   };
   // The connector process can outlive the canonical Runtime release it proxies.
   // Refresh tools after every MCP session initialization so clients do not keep
@@ -418,10 +840,14 @@ export function createForgeMcpServerFromContext(
   server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const name = request.params.name;
     const args = (request.params.arguments ?? {}) as Record<string, unknown>;
-    const ctx: ServerToolContext = { ...baseContext, signal: extra.signal };
+    const forwardedBaseContext = canonicalRuntimeRequestContext(
+      baseContext,
+      (request.params as { _meta?: unknown })._meta,
+    );
+    const ctx: ServerToolContext = { ...forwardedBaseContext, signal: extra.signal };
     if (isMultiRepositoryContext(ctx)) {
       const rpcId = (request as unknown as { id?: unknown }).id;
-      return traceControllerMcpRequest(ctx, name, args, typeof rpcId === 'string' || typeof rpcId === 'number' ? rpcId : undefined, async (requestId) => {
+      return traceControllerMcpRequest(ctx, name, args, typeof rpcId === 'string' || typeof rpcId === 'number' ? rpcId : undefined, async (requestId, _traceId, phaseTimings) => {
         // The public Gateway only exposes its stable facade schema. It may
         // proxy execution, but it never discovers one Runtime schema and
         // validates calls against another source checkout.
@@ -449,8 +875,8 @@ export function createForgeMcpServerFromContext(
           const forwardedArgs = typeof args.request_id === 'string' && args.request_id.trim()
             ? args
             : { ...args, request_id: requestId };
-          if (runtimeProxy && runtimeSchema) return runtimeProxy.callTool(name, forwardedArgs);
-          if (runtimeProxy && observeRuntimeStatus(ctx.controllerHome).ready) return runtimeProxy.callTool(name, forwardedArgs);
+          if (runtimeProxy && runtimeSchema) return runtimeProxy.callTool(ctx, name, forwardedArgs, phaseTimings);
+          if (runtimeProxy && observeRuntimeStatus(ctx.controllerHome).ready) return runtimeProxy.callTool(ctx, name, forwardedArgs, phaseTimings);
         }
         const accessResult = callAccessTool(ctx, name, args);
         if (accessResult) return accessResult;