@moretea-labs/forge 1.7.2 → 1.8.0

package/adapters/mcp/runtime-gateway/gateway-execution-adapter.ts

@@ -0,0 +1,411 @@
+import { createHash } from 'crypto';
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { callRepositoryTool, claimedSessionEditBinding } from '../tool-mapping/repository-tools';
+import { resolveRepositorySelection } from '../../../src/cli/repositories/registry';
+import { listControllerChecks } from '../../../src/cli/controller/check-runner';
+import { executionIdentityForRepository } from '../../../src/runtime/control-plane/execution/execution-identity';
+import { resolveEditValidationRepository, startOrJoinEditValidation } from '../../../src/runtime/control-plane/execution/edit-validation-coordinator';
+import { assertEditSessionDurableBinding } from '../../../src/cli/editing/edit-session';
+import { checkRequiresDurableWorkflow } from '../../../src/runtime/execution/process-runtime';
+import { runPersistedCheckViaProcessRuntime } from './persisted-check-process';
+import { buildCheckExecutionSchedule } from '../../../src/runtime/execution/process-runtime/check-scheduling';
+import { isProcessIsolatedReadDiagnostic, runReadOnlyDiagnosticViaProcessRuntime } from '../../../src/runtime/diagnostics/process-facade';
+import { result } from './result-adapter';
+
+async function runEditSessionValidationViaProcessRuntime(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: NonNullable<ReturnType<typeof resolveRepositorySelection>>,
+  editSessionId: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult> {
+  const resolved = resolveEditValidationRepository(repository, editSessionId);
+  const binding = claimedSessionEditBinding(ctx.controllerHome, resolved.repository, {
+    sessionId: ctx.sessionId,
+    principalId: ctx.principalId,
+    controllerInstanceId: ctx.controllerInstanceId,
+  }, args.work_id);
+  assertEditSessionDurableBinding(resolved.session, binding, { requireBoundIdentity: true });
+  const validation = await startOrJoinEditValidation(ctx.controllerHome, resolved.repository, {
+    editSessionId,
+    checkIds: Array.isArray(args.check_ids) ? args.check_ids.map(String) : undefined,
+    requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+    validationRequestId: typeof args.validation_request_id === 'string' ? args.validation_request_id : undefined,
+    reviewer: typeof args.reviewer === 'string' ? args.reviewer : undefined,
+    note: typeof args.note === 'string' ? args.note : undefined,
+    timeoutMs: typeof args.check_timeout_ms === 'number'
+      ? args.check_timeout_ms
+      : typeof args.timeout_ms === 'number'
+        ? args.timeout_ms
+        : undefined,
+    leaseWaitMs: typeof args.lease_wait_ms === 'number' ? args.lease_wait_ms : undefined,
+  });
+  return result(validation as unknown as Record<string, unknown>, validation.accepted === false);
+}
+
+export async function executeGatewayRoutedOperation(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+  classification: { path: 'direct' | 'fast' | 'durable' | 'reject'; reasons: string[] },
+): Promise<CallToolResult | undefined> {
+  if (isProcessIsolatedReadDiagnostic(name) && classification.path === 'fast') {
+    const repository = resolveRepositorySelection({
+      repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+      checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+      explicitPath: ctx.explicitRepository?.canonicalRoot,
+      controllerHome: ctx.controllerHome,
+      allowSoleRepository: true,
+    });
+    if (!repository) {
+      return result({
+        accepted: false,
+        mode: 'reject',
+        path: 'reject',
+        message: `${name} requires a resolvable repository`,
+      }, true);
+    }
+    try {
+      const payload = await runReadOnlyDiagnosticViaProcessRuntime({
+        controllerHome: ctx.controllerHome,
+        repository,
+        tool: name,
+        args: {
+          ...args,
+          __diagnostic_toolset: ctx.toolset,
+          __diagnostic_profile: ctx.policy.profile,
+        },
+      });
+      return result(payload, payload.accepted === false);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const processErrorCode = /^((?:PROCESS_)[A-Z0-9_]+)(?::|$)/.exec(message)?.[1];
+      const code = processErrorCode ?? 'DIAGNOSTIC_PROCESS_FAILED';
+      return result({
+        accepted: false,
+        mode: 'process_direct',
+        path: 'process_direct',
+        error: { code, message },
+        durableSideEffects: {
+          executionJobCount: 0,
+          localJobCount: 0,
+          workerSpawnCount: 0,
+          projectionUpdateCount: 0,
+        },
+      }, true);
+    }
+  }
+
+  // Edit-session verification uses the same resource-aware Process Runtime
+  // coordinator as the stable Direct Edit composite below.
+  if (name === 'verify_edit_session' && classification.path === 'fast') {
+    const repository = resolveRepositorySelection({
+      repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+      checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+      explicitPath: ctx.explicitRepository?.canonicalRoot,
+      controllerHome: ctx.controllerHome,
+      allowSoleRepository: true,
+    });
+    if (!repository) {
+      return result({ accepted: false, mode: 'reject', path: 'reject', message: 'verify_edit_session requires a resolvable repository' });
+    }
+    const editSessionId = String(args.session_id ?? '').trim();
+    if (!editSessionId) {
+      return result({ accepted: false, mode: 'reject', path: 'reject', message: 'verify_edit_session requires session_id' });
+    }
+    return runEditSessionValidationViaProcessRuntime(ctx, repository, editSessionId, args);
+  }
+
+  // Stable Direct Edit composite: checks are opt-in. Without check_ids this
+  // tool remains the ordinary synchronous patch path. With check_ids, the same
+  // call applies one coherent edit batch, returns its review evidence, and
+  // starts revision-bound validation without waiting on long checks.
+  if (name === 'repository_safe_patch_apply' && classification.path === 'direct'
+    && (args.validation_only === true || (Array.isArray(args.check_ids) && args.check_ids.length > 0))) {
+    const repository = resolveRepositorySelection({
+      repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+      checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+      explicitPath: ctx.explicitRepository?.canonicalRoot,
+      controllerHome: ctx.controllerHome,
+      allowSoleRepository: true,
+    });
+    if (!repository) {
+      return result({ accepted: false, mode: 'reject', path: 'reject', message: 'repository_safe_patch_apply requires a resolvable repository' }, true);
+    }
+
+    if (args.validation_only === true) {
+      const editSessionId = String(args.session_id ?? '').trim();
+      if (!editSessionId) {
+        return result({ accepted: false, mode: 'reject', path: 'reject', message: 'validation_only requires session_id' }, true);
+      }
+      const validation = await runEditSessionValidationViaProcessRuntime(ctx, repository, editSessionId, args);
+      const validationPayload = (validation.structuredContent ?? {}) as Record<string, unknown>;
+      return result({
+        operation: 'repository_safe_patch_apply',
+        validationOnly: true,
+        sessionId: editSessionId,
+        validation: validationPayload,
+        validationRequestId: validationPayload.validationRequestId,
+        completed: validationPayload.completed === true,
+        ok: validationPayload.ok,
+        acceptanceReady: validationPayload.completed === true && validationPayload.ok === true,
+        next: validationPayload.completed === true
+          ? validationPayload.ok === true
+            ? 'Validation passed for the exact edit revision; delivery may proceed if policy and semantic review are satisfied.'
+            : 'Validation completed with failures; return the failure evidence to ChatGPT for repair reasoning.'
+          : validationPayload.next,
+      }, validation.isError === true);
+    }
+
+    const applied = await callRepositoryTool(ctx.controllerHome, name, args, ctx);
+    if (!applied || applied.isError === true) return applied;
+    const patchPayload = (applied.structuredContent ?? {}) as Record<string, unknown>;
+    if (patchPayload.status !== 'applied') return applied;
+    const session = patchPayload.session && typeof patchPayload.session === 'object'
+      ? patchPayload.session as Record<string, unknown>
+      : undefined;
+    const editSessionId = typeof session?.sessionId === 'string' ? session.sessionId : '';
+    if (!editSessionId) return applied;
+    const validation = await runEditSessionValidationViaProcessRuntime(ctx, repository, editSessionId, args);
+    const validationPayload = (validation.structuredContent ?? {}) as Record<string, unknown>;
+    const validationCompleted = validationPayload.completed === true;
+    const validationPassed = validationCompleted && validationPayload.ok === true;
+    return result({
+      ...patchPayload,
+      validation: validationPayload,
+      validationStarted: true,
+      validationCompleted,
+      validationPassed,
+      acceptanceReady: validationPassed,
+      validationRequestId: validationPayload.validationRequestId,
+      next: validationCompleted
+        ? validationPassed
+          ? 'Patch review evidence and requested validation are complete; proceed to delivery only after ChatGPT semantic review is satisfied.'
+          : 'Patch applied but validation failed; return the failure evidence to ChatGPT before any delivery.'
+        : validationPayload.next,
+    }, validation.isError === true);
+  }
+
+  // run_check Process Runtime facade — execute here so legacy LocalBridgeJob path is skipped.
+  if (name === 'run_check' && classification.path === 'fast') {
+    const restoringDisabledRepository = false;
+    void restoringDisabledRepository;
+    const repository = resolveRepositorySelection({
+      repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+      checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+      explicitPath: ctx.explicitRepository?.canonicalRoot,
+      controllerHome: ctx.controllerHome,
+      allowSoleRepository: true,
+    });
+    if (!repository) {
+      return result({
+        accepted: false,
+        mode: 'reject',
+        path: 'reject',
+        message: 'run_check requires a resolvable repository',
+      });
+    }
+    const checkId = String(args.check_id ?? '').trim();
+    const rawBatchCheckIds = args.check_ids;
+    const hasBatchInput = Array.isArray(rawBatchCheckIds);
+    const batchCheckIds: string[] = hasBatchInput
+      ? [...new Set(rawBatchCheckIds.map((value: unknown) => String(value).trim()).filter(Boolean))]
+      : [];
+    if (checkId && hasBatchInput) {
+      return result({
+        accepted: false,
+        mode: 'reject',
+        path: 'reject',
+        message: 'run_check accepts either check_id or check_ids, not both',
+      }, true);
+    }
+    if (!checkId && batchCheckIds.length === 0) {
+      return result({
+        accepted: false,
+        mode: 'reject',
+        path: 'reject',
+        message: 'run_check requires check_id or a non-empty check_ids array',
+      }, true);
+    }
+    if (hasBatchInput) {
+      const availableChecks = listControllerChecks(repository.canonicalRoot);
+      const availableChecksById = new Map(availableChecks.map((check) => [check.id, check]));
+      const checkScheduling = buildCheckExecutionSchedule({
+        checks: availableChecks,
+        requestedCheckIds: batchCheckIds,
+        repoId: repository.repoId,
+        checkoutId: repository.activeCheckoutId,
+      });
+      const schedulePayload = {
+        waveCount: checkScheduling.waves.length,
+        maxParallel: checkScheduling.maxParallel,
+        waves: checkScheduling.waves,
+        conflicts: checkScheduling.conflicts,
+        invalidCheckIds: checkScheduling.invalidCheckIds,
+        guidance: checkScheduling.guidance,
+      };
+      if (checkScheduling.invalidCheckIds.length > 0) {
+        return result({
+          accepted: false,
+          mode: 'reject',
+          path: 'reject',
+          reason: 'invalid_check_ids',
+          checkIds: batchCheckIds,
+          checkScheduling: schedulePayload,
+          message: `run_check batch contains unregistered checks: ${checkScheduling.invalidCheckIds.join(', ')}`,
+        }, true);
+      }
+      const durableCheckIds = batchCheckIds.filter((id) => checkRequiresDurableWorkflow(availableChecksById.get(id)));
+      if (durableCheckIds.length > 0) {
+        return result({
+          accepted: false,
+          mode: 'reject',
+          path: 'reject',
+          reason: 'batch_contains_durable_check',
+          checkIds: batchCheckIds,
+          durableCheckIds,
+          checkScheduling: schedulePayload,
+          message: 'Batch run_check only launches ordinary focused checks; run release or multi-phase checks through an explicit durable workflow.',
+        }, true);
+      }
+      if (checkScheduling.waves.length !== 1 || checkScheduling.waves[0]?.checkIds.length !== batchCheckIds.length) {
+        return result({
+          accepted: false,
+          mode: 'reject',
+          path: 'reject',
+          reason: 'batch_spans_multiple_check_waves',
+          checkIds: batchCheckIds,
+          checkScheduling: schedulePayload,
+          message: 'Requested checks span multiple resource-conflicting waves. Launch one returned wave per run_check call; Forge will not hide serial waiting inside a batch.',
+        }, true);
+      }
+      const baseRequestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+      const facades = await Promise.all(batchCheckIds.map((batchCheckId, index) => {
+        const suffix = createHash('sha256').update(batchCheckId).digest('hex').slice(0, 8);
+        return runPersistedCheckViaProcessRuntime({
+          controllerHome: ctx.controllerHome,
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          repoRoot: repository.canonicalRoot,
+          executionIdentity: executionIdentityForRepository(repository),
+          checkId: batchCheckId,
+          timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+          interactiveWaitMs: 0,
+          requestId: baseRequestId ? `${baseRequestId}:batch:${index + 1}:${suffix}` : undefined,
+          forceDurable: false,
+        });
+      }));
+      const unexpectedDurable = facades.filter((facade) => facade.mode === 'durable');
+      if (unexpectedDurable.length > 0) {
+        return result({
+          accepted: false,
+          mode: 'reject',
+          path: 'reject',
+          reason: 'batch_check_escalated_to_durable',
+          checkIds: batchCheckIds,
+          checkScheduling: schedulePayload,
+          message: 'At least one batch check unexpectedly requires Durable execution; no further batch orchestration will be created.',
+        }, true);
+      }
+      const processes = facades.map((facade) => ({
+        checkId: facade.checkId,
+        processId: facade.process?.processId,
+        status: facade.process?.status,
+        completed: facade.process?.completed === true,
+        ok: facade.process?.ok,
+        exitCode: facade.process?.exitCode,
+        timedOut: facade.process?.timedOut,
+        deduplicated: facade.process?.deduplicated === true,
+        semanticDeduplicated: facade.process?.semanticDeduplicated === true,
+        durableSideEffects: facade.durableSideEffects,
+      }));
+      const completed = processes.every((process) => process.completed);
+      const mode = processes.every((process) => process.completed) ? 'direct' : 'managed';
+      const durableSideEffects = facades.reduce((total, facade) => ({
+        executionJobCount: total.executionJobCount + facade.durableSideEffects.executionJobCount,
+        localJobCount: total.localJobCount + facade.durableSideEffects.localJobCount,
+        workerSpawnCount: total.workerSpawnCount + facade.durableSideEffects.workerSpawnCount,
+        projectionUpdateCount: total.projectionUpdateCount + facade.durableSideEffects.projectionUpdateCount,
+      }), { executionJobCount: 0, localJobCount: 0, workerSpawnCount: 0, projectionUpdateCount: 0 });
+      return result({
+        accepted: true,
+        batch: true,
+        mode,
+        path: mode === 'direct' ? 'process_batch_direct' : 'process_batch_managed',
+        routing: { path: 'fast', reasons: ['run_check_batch_process_runtime'] },
+        repoId: repository.repoId,
+        checkoutId: repository.activeCheckoutId,
+        checkIds: batchCheckIds,
+        checkScheduling: schedulePayload,
+        processes,
+        processIds: processes.map((process) => process.processId).filter(Boolean),
+        completed,
+        ...(completed ? { ok: processes.every((process) => process.ok === true) } : {}),
+        durableSideEffects,
+        next: completed
+          ? 'Batch check wave finished on Process Runtime without ExecutionJob / LocalBridgeJob / Worker.'
+          : 'Batch check wave is running concurrently. Continue independent work. Attach to each returned process only when that result becomes a real dependency; do not poll or re-run the checks.',
+      });
+    }
+    const facade = await runPersistedCheckViaProcessRuntime({
+      controllerHome: ctx.controllerHome,
+      repoId: repository.repoId,
+      checkoutId: repository.activeCheckoutId,
+      repoRoot: repository.canonicalRoot,
+      executionIdentity: executionIdentityForRepository(repository),
+      checkId,
+      timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+      interactiveWaitMs: args.apply_mode === 'async' || args.mode === 'async' || args.async === true || args.background === true
+        ? 0
+        : typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : undefined,
+      requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+      forceDurable: args.force_durable === true || args.mode === 'durable',
+    });
+    if (facade.mode === 'durable') {
+      // Multi-phase/release should already be classified durable. Remaining durable
+      // reasons (missing check, explicit force) must not silently create empty jobs
+      // without a clear signal — return structured escalation instead of LocalBridge.
+      return result({
+        accepted: false,
+        mode: 'durable',
+        path: 'durable',
+        routing: {
+          path: 'durable',
+          reasons: [facade.durable?.reason ?? 'check_requires_durable'],
+        },
+        checkId: facade.checkId,
+        message: facade.durable?.reason ?? 'check requires durable workflow',
+        suggestedOperation: facade.durable?.suggestedOperation,
+        durableSideEffects: facade.durableSideEffects,
+      });
+    }
+    const handle = facade.process;
+    return result({
+      accepted: true,
+      mode: facade.mode,
+      path: facade.mode === 'direct' ? 'process_direct' : 'process_managed',
+      routing: {
+        path: facade.mode,
+        reasons: classification.reasons,
+      },
+      checkId: facade.checkId,
+      repoId: repository.repoId,
+      checkoutId: repository.activeCheckoutId,
+      processId: handle?.processId,
+      status: handle?.status,
+      completed: handle?.completed === true,
+      deduplicated: handle?.deduplicated === true,
+      semanticDeduplicated: handle?.semanticDeduplicated === true,
+      ok: handle?.ok,
+      exitCode: handle?.exitCode,
+      timedOut: handle?.timedOut,
+      stdout: handle?.stdout,
+      stderr: handle?.stderr,
+      durableSideEffects: facade.durableSideEffects,
+      next: handle?.completed
+        ? 'Check finished on Process Runtime without ExecutionJob / LocalBridgeJob / Worker.'
+        : `Check still running as managed process ${handle?.processId}. Continue independent work; attach with process_wait only when this exact result becomes a real dependency. An attach may return a running handle because transport time is bounded; continue useful work and attach again only at a later dependency boundary. Do not re-run or periodically poll the same check.`,
+    });
+  }
+  return undefined;
+}

package/adapters/mcp/runtime-gateway/legacy-ios-tool-adapter.ts

@@ -0,0 +1,105 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { callPluginAdapter } from './plugin-adapter';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+
+/**
+ * Compatibility translation only: legacy iOS MCP tool names are normalized to
+ * the canonical typed iOS plugin action surface. This module owns no runtime,
+ * repository, Work, approval, or plugin execution state.
+ */
+export interface LegacyIosPluginInvocation {
+  actionId: string;
+  requestId: string;
+  arguments: Record<string, unknown>;
+  confirmAuthorization: boolean;
+}
+
+function definedArguments(value: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+function optionalString(args: Record<string, unknown>, key: string): string | undefined {
+  return typeof args[key] === 'string' ? args[key] as string : undefined;
+}
+
+function optionalNumber(args: Record<string, unknown>, key: string): number | undefined {
+  return typeof args[key] === 'number' ? args[key] as number : undefined;
+}
+
+export function legacyIosPluginInvocation(
+  legacyTool: string,
+  args: Record<string, unknown>,
+): LegacyIosPluginInvocation | undefined {
+  const invocation = (() => {
+    switch (legacyTool) {
+      case 'ios_xcode_status':
+        return { actionId: 'xcode_status', arguments: {} };
+      case 'ios_simulators_list':
+        return { actionId: 'list_simulators', arguments: { runtime: optionalString(args, 'runtime'), name: optionalString(args, 'name') } };
+      case 'ios_project_discover':
+        return { actionId: 'discover_project', arguments: {} };
+      case 'ios_schemes_list':
+        return { actionId: 'list_schemes', arguments: { workspace: optionalString(args, 'workspace'), project: optionalString(args, 'project') } };
+      case 'ios_simulator_boot':
+        return { actionId: 'launch_simulator', arguments: { udid: String(args.udid ?? '').trim(), open_simulator: args.open_simulator !== false, timeout_ms: optionalNumber(args, 'timeout_ms') } };
+      case 'ios_app_build':
+        return { actionId: 'build', arguments: { scheme: String(args.scheme ?? '').trim(), udid: optionalString(args, 'udid'), simulator_name: optionalString(args, 'simulator_name'), workspace: optionalString(args, 'workspace'), project: optionalString(args, 'project'), configuration: optionalString(args, 'configuration'), timeout_ms: optionalNumber(args, 'timeout_ms') } };
+      case 'ios_simulator_screenshot':
+        return { actionId: 'capture_screenshot', arguments: { udid: String(args.udid ?? '').trim(), label: optionalString(args, 'label') } };
+      case 'ios_ui_smoke_test':
+        return { actionId: 'smoke_review', arguments: { scheme: optionalString(args, 'scheme'), bundle_id: optionalString(args, 'bundle_id'), udid: optionalString(args, 'udid'), simulator_name: optionalString(args, 'simulator_name'), workspace: optionalString(args, 'workspace'), project: optionalString(args, 'project'), configuration: optionalString(args, 'configuration'), app_path: optionalString(args, 'app_path'), screenshot_label: optionalString(args, 'screenshot_label') } };
+      default:
+        return undefined;
+    }
+  })();
+  if (!invocation) return undefined;
+  const requestId = typeof args.request_id === 'string' && args.request_id.trim()
+    ? args.request_id.trim()
+    : `legacy-${legacyTool}-${Date.now()}`;
+  return {
+    actionId: invocation.actionId,
+    requestId,
+    arguments: definedArguments(invocation.arguments),
+    confirmAuthorization: args.confirm_authorization === true,
+  };
+}
+
+
+const LEGACY_IOS_PLUGIN_TOOLS = new Set([
+  'ios_xcode_status', 'ios_simulators_list', 'ios_project_discover', 'ios_schemes_list',
+  'ios_simulator_boot', 'ios_app_build', 'ios_simulator_screenshot', 'ios_ui_smoke_test',
+]);
+const RETIRED_IOS_ATOMIC_TOOLS = new Set(['ios_app_install', 'ios_app_launch', 'ios_simulator_log_tail']);
+
+/** Thin compatibility dispatch. Execution remains owned by the typed iOS plugin application path. */
+export async function callLegacyIosAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (RETIRED_IOS_ATOMIC_TOOLS.has(name)) {
+    return result({
+      accepted: false,
+      mode: 'compatibility_migration',
+      path: 'plugin_action_execute',
+      rejectCode: 'LEGACY_IOS_ATOMIC_RETIRED',
+      message: `${name} no longer owns an independent iOS execution path. Use plugin_action_execute with plugin_id=ios and action_id=smoke_review for staged simulator validation.`,
+      migration: { tool: 'plugin_action_execute', plugin_id: 'ios', action_id: 'smoke_review' },
+    }, true);
+  }
+  if (!LEGACY_IOS_PLUGIN_TOOLS.has(name)) return undefined;
+  const repository = selected(ctx, args);
+  const invocation = legacyIosPluginInvocation(name, args);
+  if (!invocation) return undefined;
+  return callPluginAdapter(ctx, 'plugin_action_execute', {
+    repo_id: repository.repoId,
+    checkout_id: repository.activeCheckoutId,
+    plugin_id: 'ios',
+    action_id: invocation.actionId,
+    request_id: invocation.requestId,
+    arguments: invocation.arguments,
+    ...(invocation.confirmAuthorization ? { confirm_authorization: true } : {}),
+  });
+}

package/adapters/mcp/runtime-gateway/maintenance-adapter.ts

@@ -0,0 +1,44 @@
+import type { McpToolDefinition, CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { boundedPluginArtifactImageContent, jsonPreview, result, resultWithPluginArtifactImages } from './result-adapter';
+import { expectedRevision, repositoryRootForRepoId, selected, stringList } from './shared-adapter';
+import { applyRuntimeCleanup, previewRuntimeCleanup } from '../../../src/runtime/maintenance/cleanup';
+
+
+
+export async function callMaintenanceAdapter(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>): Promise<CallToolResult | undefined> {
+  try {
+    switch (name) {
+      case 'runtime_cleanup_preview': {
+              const repository = selected(ctx, args);
+              const preview = previewRuntimeCleanup(repository.canonicalRoot, {
+                minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+                includeTempDirs: args.include_temp_dirs !== false,
+                includeTerminalLocalJobs: args.include_terminal_local_jobs === true,
+                includeLegacyRuns: args.include_legacy_runs === true,
+                includeHistoricalAttention: args.include_historical_attention === true,
+                maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+              });
+              return result({ ...preview });
+            }
+      case 'runtime_cleanup_apply': {
+              const repository = selected(ctx, args);
+              const applied = applyRuntimeCleanup(repository.canonicalRoot, {
+                minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+                includeTempDirs: args.include_temp_dirs !== false,
+                includeTerminalLocalJobs: args.include_terminal_local_jobs === true,
+                includeLegacyRuns: args.include_legacy_runs === true,
+                includeHistoricalAttention: args.include_historical_attention === true,
+                maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+                confirmCleanup: args.confirm_cleanup === true,
+              });
+              return result({ ...applied });
+            }
+      default: return undefined;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const structuredCode = /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1];
+    return result({ error: { code: structuredCode ?? 'RUNTIME_TOOL_FAILED', message } }, true);
+  }
+}

package/adapters/mcp/runtime-gateway/model-adapter.ts

@@ -0,0 +1,63 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  buildModelClientSummary,
+  buildModelControlPlaneSummary,
+  deepSeekControllerManifest,
+  deepSeekFunctionToolManifest,
+  prepareDeepSeekControllerHandoff,
+  prepareDeepSeekControllerRequest,
+  prepareDeepSeekToolCall,
+} from '../../../src/runtime/model-clients';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+
+/** Transport-only compatibility adapter for model-client preview/manifest surfaces. */
+export function callModelAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): CallToolResult | undefined {
+  switch (name) {
+    case 'model_clients_summary':
+      return result({ clients: buildModelClientSummary(), policyOwner: 'forge', transportEncryption: 'not-configured-by-this-tool' });
+    case 'model_control_plane_summary':
+      return result({ controlPlane: buildModelControlPlaneSummary(), transportEncryption: 'not-configured-by-this-tool' });
+    case 'deepseek_tool_manifest':
+      return result({ provider: 'deepseek', tools: deepSeekFunctionToolManifest(), policyOwner: 'forge' });
+    case 'deepseek_tool_call_prepare': {
+      const functionArguments = args.function_arguments && typeof args.function_arguments === 'object' && !Array.isArray(args.function_arguments)
+        ? args.function_arguments as Record<string, unknown>
+        : {};
+      return result({ prepared: prepareDeepSeekToolCall(String(args.function_name ?? '').trim(), functionArguments) });
+    }
+    case 'deepseek_controller_manifest':
+      return result({ manifest: deepSeekControllerManifest() });
+    case 'deepseek_controller_handoff_prepare': {
+      const repository = selected(ctx, args);
+      return result({ handoff: prepareDeepSeekControllerHandoff({
+        reason: args.reason as never,
+        objective: typeof args.objective === 'string' ? args.objective : undefined,
+        repoId: repository.repoId,
+        currentController: typeof args.current_controller === 'string' ? args.current_controller : undefined,
+        blockedToolName: typeof args.blocked_tool_name === 'string' ? args.blocked_tool_name : undefined,
+        recentSafeError: typeof args.recent_safe_error === 'string' ? args.recent_safe_error : undefined,
+      }) });
+    }
+    case 'deepseek_controller_request_prepare': {
+      const repository = selected(ctx, args);
+      return result({ preview: prepareDeepSeekControllerRequest({
+        reason: args.reason as never,
+        objective: typeof args.objective === 'string' ? args.objective : undefined,
+        userMessage: typeof args.user_message === 'string' ? args.user_message : undefined,
+        repoId: repository.repoId,
+        currentController: typeof args.current_controller === 'string' ? args.current_controller : undefined,
+        blockedToolName: typeof args.blocked_tool_name === 'string' ? args.blocked_tool_name : undefined,
+        recentSafeError: typeof args.recent_safe_error === 'string' ? args.recent_safe_error : undefined,
+        model: typeof args.model === 'string' ? args.model : undefined,
+      }) });
+    }
+    default:
+      return undefined;
+  }
+}

package/adapters/mcp/runtime-gateway/persisted-check-process.ts

@@ -0,0 +1,3 @@
+// Compatibility import path. Persisted check execution belongs to Process Runtime
+// so Scheduler reconciliation can advance validation without depending on Gateway.
+export * from '../../../src/runtime/execution/process-runtime/persisted-check';