@moretea-labs/forge 1.7.0 → 1.7.2

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

@@ -2,9 +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 { assertNoBoundExecutionSessionMutation, resolveClaimedRepositoryWorkId, resolveExplicitClaimedRepositoryWork, type RepositoryWorkAttributionCaller } from '../../runtime/control-plane/execution/repository-work-attribution';
 import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
-import { getControllerSession, listControllerSessions } from '../../runtime/control-plane/facade/controller-session-store';
+import { assertWorkPathsWithinScope } from '../../runtime/control-plane/execution/work-path-scope';
+import { ensureRepositoryMutationWorkHandle } from '../../runtime/control-plane/execution/work-handle-authority';
 import { isTerminalWorkContractStatus } from '../../runtime/control-plane/facade/types';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../repositories/command-executor';
 import { withControllerLock } from '../repositories/locks';
@@ -53,11 +54,12 @@ import {
   executeRepositoryCommandViaProcessRuntime,
 } from '../../runtime/execution/process-runtime/command-facade';
 import { assessWorkMode, parseExplicitTaskMode } from '../controller/work-mode';
+import { classifyRepositoryCommand } from '../repositories/command-classifier';
 import { normalizeRepositoryCommand } from '../repositories/command-normalization';
 import { readRepositoryRange } from '../repository/inspector';
 import { getMcpPolicy } from './policy';
 import { redactMcpText } from './redaction';
-import type { CallToolResult, McpToolDefinition } from './tools';
+import type { CallToolResult, McpToolDefinition } from './tool-contract';
 import {
   boundUtf8,
   compactCommandOutput,
@@ -287,87 +289,7 @@ function withResponseMeta(payload: Record<string, unknown>, startedAt: number):
   return response;
 }
 
-export interface RepositoryToolCallerContext {
-  sessionId?: string;
-  principalId?: string;
-  controllerInstanceId?: string;
-}
-
-function claimedExplicitWork(
-  controllerHome: string,
-  repoId: string,
-  caller: RepositoryToolCallerContext | undefined,
-  requestedWorkId: string,
-) {
-  if (!caller?.principalId?.trim()) return undefined;
-  const work = getWorkContract({ controllerHome, repoId }, requestedWorkId);
-  if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${requestedWorkId}`);
-  const owner = getControllerSession({ controllerHome, 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 work;
-}
-
-function assertNoBoundExecutionSessionMutation(
-  controllerHome: string,
-  repository: ReturnType<typeof resolveRepositorySelection>,
-  caller?: RepositoryToolCallerContext,
-): void {
-  if (!caller?.principalId?.trim() || !caller.sessionId?.trim()) return;
-  const executionSession = readExecutionSession(controllerHome, {
-    sessionId: caller.sessionId,
-    principalId: caller.principalId,
-    controllerInstanceId: caller.controllerInstanceId,
-  });
-  const workId = executionSession?.activeWorkId?.trim();
-  if (!workId || executionSession?.activeRepositoryId !== repository.repoId) return;
-  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
-  if (!work) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
-  if (isTerminalWorkContractStatus(work.status)) {
-    throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
-  }
-  throw new Error(`WORK_ATTRIBUTION_REQUIRED: ${work.workId}; active execution session mutations must pass work_id explicitly`);
-}
-
-function claimedSessionWorkId(
-  controllerHome: string,
-  repository: ReturnType<typeof resolveRepositorySelection>,
-  caller?: RepositoryToolCallerContext,
-  explicitWorkId?: unknown,
-): string | undefined {
-  const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
-  if (requestedWorkId) {
-    const work = claimedExplicitWork(controllerHome, repository.repoId, caller, requestedWorkId);
-    if (!work) return undefined;
-    if (work.checkoutId && work.checkoutId !== repository.activeCheckoutId) throw new Error(`WORK_CHECKOUT_MISMATCH: ${requestedWorkId}:${repository.activeCheckoutId}`);
-    return requestedWorkId;
-  }
-  if (!caller?.principalId?.trim()) return undefined;
-  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);
-      if (work && isTerminalWorkContractStatus(work.status)) {
-        throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
-      }
-      const owner = getControllerSession({ controllerHome, repoId: repository.repoId }, workId);
-      if (work && 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;
-}
+export type RepositoryToolCallerContext = RepositoryWorkAttributionCaller;
 
 export function claimedSessionEditBinding(
   controllerHome: string,
@@ -375,7 +297,7 @@ export function claimedSessionEditBinding(
   caller?: RepositoryToolCallerContext,
   explicitWorkId?: unknown,
 ): EditSessionBinding | undefined {
-  const workId = claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId);
+  const workId = resolveClaimedRepositoryWorkId(controllerHome, repository, caller, explicitWorkId);
   if (!workId || !caller?.principalId?.trim()) return undefined;
   const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
   if (!work) return undefined;
@@ -423,7 +345,7 @@ function resolveRepositorySelectionForClaimedWork(
     allowSoleRepository: true,
   });
   if (!explicitWorkId || checkoutId) return repository;
-  const work = claimedExplicitWork(controllerHome, repository.repoId, caller, explicitWorkId);
+  const work = resolveExplicitClaimedRepositoryWork(controllerHome, repository, caller, explicitWorkId);
   if (!work?.checkoutId || work.checkoutId === repository.activeCheckoutId) return repository;
   return resolveRepositorySelection({
     repoId: repository.repoId,
@@ -445,6 +367,32 @@ function rawDefaultBranchMergeCommand(repository: ReturnType<typeof resolveRepos
   return /(?:^|[;&|]\s*)git\s+merge\b/.test(normalized.shellCommand ?? '');
 }
 
+interface HistoricalReadOnlyWorkContext {
+  workId: string;
+  status: string;
+  mode: 'historical_read_only_observation';
+  attribution: 'not_active_work';
+}
+
+function historicalReadOnlyWorkContext(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  args: Record<string, unknown>,
+): HistoricalReadOnlyWorkContext | undefined {
+  const requestedWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (!requestedWorkId) return undefined;
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, requestedWorkId);
+  if (!work || !isTerminalWorkContractStatus(work.status)) return undefined;
+  const classification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
+  if (classification.risk !== 'readonly') return undefined;
+  return {
+    workId: work.workId,
+    status: work.status,
+    mode: 'historical_read_only_observation',
+    attribution: 'not_active_work',
+  };
+}
+
 function resolveRepositoryCommandTarget(
   controllerHome: string,
   args: Record<string, unknown>,
@@ -454,6 +402,7 @@ function resolveRepositoryCommandTarget(
   repository: ReturnType<typeof resolveRepositorySelection>;
   executionIdentity: ResolvedExecutionIdentity;
   workspace?: { workspaceId: string; root: string; registered: false };
+  historicalWorkContext?: HistoricalReadOnlyWorkContext;
 } {
   const workspaceRoot = typeof args.workspace_root === 'string' ? args.workspace_root.trim() : '';
   const checkoutId = typeof args.checkout_id === 'string' ? args.checkout_id.trim() : '';
@@ -474,10 +423,37 @@ function resolveRepositoryCommandTarget(
       workspace: { workspaceId: target.workspaceId, root: target.canonicalRoot, registered: false },
     };
   }
+  // A terminal Work no longer owns mutation or checkout authority. An exact
+  // terminal work_id may still accompany a read-only observation immediately
+  // after finalize, so preserve it as explicit historical context while
+  // executing against the caller-selected/current repository checkout. Any
+  // non-read-only command continues through claimed Work resolution and fails
+  // closed for terminal attribution.
+  const selectedRepository = resolveRepositorySelection({
+    repoId: repoIdValue || undefined,
+    checkoutId: checkoutId || undefined,
+    controllerHome,
+    allowSoleRepository: true,
+  });
+  const historicalWorkContext = historicalReadOnlyWorkContext(controllerHome, selectedRepository, args);
+  if (historicalWorkContext) {
+    return {
+      repository: selectedRepository,
+      executionIdentity: {
+        schemaVersion: 1,
+        authority: 'repository',
+        repositoryId: selectedRepository.repoId,
+        checkoutId: selectedRepository.activeCheckoutId,
+        canonicalRoot: selectedRepository.canonicalRoot,
+      },
+      historicalWorkContext,
+    };
+  }
+
   const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
   const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
   const workId = explicitWorkId
-    ? claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId)
+    ? resolveClaimedRepositoryWorkId(controllerHome, repository, caller, explicitWorkId)
     : undefined;
   return {
     repository,
@@ -615,6 +591,7 @@ function compactProcessCommandPayload(input: {
   repoId: string;
   checkoutId?: string;
   workspace?: { workspaceId: string; root: string; registered: false };
+  historicalWorkContext?: HistoricalReadOnlyWorkContext;
   processId?: string;
   process?: unknown;
   completed?: boolean;
@@ -653,6 +630,7 @@ function compactProcessCommandPayload(input: {
       repoId: input.repoId,
       ...(input.checkoutId ? { checkoutId: input.checkoutId } : {}),
       ...(input.workspace ? { workspace: input.workspace } : {}),
+      ...(input.historicalWorkContext ? { historicalWorkContext: input.historicalWorkContext } : {}),
       ...(input.processId ? { processId: input.processId } : {}),
       ...(completed ? { exitCode: input.exitCode ?? (ok ? 0 : 1) } : {}),
       // A running default response otherwise loses its only dependency-bound
@@ -693,6 +671,7 @@ function compactProcessCommandPayload(input: {
     repoId: input.repoId,
     ...(input.checkoutId ? { checkoutId: input.checkoutId } : {}),
     ...(input.workspace ? { workspace: input.workspace } : {}),
+    ...(input.historicalWorkContext ? { historicalWorkContext: input.historicalWorkContext } : {}),
     ...(input.processId ? { processId: input.processId } : {}),
     ok: input.ok,
     exitCode: input.exitCode,
@@ -998,22 +977,42 @@ export async function callRepositoryTool(
       case 'repository_safe_patch_apply': {
         const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
         const binding = safePatchEditBinding(controllerHome, repository, caller, args);
+        if (binding?.workId) {
+          const work = getWorkContract({ controllerHome, repoId: repository.repoId }, binding.workId);
+          if (!work) throw new Error(`WORK_NOT_FOUND: ${binding.workId}`);
+          const requestedPaths = buildSafePatchPlan(repository, { operations: args.operations, chunkSize: args.chunk_size })
+            .chunks.flatMap((chunk) => chunk.paths);
+          assertWorkPathsWithinScope(work, requestedPaths, {
+            forbidden: 'WORK_MUTATION_FORBIDDEN_PATH',
+            outOfScope: 'WORK_MUTATION_PATH_OUT_OF_SCOPE',
+          });
+        }
         const applied = withControllerLock(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
           'mcp:repository_safe_patch_apply',
-          () => applySafePatch(repository, {
-            sessionId: args.session_id,
-            purpose: args.purpose,
-            operations: args.operations,
-            chunkSize: args.chunk_size,
-            expectedRevision: args.expected_revision,
-            allowedPaths: args.allowed_paths,
-            continueOnError: args.continue_on_error,
-            refreshFingerprints: args.refresh_fingerprints,
-            recoverStaleSession: args.recover_stale_session,
-            binding,
-          }),
+          () => {
+            if (binding?.workId) {
+              ensureRepositoryMutationWorkHandle({
+                controllerHome,
+                repository,
+                workId: binding.workId,
+                principalId: binding.principalId ?? caller?.principalId ?? '',
+              });
+            }
+            return applySafePatch(repository, {
+              sessionId: args.session_id,
+              purpose: args.purpose,
+              operations: args.operations,
+              chunkSize: args.chunk_size,
+              expectedRevision: args.expected_revision,
+              allowedPaths: args.allowed_paths,
+              continueOnError: args.continue_on_error,
+              refreshFingerprints: args.refresh_fingerprints,
+              recoverStaleSession: args.recover_stale_session,
+              binding,
+            });
+          },
           60_000,
         );
         const changedFiles = [
@@ -1098,7 +1097,7 @@ export async function callRepositoryTool(
       case 'repository_command_execute': {
         const explorationGuidance = fragmentedRepositoryExplorationGuidance(args.command);
         const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
-        const { repository, executionIdentity } = target;
+        const { repository, executionIdentity, historicalWorkContext } = target;
         const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
         if (!explicitWorkId) assertNoBoundExecutionSessionMutation(controllerHome, repository, caller);
         const deliveryWorkId = rawDefaultBranchMergeCommand(repository, args.command)
@@ -1107,6 +1106,23 @@ export async function callRepositoryTool(
         if (deliveryWorkId) {
           throw new Error(`WORK_DELIVERY_REQUIRES_FINALIZE: ${deliveryWorkId} must pass Work verification and use rh_work finalize before default-branch integration`);
         }
+        if (executionIdentity.workId) {
+          const mutationClassification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
+          if (mutationClassification.risk === 'workspace_write' || mutationClassification.risk === 'destructive') {
+            withControllerLock(
+              controllerHome,
+              { scope: 'repository', repoId: repository.repoId },
+              'mcp:repository_command_execute:mutation-authority',
+              () => ensureRepositoryMutationWorkHandle({
+                controllerHome,
+                repository,
+                workId: executionIdentity.workId!,
+                principalId: caller?.principalId ?? '',
+              }),
+              60_000,
+            );
+          }
+        }
         const timeoutMs = typeof args.timeout_ms === 'number'
           ? args.timeout_ms
           : typeof args.timeout_ms === 'string'
@@ -1206,6 +1222,13 @@ export async function callRepositoryTool(
               });
             }
             if (routeClass.route === 'process_direct' || routeClass.route === 'process_managed' || routeClass.route === 'durable') {
+              const processRequestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+              if (executionIdentity.workId && !processRequestId) {
+                throw new Error(
+                  `WORK_PROCESS_REQUEST_ID_REQUIRED: ${executionIdentity.workId}; `
+                  + 'Work-attributed Process Runtime commands require a stable request_id so reconnect/retry can resume the original Process without duplicate execution.',
+                );
+              }
               const processResult = await executeRepositoryCommandViaProcessRuntime({
                 controllerHome,
                 repository,
@@ -1217,7 +1240,7 @@ export async function callRepositoryTool(
                   : typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : undefined,
                 maxOutputBytes,
                 returnHandleImmediately,
-                requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                requestId: processRequestId || undefined,
                 workId: executionIdentity.workId,
                 executionIdentity,
                 allowNonGitWorkspace: target.workspace !== undefined,
@@ -1272,6 +1295,7 @@ export async function callRepositoryTool(
                   repoId: repository.repoId,
                   checkoutId: repository.activeCheckoutId,
                   workspace: target.workspace,
+                  historicalWorkContext,
                   processId: handle?.processId,
                   process: detailLevel === 'detail' ? handle : undefined,
                   completed,

package/src/cli/mcp/server.ts

@@ -13,7 +13,7 @@ import {
   type MultiRepositoryMcpToolContext,
 } from './multi-repository';
 import { callAccessTool } from './access-tools';
-import { callRepositoryTool } from './repository-tools';
+import { callRepositoryToolWithPostFinalizeAttribution } from './post-finalize-work-attribution';
 import { callRuntimeTool } from '../../runtime/gateway/mcp/runtime-tools';
 import { callExecutionTool } from '../../runtime/gateway/mcp/execution-tools';
 import { callProcessTool } from '../../runtime/gateway/mcp/process-tools';
@@ -450,6 +450,36 @@ export function sameCanonicalRuntimeProxyIdentity(
     && left.runtimeInstanceId === right.runtimeInstanceId;
 }
 
+export function canonicalRuntimeToolCallIsReplaySafe(name: string, args: Record<string, unknown>): boolean {
+  if (name !== 'repository_command_execute') return false;
+  const workId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+  return Boolean(workId && requestId);
+}
+
+export function canonicalRuntimeToolCallFailureIsTransient(error: unknown): boolean {
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error ?? '');
+  return /Connection closed|socket[^\n]*closed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|UND_ERR_SOCKET|fetch failed|MCP_REQUEST_FAILED/i.test(message);
+}
+
+export async function callCanonicalRuntimeToolWithReplay<T>(input: {
+  name: string;
+  args: Record<string, unknown>;
+  call: () => Promise<T>;
+  reconnect: () => Promise<void>;
+}): Promise<T> {
+  try {
+    return await input.call();
+  } catch (error) {
+    if (!canonicalRuntimeToolCallIsReplaySafe(input.name, input.args)
+      || !canonicalRuntimeToolCallFailureIsTransient(error)) {
+      throw error;
+    }
+    await input.reconnect();
+    return await input.call();
+  }
+}
+
 export interface CanonicalRuntimeProxy {
   listTools(): Promise<{ tools: Tool[] }>;
   callTool(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>, timing?: MutableGatewayProxyTiming): Promise<CallToolResult>;
@@ -743,22 +773,36 @@ export function createCanonicalRuntimeProxy(ctx: MultiRepositoryMcpToolContext):
       }
     },
     async callTool(callerContext, name, args, timing = {}) {
-      const { laneId, client } = await prepareLane(timing, name === 'process_wait' ? 'wait' : 'interactive');
+      const prepared = await prepareLane(timing, name === 'process_wait' ? 'wait' : 'interactive');
+      const laneId = prepared.laneId;
+      let activeClient = prepared.client;
       const gatewayCallStartedAtMs = Date.now();
       const callStarted = performance.now();
+      const forwardedRequest = {
+        name,
+        arguments: args,
+        _meta: canonicalRuntimeForwardingMeta(callerContext),
+      } as Parameters<Client['callTool']>[0];
       try {
         // The outer Connector session is already bound to the Canonical Runtime
         // schema and fenced by the Runtime-published fingerprint before dispatch.
         // Caller identity stays request-scoped while the inner MCP lane is reused.
-        const response = await client.callTool(
-          {
-            name,
-            arguments: args,
-            _meta: canonicalRuntimeForwardingMeta(callerContext),
-          } as Parameters<Client['callTool']>[0],
-          undefined,
-          { timeout: CANONICAL_RUNTIME_TOOL_CALL_TIMEOUT_MS },
-        );
+        // Only keyed Work-attributed Process Runtime commands may replay after a
+        // transient inner disconnect: the stable request_id resolves to the
+        // original Process instead of spawning the side effect twice.
+        const response = await callCanonicalRuntimeToolWithReplay({
+          name,
+          args,
+          call: async () => await activeClient.callTool(
+            forwardedRequest,
+            undefined,
+            { timeout: CANONICAL_RUNTIME_TOOL_CALL_TIMEOUT_MS },
+          ),
+          reconnect: async () => {
+            await closeLane(laneId, activeClient);
+            activeClient = await clientForCurrentRuntime(laneId, timing);
+          },
+        });
         const result = response as unknown as CallToolResult;
         timing.gatewayProxyCallMs = roundedMs(performance.now() - callStarted);
         Object.assign(timing, deriveCanonicalForwardingTiming({
@@ -771,7 +815,7 @@ export function createCanonicalRuntimeProxy(ctx: MultiRepositoryMcpToolContext):
         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);
+        await closeLane(laneId, activeClient);
         throw error;
       } finally {
         scheduler.release(laneId);
@@ -892,7 +936,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, ctx);
+        const repositoryResult = await callRepositoryToolWithPostFinalizeAttribution(ctx.controllerHome, name, args, ctx);
         if (repositoryResult) return repositoryResult;
         return callMultiRepositoryTool(ctx, name, args);
       });

package/src/cli/mcp/tool-contract.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult as SdkCallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+/** Transport-neutral MCP tool schema used by legacy, repository and Runtime surfaces. */
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+}
+
+/** Bounded text-first result contract shared by Forge MCP adapters. */
+export type CallToolResult = Omit<SdkCallToolResult, 'content'> & {
+  content: Array<{ type: 'text'; text: string }>;
+};

package/src/cli/mcp/toolset.ts

@@ -1,4 +1,4 @@
-import type { McpToolDefinition } from './tools';
+import type { McpToolDefinition } from './tool-contract';
 import type { MultiRepositoryMcpToolContext } from './multi-repository';
 import { buildMultiRepositoryToolDefinitions } from './multi-repository';
 import { accessToolDefinitions } from './access-tools';
@@ -7,7 +7,7 @@ import {
   type ControllerAccessState,
 } from './access-mode';
 import { repositoryToolDefinitions } from './repository-tools';
-import { runtimeToolDefinitions } from '../../runtime/gateway/mcp/runtime-tools';
+import { runtimeToolDefinitions } from '../../runtime/gateway/mcp/runtime-tool-definitions';
 import { executionToolDefinitions } from '../../runtime/gateway/mcp/execution-tools';
 import { processToolDefinitions } from '../../runtime/gateway/mcp/process-tools';
 import { injectDurableCommandFields } from '../../runtime/gateway/mcp/router';

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

@@ -1125,6 +1125,29 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
     });
   });
 
+  // Recovery probes this endpoint every few seconds. Keep it strictly in-memory
+  // and transport-scoped: whole-control-plane readiness below may traverse every
+  // repository projection and probe the local bridge, which must never become a
+  // periodic event-loop load generator for the public MCP Connector itself.
+  app.get('/transport-ready', (_req, res) => {
+    const sessionSnapshot = sessionRegistry.snapshot();
+    const sessionCapacityReady = sessionSnapshot.acceptingNewSessions
+      && runtimeStats.initializing < MAX_INITIALIZING_SESSIONS
+      && runtimeStats.activePosts < MAX_ACTIVE_POSTS;
+    res.status(sessionCapacityReady ? 200 : 503).json({
+      ready: sessionCapacityReady,
+      profile: toolContext.policy.profile,
+      gateway: sessionCapacityReady ? 'ready' : 'saturated',
+      sessionCapacity: sessionSnapshot,
+      runtimeCapacity: {
+        initializing: runtimeStats.initializing,
+        maximumInitializing: MAX_INITIALIZING_SESSIONS,
+        activePosts: runtimeStats.activePosts,
+        maximumActivePosts: MAX_ACTIVE_POSTS,
+      },
+    });
+  });
+
   app.get('/ready', async (_req, res) => {
     const runtimeGeneration = currentRuntimeGeneration();
     const sessionSnapshot = sessionRegistry.snapshot();

package/src/cli/repositories/command-classifier.ts

@@ -42,7 +42,7 @@ const READ_ONLY_GIT_SUBCOMMANDS = new Set([
   'count-objects', 'verify-pack', 'check-ignore',
 ]);
 
-function shellSegments(command: string): string[] {
+export function shellSegments(command: string): string[] {
   const segments: string[] = [];
   let current = '';
   let quote: "'" | '"' | undefined;
@@ -87,7 +87,7 @@ function shellSegments(command: string): string[] {
   return segments;
 }
 
-function shellWordsPreservingQuotes(segment: string): string[] {
+export function shellWordsPreservingQuotes(segment: string): string[] {
   const words: string[] = [];
   let current = '';
   let quote: "'" | '"' | undefined;

package/src/cli/repositories/command-executor.ts

@@ -72,6 +72,8 @@ export interface ExecuteRepositoryCommandInput {
   allowNonGitWorkspace?: boolean;
   /** Internal: command-facade already classified this as a bounded local script; retain policy/snapshot/audit without durable Process state. */
   allowOpaqueLocalScript?: boolean;
+  /** Internal/test seam: bound dirty-path fingerprint enrichment independently from child execution lifetime. */
+  snapshotFingerprintTimeoutMs?: number;
 }
 
 
@@ -98,6 +100,8 @@ export interface RepositoryCommandExecution {
   authorizationDecision?: AuthorizationDecision;
   approvalRequestId?: string;
   infrastructureError?: { code: string; message: string };
+  /** Child execution completed, but post-execution repository evidence could not be proven. Mutation state is unknown until a later authoritative inspection. */
+  evidenceError?: { code: string; message: string };
   externalPathUsages?: RepositoryCommandExternalPathUsage[];
 }
 
@@ -307,6 +311,7 @@ async function prepareRepositoryCommandExecutionAsync(
     ? emptyWorkspaceSnapshot()
     : await repositorySnapshotAsync(root, input.signal, {
         pathFingerprints: !(classification.risk === 'readonly' && controllerHome === undefined),
+        fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
       }));
   return finalizePreparedExecution(
     repository,
@@ -565,9 +570,19 @@ export async function executeRepositoryCommandAsync(
     ...hooks,
     signal,
   });
-  const after = input.allowNonGitWorkspace
-    ? before
-    : await repositorySnapshotAsync(root, signal?.aborted ? undefined : signal);
+  let after: RepositoryCommandSnapshot | undefined = input.allowNonGitWorkspace ? before : undefined;
+  let evidenceError: RepositoryCommandExecution['evidenceError'];
+  if (!input.allowNonGitWorkspace) {
+    try {
+      after = await repositorySnapshotAsync(root, signal?.aborted ? undefined : signal, {
+        fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = message.includes(':') ? message.slice(0, message.indexOf(':')) : 'POST_EXECUTION_EVIDENCE_FAILED';
+      evidenceError = { code, message };
+    }
+  }
   const execution: RepositoryCommandExecution = {
     ...base,
     status: 'executed',
@@ -578,8 +593,9 @@ export async function executeRepositoryCommandAsync(
     stdout: result.stdout,
     stderr: result.stderr,
     after,
-    repositoryChanged: snapshotChanged(before, after),
-    changedPaths: changedSnapshotPaths(before, after),
+    repositoryChanged: after ? snapshotChanged(before, after) : undefined,
+    changedPaths: after ? changedSnapshotPaths(before, after) : undefined,
+    evidenceError,
     policyDecision: 'allowed',
     externalPathUsages: externalPathUsages.length > 0 ? externalPathUsages : undefined,
     infrastructureError: result.timedOut
@@ -594,7 +610,9 @@ export async function executeRepositoryCommandAsync(
         }
         : undefined,
   };
-  if (execution.repositoryChanged) invalidateRepositoryReadCaches(root);
+  // Unknown post-execution mutation evidence is conservatively cache-invalidating;
+  // later reads must re-observe the repository rather than reuse a false unchanged state.
+  if (execution.repositoryChanged === true || execution.evidenceError) invalidateRepositoryReadCaches(root);
   auditCommand(controllerHome, repository, execution);
   return execution;
 }

package/src/cli/repositories/repository-snapshot.ts

@@ -84,7 +84,7 @@ const MAX_DIRTY_PATHS = 200;
 export async function repositorySnapshotAsync(
   root: string,
   signal?: AbortSignal,
-  options: { pathFingerprints?: boolean } = {},
+  options: { pathFingerprints?: boolean; fingerprintTimeoutMs?: number } = {},
 ): Promise<RepositoryCommandSnapshot> {
   const [headResult, branchResult, statusResult, refsResult] = await Promise.all([
     gitAsync(root, ['rev-parse', '--verify', 'HEAD'], signal), gitAsync(root, ['branch', '--show-current'], signal),
@@ -107,7 +107,10 @@ export async function repositorySnapshotAsync(
   let pathFingerprints: Record<string, string> = {};
   if (includePathFingerprints) {
     const { computePathFingerprintsAsync } = await import('../../runtime/execution/thin-harness/fingerprint-worker');
-    const fingerprint = await computePathFingerprintsAsync({ root, paths, statusByPath: Object.fromEntries(byPath), maxFileBytes: 256 * 1024, maxTotalBytes: 8 * 1024 * 1024, maxPaths: MAX_DIRTY_PATHS }, { signal, timeoutMs: 5_000 });
+    const fingerprintTimeoutMs = typeof options.fingerprintTimeoutMs === 'number' && Number.isFinite(options.fingerprintTimeoutMs)
+      ? Math.max(1, Math.trunc(options.fingerprintTimeoutMs))
+      : 5_000;
+    const fingerprint = await computePathFingerprintsAsync({ root, paths, statusByPath: Object.fromEntries(byPath), maxFileBytes: 256 * 1024, maxTotalBytes: 8 * 1024 * 1024, maxPaths: MAX_DIRTY_PATHS }, { signal, timeoutMs: fingerprintTimeoutMs });
     pathFingerprints = fingerprint.pathFingerprints;
   }
   return { head, branch: branchResult.ok ? branchResult.stdout || null : null, status: statusResult.stdout, dirty: paths.length > 0, refsHash: createHash('sha256').update(refs).digest('hex'), paths, pathFingerprints };