@moretea-labs/forge 1.5.1 → 1.6.0

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/transports/http.ts

@@ -1,4 +1,6 @@
 import { randomUUID, timingSafeEqual } from 'crypto';
+import { existsSync, watch } from 'fs';
+import { dirname } from 'path';
 import express, { type Request, type Response, type NextFunction } from 'express';
 import { tokenHandler } from '@modelcontextprotocol/sdk/server/auth/handlers/token.js';
 import { revocationHandler } from '@modelcontextprotocol/sdk/server/auth/handlers/revoke.js';
@@ -37,7 +39,7 @@ import { readForgeRuntimeStatus } from '../../../runtime/control-plane/runtime-s
 import { runtimeIdentitySnapshot } from '../../../runtime/gateway/mcp/runtime-tools';
 import { projectionBlocksReadiness, readRepositoryProjectionSnapshot } from '../../../runtime/projections/materialized-view';
 import { readRuntimeGeneration } from '../../../runtime/control-plane/runtime-generation';
-import { readRuntimeStatusSnapshot } from '../../../runtime/root/status';
+import { readRuntimeStatusSnapshot, runtimeStatusPath } from '../../../runtime/root/status';
 import { getRepository, listRepositories } from '../../repositories/registry';
 import { buildControllerTaskLedgerProjection } from '../../controller/task-ledger';
 import { legacyIssueAuthorityRetired } from '../../controller/legacy-issue-cutover';
@@ -740,6 +742,7 @@ async function handleMcpPost(
         principalId,
       });
       const runtimeSchema = await resolveRuntimeSchema?.(sessionContext);
+      let server: ReturnType<typeof createForgeMcpServerFromContext> | undefined;
       transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         onsessioninitialized: (newSessionId: string): void => {
@@ -752,6 +755,7 @@ async function handleMcpPost(
             clientIdentity,
             toolSurfaceFingerprint: runtimeSchema?.fingerprint ?? currentToolSurfaceFingerprint(),
             toolNames: runtimeSchema?.toolNames,
+            notifyToolListChanged: async () => { await server?.sendToolListChanged(); },
           });
           initializedSessionId = newSessionId;
         },
@@ -759,7 +763,7 @@ async function handleMcpPost(
       transport.onclose = () => {
         if (transport?.sessionId) registry.detach(transport.sessionId);
       };
-      const server = createForgeMcpServerFromContext(sessionContext, runtimeSchema);
+      server = createForgeMcpServerFromContext(sessionContext, runtimeSchema);
       await server.connect(transport);
       await transport.handleRequest(req, res, body);
     } finally {
@@ -917,6 +921,23 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const currentRuntimeToolSurfaceFingerprint = () => runtimeControllerHome
     ? readRuntimeStatusSnapshot(runtimeControllerHome)?.toolSurfaceFingerprint
     : undefined;
+  let observedRuntimeToolSurfaceFingerprint = currentRuntimeToolSurfaceFingerprint();
+  let toolSurfaceNotificationTimer: ReturnType<typeof setTimeout> | undefined;
+  const runtimeStatusDirectory = runtimeControllerHome ? dirname(runtimeStatusPath(runtimeControllerHome)) : undefined;
+  const runtimeStatusWatcher = runtimeStatusDirectory && existsSync(runtimeStatusDirectory)
+    ? watch(runtimeStatusDirectory, { persistent: false }, (_event, filename) => {
+      if (String(filename ?? '') !== 'status.json') return;
+      if (toolSurfaceNotificationTimer) clearTimeout(toolSurfaceNotificationTimer);
+      toolSurfaceNotificationTimer = setTimeout(() => {
+        const currentFingerprint = currentRuntimeToolSurfaceFingerprint();
+        if (!currentFingerprint || currentFingerprint === observedRuntimeToolSurfaceFingerprint) return;
+        observedRuntimeToolSurfaceFingerprint = currentFingerprint;
+        void sessionRegistry.notifyToolListChanged(currentFingerprint);
+      }, 25);
+      toolSurfaceNotificationTimer.unref();
+    })
+    : undefined;
+  runtimeStatusWatcher?.on('error', () => undefined);
   const resolveRuntimeSchema = runtimeControllerHome
     ? async (context: McpToolContext): Promise<CanonicalRuntimeToolSchema | undefined> => {
       if (!('controllerHome' in context)) return undefined;
@@ -1260,6 +1281,8 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
 
   httpServer.on('close', () => {
     clearInterval(cleanupTimer);
+    if (toolSurfaceNotificationTimer) clearTimeout(toolSurfaceNotificationTimer);
+    runtimeStatusWatcher?.close();
     void sessionRegistry.closeAll('shutdown');
   });
 

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

@@ -31,6 +31,9 @@ export interface ManagedMcpSession<
   toolSurfaceFingerprint?: string;
   /** Exact tool names returned by the Canonical Runtime at initialize time. */
   toolNames?: string[];
+  /** Standard MCP tools/list_changed notification bound to this session's connected Server. */
+  notifyToolListChanged?: () => Promise<void> | void;
+  lastNotifiedToolSurfaceFingerprint?: string;
   createdAt: number;
   lastActivityAt: number;
   streamOpenedAt?: number;
@@ -88,6 +91,7 @@ interface RegisterMcpSession<TTransport extends ClosableMcpTransport, TContext>
   clientIdentity: string;
   toolSurfaceFingerprint?: string;
   toolNames?: string[];
+  notifyToolListChanged?: () => Promise<void> | void;
   initialPost?: boolean;
 }
 
@@ -206,6 +210,26 @@ export class McpSessionRegistry<
     if (session) session.lastActivityAt = this.now();
   }
 
+  async notifyToolListChanged(currentFingerprint: string | undefined): Promise<number> {
+    if (!currentFingerprint) return 0;
+    let notified = 0;
+    await Promise.all(Array.from(this.sessions.values()).map(async (session) => {
+      if (!session.toolSurfaceFingerprint
+        || session.toolSurfaceFingerprint === currentFingerprint
+        || session.lastNotifiedToolSurfaceFingerprint === currentFingerprint
+        || !session.notifyToolListChanged) return;
+      try {
+        await session.notifyToolListChanged();
+        session.lastNotifiedToolSurfaceFingerprint = currentFingerprint;
+        notified += 1;
+      } catch {
+        // Fingerprint fencing remains authoritative. A broken notification
+        // stream must not mark a stale session as refreshed or close active work.
+      }
+    }));
+    return notified;
+  }
+
   beginPost(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
     const session = this.sessions.get(sessionId);
     if (!session) return undefined;