@moretea-labs/forge 1.8.0 → 1.8.2

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, 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,
     },
   }),
@@ -245,25 +244,23 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
     validation_only: { type: 'boolean', description: 'When true, do not edit. Reconcile/reuse the existing session validation Processes identified by session_id/check_ids/validation_request_id.' },
     apply_mode: { type: 'string', enum: ['sync', 'async'], description: 'Defaults to sync for interactive development. Set async only for a separately durable operation.' },
   }),
-  definition('repository_command_preview', 'Preview one repository-scoped local command with classification, approval token, and Git snapshots.', {
+  definition('execute_command', 'Single terminal entry. Repository and authorized workspace commands need no Work or Plan. Explicit scope=host uses the existing ForgeInstance process:exec Grant. Process Runtime owns execution, process handles and timeouts; Git ownership checks remain mechanical.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-    command: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Legacy shell string or typed argv array. Typed argv executes without a shell.' },
+    work_id: { type: 'string', description: 'Optional Work provenance; ordinary commands never require a Work. Work-attributed effects require a stable request_id.' },
+    scope: { type: 'string', enum: ['repository', 'host'], description: 'Defaults to repository; host requires an explicit process:exec ForgeInstance Grant.' },
+    command: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Repository: typed argv or shell string; host: typed argv only.' },
+    shell_command: { type: 'string', description: 'Host shell only; mutually exclusive with command and requires scope=host.' },
+    request_id: { type: 'string', description: 'Stable invocation id for reconnect without duplicate effects.' },
     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.', {
-    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.' },
-    command: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Legacy shell string or typed argv array. Typed argv executes without a shell.' },
-    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.' },
-    approval_token: { type: 'string', description: 'Exact approval token returned by repository_command_preview.' },
+    dry_run: { type: 'boolean', description: 'Preview without executing: returns command classification, approval token and Git snapshots for repository/workspace target.' },
+    approval_token: { type: 'string', description: 'Exact approval token returned by execute_command(dry_run=true).' },
     approval_request_id: { type: 'string', description: 'Resolved approvalRequestId returned by approval_resolve.' },
     timeout_ms: { type: 'number', description: 'Optional execution timeout in milliseconds.' },
-    max_output_bytes: { type: 'number', description: 'Optional cap for captured stdout/stderr.' },
-  }, ['command']),
+    max_output_bytes: { type: 'number', minimum: 1024, maximum: 1048576, description: 'Captured output limit 1024–1048576 bytes.' },
+    interactive_wait_ms: { type: 'number', description: 'Optional short attachment window; long-running processes return a handle.' },
+  }),
 
   // Thin Harness V1 is exposed through repository_workbench operations to keep the stable tool surface bounded.
 ];
@@ -306,11 +303,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 +337,49 @@ 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;
+  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,
+    });
+  }
   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 (!work) return repository;
+  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 +396,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 +409,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 +426,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 +442,7 @@ function resolveRepositoryCommandTarget(
     }
     const target = resolveEphemeralWorkspaceTarget(workspaceRoot, controllerHome);
     return {
-      repository: target.repository,
+      commandTarget: target.commandTarget,
       executionIdentity: {
         schemaVersion: 1,
         authority: 'ephemeral_workspace',
@@ -442,6 +469,7 @@ function resolveRepositoryCommandTarget(
   if (historicalWorkContext) {
     return {
       repository: selectedRepository,
+      commandTarget: selectedRepository,
       executionIdentity: {
         schemaVersion: 1,
         authority: 'repository',
@@ -460,6 +488,7 @@ function resolveRepositoryCommandTarget(
     : undefined;
   return {
     repository,
+    commandTarget: repository,
     executionIdentity: {
       schemaVersion: 1,
       authority: 'repository',
@@ -557,33 +586,6 @@ function failure(error: unknown): RepositoryToolResult {
   return { ...result({ error: { code, message, ...(compactDetails !== undefined ? { details: compactDetails } : {}) } }), isError: true };
 }
 
-interface RepositoryExplorationGuidance {
-  code: 'FRAGMENTED_REPOSITORY_EXPLORATION';
-  recommendedTool: 'rh_context';
-  recommendedOperation: 'search';
-  message: string;
-}
-
-function fragmentedRepositoryExplorationGuidance(command: unknown): RepositoryExplorationGuidance | undefined {
-  if (typeof command !== 'string') return undefined;
-  const segments = command.split(/(?:&&|\|\||[;|])/g);
-  const readPrograms = new Set<string>();
-  let readStepCount = 0;
-  for (const segment of segments) {
-    const match = segment.trim().match(/^(?:(?:command|env)\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*(rg|grep|sed|cat|head|tail)\b/i);
-    if (!match) continue;
-    readStepCount += 1;
-    readPrograms.add(match[1]!.toLowerCase());
-  }
-  if (readStepCount < 2) return undefined;
-  return {
-    code: 'FRAGMENTED_REPOSITORY_EXPLORATION',
-    recommendedTool: 'rh_context',
-    recommendedOperation: 'search',
-    message: `Detected ${readStepCount} chained repository read steps (${[...readPrograms].join(', ')}). Prefer a broad rh_context request first, then repeat rh_context with selected paths or relationships when more evidence can improve correctness; keep shell search as fallback when the Context Plane cannot supply the needed evidence.`,
-  };
-}
-
 function compactProcessCommandPayload(input: {
   accepted?: boolean;
   mode: string;
@@ -591,7 +593,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;
@@ -607,7 +612,6 @@ function compactProcessCommandPayload(input: {
   /** summary (default) omits nested process / routing dumps; detail restores diagnostics. */
   detailLevel?: 'summary' | 'detail';
   includeFullProcess?: boolean;
-  guidance?: RepositoryExplorationGuidance;
 }): Record<string, unknown> {
   const output = compactCommandOutput(input.stdout, input.stderr, { ok: input.ok === true });
   const detail = input.detailLevel === 'detail' || input.includeFullProcess === true;
@@ -643,7 +647,6 @@ function compactProcessCommandPayload(input: {
       stderr: output.stderr ?? '',
       ...(output.stdoutTruncated ? { stdoutTruncated: true, stdoutBytes: output.stdoutBytes } : {}),
       ...(output.stderrTruncated ? { stderrTruncated: true, stderrBytes: output.stderrBytes } : {}),
-      ...(input.guidance ? { guidance: input.guidance, suggestedOperation: 'rh_context' } : {}),
     };
     if (completed && !ok) {
       payload.error = {
@@ -692,7 +695,6 @@ function compactProcessCommandPayload(input: {
       }
       : {}),
     durableSideEffects: effects,
-    ...(input.guidance ? { guidance: input.guidance, suggestedOperation: 'rh_context' } : {}),
     next: input.next,
     detailLevel: 'detail',
   };
@@ -700,8 +702,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,
@@ -734,7 +736,7 @@ export async function callRepositoryTool(
   args: Record<string, unknown>,
   caller?: RepositoryToolCallerContext,
 ): Promise<RepositoryToolResult | undefined> {
-  if (!name.startsWith('repository_') && name !== 'read_repository_file') return undefined;
+  if (!name.startsWith('repository_') && name !== 'read_repository_file' && name !== 'execute_command') return undefined;
   try {
     const repoIdValue = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
     switch (name) {
@@ -867,39 +869,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',
@@ -920,12 +889,12 @@ export async function callRepositoryTool(
       case 'repository_git_status': {
         const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
         const status = args.refresh === true
-          ? writeRepositoryGitStatusSample(controllerHome, repository)
+          ? await writeRepositoryGitStatusSample(controllerHome, repository)
           : 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 +941,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 },
@@ -1003,12 +962,15 @@ export async function callRepositoryTool(
                 workId: binding?.workId,
               });
             }
-            const mutationAuthority = binding?.workId
+            // A validation-only reattachment is not repository mutation admission;
+            // it must never promote a thin investigation to repository_change.
+            const mutationAuthority = binding?.workId && args.validation_only !== true
               ? ensureRepositoryMutationWorkHandle({
                   controllerHome,
                   repository,
                   workId: binding.workId,
                   principalId: binding.principalId ?? caller?.principalId ?? '',
+                  sessionId: caller?.sessionId,
                 })
               : undefined;
             const patchResult = applySafePatch(repository, {
@@ -1080,8 +1042,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,
@@ -1094,38 +1056,47 @@ export async function callRepositoryTool(
         };
         return ok ? result(payload) : { ...result(payload), isError: true };
       }
-      case 'repository_command_preview': {
-        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
-        const { repository } = target;
-        const execution = withControllerLock(
-          controllerHome,
-          { scope: 'repository', repoId: repository.repoId },
-          'mcp:repository_command_preview',
-          () => executeRepositoryCommand(controllerHome, repository, {
-            command: args.command as string | string[],
-            cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
-            dryRun: true,
-            allowNonGitWorkspace: target.workspace !== undefined,
-          }),
-          60_000,
-        );
-        return result({
-          ...execution as unknown as Record<string, unknown>,
-          ...(target.workspace ? { workspace: target.workspace } : {}),
-        });
-      }
-      case 'repository_command_execute': {
-        const explorationGuidance = fragmentedRepositoryExplorationGuidance(args.command);
+      case 'execute_command': {
+        if (args.scope !== undefined && args.scope !== 'repository') throw new Error('COMMAND_SCOPE_INVALID: host scope uses the authorized host command lane');
+        if (args.shell_command !== undefined) throw new Error('COMMAND_SCOPE_INVALID: shell_command requires scope=host');
+        if (args.command === undefined) throw new Error('COMMAND_REQUIRED: repository commands require command');
+        if (args.dry_run === true) {
+          const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
+          const { commandTarget } = target;
+          const execution = withControllerLock(
+            controllerHome,
+            { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
+            'mcp:execute_command:preview',
+            () => executeRepositoryCommand(controllerHome, commandTarget, {
+              command: args.command as string | string[],
+              cwd: typeof args.cwd === 'string' ? args.cwd : undefined,
+              dryRun: true,
+              allowNonGitWorkspace: target.workspace !== undefined,
+            }),
+            60_000,
+          );
+          const { repoId: _previewRepoId, checkoutId: _previewCheckoutId, ...workspacePreviewFields } = execution as unknown as Record<string, unknown>;
+          return result({
+            ...(commandTarget.repoId ? execution as unknown as Record<string, unknown> : workspacePreviewFields),
+            ...(commandTarget.repoId ? {} : { scopeId: commandExecutionScopeKey(commandTarget) }),
+            ...(target.workspace ? { workspace: target.workspace } : {}),
+          });
+        }
         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 +1126,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 +1139,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,54 +1147,46 @@ export async function callRepositoryTool(
           if (executionIdentity.workId) {
             mutationAuthority = withControllerLock(
               controllerHome,
-              { scope: 'repository', repoId: repository.repoId },
-              'mcp:repository_command_execute:mutation-authority',
+              { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
+              'mcp:execute_command: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 },
-              'mcp:repository_command_execute:unattributed-mutation-authority',
+              { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
+              'mcp:execute_command: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',
+              operation: 'execute_command',
               mode: 'durable',
               timeoutMs,
               background: args.background === true || args.async === true,
@@ -1255,8 +1218,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 +1239,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 +1248,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,19 +1261,19 @@ 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 },
-                    'mcp:repository_command_execute:mutation-started',
+                    { scope: 'repository', repoId: commandExecutionScopeKey(commandTarget) },
+                    'mcp:execute_command:mutation-started',
                     () => markRepositoryMutationStarted({
                       controllerHome,
                       repository,
@@ -1342,8 +1303,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',
@@ -1352,7 +1312,7 @@ export async function callRepositoryTool(
                     message: authorization.decision === 'user_confirmation_required'
                       ? authorization.humanSummary
                       : authorization.reason,
-                    suggestedOperation: 'repository_command_preview',
+                    suggestedOperation: 'execute_command(dry_run=true)',
                   });
                 }
                 const completed = directWithoutHandle || handle?.completed === true;
@@ -1370,8 +1330,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,
@@ -1382,7 +1341,6 @@ export async function callRepositoryTool(
                   stdout: processResult.stdout,
                   stderr: processResult.stderr,
                   durableSideEffects: processResult.durableSideEffects,
-                  guidance: explorationGuidance,
                   next: directWithoutHandle
                     ? processResult.reason === 'readonly_fast_path'
                       ? 'Bounded readonly execution completed without Process record / Lease / Local Job / ExecutionJob / Worker.'
@@ -1424,7 +1382,7 @@ export async function callRepositoryTool(
             // Process Runtime is authoritative. Falling through could spawn the
             // same command again through the legacy Fast/Local Job path.
             if (process.env.FORGE_DEBUG_PROCESS_RUNTIME === '1') {
-              console.error('[repository_command_execute] process runtime error', error);
+              console.error('[execute_command] process runtime error', error);
             }
             return failure(error);
           }
@@ -1434,8 +1392,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 +1406,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 +1420,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 +1434,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,
@@ -1495,7 +1452,7 @@ export async function callRepositoryTool(
             }
           } catch (error) {
             if (process.env.FORGE_DEBUG_PROCESS_RUNTIME === '1') {
-              console.error('[repository_command_execute] durable worker inline process runtime error', error);
+              console.error('[execute_command] durable worker inline process runtime error', error);
             }
           }
         }
@@ -1505,7 +1462,7 @@ export async function callRepositoryTool(
           path: 'external_controller_required',
           routing: compactRoutingSummary({ path: 'durable', mode: 'durable', reasons: [routingDecision.reasons.join(','), 'local_bridge_execution_retired'] }),
           message: 'This command requires explicit external Controller handling; Local Bridge Jobs are retired for repository commands.',
-          suggestedOperation: 'Create or claim WorkContract, then use rh_work.launcher_start or a Process Runtime-compatible command.',
+          next: 'This execution boundary requires separate external authority; the model chooses an authorized domain capability or alternative command based on the task.',
           externalEffect: {
             outcome: 'not_started',
             ambiguousFailureOutcome: 'outcome_unknown',
@@ -1544,8 +1501,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 +1526,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)