@moretea-labs/forge 1.5.0 → 1.6.0

package/src/cli/mcp/auth.ts

@@ -21,6 +21,8 @@ export interface McpLocalConfig {
   chatgpt?: {
     serverName?: string;
     endpoint?: string;
+    /** Loopback OAuth MCP endpoint used by ChatGPT tunnels/connectors. */
+    localEndpoint?: string;
   };
   profile?: string;
   toolset?: 'core' | 'advanced' | 'full';

package/src/cli/mcp/paths.ts

@@ -93,7 +93,13 @@ function nearestExistingPath(path: string): string | undefined {
   return current;
 }
 
-export function resolveMcpPath(repoRoot: string, inputPath: string, policy: McpPolicy, intent: McpPathIntent): McpPathDecision {
+export function resolveMcpPath(
+  repoRoot: string,
+  inputPath: string,
+  policy: McpPolicy,
+  intent: McpPathIntent,
+  canonicalRepoRoot?: string,
+): McpPathDecision {
   const normalized = normalizeMcpRelativePath(inputPath);
   if (!normalized.ok || !normalized.relativePath) return normalized;
 
@@ -107,7 +113,7 @@ export function resolveMcpPath(repoRoot: string, inputPath: string, policy: McpP
     return { ok: false, relativePath, reason: `path is not allowed for ${intent}: ${relativePath}` };
   }
 
-  const repoRealpath = realpathSync(repoRoot);
+  const repoRealpath = canonicalRepoRoot ?? realpathSync(repoRoot);
   const absolutePath = resolve(repoRealpath, relativePath);
   if (intent === 'read' && !existsSync(absolutePath)) {
     return { ok: false, relativePath, reason: `path does not exist: ${relativePath}` };

package/src/cli/mcp/repository-tools.ts

@@ -2,6 +2,10 @@ import { bindRepositoryEntities } from '../repositories/entity-migration';
 import { bootstrapLocalProject, diagnoseLatestLocalProjectSource } from '../repositories/local-project-onboarding';
 import { resolveEphemeralWorkspaceTarget } from '../repositories/ephemeral-workspace';
 import type { ResolvedExecutionIdentity } from '../../runtime/control-plane/execution/execution-identity';
+import { readExecutionSession } from '../../runtime/control-plane/execution/session-store';
+import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
+import { getControllerSession, listControllerSessions } from '../../runtime/control-plane/facade/controller-session-store';
+import { isTerminalWorkContractStatus } from '../../runtime/control-plane/facade/types';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../repositories/command-executor';
 import { withControllerLock } from '../repositories/locks';
 import {
@@ -9,6 +13,7 @@ import {
   findIdenticalRepositoryRegistration,
   getRepository,
   listRepositories,
+  reconcileRepositoryCheckouts,
   refreshRepository,
   registerRepository,
   removeRepository,
@@ -19,7 +24,7 @@ import {
 } from '../repositories/registry';
 import { buildControllerWorkbench } from '../repositories/workbench';
 import { applySafePatch, buildSafePatchPlan } from '../repositories/safe-patch';
-import { getEditSessionDiff } from '../editing/edit-session';
+import { getEditSessionDiff, type EditSessionBinding } from '../editing/edit-session';
 import { buildSyncOperationDigest, classifyUserFacingError } from '../../runtime/control-plane/facade/operation-digest';
 import { diagnoseRepositoryStuckState, listRepositoryGoalRuns, readRepositoryGoalRegistry, runRepositoryGoal, upsertRepositoryGoal } from '../repositories/goal-registry';
 import {
@@ -49,6 +54,7 @@ import {
   executeRepositoryCommandViaProcessRuntime,
 } from '../../runtime/execution/process-runtime/command-facade';
 import { assessWorkMode, parseExplicitTaskMode } from '../controller/work-mode';
+import { normalizeRepositoryCommand } from '../repositories/command-normalization';
 import type { CallToolResult, McpToolDefinition } from './tools';
 import {
   boundUtf8,
@@ -240,6 +246,7 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
   definition('repository_safe_patch_apply', 'Apply one coherent deterministic edit batch and return bounded review evidence. Checks are opt-in: pass check_ids only when the batch is stable. Long checks return managed Process handles instead of blocking the MCP call; use validation_only with the returned session/request ids to join later without replaying the patch.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
+    work_id: { type: 'string', description: 'Optional durable Work identity. Workflow controllers should pass the exact claimed Work id so attribution survives transient MCP transport sessions.' },
     session_id: { type: 'string', description: 'Existing edit session id. Required for validation_only; otherwise omit to create one.' },
     purpose: { type: 'string', description: 'Purpose for a newly created edit session.' },
     operations: { type: 'array', items: { type: 'object' }, description: 'Edit operations using the same shape as apply_patch. Required unless validation_only=true.' },
@@ -266,6 +273,7 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
   definition('repository_command_execute', 'Execute one repository-scoped local command through Full Access, Goal delegation, or a resumable approval request. Legacy preview-token callers remain compatible.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
+    work_id: { type: 'string', description: 'Optional durable Work identity. Workflow controllers should pass the exact claimed Work id so attribution survives transient MCP transport sessions.' },
     command: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Legacy shell string or typed argv array. Typed argv executes without a shell.' },
     cwd: { type: 'string', description: 'Optional root-relative working directory.' },
     workspace_root: { type: 'string', description: 'Absolute existing local directory used as an ephemeral execution root. Mutually exclusive with repo_id/checkout_id; does not register or initialize the directory.' },
@@ -302,10 +310,89 @@ function withResponseMeta(payload: Record<string, unknown>, startedAt: number):
   return response;
 }
 
+export interface RepositoryToolCallerContext {
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+}
+
+function claimedSessionWorkId(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  caller?: RepositoryToolCallerContext,
+  explicitWorkId?: unknown,
+): string | undefined {
+  if (!caller?.principalId?.trim()) return undefined;
+  const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
+  if (requestedWorkId) {
+    const work = getWorkContract({ controllerHome, repoId: repository.repoId }, requestedWorkId);
+    if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${requestedWorkId}`);
+    if (work.checkoutId && work.checkoutId !== repository.activeCheckoutId) throw new Error(`WORK_CHECKOUT_MISMATCH: ${requestedWorkId}:${repository.activeCheckoutId}`);
+    const owner = getControllerSession({ controllerHome, repoId: repository.repoId }, requestedWorkId);
+    if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${requestedWorkId}`);
+    if ((owner.principalId?.trim() || owner.controllerId) !== caller.principalId.trim()) throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${requestedWorkId}`);
+    return requestedWorkId;
+  }
+  if (caller.sessionId?.trim()) {
+    const executionSession = readExecutionSession(controllerHome, {
+      sessionId: caller.sessionId,
+      principalId: caller.principalId,
+      controllerInstanceId: caller.controllerInstanceId,
+    });
+    const workId = executionSession?.activeWorkId?.trim();
+    if (workId && executionSession?.activeRepositoryId === repository.repoId && (!executionSession.activeCheckoutId || executionSession.activeCheckoutId === repository.activeCheckoutId)) {
+      const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+      const owner = getControllerSession({ controllerHome, repoId: repository.repoId }, workId);
+      if (work && !isTerminalWorkContractStatus(work.status) && owner?.sessionId === caller.sessionId && (owner.principalId?.trim() || owner.controllerId) === caller.principalId.trim()) return workId;
+    }
+  }
+  const principal = caller.principalId.trim();
+  const candidates = listControllerSessions({ controllerHome, repoId: repository.repoId })
+    .filter((owner) => (owner.principalId?.trim() || owner.controllerId) === principal)
+    .map((owner) => ({ owner, work: getWorkContract({ controllerHome, repoId: repository.repoId }, owner.workId) }))
+    .filter((entry): entry is { owner: ReturnType<typeof listControllerSessions>[number]; work: NonNullable<ReturnType<typeof getWorkContract>> } => Boolean(entry.work && !isTerminalWorkContractStatus(entry.work.status) && (!entry.work.checkoutId || entry.work.checkoutId === repository.activeCheckoutId)));
+  if (candidates.length === 1) return candidates[0].work.workId;
+  if (candidates.length > 1) throw new Error(`WORK_ATTRIBUTION_AMBIGUOUS: principal ${principal} owns ${candidates.length} active Works on checkout ${repository.activeCheckoutId}`);
+  return undefined;
+}
+
+function claimedSessionEditBinding(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  caller?: RepositoryToolCallerContext,
+  explicitWorkId?: unknown,
+): EditSessionBinding | undefined {
+  const workId = claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId);
+  if (!workId || !caller?.principalId?.trim()) return undefined;
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  if (!work) return undefined;
+  return {
+    workId,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    principalId: caller.principalId.trim(),
+    controllerInstanceId: caller.controllerInstanceId,
+    routeDecisionFingerprint: work.routeDecisionFingerprint,
+  };
+}
+
+function activeWorkflowRawDefaultMergeBlocked(repository: ReturnType<typeof resolveRepositorySelection>, workId: string | undefined, command: unknown): boolean {
+  if (!workId || !repository.defaultBranch) return false;
+  const checkout = repository.checkouts.find((entry) => entry.checkoutId === repository.activeCheckoutId);
+  if (checkout?.branch !== repository.defaultBranch) return false;
+  const normalized = normalizeRepositoryCommand(command);
+  if (normalized.kind === 'argv') {
+    const executable = normalized.executable?.split('/').pop();
+    return executable === 'git' && normalized.args?.[0] === 'merge';
+  }
+  return /(?:^|[;&|]\s*)git\s+merge\b/.test(normalized.shellCommand ?? '');
+}
+
 function resolveRepositoryCommandTarget(
   controllerHome: string,
   args: Record<string, unknown>,
   repoIdValue: string,
+  caller?: RepositoryToolCallerContext,
 ): {
   repository: ReturnType<typeof resolveRepositorySelection>;
   executionIdentity: ResolvedExecutionIdentity;
@@ -336,6 +423,7 @@ function resolveRepositoryCommandTarget(
     controllerHome,
     allowSoleRepository: true,
   });
+  const workId = claimedSessionWorkId(controllerHome, repository, caller, args.work_id);
   return {
     repository,
     executionIdentity: {
@@ -344,6 +432,7 @@ function resolveRepositoryCommandTarget(
       repositoryId: repository.repoId,
       checkoutId: repository.activeCheckoutId,
       canonicalRoot: repository.canonicalRoot,
+      ...(workId ? { workId } : {}),
     },
   };
 }
@@ -551,6 +640,18 @@ function emptyRepositoryMigration(repository: ReturnType<typeof registerReposito
   };
 }
 
+function registrationOnlyMetadataRefresh(
+  match: ReturnType<typeof findIdenticalRepositoryRegistration>,
+): boolean {
+  if (!match || match.identical || match.reasons.length === 0) return false;
+  const metadataReasons = new Set([
+    'remote_identity_changed',
+    'default_branch_changed',
+    'display_name_changed',
+  ]);
+  return match.reasons.every((reason) => metadataReasons.has(reason));
+}
+
 function registrationOnlyAttachedExistingWorktree(repository: ReturnType<typeof registerRepository>): boolean {
   const selected = repository.checkouts.find((checkout) => checkout.checkoutId === repository.activeCheckoutId);
   return selected?.worktree === true
@@ -561,6 +662,7 @@ export async function callRepositoryTool(
   controllerHome: string,
   name: string,
   args: Record<string, unknown>,
+  caller?: RepositoryToolCallerContext,
 ): Promise<RepositoryToolResult | undefined> {
   if (!name.startsWith('repository_')) return undefined;
   try {
@@ -587,16 +689,17 @@ export async function callRepositoryTool(
             startedAt,
           ));
         }
+        const metadataRefresh = registrationOnlyMetadataRefresh(identical);
         const repository = registerRepository(registerInput);
-        // Adding a worktree checkout to an already registered repository changes
-        // checkout inventory only. Existing Issue/Task entities are already
-        // bound to this repoId, so re-running historical migration is wasted work
-        // and can produce misleading cross-repository rebinding diagnostics.
-        const migration = registrationOnlyAttachedExistingWorktree(repository)
+        // Adding a worktree checkout or changing only display/remote/default-branch
+        // metadata preserves repository + checkout authority. Existing entities
+        // are already bound to the stable repoId, so a historical migration scan
+        // would only add latency and stale unresolved diagnostics.
+        const migration = registrationOnlyAttachedExistingWorktree(repository) || metadataRefresh
           ? emptyRepositoryMigration(repository)
           : bindRepositoryEntities(repository);
         return result(withResponseMeta(
-          summarizeRepositoryRegistration(repository, migration, args.detail_level === 'detail'),
+          summarizeRepositoryRegistration(repository, migration, args.detail_level === 'detail', metadataRefresh),
           startedAt,
         ));
       }
@@ -623,6 +726,11 @@ export async function callRepositoryTool(
       case 'repository_list':
         return result({ repositories: listRepositories(controllerHome, { includeRemoved: args.include_removed === true }).map(repositorySummary) });
       case 'repository_get': {
+        // Repository inspection is also the bounded reconciliation point for
+        // checkout lifecycle drift caused by worktrees being removed outside
+        // Forge. Reuse the existing registry reconciler so stale worktrees are
+        // not exposed as lifecycle=active to automation callers.
+        reconcileRepositoryCheckouts(repoIdValue, controllerHome);
         const repository = getRepository(repoIdValue, controllerHome, { includeRemoved: args.include_removed === true });
         return result(summarizeRepositoryInspection(repository, args.detail_level === 'detail'));
       }
@@ -815,6 +923,7 @@ export async function callRepositoryTool(
           controllerHome,
           allowSoleRepository: true,
         });
+        const binding = claimedSessionEditBinding(controllerHome, repository, caller, args.work_id);
         const applied = withControllerLock(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
@@ -829,6 +938,7 @@ export async function callRepositoryTool(
             continueOnError: args.continue_on_error,
             refreshFingerprints: args.refresh_fingerprints,
             recoverStaleSession: args.recover_stale_session,
+            binding,
           }),
           60_000,
         );
@@ -892,7 +1002,7 @@ export async function callRepositoryTool(
         return ok ? result(payload) : { ...result(payload), isError: true };
       }
       case 'repository_command_preview': {
-        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue);
+        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
         const { repository } = target;
         const execution = withControllerLock(
           controllerHome,
@@ -912,8 +1022,11 @@ export async function callRepositoryTool(
         });
       }
       case 'repository_command_execute': {
-        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue);
+        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
         const { repository, executionIdentity } = target;
+        if (activeWorkflowRawDefaultMergeBlocked(repository, executionIdentity.workId, args.command)) {
+          throw new Error(`WORK_DELIVERY_REQUIRES_FINALIZE: ${executionIdentity.workId} must pass Work verification and use rh_work finalize before default-branch integration`);
+        }
         const timeoutMs = typeof args.timeout_ms === 'number'
           ? args.timeout_ms
           : typeof args.timeout_ms === 'string'
@@ -972,6 +1085,7 @@ export async function callRepositoryTool(
                 maxOutputBytes,
                 returnHandleImmediately,
                 requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                workId: executionIdentity.workId,
                 executionIdentity,
                 allowNonGitWorkspace: target.workspace !== undefined,
               });
@@ -1111,6 +1225,7 @@ export async function callRepositoryTool(
                 timeoutMs,
                 maxOutputBytes,
                 requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                workId: executionIdentity.workId,
                 executionIdentity,
               });
               if (processResult.route === 'process_direct') {

package/src/cli/mcp/server.ts

@@ -48,6 +48,38 @@ function recordRequestId(args: Record<string, unknown>, rpcId: string | number |
   return explicit || `mcp-rpc:${rpcId === undefined ? randomUUID() : String(rpcId)}`;
 }
 
+function firstTimingString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+function timingIdentity(value: CallToolResult | undefined): {
+  repoId?: string;
+  workId?: string;
+  processId?: string;
+  route?: string;
+} {
+  if (!value?.structuredContent || typeof value.structuredContent !== 'object' || Array.isArray(value.structuredContent)) return {};
+  const structured = value.structuredContent as Record<string, unknown>;
+  const work = structured.work && typeof structured.work === 'object' && !Array.isArray(structured.work)
+    ? structured.work as Record<string, unknown>
+    : undefined;
+  const process = structured.process && typeof structured.process === 'object' && !Array.isArray(structured.process)
+    ? structured.process as Record<string, unknown>
+    : undefined;
+  const resultRef = structured.resultRef && typeof structured.resultRef === 'object' && !Array.isArray(structured.resultRef)
+    ? structured.resultRef as Record<string, unknown>
+    : undefined;
+  return {
+    repoId: firstTimingString(structured.repoId, structured.repo_id, work?.repositoryId, work?.repoId),
+    workId: firstTimingString(structured.workId, structured.work_id, work?.workId),
+    processId: firstTimingString(structured.processId, structured.process_id, process?.processId, resultRef?.processId),
+    route: firstTimingString(structured.route, structured.path, structured.mode, process?.route),
+  };
+}
+
 function tracedResult(
   value: CallToolResult | undefined,
   traceId: string,
@@ -79,15 +111,18 @@ async function traceControllerMcpRequest(
   name: string,
   args: Record<string, unknown>,
   rpcId: string | number | undefined,
-  handler: () => Promise<CallToolResult>,
+  handler: (requestId: string) => Promise<CallToolResult>,
 ): Promise<CallToolResult> {
+  const startedAtWall = new Date().toISOString();
   const startedAt = performance.now();
   const traceId = randomUUID();
   const requestId = recordRequestId(args, rpcId);
   let outcome: 'ok' | 'error' | 'exception' = 'ok';
   let errorCode: string | undefined;
+  let executionIdentity: ReturnType<typeof timingIdentity> = {};
   try {
-    const value = await handler();
+    const value = await handler(requestId);
+    executionIdentity = timingIdentity(value);
     if (value?.isError) {
       outcome = 'error';
       const error = value.structuredContent && typeof value.structuredContent === 'object'
@@ -133,8 +168,11 @@ async function traceControllerMcpRequest(
       traceId,
       requestId,
       ...(rpcId === undefined ? {} : { rpcId }),
+      layer: ctx.runtimeSourceRoot ? 'canonical_runtime' : 'public_gateway',
+      startedAt: startedAtWall,
       outcome,
       ...(errorCode ? { errorCode } : {}),
+      ...executionIdentity,
       totalToolDurationMs: Math.round((performance.now() - startedAt) * 100) / 100,
     });
   }
@@ -215,19 +253,117 @@ export async function readCanonicalRuntimeToolSchema(
   };
 }
 
-async function proxyRuntimeToolCall(
-  ctx: MultiRepositoryMcpToolContext,
-  name: string,
-  args: Record<string, unknown>,
-): Promise<CallToolResult> {
-  return withCanonicalRuntimeClient(ctx, async (client) => {
-    // 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.
-    const response = await client.callTool({ name, arguments: args });
-    return response as unknown as CallToolResult;
-  });
+interface CanonicalRuntimeProxyIdentity {
+  endpoint: URL;
+  token: string;
+  principalId: string;
+  sessionId: string;
+}
+
+function canonicalRuntimeProxyIdentity(ctx: MultiRepositoryMcpToolContext): CanonicalRuntimeProxyIdentity {
+  return {
+    endpoint: canonicalRuntimeEndpoint(ctx),
+    token: canonicalRuntimeToken(ctx),
+    principalId: ctx.principalId?.trim() ?? '',
+    sessionId: ctx.sessionId?.trim() ?? '',
+  };
+}
+
+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;
+}
+
+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;
+
+  const closeCurrent = async (expectedClient?: Client): Promise<void> => {
+    if (!current || (expectedClient && current.client !== expectedClient)) return;
+    const closing = current.client;
+    current = undefined;
+    await closing.close().catch(() => undefined);
+  };
+
+  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}`,
+    };
+    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);
+    }
+  };
+
+  const clientForCurrentRuntime = async (): Promise<Client> => {
+    const identity = canonicalRuntimeProxyIdentity(ctx);
+    if (current && sameCanonicalRuntimeProxyIdentity(current.identity, identity)) return current.client;
+
+    if (connecting) {
+      const pending = await connecting;
+      if (sameCanonicalRuntimeProxyIdentity(pending.identity, identity)) return pending.client;
+    }
+
+    await closeCurrent();
+    connecting = connect(identity);
+    try {
+      current = await connecting;
+      return current.client;
+    } finally {
+      connecting = undefined;
+    }
+  };
+
+  return {
+    async callTool(name, args) {
+      const client = await clientForCurrentRuntime();
+      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.
+        const response = await client.callTool(
+          { name, arguments: args },
+          undefined,
+          { timeout: CANONICAL_RUNTIME_MCP_TIMEOUT_MS },
+        );
+        return response as unknown as CallToolResult;
+      } 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);
+        throw error;
+      }
+    },
+    async close() {
+      if (connecting) {
+        await connecting.catch(() => undefined);
+        connecting = undefined;
+      }
+      await closeCurrent();
+    },
+  };
 }
 
 function canonicalRuntimeSchemaMatchesGateway(ctx: MultiRepositoryMcpToolContext): boolean {
@@ -257,6 +393,12 @@ export function createForgeMcpServerFromContext(
     { name: 'forge-mcp', version: FORGE_VERSION },
     { capabilities: { tools: { listChanged: true } }, instructions: mcpServerInstructions(baseContext.policy.profile) },
   );
+  const runtimeProxy = isMultiRepositoryContext(baseContext) && !getRuntimeWriteClaim()
+    ? createCanonicalRuntimeProxy(baseContext)
+    : undefined;
+  server.onclose = () => {
+    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
   // a stale schema when the bounded Runtime surface changes behind the gateway.
@@ -279,7 +421,7 @@ export function createForgeMcpServerFromContext(
     const ctx: ServerToolContext = { ...baseContext, 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 () => {
+      return traceControllerMcpRequest(ctx, name, args, typeof rpcId === 'string' || typeof rpcId === 'number' ? rpcId : undefined, async (requestId) => {
         // 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.
@@ -304,8 +446,11 @@ export function createForgeMcpServerFromContext(
         // Gateway processes from acquiring Process Runtime leases or evaluating
         // Runtime source coherence against their own checkout.
         if (!getRuntimeWriteClaim()) {
-          if (runtimeSchema) return proxyRuntimeToolCall(ctx, name, args);
-          if (observeRuntimeStatus(ctx.controllerHome).ready) return proxyRuntimeToolCall(ctx, name, args);
+          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);
         }
         const accessResult = callAccessTool(ctx, name, args);
         if (accessResult) return accessResult;
@@ -321,7 +466,7 @@ export function createForgeMcpServerFromContext(
         if (runtimeResult) return runtimeResult;
         const durableResult = await routeDurableMcpCall(ctx, name, args);
         if (durableResult) return durableResult;
-        const repositoryResult = await callRepositoryTool(ctx.controllerHome, name, args);
+        const repositoryResult = await callRepositoryTool(ctx.controllerHome, name, args, ctx);
         if (repositoryResult) return repositoryResult;
         return callMultiRepositoryTool(ctx, name, args);
       });

package/src/cli/mcp/setup.ts

@@ -303,6 +303,7 @@ export function runMcpSetupChatgpt(opts: {
   endpoint?: string;
   serverName?: string;
   localControllerPort?: string;
+  connectorPort?: string;
 }): McpSetupResult {
   const repoRoot = resolveMcpRepoRoot(opts.repo ?? ".");
   const controllerHome = opts.userLevel
@@ -319,6 +320,11 @@ export function runMcpSetupChatgpt(opts: {
     : existingConfig?.localController?.port ?? (parsedPort < 65_535 ? parsedPort + 1 : 8766);
   if (!Number.isInteger(localControllerPort) || localControllerPort < 1 || localControllerPort > 65_535) throw new Error(`forge mcp setup chatgpt: invalid Local Controller port ${opts.localControllerPort}`);
   if (localControllerPort === parsedPort) throw new Error('forge mcp setup chatgpt: Local Controller port must differ from MCP port');
+  const connectorPort = opts.connectorPort !== undefined
+    ? Number(opts.connectorPort)
+    : parsedPort <= 65_533 ? parsedPort + 2 : 8767;
+  if (!Number.isInteger(connectorPort) || connectorPort < 1 || connectorPort > 65_535) throw new Error(`forge mcp setup chatgpt: invalid connector port ${opts.connectorPort}`);
+  if (connectorPort === parsedPort || connectorPort === localControllerPort) throw new Error('forge mcp setup chatgpt: connector port must differ from Runtime and Local Controller ports');
   const existingServerName = existingConfig?.chatgpt?.serverName;
   const migratedServerName =
     existingServerName && !LEGACY_DEFAULT_SERVER_NAMES.has(existingServerName)
@@ -356,6 +362,7 @@ export function runMcpSetupChatgpt(opts: {
       ...existingConfig?.chatgpt,
       serverName,
       ...(endpoint ? { endpoint } : {}),
+      localEndpoint: `http://127.0.0.1:${connectorPort}/mcp`,
     },
     profile: existingConfig?.profile ?? "controller",
     toolset,
@@ -421,7 +428,8 @@ export function runMcpSetupChatgpt(opts: {
       "[forge mcp] Profile: controller",
       `[forge mcp] Toolset: ${config.toolset}`,
       `[forge mcp] ChatGPT MCP server name: ${serverName}`,
-      `[forge mcp] Local endpoint: http://${host}:${port}/mcp`,
+      `[forge mcp] Internal Runtime endpoint: http://${host}:${port}/mcp`,
+      `[forge mcp] ChatGPT local OAuth endpoint: http://127.0.0.1:${connectorPort}/mcp`,
       `[forge mcp] Local Controller: http://${config.localController.host}:${config.localController.port}/`,
       `[forge mcp] Optional external delegation: ${config.devMode.agentRunner ? `enabled (${config.devMode.allowedAgents.join(',') || 'none'})` : 'disabled'}`,
       endpoint