@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/runtime-gateway/context-pack-sidecar.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import type { McpPolicy, McpProfileName } from '../types';
+import { buildControllerContextPackAsync } from '../../../src/cli/controller/context-pack';
+import type { ControllerContextPackOptions } from '../../../src/cli/controller/context/types';
+import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../../../src/runtime/execution/process-runtime/canary';
+
+interface ContextPackEnvelope {
+  schemaVersion: 1;
+  repoRoot: string;
+  policy: McpPolicy;
+  options: ControllerContextPackOptions;
+}
+
+function profile(value: unknown): McpProfileName {
+  if (value === 'planner' || value === 'executor' || value === 'orchestrator' || value === 'controller') return value;
+  throw new Error('CONTEXT_PACK_POLICY_PROFILE_INVALID');
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new Error('CONTEXT_PACK_POLICY_GLOBS_INVALID');
+  }
+  return value.map(String);
+}
+
+function policy(value: unknown): McpPolicy {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('CONTEXT_PACK_POLICY_INVALID');
+  const input = value as Record<string, unknown>;
+  const execution = input.execution;
+  if (!execution || typeof execution !== 'object' || Array.isArray(execution)) throw new Error('CONTEXT_PACK_POLICY_EXECUTION_INVALID');
+  const e = execution as Record<string, unknown>;
+  const maxFileBytes = Number(input.maxFileBytes);
+  if (!Number.isFinite(maxFileBytes) || maxFileBytes <= 0) throw new Error('CONTEXT_PACK_POLICY_MAX_FILE_BYTES_INVALID');
+  return {
+    profile: profile(input.profile),
+    readGlobs: stringList(input.readGlobs),
+    writeGlobs: stringList(input.writeGlobs),
+    denyGlobs: stringList(input.denyGlobs),
+    maxFileBytes,
+    execution: {
+      fixedWorkflowCheck: e.fixedWorkflowCheck === true,
+      codexRunner: e.codexRunner === true,
+      agentRunner: e.agentRunner === true,
+      allowedAgents: Array.isArray(e.allowedAgents)
+        ? e.allowedAgents.filter((entry): entry is 'codex' | 'claude' => entry === 'codex' || entry === 'claude')
+        : [],
+      runnerTimeoutMs: Number(e.runnerTimeoutMs) || 0,
+      runnerMaxTimeoutMs: Number(e.runnerMaxTimeoutMs) || 0,
+    },
+  };
+}
+
+export async function runContextPackSidecar(
+  argv = process.argv.slice(2),
+  input = readFileSync(0, 'utf8'),
+): Promise<number> {
+  if (argv.includes(PROCESS_RUNTIME_RELEASE_CANARY_ARG)) {
+    process.stdout.write('forge context-pack release canary\n');
+    return 0;
+  }
+  const envelope = JSON.parse(input) as ContextPackEnvelope;
+  if (envelope.schemaVersion !== 1 || typeof envelope.repoRoot !== 'string' || !envelope.repoRoot.trim()) {
+    throw new Error('CONTEXT_PACK_REQUEST_INVALID');
+  }
+  const pack = await buildControllerContextPackAsync(
+    resolve(envelope.repoRoot),
+    policy(envelope.policy),
+    envelope.options && typeof envelope.options === 'object' ? envelope.options : {},
+  );
+  process.stdout.write(`${JSON.stringify({ schemaVersion: 1, pack })}\n`);
+  return 0;
+}
+
+if (import.meta.main) {
+  try {
+    process.exitCode = await runContextPackSidecar();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

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

@@ -54,7 +54,7 @@ export function runtimeIdentitySnapshot(ctx: MultiRepositoryMcpToolContext): Run
 export function authenticatedFacadeControllerIdentity(
   ctx: MultiRepositoryMcpToolContext,
   args: Record<string, unknown>,
-  _options: { allowTransportSessionRollover?: boolean } = {},
+  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();
@@ -76,8 +76,16 @@ export function authenticatedFacadeControllerIdentity(
   // 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 transportRolloverRequested = Boolean(
+    transportSessionId
+    && requestedSessionId
+    && requestedSessionId !== transportSessionId,
+  );
+  if (transportRolloverRequested && options.allowTransportSessionRollover !== true) {
+    throw new Error('CONTROLLER_TRANSPORT_SESSION_ROLLOVER_NOT_ALLOWED: this operation must use the current authenticated transport session or an explicit controller_authority_id');
+  }
   const compatibilityAuthorityId = (!transportSessionId && requestedSessionId ? requestedSessionId : '')
-    || (transportSessionId && requestedSessionId !== transportSessionId ? requestedSessionId : '');
+    || (transportRolloverRequested ? requestedSessionId : '');
   const controllerAuthorityId = requestedAuthorityId || compatibilityAuthorityId;
   const authorityViaSessionCompatibility = !requestedAuthorityId && Boolean(compatibilityAuthorityId);
   if (requestedControllerId && requestedControllerId !== principalId) {
@@ -117,7 +125,11 @@ export function assertFacadeControllerRoundAuthority(
   workId: string,
   args: Record<string, unknown>,
 ): ControllerRoundRelayRecord | undefined {
-  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  // A frozen client may carry its explicit controller authority through the
+  // bounded `session_id` compatibility carrier. Resolving that carrier is not an
+  // authorization shortcut: `assertControllerRoundInvocationAuthority` still owns
+  // the exact principal/Work/round comparison below.
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
   return assertControllerRoundInvocationAuthority({
     ...store,
     workId,
@@ -165,7 +177,10 @@ export function currentFacadeTerminalizationAuthority(
   workId: string,
   args: Record<string, unknown>,
 ): ControllerTerminalizationAuthority {
-  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  // Frozen clients may carry an exact controller authority through the bounded
+  // `session_id` compatibility carrier; the terminalization authority check below
+  // still owns the exact owner/Work/revision comparison.
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
   return controllerTerminalizationAuthorityForInvocation({
     ...store,
     workId,
@@ -181,7 +196,7 @@ export function currentTerminalCleanupAuthority(
   workId: string,
   args: Record<string, unknown>,
 ): ControllerTerminalizationAuthority {
-  const identity = authenticatedFacadeControllerIdentity(ctx, args);
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
   return terminalCleanupAuthorityForInvocation({
     ...store,
     workId,

package/adapters/mcp/runtime-gateway/core-capability-adapter.ts

@@ -0,0 +1,258 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { callRepositoryTool } from '../tool-mapping/repository-tools';
+import { commitSelectedPaths, selectedPathDiff, stageSelectedPaths } from '../../../src/cli/repositories/selected-path-actions';
+import { deliverWork } from '../../../src/runtime/control-plane/execution/work-delivery-service';
+import { validateWork } from '../../../src/runtime/control-plane/execution/work-operation-service';
+import { startOrResumeSession } from './execution-tools';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+import { callWorkflowSupervisorAdapter } from './workflow-supervisor-adapter';
+import {
+  claimControllerRoundSession,
+  getControllerRoundRelay,
+  releaseObservedControllerSession,
+  submitControllerRoundDisposition,
+  type ControllerRoundDisposition,
+} from '../../../packages/kernel/controller/api/index';
+import { recoverControllerAuthority } from '../../../src/runtime/control-plane/execution/controller-authority-recovery';
+import { authenticatedFacadeControllerIdentity, runtimeIdentitySnapshot } from './controller-authority-adapter';
+import { readControllerConnectionSnapshot, repairControllerConnection } from '../../../src/runtime/control-plane/facade/controller-connection';
+import { readLocalConversationProviderStatus, sendLocalConversation } from '../../../src/runtime/control-plane/launcher/local-conversation-controller';
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+export async function callCoreCapabilityAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (name !== 'capability_execute') return undefined;
+  const capabilityId = typeof args.capability_id === 'string' ? args.capability_id.trim() : '';
+  const action = typeof args.action === 'string' ? args.action.trim() : '';
+  const input = object(args.arguments);
+
+  try {
+    if (capabilityId === 'controller.connection') {
+      if (action === 'get') return result({ ...readControllerConnectionSnapshot(ctx.controllerHome) });
+      if (action === 'repair_connector') return result(repairControllerConnection(ctx.controllerHome));
+      return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.connection action: ${action || '<empty>'}` } }, true);
+    }
+    if (capabilityId === 'controller.local_conversation') {
+      if (action === 'status') return result({ ...readLocalConversationProviderStatus() });
+      if (action === 'send') {
+        const conversationId = typeof input.conversation_id === 'string' ? input.conversation_id.trim() : '';
+        const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
+        const providerSessionId = typeof input.provider_session_id === 'string' ? input.provider_session_id.trim() : undefined;
+        const timeoutMs = typeof input.timeout_ms === 'number' ? input.timeout_ms : undefined;
+        const requestedRepoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
+        const repository = requestedRepoId ? selected(ctx, args) : undefined;
+        return result({ ...await sendLocalConversation({
+          controllerHome: ctx.controllerHome,
+          conversationId,
+          prompt,
+          providerSessionId,
+          repoId: repository?.repoId,
+          timeoutMs,
+        }) });
+      }
+      return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.local_conversation action: ${action || '<empty>'}` } }, true);
+    }
+    if (capabilityId === 'controller.workflow_supervisor') {
+      const forwarded = await callWorkflowSupervisorAdapter(ctx, 'supervisor_task', {
+        ...input,
+        operation: action,
+        request_id: typeof args.request_id === 'string' ? args.request_id.trim() : '',
+        ...(typeof args.repo_id === 'string' && args.repo_id.trim() ? { repo_id: args.repo_id.trim() } : {}),
+      });
+      return forwarded ?? result({ error: { code: 'CORE_CAPABILITY_ROUTE_UNAVAILABLE', message: 'Workflow Supervisor capability route is unavailable.' } }, true);
+    }
+    if (capabilityId === 'controller.round_recovery') {
+      if (action !== 'recover_and_dispose') {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.round_recovery action: ${action || '<empty>'}` } }, true);
+      }
+      if (input.user_directed !== true) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_USER_REQUIRED: user_directed=true is required.');
+      const workId = typeof input.work_id === 'string' ? input.work_id.trim() : '';
+      const recoveryReason = typeof input.recovery_reason === 'string' ? input.recovery_reason.trim() : '';
+      const disposition = typeof input.disposition === 'string' ? input.disposition.trim() as ControllerRoundDisposition : undefined;
+      const handoffId = typeof input.handoff_id === 'string' ? input.handoff_id.trim() : undefined;
+      if (!workId) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_WORK_REQUIRED');
+      if (!recoveryReason) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_REASON_REQUIRED');
+      if (!disposition || !['continue_immediately', 'wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
+        throw new Error('CONTROLLER_RELAY_DISPOSITION_INVALID');
+      }
+      if (disposition === 'wait_for_user' && !handoffId) throw new Error('CONTROLLER_RELAY_WAIT_FOR_USER_HANDOFF_REQUIRED');
+
+      const repository = selected(ctx, args);
+      const store = { controllerHome: ctx.controllerHome, repoId: repository.repoId };
+      const before = getControllerRoundRelay(store, workId);
+      if (!before) throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_RELAY_REQUIRED: ${workId}`);
+      const identity = authenticatedFacadeControllerIdentity(ctx, {});
+      const recovered = recoverControllerAuthority({
+        controllerHome: ctx.controllerHome,
+        repoId: repository.repoId,
+        repositoryActiveCheckoutId: repository.activeCheckoutId,
+        workId,
+        requestedBy: 'user',
+        recoveryReason,
+        identity,
+        runtime: runtimeIdentitySnapshot(ctx),
+        leaseMs: 60_000,
+      });
+      if (!('relay' in recovered)) throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_RELAY_REQUIRED: ${workId}`);
+      if (before.providerDispatchEffectId && recovered.relay.providerDispatchEffectId !== before.providerDispatchEffectId) {
+        throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_EFFECT_CHANGED: ${workId}`);
+      }
+
+      const claimed = claimControllerRoundSession(store, {
+        workId,
+        relayWorkId: workId,
+        sessionClaim: {
+          workId,
+          controllerId: identity.controllerId,
+          controllerType: identity.controllerType,
+          sessionId: identity.sessionId,
+          principalId: identity.principalId,
+          controllerInstanceId: identity.controllerInstanceId,
+          leaseMs: 60_000,
+        },
+      });
+      if (!claimed.relay || claimed.relay.status !== 'claimed') throw new Error(`CONTROLLER_RELAY_ROUND_NOT_CLAIMED: ${claimed.relay?.status ?? 'missing'}`);
+
+      let disposed;
+      let releaseResult;
+      try {
+        disposed = submitControllerRoundDisposition(store, {
+          workId,
+          identity: {
+            controllerId: claimed.session.controllerId,
+            controllerType: claimed.session.controllerType,
+            principalId: claimed.session.principalId?.trim() || claimed.session.controllerId,
+            controllerInstanceId: claimed.session.controllerInstanceId?.trim() || '',
+            sessionId: claimed.session.sessionId,
+          },
+          disposition,
+          relayScopeId: recovered.relay.relayScopeId,
+          requirementId: recovered.relay.requirementId,
+          ...(handoffId ? { handoffId } : {}),
+          reason: recoveryReason,
+        });
+      } finally {
+        releaseResult = releaseObservedControllerSession(store, {
+          workId,
+          actor: `controller-round-recovery:${identity.controllerId}`,
+          owner: claimed.session,
+        });
+      }
+      if (!releaseResult?.allowed) throw new Error(`WORK_CONTROLLER_RELEASE_FENCED: ${workId}:${releaseResult?.reason ?? 'unknown'}`);
+      const after = getControllerRoundRelay(store, workId);
+      return result({
+        repoId: repository.repoId,
+        workId,
+        authorityRecovered: true,
+        claimed: true,
+        disposition,
+        dispositionStatus: disposed.status,
+        relayScopeId: disposed.relayScopeId,
+        ownerReleased: true,
+        providerDispatchEffectId: after?.providerDispatchEffectId,
+        providerDispatchEffectPreserved: before.providerDispatchEffectId === after?.providerDispatchEffectId,
+        providerRedispatched: false,
+      });
+    }
+    if (capabilityId === 'repository.direct_edit') {
+      const toolName = action === 'plan'
+        ? 'repository_safe_patch_plan'
+        : action === 'apply'
+          ? 'repository_safe_patch_apply'
+          : undefined;
+      if (!toolName) {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.direct_edit action: ${action || '<empty>'}` } }, true);
+      }
+      const workId = action === 'apply' && typeof input.work_id === 'string' ? input.work_id.trim() : '';
+      const callerSession = workId && (!ctx.sessionId || !ctx.principalId || !ctx.controllerInstanceId)
+        ? startOrResumeSession(ctx)
+        : undefined;
+      const forwarded = await callRepositoryTool(ctx.controllerHome, toolName, {
+        ...input,
+        ...(typeof args.repo_id === 'string' && args.repo_id.trim() ? { repo_id: args.repo_id.trim() } : {}),
+        ...(typeof args.checkout_id === 'string' && args.checkout_id.trim() ? { checkout_id: args.checkout_id.trim() } : {}),
+      }, {
+        sessionId: callerSession?.sessionId ?? ctx.sessionId,
+        principalId: callerSession?.principalId ?? ctx.principalId,
+        controllerInstanceId: callerSession?.controllerInstanceId ?? ctx.controllerInstanceId,
+      });
+      return forwarded ?? result({
+        error: { code: 'CORE_CAPABILITY_ROUTE_UNAVAILABLE', message: 'Repository direct-edit capability route is unavailable.' },
+      }, true);
+    }
+    if (capabilityId === 'repository.validation') {
+      if (action !== 'validate_work') {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.validation action: ${action || '<empty>'}` } }, true);
+      }
+      const repository = selected(ctx, args);
+      const sessionId = typeof input.session_id === 'string' && input.session_id.trim()
+        ? input.session_id.trim()
+        : startOrResumeSession(ctx).sessionId;
+      return result(await validateWork(ctx, {
+        ...input,
+        session_id: sessionId,
+        repo_id: repository.repoId,
+        request_id: typeof args.request_id === 'string' ? args.request_id.trim() : '',
+      }));
+    }
+    if (capabilityId !== 'repository.git') {
+      return result({ error: { code: 'CORE_CAPABILITY_UNSUPPORTED', message: `Unsupported core capability: ${capabilityId || '<empty>'}` } }, true);
+    }
+    const repository = selected(ctx, args);
+    switch (action) {
+      case 'diff_paths':
+        return result({
+          ...selectedPathDiff(repository, {
+            paths: input.paths,
+            staged: input.staged === true,
+            maxBytes: typeof input.max_bytes === 'number' ? input.max_bytes : undefined,
+          }),
+        });
+      case 'stage_paths': {
+        const staged = stageSelectedPaths(ctx.controllerHome, repository, { paths: input.paths });
+        return result({
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          ...staged,
+        }, staged.execution.ok !== true);
+      }
+      case 'commit_paths': {
+        const committed = commitSelectedPaths(ctx.controllerHome, repository, {
+          paths: input.paths,
+          message: input.message,
+        });
+        return result({
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          ...committed,
+        }, Boolean(committed.error));
+      }
+      case 'deliver_work': {
+        const sessionId = typeof input.session_id === 'string' && input.session_id.trim()
+          ? input.session_id.trim()
+          : startOrResumeSession(ctx).sessionId;
+        const delivered = await deliverWork(ctx, {
+          ...input,
+          session_id: sessionId,
+          repo_id: repository.repoId,
+        });
+        return result(delivered);
+      }
+      default:
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.git action: ${action || '<empty>'}` } }, true);
+    }
+  } 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 ?? 'CORE_CAPABILITY_FAILED', message } }, true);
+  }
+}

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

@@ -5,11 +5,13 @@ import {
   engineeringRequirementContextDigest,
   type ContextClosureReceipt,
   type EngineeringAdmissionEvidence,
+  type EngineeringDecisionArea,
   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';
+import { ENGINEERING_DECISION_INPUT_ENTRIES, engineeringDecisionInputKey } from './engineering-tool-contract';
 
 type RecordValue = Record<string, unknown>;
 function object(value: unknown, code: string): RecordValue {
@@ -25,6 +27,10 @@ function strings(value: unknown, code: string): string[] {
   return value.map((entry) => text(entry, code));
 }
 
+function engineeringDecisionErrorCode(area: EngineeringDecisionArea): string {
+  return `ENGINEERING_DESIGN_${engineeringDecisionInputKey(area).toUpperCase()}_REQUIRED`;
+}
+
 export function mintEngineeringAdmissionEvidence(input: {
   repoRoot: string;
   sourceRevision: string;
@@ -60,33 +66,10 @@ export function mintEngineeringAdmissionEvidence(input: {
 
   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 decisions = Object.fromEntries(ENGINEERING_DECISION_INPUT_ENTRIES.map(({ area, field }) => [
+    area,
+    text(decisionsInput[field], engineeringDecisionErrorCode(area)),
+  ])) as Record<EngineeringDecisionArea, string>;
   const budgetInput = object(design.complexity_budget, 'ENGINEERING_COMPLEXITY_BUDGET_REQUIRED');
   const complexityBudget = {
     addedWriters: Number(budgetInput.added_writers ?? 0),

package/adapters/mcp/runtime-gateway/engineering-tool-contract.ts

@@ -0,0 +1,15 @@
+import {
+  ENGINEERING_DECISION_AREAS,
+  type EngineeringDecisionArea,
+} from '../../../packages/kernel/work/api/index';
+
+export function engineeringDecisionInputKey(area: EngineeringDecisionArea): string {
+  return area.replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`);
+}
+
+export const ENGINEERING_DECISION_INPUT_ENTRIES = ENGINEERING_DECISION_AREAS.map((area) => ({
+  area,
+  field: engineeringDecisionInputKey(area),
+}));
+
+export const ENGINEERING_DECISION_INPUT_FIELDS = ENGINEERING_DECISION_INPUT_ENTRIES.map(({ field }) => field);

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

@@ -1,7 +1,7 @@
 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 { repositoryGitWorkspaceChanges } 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';
@@ -11,33 +11,10 @@ import { readControllerResult, searchControllerResult } from '../../../src/runti
 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';
+import { 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 } };
@@ -52,24 +29,16 @@ export const executionToolDefinitions: McpToolDefinition[] = [
   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' } },
+    objective: { type: 'string' }, goal_id: { type: 'string' }, acceptance_criteria: { 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.' },
+    adopt_candidate_head: { type: 'string', description: 'Explicit current successor commit to adopt after exact identity, ownership, cleanliness, and ancestry validation.' },
+    relocate_to_new_worktree: { type: 'boolean', description: 'Move this existing Work identity to its own managed worktree, with exact previous/candidate HEADs and base_ref. WorkHandle and WorkContract placement commit atomically; the source checkout is not mutated.' },
   }, [], 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_inspect', 'Collect bounded Git, WorkContract, changed-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_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' } },
+    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' } }, interactive_wait_ms: { type: 'number', description: 'Optional bounded attach window for checks launched by this validation call. Defaults to asynchronous behavior.' },
   }, ['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),
@@ -77,15 +46,9 @@ export const executionToolDefinitions: McpToolDefinition[] = [
 
 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.
- */
+/** Repository execution and validation remain Process/WorkHandle operations; semantic Work completion is separate. */
 const DURABLE_WORK_OPERATION_NAMES = new Set([
-  'work_execute',
   'work_validate',
-  'work_finalize',
 ]);
 
 export function isDurableWorkOperation(name: string): boolean {
@@ -102,7 +65,7 @@ function failure(error: unknown): CallToolResult {
   return result({ error: { code, message } }, true);
 }
 
-function startOrResumeSession(ctx: MultiRepositoryMcpToolContext): ExecutionSessionContext {
+export function startOrResumeSession(ctx: MultiRepositoryMcpToolContext): ExecutionSessionContext {
   const permissionVersion = ctx.explicitRepository ? currentPermissionSnapshotVersion(ctx.controllerHome, ctx.explicitRepository.repoId) : 0;
   return startExecutionSession(ctx.controllerHome, {
     sessionId: ctx.sessionId,
@@ -121,8 +84,8 @@ function inspectWork(ctx: MultiRepositoryMcpToolContext, args: Record<string, un
   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 candidate = repositoryGitWorkspaceChanges(validated.worktreeRepository);
+  const { status, diff } = candidate;
   const contract = contractFor(ctx, handle);
   const checks = contract?.checks ?? [];
   const packageManifest = existsSync(`${validated.worktreeRepository.canonicalRoot}/package.json`)
@@ -132,18 +95,17 @@ function inspectWork(ctx: MultiRepositoryMcpToolContext, args: Record<string, un
     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 } },
+    git: { status, diff: { ...diff, staged: { nameOnly: candidate.staged.nameOnly, stat: candidate.staged.stat, truncated: candidate.staged.truncated }, unstaged: { nameOnly: candidate.unstaged.nameOnly, stat: candidate.unstaged.stat, truncated: candidate.unstaged.truncated }, untracked: status.untracked } },
     workContract: contract ? {
       workId: contract.workId,
-      status: contract.status,
+      state: contract.semanticState,
       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 },
+    paths: { changed: candidate.changedPaths },
     checks: checks.map((checkId) => ({ checkId, registered: listControllerChecks(validated.worktreeRepository.canonicalRoot).some((check) => check.id === checkId) })),
     package: packageManifest ? { name: packageManifest.name, scripts: packageManifest.scripts } : undefined,
   };
@@ -164,9 +126,7 @@ export async function callExecutionTool(ctx: MultiRepositoryMcpToolContext, name
       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;

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

@@ -20,11 +20,12 @@ async function runEditSessionValidationViaProcessRuntime(
   args: Record<string, unknown>,
 ): Promise<CallToolResult> {
   const resolved = resolveEditValidationRepository(repository, editSessionId);
+  const explicitWorkId = typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined;
   const binding = claimedSessionEditBinding(ctx.controllerHome, resolved.repository, {
     sessionId: ctx.sessionId,
     principalId: ctx.principalId,
     controllerInstanceId: ctx.controllerInstanceId,
-  }, args.work_id);
+  }, explicitWorkId ?? resolved.session.workId);
   assertEditSessionDurableBinding(resolved.session, binding, { requireBoundIdentity: true });
   const validation = await startOrJoinEditValidation(ctx.controllerHome, resolved.repository, {
     editSessionId,