@moretea-labs/forge 1.8.0 → 1.8.1

package/adapters/mcp/tool-mapping/repository-tools.ts

@@ -1,12 +1,13 @@
 import { bindRepositoryEntities } from '../../../src/cli/repositories/entity-migration';
 import { bootstrapLocalProject, diagnoseLatestLocalProjectSource } from '../../../src/cli/repositories/local-project-onboarding';
 import { resolveEphemeralWorkspaceTarget } from '../../../src/cli/repositories/ephemeral-workspace';
-import type { ResolvedExecutionIdentity } from '../../../src/runtime/control-plane/execution/execution-identity';
+import { commandExecutionScopeKey, type RepositoryCommandScopeTarget } from '../../../src/cli/repositories/command-scope';
+import { executionIdentityForWork, type ResolvedExecutionIdentity } from '../../../src/runtime/control-plane/execution/execution-identity';
 import { assertNoBoundExecutionSessionMutation, resolveClaimedRepositoryWorkId, resolveExplicitClaimedRepositoryWork, type RepositoryWorkAttributionCaller } from '../../../src/runtime/control-plane/execution/repository-work-attribution';
-import { getWorkContract } from '../../../packages/kernel/work/api';
-import { assertWorkPathsWithinScope } from '../../../src/runtime/control-plane/execution/work-path-scope';
+import { getWorkContract, promoteWorkToRepositoryChange, semanticWorkState, type WorkContract } from '../../../packages/kernel/work/api';
 import { assertCanonicalRepositoryMutationWorkHandleAvailable, ensureRepositoryMutationWorkHandle, markRepositoryMutationStarted } from '../../../src/runtime/control-plane/execution/work-handle-authority';
-import { isTerminalWorkContractStatus } from '../../../src/runtime/control-plane/facade/types';
+import { readWorkHandle } from '../../../src/runtime/control-plane/execution/work-handle-store';
+import { ensureRunningRepositoryWorkCheckout } from '../../../src/runtime/control-plane/execution/retained-work-resume';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../../../src/cli/repositories/command-executor';
 import { withControllerLock } from '../../../src/cli/repositories/locks';
 import {
@@ -37,7 +38,6 @@ import {
   repositoryGitMergeBranch,
   repositoryGitStatus,
   repositoryGitSwitchBranch,
-  resolveRepositoryGitCommitScope,
 } from '../../../src/cli/repositories/structured-git';
 import {
   readRepositoryGitStatusSample,
@@ -56,7 +56,6 @@ import {
   classifyRepositoryCommandRoute,
   executeRepositoryCommandViaProcessRuntime,
 } from '../../../src/runtime/execution/process-runtime/command-facade';
-import { assessWorkMode, parseExplicitTaskMode } from '../../../src/cli/controller/work-mode';
 import { classifyRepositoryCommand } from '../../../src/cli/repositories/command-classifier';
 import { normalizeRepositoryCommand } from '../../../src/cli/repositories/command-normalization';
 import { readRepositoryRange } from '../../../src/cli/repository/inspector';
@@ -157,12 +156,12 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
     include_removed: { type: 'boolean' },
     operation: {
       type: 'string',
-      enum: ['summary', 'batch_execute', 'lanes_execute', 'lanes_integrate', 'fast_receipt_get', 'fast_receipt_list', 'execution_route', 'assess_work_mode'],
-      description: 'Defaults to summary. Use batch_execute for multi-step Fast Path (one parent receipt). Use lanes_execute for limited parallel reads. Use assess_work_mode for Fast/Durable routing advice.',
+      enum: ['summary', 'batch_execute', 'lanes_execute', 'lanes_integrate', 'fast_receipt_get', 'fast_receipt_list', 'execution_route'],
+      description: 'Defaults to summary. Use batch_execute for multi-step repository capability execution and lanes_execute for limited parallel reads. Workflow/mode selection belongs to the model/user, not Workbench.',
     },
     payload: {
       type: 'object',
-      description: 'Operation-specific bounded arguments. Batch write operations should include request_id. For batch_execute: { steps:[{id?, kind, input}], stop_on_error?, allowed_paths?, timeout_ms?, request_id?, purpose? }. For assess_work_mode: { description, known_paths?, expected_files?, requires_parallelism?, independent_task_count?, agent_requested? }. Agent routing is opt-in only.',
+      description: 'Operation-specific bounded arguments. Batch write operations should include request_id. For batch_execute: { steps:[{id?, kind, input}], stop_on_error?, allowed_paths?, timeout_ms?, request_id?, purpose? }.' ,
       additionalProperties: true,
     },
   }),
@@ -252,7 +251,7 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
     cwd: { type: 'string', description: 'Optional root-relative working directory.' },
     workspace_root: { type: 'string', description: 'Absolute existing local directory used as an ephemeral execution root. Mutually exclusive with repo_id/checkout_id; does not register or initialize the directory.' },
   }, ['command'], true),
-  definition('repository_command_execute', 'Execute one repository-scoped command through the thinnest eligible lane: ephemeral for ordinary local work, an in-memory lightweight handle when it outlives the interaction budget, or explicit Durable handling for Work/external/release effects. Lightweight handles have no SQLite, Lease, recovery, or replay membership. Use rh_context for routine code discovery/reading; shell exploration is fallback-only.', {
+  definition('repository_command_execute', 'Compatibility facade for commands whose domain context is a repository/workspace. Repository targeting, Git/source mutation fences, and compatibility response fields live here; Process Runtime owns command execution and process identity. New broad host-local command callers should use process_exec. Use rh_context for routine code discovery/reading; shell exploration is fallback-only.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
     work_id: { type: 'string', description: 'Optional durable Work identity. Workflow controllers should pass the exact claimed Work id so attribution survives transient MCP transport sessions.' },
@@ -306,11 +305,10 @@ export function claimedSessionEditBinding(
   if (!work) return undefined;
   return {
     workId,
-    repoId: repository.repoId,
-    checkoutId: repository.activeCheckoutId,
+  repoId: repository.repoId,
+  checkoutId: repository.activeCheckoutId,
     principalId: caller.principalId.trim(),
     controllerInstanceId: caller.controllerInstanceId,
-    routeDecisionFingerprint: work.routeDecisionFingerprint,
   };
 }
 
@@ -341,21 +339,52 @@ function resolveRepositorySelectionForClaimedWork(
 ): ReturnType<typeof resolveRepositorySelection> {
   const checkoutId = typeof args.checkout_id === 'string' ? args.checkout_id.trim() : '';
   const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
-  const repository = resolveRepositorySelection({
+  let repository = resolveRepositorySelection({
     repoId: repoIdValue || undefined,
     checkoutId: checkoutId || undefined,
     controllerHome,
     allowSoleRepository: true,
   });
-  if (!explicitWorkId || checkoutId) return repository;
-  const work = resolveExplicitClaimedRepositoryWork(controllerHome, repository, caller, explicitWorkId);
-  if (!work?.checkoutId || work.checkoutId === repository.activeCheckoutId) return repository;
-  return resolveRepositorySelection({
-    repoId: repository.repoId,
-    checkoutId: work.checkoutId,
-    controllerHome,
-    allowSoleRepository: true,
-  });
+  if (!explicitWorkId) return repository;
+  const recordedWork = getWorkContract({ controllerHome, repoId: repository.repoId }, explicitWorkId);
+  const recordedHandle = readWorkHandle(controllerHome, repository.repoId, explicitWorkId);
+  const workCheckoutId = recordedHandle?.checkoutId?.trim() || recordedWork?.checkoutId?.trim();
+  if (!checkoutId && workCheckoutId && workCheckoutId !== repository.activeCheckoutId) {
+    repository = resolveRepositorySelection({
+      repoId: repository.repoId,
+      checkoutId: workCheckoutId,
+      controllerHome,
+      allowSoleRepository: true,
+    });
+  }
+  let work = resolveExplicitClaimedRepositoryWork(controllerHome, repository, caller, explicitWorkId);
+  if (!work) return repository;
+  if (work.workKind !== 'repository_change') {
+    work = promoteWorkToRepositoryChange({ controllerHome, repoId: repository.repoId }, work.workId);
+  }
+  const principalId = caller?.principalId?.trim();
+  const sessionId = caller?.sessionId?.trim();
+  const controllerInstanceId = caller?.controllerInstanceId?.trim();
+  if (principalId && sessionId && controllerInstanceId) {
+    ensureRunningRepositoryWorkCheckout({
+      controllerHome,
+      repository,
+      workId: work.workId,
+      identity: { principalId, sessionId, controllerInstanceId },
+    });
+    const refreshedWork = getWorkContract({ controllerHome, repoId: repository.repoId }, work.workId);
+    const refreshedHandle = readWorkHandle(controllerHome, repository.repoId, work.workId);
+    const refreshedCheckoutId = refreshedHandle?.checkoutId?.trim() || refreshedWork?.checkoutId?.trim();
+    if (refreshedCheckoutId && refreshedCheckoutId !== repository.activeCheckoutId) {
+      repository = resolveRepositorySelection({
+        repoId: repository.repoId,
+        checkoutId: refreshedCheckoutId,
+        controllerHome,
+        allowSoleRepository: true,
+      });
+    }
+  }
+  return repository;
 }
 
 function rawDefaultBranchMergeCommand(repository: ReturnType<typeof resolveRepositorySelection>, command: unknown): boolean {
@@ -372,7 +401,7 @@ function rawDefaultBranchMergeCommand(repository: ReturnType<typeof resolveRepos
 
 interface HistoricalReadOnlyWorkContext {
   workId: string;
-  status: string;
+  state: WorkContract['semanticState'];
   mode: 'historical_read_only_observation';
   attribution: 'not_active_work';
 }
@@ -385,12 +414,12 @@ function historicalReadOnlyWorkContext(
   const requestedWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
   if (!requestedWorkId) return undefined;
   const work = getWorkContract({ controllerHome, repoId: repository.repoId }, requestedWorkId);
-  if (!work || !isTerminalWorkContractStatus(work.status)) return undefined;
+  if (!work || semanticWorkState(work) === 'open') return undefined;
   const classification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
   if (classification.risk !== 'readonly') return undefined;
   return {
     workId: work.workId,
-    status: work.status,
+    state: work.semanticState,
     mode: 'historical_read_only_observation',
     attribution: 'not_active_work',
   };
@@ -402,7 +431,10 @@ function resolveRepositoryCommandTarget(
   repoIdValue: string,
   caller?: RepositoryToolCallerContext,
 ): {
-  repository: ReturnType<typeof resolveRepositorySelection>;
+  /** Present only for a repository target; absent for an arbitrary workspace. */
+  repository?: ReturnType<typeof resolveRepositorySelection>;
+  /** Typed command target used for scope, cwd, policy, audit and approval storage. */
+  commandTarget: RepositoryCommandScopeTarget;
   executionIdentity: ResolvedExecutionIdentity;
   workspace?: { workspaceId: string; root: string; registered: false };
   historicalWorkContext?: HistoricalReadOnlyWorkContext;
@@ -415,7 +447,7 @@ function resolveRepositoryCommandTarget(
     }
     const target = resolveEphemeralWorkspaceTarget(workspaceRoot, controllerHome);
     return {
-      repository: target.repository,
+      commandTarget: target.commandTarget,
       executionIdentity: {
         schemaVersion: 1,
         authority: 'ephemeral_workspace',
@@ -442,6 +474,7 @@ function resolveRepositoryCommandTarget(
   if (historicalWorkContext) {
     return {
       repository: selectedRepository,
+      commandTarget: selectedRepository,
       executionIdentity: {
         schemaVersion: 1,
         authority: 'repository',
@@ -460,6 +493,7 @@ function resolveRepositoryCommandTarget(
     : undefined;
   return {
     repository,
+    commandTarget: repository,
     executionIdentity: {
       schemaVersion: 1,
       authority: 'repository',
@@ -591,7 +625,10 @@ function compactProcessCommandPayload(input: {
   route?: string;
   reasons: string[];
   decision?: unknown;
-  repoId: string;
+  /** Repository id for a repository target; absent for an arbitrary workspace target. */
+  repoId?: string;
+  /** Workspace scope id when the target is an arbitrary workspace. */
+  scopeId?: string;
   checkoutId?: string;
   workspace?: { workspaceId: string; root: string; registered: false };
   historicalWorkContext?: HistoricalReadOnlyWorkContext;
@@ -700,8 +737,8 @@ function compactProcessCommandPayload(input: {
 
 function emptyRepositoryMigration(repository: ReturnType<typeof registerRepository>) {
   return {
-    repoId: repository.repoId,
-    checkoutId: repository.activeCheckoutId,
+  repoId: repository.repoId,
+  checkoutId: repository.activeCheckoutId,
     scanned: 0,
     updated: 0,
     unresolved: 0,
@@ -867,39 +904,6 @@ export async function callRepositoryTool(
         const payload = typeof args.payload === 'object' && args.payload !== null
           ? args.payload as Record<string, unknown>
           : {};
-        if (operation === 'assess_work_mode') {
-          const description = typeof payload.description === 'string'
-            ? payload.description
-            : typeof args.description === 'string' ? args.description : '';
-          const assessment = assessWorkMode({
-            description,
-            knownPaths: Array.isArray(payload.known_paths) ? payload.known_paths.map(String) : undefined,
-            expectedFiles: typeof payload.expected_files === 'number' ? payload.expected_files : undefined,
-            expectedChangedLines: typeof payload.expected_changed_lines === 'number' ? payload.expected_changed_lines : undefined,
-            requiresInvestigation: payload.requires_investigation === true,
-            requiresParallelism: payload.requires_parallelism === true,
-            requiresLongRunningChecks: payload.requires_long_running_checks === true,
-            needsDependencies: payload.needs_dependencies === true,
-            requiresIndependentDeliverables: payload.requires_independent_deliverables === true,
-            independentTaskCount: typeof payload.independent_task_count === 'number' ? payload.independent_task_count : undefined,
-            requiresRemoteWrite: payload.requires_remote_write === true || payload.remote_write === true,
-            requiresRecovery: payload.requires_recovery === true,
-            agentRequested: payload.agent_requested === true || payload.requires_worker === true,
-            requiresWorkerIsolation: payload.requires_worker_isolation === true,
-            risk: typeof payload.risk === 'string' ? payload.risk as 'low' | 'medium' | 'high' | 'destructive' : undefined,
-            explicitMode: parseExplicitTaskMode(payload.mode),
-          });
-          return result({
-            assessment,
-            routing: {
-              path: assessment.executionPath,
-              reasons: assessment.reasons,
-              recommendedMode: assessment.recommendedMode,
-              issueRequired: assessment.issueRequired,
-            },
-            nextTools: assessment.nextTools,
-          });
-        }
         const internalTool = {
           batch_execute: 'repository_batch_execute',
           lanes_execute: 'repository_lanes_execute',
@@ -924,8 +928,8 @@ export async function callRepositoryTool(
           : readRepositoryGitStatusSample(controllerHome, repository.repoId, repository.activeCheckoutId);
         return result({
           status: status ?? {
-            repoId: repository.repoId,
-            checkoutId: repository.activeCheckoutId,
+  repoId: repository.repoId,
+  checkoutId: repository.activeCheckoutId,
             sampleSource: 'daemon-sample',
             sampled: false,
             observedAt: null,
@@ -972,24 +976,14 @@ export async function callRepositoryTool(
           allowSoleRepository: true,
         });
         return result({
-          repoId: repository.repoId,
-          checkoutId: repository.activeCheckoutId,
+  repoId: repository.repoId,
+  checkoutId: repository.activeCheckoutId,
           plan: buildSafePatchPlan(repository, { operations: args.operations, chunkSize: args.chunk_size }),
         });
       }
       case 'repository_safe_patch_apply': {
         const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
         const binding = safePatchEditBinding(controllerHome, repository, caller, args);
-        if (binding?.workId) {
-          const work = getWorkContract({ controllerHome, repoId: repository.repoId }, binding.workId);
-          if (!work) throw new Error(`WORK_NOT_FOUND: ${binding.workId}`);
-          const requestedPaths = buildSafePatchPlan(repository, { operations: args.operations, chunkSize: args.chunk_size })
-            .chunks.flatMap((chunk) => chunk.paths);
-          assertWorkPathsWithinScope(work, requestedPaths, {
-            forbidden: 'WORK_MUTATION_FORBIDDEN_PATH',
-            outOfScope: 'WORK_MUTATION_PATH_OUT_OF_SCOPE',
-          });
-        }
         const applied = withControllerLock(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
@@ -1009,6 +1003,7 @@ export async function callRepositoryTool(
                   repository,
                   workId: binding.workId,
                   principalId: binding.principalId ?? caller?.principalId ?? '',
+                  sessionId: caller?.sessionId,
                 })
               : undefined;
             const patchResult = applySafePatch(repository, {
@@ -1080,8 +1075,8 @@ export async function callRepositoryTool(
           errorMessage: firstFailure?.message,
         });
         const payload = {
-          repoId: repository.repoId,
-          checkoutId: repository.activeCheckoutId,
+  repoId: repository.repoId,
+  checkoutId: repository.activeCheckoutId,
           ...applied as unknown as Record<string, unknown>,
           phase: digest.phase,
           statusLabel: digest.statusLabel,
@@ -1096,12 +1091,12 @@ export async function callRepositoryTool(
       }
       case 'repository_command_preview': {
         const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
-        const { repository } = target;
+        const { commandTarget } = target;
         const execution = withControllerLock(
           controllerHome,
-          { scope: 'repository', repoId: repository.repoId },
+          { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
           'mcp:repository_command_preview',
-          () => executeRepositoryCommand(controllerHome, repository, {
+          () => executeRepositoryCommand(controllerHome, commandTarget, {
             command: args.command as string | string[],
             cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
             dryRun: true,
@@ -1109,23 +1104,32 @@ export async function callRepositoryTool(
           }),
           60_000,
         );
+        // Repository targets keep repoId/checkoutId. An arbitrary workspace target
+        // reports its workspace scope id and never a repository id.
+        const { repoId: _previewRepoId, checkoutId: _previewCheckoutId, ...workspacePreviewFields } = execution as unknown as Record<string, unknown>;
         return result({
-          ...execution as unknown as Record<string, unknown>,
+          ...(commandTarget.repoId ? execution as unknown as Record<string, unknown> : workspacePreviewFields),
+          ...(commandTarget.repoId ? {} : { scopeId: commandExecutionScopeKey(commandTarget) }),
           ...(target.workspace ? { workspace: target.workspace } : {}),
         });
       }
       case 'repository_command_execute': {
         const explorationGuidance = fragmentedRepositoryExplorationGuidance(args.command);
         let target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
-        let { repository, executionIdentity, historicalWorkContext } = target;
+        let { repository, commandTarget, executionIdentity, historicalWorkContext } = target;
+        // Repository targets keep their established identity fields. An arbitrary
+        // workspace target reports a workspace scope id and never a repository id.
+        const commandScopeKey = commandExecutionScopeKey(commandTarget);
+        const scopeFields: Record<string, unknown> = repository
+          ? { repoId: commandScopeKey, checkoutId: commandTarget.activeCheckoutId }
+          : { scopeId: commandScopeKey };
         const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
-        if (!explicitWorkId) assertNoBoundExecutionSessionMutation(controllerHome, repository, caller);
-        const deliveryWorkId = rawDefaultBranchMergeCommand(repository, args.command)
-          ? executionIdentity.workId
-          : undefined;
-        if (deliveryWorkId) {
-          throw new Error(`WORK_DELIVERY_REQUIRES_FINALIZE: ${deliveryWorkId} must pass Work verification and use rh_work finalize before default-branch integration`);
-        }
+        // Repository-semantic checks apply only when a repository target exists;
+        // an arbitrary workspace has no bound session, default branch, or Work.
+        if (repository && !explicitWorkId) assertNoBoundExecutionSessionMutation(controllerHome, repository, caller);
+        // Git integration is a capability with its own repository, scope and
+        // concurrency checks.  A Work's semantic completion and any optional
+        // verification/review evidence never admit or deny this operation.
         const timeoutMs = typeof args.timeout_ms === 'number'
           ? args.timeout_ms
           : typeof args.timeout_ms === 'string'
@@ -1155,7 +1159,7 @@ export async function callRepositoryTool(
         const routeClass = classifyRepositoryCommandRoute(args.command as string | string[], {
           forceDurable,
           workId: executionIdentity.workId,
-          defaultBranch: repository.defaultBranch,
+          defaultBranch: commandTarget.defaultBranch,
           timeoutMs,
         });
         const processRequestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
@@ -1168,7 +1172,7 @@ export async function callRepositoryTool(
           );
         }
         let mutationAuthority: ReturnType<typeof ensureRepositoryMutationWorkHandle> | undefined;
-        const mutationClassification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
+        const mutationClassification = classifyRepositoryCommand(args.command as string | string[], commandTarget.defaultBranch);
         if (
           (mutationClassification.risk === 'workspace_write' || mutationClassification.risk === 'destructive')
           && (routeClass.route === 'process_direct' || routeClass.route === 'process_managed')
@@ -1176,51 +1180,43 @@ export async function callRepositoryTool(
           if (executionIdentity.workId) {
             mutationAuthority = withControllerLock(
               controllerHome,
-              { scope: 'repository', repoId: repository.repoId },
+              { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
               'mcp:repository_command_execute:mutation-authority',
               () => ensureRepositoryMutationWorkHandle({
                 controllerHome,
-                repository,
+                repository: repository!,
                 workId: executionIdentity.workId!,
                 principalId: caller?.principalId ?? '',
+                sessionId: caller?.sessionId,
                 deferEffectPromotion: true,
               }),
               60_000,
             );
-            // Pre-mutation reconciliation may advance expectedHead. Re-resolve
-            // immutable execution identity after that durable CAS and before spawn.
-            target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
-            ({ repository, executionIdentity, historicalWorkContext } = target);
+            // Pre-mutation reconciliation may advance expectedHead. Preserve the
+            // complete WorkHandle identity after that CAS; rebuilding a generic
+            // repository identity here drops branch/expectedHead and prevents the
+            // successful command from settling its legitimate successor HEAD.
+            executionIdentity = executionIdentityForWork(repository!, mutationAuthority.handle);
           } else {
             withControllerLock(
               controllerHome,
-              { scope: 'repository', repoId: repository.repoId },
+              { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
               'mcp:repository_command_execute:unattributed-mutation-authority',
               () => assertCanonicalRepositoryMutationWorkHandleAvailable({
                 controllerHome,
-                repositoryId: repository.repoId,
-                checkoutId: repository.activeCheckoutId,
+                repositoryId: commandExecutionScopeKey(commandTarget),
+                checkoutId: commandTarget.activeCheckoutId ?? '',
               }),
               60_000,
             );
           }
         }
-        if (executionIdentity.workId && (rawCommitScope.kind === 'staged_index' || rawCommitScope.kind === 'explicit_paths')) {
-          const work = getWorkContract({ controllerHome, repoId: repository.repoId }, executionIdentity.workId);
-          if (!work) throw new Error(`WORK_NOT_FOUND: ${executionIdentity.workId}`);
-          const commitScope = resolveRepositoryGitCommitScope(repository, {
-            paths: rawCommitScope.kind === 'explicit_paths' ? rawCommitScope.paths : undefined,
-          });
-          assertWorkPathsWithinScope(work, commitScope.paths, {
-            forbidden: 'WORK_COMMIT_STAGED_PATH_FORBIDDEN',
-            outOfScope: 'WORK_COMMIT_STAGED_PATH_OUT_OF_SCOPE',
-          });
-        }
-        // repository_command_execute owns its command execution architecture.
-        // Do not send ordinary command text through Thin Harness semantic risk
-        // routing: that creates duplicate regex/classifier policy and turns
-        // unknown CLI shapes into false durable/reject decisions. Only an
-        // explicitly requested durable mode uses the generic durable router.
+        // Compatibility boundary only: this facade owns repository-domain
+        // context (target resolution, Git/source mutation fencing and legacy
+        // response translation), while Unified Process Runtime owns execution,
+        // handles, cancellation and persistence. Do not create another generic
+        // command executor here. Thin Harness is consulted only for an explicit
+        // external durable boundary, not as a second command classifier.
         const routingDecision = forceDurable
           ? routeExecution({
               operation: 'repository_command_execute',
@@ -1255,8 +1251,7 @@ export async function callRepositoryTool(
                 path: routeClass.reason,
                 route: 'reject',
                 status: 'rejected',
-                repoId: repository.repoId,
-                checkoutId: repository.activeCheckoutId,
+                ...scopeFields,
                 workspace: target.workspace,
                 message: routeClass.reason === 'standalone_recovery_lifecycle_required'
                   ? 'Canonical Runtime and connector lifecycle operations must be submitted to the standalone Forge Recovery owner, not executed as a child of repository Process Runtime.'
@@ -1277,8 +1272,7 @@ export async function callRepositoryTool(
                 accepted: false,
                 mode: 'durable',
                 path: 'ephemeral_workspace_promotion_required',
-                repoId: repository.repoId,
-                checkoutId: repository.activeCheckoutId,
+                ...scopeFields,
                 workspace: target.workspace,
                 message: 'Ephemeral workspaces must be registered before durable remote effects so Process identity and reconciliation have a stable repository authority.',
                 suggestedOperation: 'repository_register',
@@ -1287,7 +1281,7 @@ export async function callRepositoryTool(
             if (routeClass.route === 'process_direct' || routeClass.route === 'process_managed' || routeClass.route === 'durable') {
               const processResult = await executeRepositoryCommandViaProcessRuntime({
                 controllerHome,
-                repository,
+                repository: commandTarget,
                 command: args.command as string | string[],
                 cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
                 timeoutMs,
@@ -1300,18 +1294,18 @@ export async function callRepositoryTool(
                 workId: executionIdentity.workId,
                 executionIdentity,
                 allowNonGitWorkspace: target.workspace !== undefined,
+                principalId: caller?.principalId ?? undefined,
               });
-              if (mutationAuthority && (processResult.route === 'process_direct' || processResult.route === 'process_managed')) {
+              if (repository && mutationAuthority && (processResult.route === 'process_direct' || processResult.route === 'process_managed')) {
                 const processHandle = processResult.process;
                 const postStatus = repositoryGitStatus(repository);
                 const expectedHead = mutationAuthority.handle.expectedHead;
-                const mutationObserved = (processHandle !== undefined && processHandle.completed !== true)
-                  || !postStatus.clean
+                const mutationObserved = !postStatus.clean
                   || (Boolean(postStatus.head) && postStatus.head !== expectedHead);
                 if (mutationObserved) {
                   withControllerLock(
                     controllerHome,
-                    { scope: 'repository', repoId: repository.repoId },
+                    { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
                     'mcp:repository_command_execute:mutation-started',
                     () => markRepositoryMutationStarted({
                       controllerHome,
@@ -1342,8 +1336,7 @@ export async function callRepositoryTool(
                     mode: processResult.route,
                     path: processResult.reason ?? routeClass.reason,
                     route: processResult.route,
-                    repoId: repository.repoId,
-                    checkoutId: repository.activeCheckoutId,
+                    ...scopeFields,
                     workspace: target.workspace,
                     status: processResult.executionStatus,
                     policyDecision: processResult.policyDecision ?? 'approval_required',
@@ -1370,8 +1363,7 @@ export async function callRepositoryTool(
                   route: processResult.route,
                   reasons: [processResult.reason ?? routeClass.reason, ...routingDecision.reasons],
                   decision: detailLevel === 'detail' ? routingDecision : undefined,
-                  repoId: repository.repoId,
-                  checkoutId: repository.activeCheckoutId,
+                  ...scopeFields,
                   workspace: target.workspace,
                   historicalWorkContext,
                   processId: handle?.processId,
@@ -1434,8 +1426,7 @@ export async function callRepositoryTool(
             accepted: false,
             mode: 'durable',
             path: 'ephemeral_workspace_promotion_required',
-            repoId: repository.repoId,
-            checkoutId: repository.activeCheckoutId,
+            ...scopeFields,
             workspace: target.workspace,
             message: 'Ephemeral workspaces support bounded local Direct/Managed execution only. Register the directory before durable, remote, release, or resumable Work.',
             suggestedOperation: 'repository_register',
@@ -1449,13 +1440,13 @@ export async function callRepositoryTool(
           try {
             const routeClass = classifyRepositoryCommandRoute(args.command as string | string[], {
               forceDurable: false,
-              defaultBranch: repository.defaultBranch,
+              defaultBranch: commandTarget.defaultBranch,
               timeoutMs,
             });
             if (routeClass.route === 'process_direct') {
               const processResult = await executeRepositoryCommandViaProcessRuntime({
                 controllerHome,
-                repository,
+                repository: commandTarget,
                 command: args.command as string | string[],
                 cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
                 timeoutMs,
@@ -1463,6 +1454,7 @@ export async function callRepositoryTool(
                 requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
                 workId: executionIdentity.workId,
                 executionIdentity,
+                principalId: caller?.principalId ?? undefined,
               });
               if (processResult.route === 'process_direct') {
                 const execRecord = processResult.process as unknown as Record<string, unknown> | undefined;
@@ -1476,8 +1468,7 @@ export async function callRepositoryTool(
                     mode: 'durable',
                     reasons: ['durable_worker_inline_process_direct', routeClass.reason, ...routingDecision.reasons],
                   }),
-                  repoId: repository.repoId,
-                  checkoutId: repository.activeCheckoutId,
+                  ...scopeFields,
                   ok,
                   processId: typeof execRecord?.processId === 'string' ? execRecord.processId : undefined,
                   status: typeof execRecord?.status === 'string' ? execRecord.status : undefined,
@@ -1544,8 +1535,8 @@ export async function callRepositoryTool(
         const batch = await executeRepositoryBatch(
           { controllerHome, repository },
           {
-            repoId: repository.repoId,
-            checkoutId: repository.activeCheckoutId,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
             mode: args.mode === 'fast' || args.mode === 'durable' || args.mode === 'auto' ? args.mode : 'auto',
             steps,
             stopOnError: args.stop_on_error !== false,
@@ -1569,8 +1560,8 @@ export async function callRepositoryTool(
         const lanes = await executeLightweightLanes(
           { controllerHome, repository },
           {
-            repoId: repository.repoId,
-            checkoutId: repository.activeCheckoutId,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
             readLanes: Array.isArray(args.read_lanes)
               ? args.read_lanes
                 .filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null)

package/adapters/mcp/toolset-names.ts

@@ -38,6 +38,11 @@ export const DEFAULT_CONTROLLER_TOOL_NAMES = [
   'plugin_action_execute',
 
   // Managed Process Runtime lifecycle (attach / poll / cancel — never re-exec).
+  // process_exec is the canonical host-local command lane: the Forge instance is
+  // the target, cwd is an execution argument, and it is authorized by one
+  // explicit `process:exec` canonical Grant. repository_command_execute stays as
+  // translation-only compatibility over the repository target.
+  'process_exec',
   'process_get',
   'process_wait',
   'process_logs',

package/adapters/mcp/toolset.ts

@@ -11,6 +11,8 @@ import { runtimeToolDefinitions } from './runtime-gateway/runtime-tool-definitio
 import { executionToolDefinitions } from './runtime-gateway/execution-tools';
 import { processToolDefinitions } from './runtime-gateway/process-tools';
 import { injectDurableCommandFields } from './runtime-gateway/router';
+import { injectAutomationEnvelopeFields } from './runtime-gateway/automation-receipt-adapter';
+import { injectCognitionSettlementFields } from './runtime-gateway/cognition-settlement';
 import { DEFAULT_CONTROLLER_TOOL_NAMES, PREFERRED_FACADE_TOOL_NAMES, STABLE_CONTROLLER_TOOL_NAMES } from './toolset-names';
 export { BOOTSTRAP_CONTROLLER_TOOL_NAMES, CORE_CONTROLLER_TOOL_NAMES, DEFAULT_CONTROLLER_TOOL_NAMES, PREFERRED_FACADE_TOOL_NAMES, STABLE_CONTROLLER_TOOL_NAMES } from './toolset-names';
 import type { McpToolset } from './types';
@@ -197,10 +199,9 @@ function buildStaticControllerExposureSnapshot(
   const definitions = expectedToolNames
     .map((name) => definitionByName.get(name))
     .filter((definition): definition is McpToolDefinition => Boolean(definition))
-    // Fingerprint the definitions that ListTools actually returns. The server
-    // adds durable command fields to every object schema, so calculating the
-    // fence from the pre-injection form would miss a change to those fields.
-    .map(injectDurableCommandFields);
+    // Fingerprint the exact definitions that ListTools returns. Shared transport
+    // contracts are injected here once rather than re-declared by domain registries.
+    .map((definition) => injectCognitionSettlementFields(injectAutomationEnvelopeFields(injectDurableCommandFields(definition))));
   const actualToolNames = definitions.map((tool) => tool.name);
   const actualSet = new Set(actualToolNames);
   const expectedSet = new Set(expectedToolNames);
@@ -272,7 +273,7 @@ export function clearControllerExposureCacheForTest(): void {
 export function allControllerToolDefinitions(ctx: MultiRepositoryMcpToolContext): McpToolDefinition[] {
   return uniqueDefinitions(
     runtimeToolDefinitions.concat(executionToolDefinitions, processToolDefinitions, accessToolDefinitions, repositoryToolDefinitions, buildMultiRepositoryToolDefinitions(ctx)),
-  ).definitions;
+  ).definitions.map((definition) => injectCognitionSettlementFields(injectAutomationEnvelopeFields(injectDurableCommandFields(definition))));
 }
 
 export function controllerExposureSnapshot(ctx: MultiRepositoryMcpToolContext): ControllerExposureSnapshot {