@moretea-labs/forge 1.7.2 → 1.8.0

package/adapters/mcp/runtime-gateway/controller-authority-adapter.ts

@@ -0,0 +1,191 @@
+import { randomUUID } from 'crypto';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  assertControllerInvocationAuthority,
+  assertControllerRoundInvocationAuthority,
+  bindControllerOwnershipForInvocation,
+  controllerInvocationAuthorityMatches,
+  controllerTerminalizationAuthorityForInvocation,
+  terminalCleanupAuthorityForInvocation,
+} from '../../../src/runtime/control-plane/execution/controller-authority-recovery';
+import { currentControllerInstanceId } from '../../../src/runtime/control-plane/execution/session-store';
+import { observeRuntimeStatus } from '../../../src/runtime/root/status';
+import { chatgptControllerRoundRecoveryAuthorized } from '../../../src/runtime/root/controller-round-composition';
+import {
+  getControllerSession,
+  type ControllerRoundRelayRecord,
+  type ControllerTerminalizationAuthority,
+} from '../../../packages/kernel/controller/api/index';
+
+export interface RuntimeIdentitySnapshot {
+  releaseId?: string;
+  artifactIdentity?: string;
+  runtimeCommit?: string;
+  buildCommit?: string;
+  startedAt?: string;
+  runtimeInstanceId?: string;
+  controllerInstanceId?: string;
+  endpoint?: string;
+  running?: boolean;
+  ready?: boolean;
+  reasonCodes?: string[];
+  toolset?: string;
+  profile?: string;
+}
+
+export function runtimeIdentitySnapshot(ctx: MultiRepositoryMcpToolContext): RuntimeIdentitySnapshot {
+  const observation = observeRuntimeStatus(ctx.controllerHome);
+  const snapshot = observation.snapshot;
+  return {
+    releaseId: snapshot?.releaseId,
+    artifactIdentity: snapshot?.artifactIdentity,
+    startedAt: snapshot?.startedAt,
+    runtimeInstanceId: snapshot?.runtimeInstanceId,
+    controllerInstanceId: snapshot?.runtimeInstanceId,
+    endpoint: snapshot?.endpoint,
+    running: observation.running,
+    ready: observation.ready,
+    reasonCodes: observation.reasonCodes,
+    toolset: ctx.toolset,
+    profile: ctx.policy.profile,
+  };
+}
+
+export function authenticatedFacadeControllerIdentity(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+  _options: { allowTransportSessionRollover?: boolean } = {},
+): { controllerId: string; principalId: string; sessionId: string; transportSessionId?: string; controllerAuthorityId?: string; authorityViaSessionCompatibility?: boolean; controllerInstanceId: string; controllerType: 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human' } {
+  const principalId = ctx.principalId?.trim();
+  const transportSessionId = ctx.sessionId?.trim();
+  const requestedControllerId = typeof args.controller_id === 'string' ? args.controller_id.trim() : '';
+  const requestedSessionId = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  const requestedAuthorityId = typeof args.controller_authority_id === 'string' ? args.controller_authority_id.trim() : '';
+  if (!principalId) {
+    // Preserve the bounded legacy stdio contract when no authenticated
+    // transport identity exists at all. Modern MCP requests carry a principal
+    // without a protocol session and reach the principal guard below; an
+    // unauthenticated legacy request must not silently mint one.
+    if (!transportSessionId && !requestedSessionId) {
+      throw new Error('CONTROLLER_AUTHENTICATED_SESSION_REQUIRED: reconnect or provide session_id through the authenticated MCP transport');
+    }
+    throw new Error('CONTROLLER_AUTHENTICATED_PRINCIPAL_REQUIRED: use an authenticated MCP transport');
+  }
+  // Legacy MCP sessions remain replaceable transport bindings. Modern MCP has no
+  // protocol session, so a fresh request-scoped execution binding is minted when
+  // the caller does not provide an explicit compatibility carrier. Durable Work
+  // authority is never derived from this request binding.
+  const sessionId = transportSessionId || requestedSessionId || `mcp_request_${randomUUID().replace(/-/g, '')}`;
+  const compatibilityAuthorityId = (!transportSessionId && requestedSessionId ? requestedSessionId : '')
+    || (transportSessionId && requestedSessionId !== transportSessionId ? requestedSessionId : '');
+  const controllerAuthorityId = requestedAuthorityId || compatibilityAuthorityId;
+  const authorityViaSessionCompatibility = !requestedAuthorityId && Boolean(compatibilityAuthorityId);
+  if (requestedControllerId && requestedControllerId !== principalId) {
+    throw new Error('CONTROLLER_ID_CONTEXT_MISMATCH: controller_id must match the authenticated principal');
+  }
+  const requestedControllerType = typeof args.controller_type === 'string' && ['chatgpt', 'codex', 'claude', 'grok', 'human'].includes(args.controller_type)
+    ? args.controller_type as 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human'
+    : undefined;
+  const transportControllerType = ctx.controllerType;
+  if (transportControllerType && requestedControllerType && requestedControllerType !== transportControllerType) {
+    throw new Error('CONTROLLER_TYPE_CONTEXT_MISMATCH: controller_type must match the authenticated transport provider');
+  }
+  return {
+    controllerId: principalId,
+    principalId,
+    sessionId,
+    ...(transportSessionId ? { transportSessionId } : {}),
+    ...(controllerAuthorityId ? { controllerAuthorityId } : {}),
+    ...(authorityViaSessionCompatibility ? { authorityViaSessionCompatibility: true } : {}),
+    controllerType: transportControllerType ?? requestedControllerType ?? 'chatgpt',
+    controllerInstanceId: ctx.controllerInstanceId?.trim() || currentControllerInstanceId(),
+  };
+}
+
+export function dispatchedChatgptRelayAuthorizesStaleControllerRecovery(
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  relay: ControllerRoundRelayRecord | undefined,
+  controllerType: 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human',
+): boolean {
+  return controllerType === 'chatgpt' && chatgptControllerRoundRecoveryAuthorized(store, workId, relay);
+}
+
+export function assertFacadeControllerRoundAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerRoundRelayRecord | undefined {
+  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  return assertControllerRoundInvocationAuthority({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+  });
+}
+
+export function sessionlessFacadeControllerAuthorityMatches(
+  owner: NonNullable<ReturnType<typeof getControllerSession>> | undefined,
+  identity: { transportSessionId?: string; controllerAuthorityId?: string },
+): boolean {
+  return controllerInvocationAuthorityMatches(owner, identity);
+}
+
+export function assertSessionlessFacadeControllerAuthority(
+  owner: NonNullable<ReturnType<typeof getControllerSession>> | undefined,
+  identity: { transportSessionId?: string; controllerAuthorityId?: string },
+  workId: string,
+): void {
+  assertControllerInvocationAuthority(owner, identity, workId);
+}
+
+export function bindFacadeControllerOwnership(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  identity: ReturnType<typeof authenticatedFacadeControllerIdentity>,
+  options: { allowClaimIfMissing?: boolean; leaseMs?: number; relayScopeId?: string } = {},
+) {
+  return bindControllerOwnershipForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: options.relayScopeId,
+    runtime: runtimeIdentitySnapshot(ctx),
+    allowClaimIfMissing: options.allowClaimIfMissing,
+    leaseMs: options.leaseMs,
+  });
+}
+
+export function currentFacadeTerminalizationAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerTerminalizationAuthority {
+  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  return controllerTerminalizationAuthorityForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+    runtime: runtimeIdentitySnapshot(ctx),
+  });
+}
+
+export function currentTerminalCleanupAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerTerminalizationAuthority {
+  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  return terminalCleanupAuthorityForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+  });
+}

package/adapters/mcp/runtime-gateway/engineering-preconditions.ts

@@ -0,0 +1,147 @@
+import {
+  buildDesignDecisionContractReceipt,
+  buildIndependentCritiqueReceipt,
+  buildProductDoDReceipt,
+  engineeringRequirementContextDigest,
+  type ContextClosureReceipt,
+  type EngineeringAdmissionEvidence,
+  type IndependentCritiqueFinding,
+  type ProjectEngineeringContractReceipt,
+} from '../../../packages/kernel/work/api/index';
+import { loadProjectEngineeringContract } from '../../../src/runtime/context/project-engineering-contract';
+import { validateRuntimeIssuedContextClosureReceipt } from '../../../src/runtime/context/context-closure';
+
+type RecordValue = Record<string, unknown>;
+function object(value: unknown, code: string): RecordValue {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(code);
+  return value as RecordValue;
+}
+function text(value: unknown, code: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(code);
+  return value.trim();
+}
+function strings(value: unknown, code: string): string[] {
+  if (!Array.isArray(value)) throw new Error(code);
+  return value.map((entry) => text(entry, code));
+}
+
+export function mintEngineeringAdmissionEvidence(input: {
+  repoRoot: string;
+  sourceRevision: string;
+  draft: unknown;
+  requirementContext: { objective: string; acceptanceCriteria: string[] };
+  existingProjectContractReceipt?: ProjectEngineeringContractReceipt;
+  now?: () => string;
+}): EngineeringAdmissionEvidence {
+  const draft = object(input.draft, 'ENGINEERING_PRECONDITIONS_INVALID');
+  const sourceRevision = text(input.sourceRevision, 'ENGINEERING_PRECONDITIONS_SOURCE_REQUIRED');
+  const closure = validateRuntimeIssuedContextClosureReceipt(object(draft.context_closure, 'ENGINEERING_CONTEXT_CLOSURE_REQUIRED') as unknown as ContextClosureReceipt);
+  if (closure.sourceRevision !== sourceRevision) throw new Error('ENGINEERING_CONTEXT_CLOSURE_SOURCE_DRIFT');
+  if (closure.readiness.status !== 'ready') throw new Error(`ENGINEERING_CONTEXT_CLOSURE_NOT_READY: ${closure.readiness.reasonCodes.join(',') || closure.readiness.status}`);
+
+  const loadedProject = input.existingProjectContractReceipt
+    ? { status: 'ready' as const, receipt: input.existingProjectContractReceipt }
+    : loadProjectEngineeringContract({ repoRoot: input.repoRoot, sourceRevision });
+  const projectContractReceipt = loadedProject.status === 'ready' ? loadedProject.receipt : undefined;
+  if (!projectContractReceipt) throw new Error('ENGINEERING_PROJECT_CONTRACT_REQUIRED');
+  const requirementDigest = engineeringRequirementContextDigest(input.requirementContext);
+  const recordedAt = (input.now ?? (() => new Date().toISOString()))();
+
+  const dod = object(draft.product_dod, 'ENGINEERING_PRODUCT_DOD_REQUIRED');
+  const productDodReceipt = buildProductDoDReceipt({
+    sourceRevision,
+    userOutcome: text(dod.user_outcome, 'ENGINEERING_PRODUCT_DOD_USER_OUTCOME_REQUIRED'),
+    completionConditions: strings(dod.completion_conditions, 'ENGINEERING_PRODUCT_DOD_COMPLETION_REQUIRED'),
+    nonRegression: strings(dod.non_regression, 'ENGINEERING_PRODUCT_DOD_NON_REGRESSION_REQUIRED'),
+    performanceExpectations: strings(dod.performance_expectations, 'ENGINEERING_PRODUCT_DOD_PERFORMANCE_REQUIRED'),
+    nonGoals: strings(dod.non_goals, 'ENGINEERING_PRODUCT_DOD_NON_GOALS_REQUIRED'),
+    recordedAt,
+  });
+
+  const design = object(draft.design_decision, 'ENGINEERING_DESIGN_DECISION_REQUIRED');
+  const decisionsInput = object(design.decisions, 'ENGINEERING_DESIGN_DECISIONS_REQUIRED');
+  const decisions = {
+    ownership: text(decisionsInput.ownership, 'ENGINEERING_DESIGN_OWNERSHIP_REQUIRED'),
+    singleWriter: text(decisionsInput.single_writer, 'ENGINEERING_DESIGN_SINGLE_WRITER_REQUIRED'),
+    transaction: text(decisionsInput.transaction, 'ENGINEERING_DESIGN_TRANSACTION_REQUIRED'),
+    lifecycle: text(decisionsInput.lifecycle, 'ENGINEERING_DESIGN_LIFECYCLE_REQUIRED'),
+    concurrency: text(decisionsInput.concurrency, 'ENGINEERING_DESIGN_CONCURRENCY_REQUIRED'),
+    persistence: text(decisionsInput.persistence, 'ENGINEERING_DESIGN_PERSISTENCE_REQUIRED'),
+    failure: text(decisionsInput.failure, 'ENGINEERING_DESIGN_FAILURE_REQUIRED'),
+    projectionCache: text(decisionsInput.projection_cache, 'ENGINEERING_DESIGN_PROJECTION_CACHE_REQUIRED'),
+    time: text(decisionsInput.time, 'ENGINEERING_DESIGN_TIME_REQUIRED'),
+    performance: text(decisionsInput.performance, 'ENGINEERING_DESIGN_PERFORMANCE_REQUIRED'),
+    compatibility: text(decisionsInput.compatibility, 'ENGINEERING_DESIGN_COMPATIBILITY_REQUIRED'),
+    semanticScopeIdentity: text(decisionsInput.semantic_scope_identity, 'ENGINEERING_DESIGN_SEMANTIC_SCOPE_IDENTITY_REQUIRED'),
+    authorizationTrust: text(decisionsInput.authorization_trust, 'ENGINEERING_DESIGN_AUTHORIZATION_TRUST_REQUIRED'),
+    resourceFencing: text(decisionsInput.resource_fencing, 'ENGINEERING_DESIGN_RESOURCE_FENCING_REQUIRED'),
+    deploymentTopology: text(decisionsInput.deployment_topology, 'ENGINEERING_DESIGN_DEPLOYMENT_TOPOLOGY_REQUIRED'),
+    schemaEvolutionDurability: text(decisionsInput.schema_evolution_durability, 'ENGINEERING_DESIGN_SCHEMA_EVOLUTION_DURABILITY_REQUIRED'),
+    idempotencyReplay: text(decisionsInput.idempotency_replay, 'ENGINEERING_DESIGN_IDEMPOTENCY_REPLAY_REQUIRED'),
+    retentionGc: text(decisionsInput.retention_gc, 'ENGINEERING_DESIGN_RETENTION_GC_REQUIRED'),
+    observabilityEvidence: text(decisionsInput.observability_evidence, 'ENGINEERING_DESIGN_OBSERVABILITY_EVIDENCE_REQUIRED'),
+    recoveryFailureDomain: text(decisionsInput.recovery_failure_domain, 'ENGINEERING_DESIGN_RECOVERY_FAILURE_DOMAIN_REQUIRED'),
+    capacityBackpressure: text(decisionsInput.capacity_backpressure, 'ENGINEERING_DESIGN_CAPACITY_BACKPRESSURE_REQUIRED'),
+    releaseUpgradeRollback: text(decisionsInput.release_upgrade_rollback, 'ENGINEERING_DESIGN_RELEASE_UPGRADE_ROLLBACK_REQUIRED'),
+    securityPrivacy: text(decisionsInput.security_privacy, 'ENGINEERING_DESIGN_SECURITY_PRIVACY_REQUIRED'),
+    portability: text(decisionsInput.portability, 'ENGINEERING_DESIGN_PORTABILITY_REQUIRED'),
+    migrationRetirement: text(decisionsInput.migration_retirement, 'ENGINEERING_DESIGN_MIGRATION_RETIREMENT_REQUIRED'),
+  };
+  const budgetInput = object(design.complexity_budget, 'ENGINEERING_COMPLEXITY_BUDGET_REQUIRED');
+  const complexityBudget = {
+    addedWriters: Number(budgetInput.added_writers ?? 0),
+    addedDurableMechanisms: Number(budgetInput.added_durable_mechanisms ?? 0),
+    projectionPaths: Number(budgetInput.projection_paths ?? 0),
+    globalInvalidations: Number(budgetInput.global_invalidations ?? 0),
+    lifecycleHooks: Number(budgetInput.lifecycle_hooks ?? 0),
+    synchronousCriticalPathWork: Number(budgetInput.synchronous_critical_path_work ?? 0),
+    notes: Array.isArray(budgetInput.notes) ? budgetInput.notes.map(String) : [],
+  };
+  const mutationClass = design.mutation_class;
+  if (mutationClass !== 'readonly' && mutationClass !== 'isolated_write' && mutationClass !== 'integration_write' && mutationClass !== 'external_effect') {
+    throw new Error('ENGINEERING_MUTATION_CLASS_INVALID');
+  }
+  const designDecisionReceipt = buildDesignDecisionContractReceipt({
+    sourceRevision,
+    contextClosureReceiptId: closure.receiptId,
+    productDodReceiptId: productDodReceipt.receiptId,
+    semanticScopeKeys: strings(design.semantic_scope_keys, 'ENGINEERING_SEMANTIC_SCOPE_REQUIRED'),
+    mutationClass,
+    decisions,
+    complexityBudget,
+    ...(typeof design.supersedes_receipt_id === 'string' && design.supersedes_receipt_id.trim() ? { supersedesReceiptId: design.supersedes_receipt_id.trim() } : {}),
+    recordedAt,
+  });
+
+  const critique = object(draft.independent_critique, 'ENGINEERING_INDEPENDENT_CRITIQUE_REQUIRED');
+  const decision = critique.decision;
+  if (decision !== 'approved' && decision !== 'changes_required' && decision !== 'blocked') throw new Error('ENGINEERING_CRITIQUE_DECISION_INVALID');
+  const findings = Array.isArray(critique.findings)
+    ? critique.findings.map((entry) => {
+        const finding = object(entry, 'ENGINEERING_CRITIQUE_FINDING_INVALID');
+        const severity = finding.severity;
+        if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low' && severity !== 'info') throw new Error('ENGINEERING_CRITIQUE_SEVERITY_INVALID');
+        return { severity: severity as IndependentCritiqueFinding['severity'], summary: text(finding.summary, 'ENGINEERING_CRITIQUE_SUMMARY_REQUIRED') };
+      })
+    : [];
+  const independentCritiqueReceipt = buildIndependentCritiqueReceipt({
+    sourceRevision,
+    contextClosureReceiptId: closure.receiptId,
+    productDodReceiptId: productDodReceipt.receiptId,
+    designDecisionReceiptId: designDecisionReceipt.receiptId,
+    requirementDigest,
+    projectContractDigest: projectContractReceipt.contentDigest,
+    decision,
+    findings,
+    recordedAt,
+  });
+
+  return {
+    projectContractReceipt,
+    contextClosureReceipt: closure,
+    contextClosureReceiptId: closure.receiptId,
+    productDodReceipt,
+    designDecisionReceipt,
+    independentCritiqueReceipt,
+  };
+}

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

@@ -0,0 +1,28 @@
+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 { cancelExecutionJob, findExecutionJob, getExecutionJob, getExecutionJobByRequestId, listExecutionJobs } from '../../../src/runtime/execution/jobs/store';
+import { summarizeExecutionJob } from './runtime-tool-shared';
+
+
+
+export async function callExecutionControlAdapter(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>): Promise<CallToolResult | undefined> {
+  try {
+    switch (name) {
+      case 'cancel_job': {
+              const jobId = String(args.job_id ?? '').trim();
+              const job = typeof args.repo_id === 'string' ? getExecutionJob(ctx.controllerHome, args.repo_id, jobId) : findExecutionJob(ctx.controllerHome, jobId);
+              if (!job) return result({ error: { code: 'JOB_NOT_FOUND', message: jobId } }, true);
+              const cancelled = await cancelExecutionJob(ctx.controllerHome, job.repoId, job.jobId, typeof args.reason === 'string' ? args.reason : undefined);
+              const repoRoot = repositoryRootForRepoId(ctx.controllerHome, cancelled.repoId);
+              return result({ job: summarizeExecutionJob(cancelled, repoRoot) });
+            }
+      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/execution-tools.ts

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync } from 'fs';
+import type { McpToolDefinition, CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { repositoryGitStatus, repositoryGitDiff } from '../../../src/cli/repositories/structured-git';
+import { listControllerChecks } from '../../../src/cli/controller/check-runner';
+import { buildWorkContinuationSnapshot } from '../../../src/runtime/control-plane/facade/work-continuation';
+import { currentControllerInstanceId, startExecutionSession, type ExecutionSessionContext } from '../../../src/runtime/control-plane/execution/session-store';
+import { currentPermissionSnapshotVersion, validateWorkHandle } from '../../../src/runtime/control-plane/execution/validation';
+import { resolveAuthorizationRequest } from '../../../src/runtime/control-plane/governance/authorization';
+import { readControllerResult, searchControllerResult } from '../../../src/runtime/evidence/result-store';
+import { resumeExecutionJobAfterApproval } from '../../../src/runtime/execution/jobs/store';
+import { recordMcpTiming, type McpTimingTrace } from '../../../src/runtime/diagnostics/mcp-timing';
+import { compactHandle, contractFor, identityFor, makeBoundedWorkResult, principalFor, requireSession, workForSession } from '../../../src/runtime/control-plane/execution/work-execution-support';
+import { finalizeWork } from '../../../src/runtime/control-plane/execution/work-finalization-service';
+import { bindSessionRepository, prepareWork } from '../../../src/runtime/control-plane/execution/work-preparation-service';
+import { executeWork, validateWork } from '../../../src/runtime/control-plane/execution/work-operation-service';
+
+
+// Compatibility exports: implementation authority lives in control-plane execution.
+export {
+  inspectWorkTargetAdvance,
+  targetAdvanceLinearMergeCommits,
+  planTargetAdvanceValidationAuthority,
+  targetAdvanceWorkScopeViolation,
+  inspectDirectTargetDelivery,
+  inspectTargetDirtyWorkOwnership,
+  inspectDirectCanonicalTargetAdvanceReconciliation,
+  completionReceiptChangedPaths,
+  inspectCleanupOnlyMergedHead,
+  resetFinalizationStagesForRequest,
+} from '../../../src/runtime/control-plane/execution/work-finalization-service';
+export { releasePreparedWorkOwnership } from '../../../src/runtime/control-plane/execution/work-execution-support';
+export { selectDefaultWorkValidationChecks } from '../../../src/runtime/control-plane/execution/work-operation-service';
+export type {
+  DirectCanonicalTargetAdvanceInspection,
+  DirectTargetDeliveryInspection,
+  TargetAdvanceValidationTransferPlan,
+  TargetDirtyWorkOwnershipInspection,
+  WorkTargetAdvanceInspection,
+} from '../../../src/runtime/control-plane/execution/work-finalization-service';
+
+function definition(name: string, description: string, properties: Record<string, unknown>, required: string[] = [], readOnlyHint = false, destructiveHint = false): McpToolDefinition {
+  return { name, description, inputSchema: { type: 'object', properties, ...(required.length ? { required } : {}), additionalProperties: false }, annotations: { readOnlyHint, openWorldHint: false, destructiveHint } };
+}
+
+const sessionId = { type: 'string', description: 'Controller-issued session id returned by session_start. Omit only when the MCP transport binds one.' };
+const workId = { type: 'string', description: 'Controller-owned work handle id returned by work_prepare.' };
+const repoId = { type: 'string', description: 'Stable repository id. Repository switching must be explicit through session_bind_repository.' };
+
+export const executionToolDefinitions: McpToolDefinition[] = [
+  definition('session_start', 'Start or resume a controller-owned MCP execution session. Identity comes from the authenticated/controller-issued transport context.', {}, [], false),
+  definition('session_bind_repository', 'Explicitly bind the current session to one registered repository and checkout.', { session_id: sessionId, repo_id: repoId, checkout_id: { type: 'string' } }, ['repo_id'], false),
+  definition('work_prepare', 'Prepare or reuse one controller-owned work handle and bind it to a WorkContract, checkout, branch, and permission snapshot.', {
+    session_id: sessionId, repo_id: repoId, checkout_id: { type: 'string' }, work_id: workId,
+    objective: { type: 'string' }, goal_id: { type: 'string' }, acceptance_criteria: { type: 'array', items: { type: 'string' } }, allowed_paths: { type: 'array', items: { type: 'string' } }, checks: { type: 'array', items: { type: 'string' } },
+    isolation: { type: 'string', enum: ['reuse', 'new_worktree', 'auto'] }, base_ref: { type: 'string' }, needs_dependencies: { type: 'boolean' },
+    expected_previous_head: { type: 'string', description: 'Explicit prior WorkHandle HEAD required for audited successor adoption of an existing work_id.' },
+    adopt_candidate_head: { type: 'string', description: 'Explicit current successor commit to adopt after exact identity, ownership, cleanliness, ancestry, and path-scope validation.' },
+  }, [], false),
+  definition('work_inspect', 'Collect bounded Git, WorkContract, path, check, and readiness evidence through one work handle.', { session_id: sessionId, repo_id: repoId, work_id: workId, detail: { type: 'string', enum: ['summary', 'detail'] } }, ['work_id'], true),
+  definition('work_execute', 'Execute approved, repository-scoped commands against a validated work handle while preserving the existing command policy and audit path.', {
+    session_id: sessionId, controller_id: { type: 'string', description: 'Controller identity that holds the Work lease. Defaults to the authenticated principal.' }, repo_id: repoId, work_id: workId,
+    command: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }] }, approval_token: { type: 'string' }, cwd: { type: 'string' }, timeout_ms: { type: 'number' }, max_output_bytes: { type: 'number' },
+    commands: { type: 'array', items: { type: 'object' } }, approval_request_id: { type: 'string' },
+  }, ['work_id'], false),
+  definition('work_validate', 'Run targeted checks or read-only validation commands against a work handle with full current-state validation.', {
+    session_id: sessionId, controller_id: { type: 'string', description: 'Controller identity that holds the Work lease. Defaults to the authenticated principal.' }, repo_id: repoId, work_id: workId, check_ids: { type: 'array', items: { type: 'string' } }, commands: { type: 'array', items: { type: 'object' } },
+  }, ['work_id'], false),
+  definition('work_finalize', 'Idempotently validate, commit, merge, clean a managed worktree, and complete the existing WorkContract in independently recorded stages.', {
+    session_id: sessionId, controller_id: { type: 'string', description: 'Controller identity that holds the Work lease. Defaults to the authenticated principal.' }, repo_id: repoId, work_id: workId, commit: { type: 'boolean' }, message: { type: 'string' }, merge: { type: 'boolean' }, target_branch: { type: 'string' }, remote_write: { type: 'boolean', description: 'When true, push the exact locally integrated target revision to origin before cleanup and Work terminalization.' }, delete_branch: { type: 'boolean' }, cleanup: { type: 'boolean' }, no_ff: { type: 'boolean' }, approval_request_id: { type: 'string' },
+    completion_outcome: { type: 'string', enum: ['completed_changed', 'completed_no_change'] }, no_change_evidence: { type: 'string', description: 'Objective-specific proof that the requested state already holds; required for completed_no_change.' },
+  }, ['work_id'], false, true),
+  definition('approval_resolve', 'Resolve a controller approval request from the current conversation; GUI approval is optional and not required for continuation.', { session_id: sessionId, repo_id: repoId, work_id: workId, approval_request_id: { type: 'string' }, confirm_authorization: { type: 'boolean' } }, ['approval_request_id', 'confirm_authorization'], false),
+  definition('result_read', 'Read a session-scoped result reference with bounded pagination.', { session_id: sessionId, result_ref: { type: 'string' }, work_id: workId, cursor: { type: 'number' }, limit: { type: 'number' } }, ['result_ref'], true),
+  definition('result_search', 'Search a session-scoped result reference without returning the full payload.', { session_id: sessionId, result_ref: { type: 'string' }, work_id: workId, query: { type: 'string' }, limit: { type: 'number' } }, ['result_ref', 'query'], true),
+];
+
+const executionToolNames = new Set(executionToolDefinitions.map((tool) => tool.name));
+
+/**
+ * Work mutation tool names remain grouped for compatibility with older Worker
+ * entrypoints. On the public MCP surface they execute directly through
+ * WorkContract + Process Runtime ownership rather than durable ExecutionJobs.
+ */
+const DURABLE_WORK_OPERATION_NAMES = new Set([
+  'work_execute',
+  'work_validate',
+  'work_finalize',
+]);
+
+export function isDurableWorkOperation(name: string): boolean {
+  return DURABLE_WORK_OPERATION_NAMES.has(name);
+}
+
+function result(value: Record<string, unknown>, isError = false): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value, ...(isError ? { isError: true } : {}) };
+}
+
+function failure(error: unknown): CallToolResult {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = message.includes(':') ? message.slice(0, message.indexOf(':')) : 'EXECUTION_TOOL_FAILED';
+  return result({ error: { code, message } }, true);
+}
+
+function startOrResumeSession(ctx: MultiRepositoryMcpToolContext): ExecutionSessionContext {
+  const permissionVersion = ctx.explicitRepository ? currentPermissionSnapshotVersion(ctx.controllerHome, ctx.explicitRepository.repoId) : 0;
+  return startExecutionSession(ctx.controllerHome, {
+    sessionId: ctx.sessionId,
+    principalId: principalFor(ctx),
+    controllerInstanceId: ctx.controllerInstanceId ?? currentControllerInstanceId(),
+    permissionSnapshotVersion: permissionVersion,
+    capabilitySnapshotVersion: 1,
+  });
+}
+
+function inspectWork(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): Record<string, unknown> {
+  const session = requireSession(ctx, args);
+  // work_inspect is authorized read-only evidence; it must not require the write lease.
+  const handle = workForSession(ctx, session, args);
+  const started = performance.now();
+  const validationStarted = performance.now();
+  const validated = validateWorkHandle(ctx.controllerHome, handle, identityFor(ctx, args), 'cheap', 'inspect');
+  const validationMs = performance.now() - validationStarted;
+  const status = repositoryGitStatus(validated.worktreeRepository);
+  const diff = repositoryGitDiff(validated.worktreeRepository, { maxBytes: 64 * 1024 });
+  const contract = contractFor(ctx, handle);
+  const checks = contract?.checks ?? [];
+  const packageManifest = existsSync(`${validated.worktreeRepository.canonicalRoot}/package.json`)
+    ? JSON.parse(readFileSync(`${validated.worktreeRepository.canonicalRoot}/package.json`, 'utf-8')) as Record<string, unknown>
+    : undefined;
+  const value = {
+    session: { sessionId: session.sessionId, repoId: session.activeRepositoryId, checkoutId: session.activeCheckoutId },
+    work: compactHandle(handle),
+    readiness: { valid: true, warnings: validated.warnings, permissionSnapshotVersion: handle.permissionSnapshotVersion },
+    git: { status, diff: { nameOnly: diff.nameOnly, stat: diff.stat, patch: diff.patch, truncated: diff.truncated } },
+    workContract: contract ? {
+      workId: contract.workId,
+      status: contract.status,
+      objective: contract.objective,
+      checks: contract.checks,
+      acceptanceCriteria: contract.acceptanceCriteria,
+      allowedPaths: contract.allowedPaths,
+      semantics: buildWorkContinuationSnapshot(contract).semantics,
+    } : undefined,
+    continuation: contract ? buildWorkContinuationSnapshot(contract) : undefined,
+    paths: { allowed: handle.workContractId ? contract?.allowedPaths ?? [] : [], relevant: diff.nameOnly },
+    checks: checks.map((checkId) => ({ checkId, registered: listControllerChecks(validated.worktreeRepository.canonicalRoot).some((check) => check.id === checkId) })),
+    package: packageManifest ? { name: packageManifest.name, scripts: packageManifest.scripts } : undefined,
+  };
+  const response = makeBoundedWorkResult(ctx, session, handle.repositoryId, handle.workId, 'inspection', value);
+  const trace: McpTimingTrace = { tool: 'work_inspect', sessionResolutionMs: 0, repositoryResolutionMs: 0, workHandleValidationMs: Math.round(validationMs * 100) / 100, resultSerializationMs: 0, totalToolDurationMs: Math.round((performance.now() - started) * 100) / 100, sessionId: session.sessionId, repoId: handle.repositoryId, workId: handle.workId };
+  recordMcpTiming(ctx.controllerHome, trace);
+  return response;
+}
+
+export async function callExecutionTool(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>): Promise<CallToolResult | undefined> {
+  if (!executionToolNames.has(name)) return undefined;
+  try {
+    switch (name) {
+      case 'session_start': {
+        const session = startOrResumeSession(ctx);
+        return result({ session: { sessionId: session.sessionId, principalId: session.principalId, activeRepositoryId: session.activeRepositoryId, activeCheckoutId: session.activeCheckoutId, activeWorkId: session.activeWorkId, permissionSnapshotVersion: session.permissionSnapshotVersion, capabilitySnapshotVersion: session.capabilitySnapshotVersion, controllerInstanceId: session.controllerInstanceId, createdAt: session.createdAt, updatedAt: session.updatedAt } });
+      }
+      case 'session_bind_repository': return result(bindSessionRepository(ctx, args));
+      case 'work_prepare': return result(prepareWork(ctx, args));
+      case 'work_inspect': return result(inspectWork(ctx, args));
+      case 'work_execute': return result(await executeWork(ctx, args));
+      case 'work_validate': return result(await validateWork(ctx, args));
+      case 'work_finalize': return result(await finalizeWork(ctx, args));
+      case 'approval_resolve': {
+        const session = requireSession(ctx, args);
+        const repositoryId = typeof args.repo_id === 'string' && args.repo_id.trim() ? args.repo_id.trim() : session.activeRepositoryId;
+        if (!repositoryId) throw new Error('SESSION_REPOSITORY_REQUIRED: bind a repository before resolving approval');
+        const resolved = resolveAuthorizationRequest({
+          controllerHome: ctx.controllerHome,
+          repositoryId,
+          approvalRequestId: String(args.approval_request_id ?? ''),
+          sessionId: session.sessionId,
+          principalId: session.principalId,
+          workId: typeof args.work_id === 'string' ? args.work_id : session.activeWorkId,
+          permissionSnapshotVersion: currentPermissionSnapshotVersion(ctx.controllerHome, repositoryId),
+          confirm: args.confirm_authorization === true,
+        });
+        const resumed = resumeExecutionJobAfterApproval(ctx.controllerHome, repositoryId, resolved.approvalRequestId);
+        return result({
+          authorization: { decision: 'allow', source: 'user_confirmation', reason: 'User confirmation was recorded for the exact pending operation.' },
+          approval: resolved,
+          resumedJob: resumed ? { jobId: resumed.jobId, status: resumed.status, requestId: resumed.requestId } : undefined,
+          continuation: resumed
+            ? `The original durable Job ${resumed.jobId} was resumed with the resolved approval request.`
+            : `Retry the original operation with approval_request_id=${resolved.approvalRequestId}.`,
+        });
+      }
+      case 'result_read': {
+        const session = requireSession(ctx, args);
+        return result(readControllerResult({ controllerHome: ctx.controllerHome, resultRef: String(args.result_ref ?? ''), sessionId: session.sessionId, principalId: session.principalId, workId: typeof args.work_id === 'string' ? args.work_id : undefined, cursor: typeof args.cursor === 'number' ? args.cursor : undefined, limit: typeof args.limit === 'number' ? args.limit : undefined }));
+      }
+      case 'result_search': {
+        const session = requireSession(ctx, args);
+        return result(searchControllerResult({ controllerHome: ctx.controllerHome, resultRef: String(args.result_ref ?? ''), sessionId: session.sessionId, principalId: session.principalId, workId: typeof args.work_id === 'string' ? args.work_id : undefined, query: String(args.query ?? ''), limit: typeof args.limit === 'number' ? args.limit : undefined }));
+      }
+      default: return undefined;
+    }
+  } catch (error) {
+    return failure(error);
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  applyExternalFilesystemGrant,
+  listExternalFilesystemTargets,
+  previewExternalFilesystemGrant,
+  readExternalFilesystemSnapshot,
+} from '../../../src/runtime/safe-tooling';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+
+/** Transport-only compatibility adapter for explicit external-filesystem capabilities. */
+export function callFilesystemAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): CallToolResult | undefined {
+  switch (name) {
+    case 'external_filesystem_targets_list': {
+      const repository = selected(ctx, args);
+      return result(listExternalFilesystemTargets(repository.canonicalRoot));
+    }
+    case 'external_filesystem_grant_preview': {
+      const repository = selected(ctx, args);
+      return result(previewExternalFilesystemGrant(repository.canonicalRoot, args) as unknown as Record<string, unknown>);
+    }
+    case 'external_filesystem_grant_apply': {
+      const repository = selected(ctx, args);
+      return result(applyExternalFilesystemGrant(repository.canonicalRoot, args) as unknown as Record<string, unknown>);
+    }
+    case 'external_filesystem_text_snapshot': {
+      const repository = selected(ctx, args);
+      return result(readExternalFilesystemSnapshot(repository.canonicalRoot, args) as unknown as Record<string, unknown>);
+    }
+    default:
+      return undefined;
+  }
+}