@moretea-labs/forge 1.6.0 → 1.7.0

package/src/cli/mcp/repository-tools.ts

@@ -24,9 +24,8 @@ import {
 } from '../repositories/registry';
 import { buildControllerWorkbench } from '../repositories/workbench';
 import { applySafePatch, buildSafePatchPlan } from '../repositories/safe-patch';
-import { getEditSessionDiff, type EditSessionBinding } from '../editing/edit-session';
+import { getEditSession, getEditSessionDiff, type EditSessionBinding } from '../editing/edit-session';
 import { buildSyncOperationDigest, classifyUserFacingError } from '../../runtime/control-plane/facade/operation-digest';
-import { diagnoseRepositoryStuckState, listRepositoryGoalRuns, readRepositoryGoalRegistry, runRepositoryGoal, upsertRepositoryGoal } from '../repositories/goal-registry';
 import {
   repositoryGitCommit,
   repositoryGitCreateBranch,
@@ -55,6 +54,9 @@ import {
 } from '../../runtime/execution/process-runtime/command-facade';
 import { assessWorkMode, parseExplicitTaskMode } from '../controller/work-mode';
 import { normalizeRepositoryCommand } from '../repositories/command-normalization';
+import { readRepositoryRange } from '../repository/inspector';
+import { getMcpPolicy } from './policy';
+import { redactMcpText } from './redaction';
 import type { CallToolResult, McpToolDefinition } from './tools';
 import {
   boundUtf8,
@@ -117,6 +119,13 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
     include_removed: { type: 'boolean' },
     detail_level: { type: 'string', enum: ['summary', 'detail'], description: 'Defaults to summary; detail returns the complete checkout history.' },
   }, ['repo_id'], true),
+  definition('read_repository_file', 'Read a line range from one policy-readable repository file.', {
+    repo_id: repoId,
+    checkout_id: { type: 'string' },
+    path: { type: 'string' },
+    start_line: { type: 'number' },
+    end_line: { type: 'number' },
+  }, ['path'], true),
   definition('repository_validate', 'Validate repository identity and migrate legacy ownership.', {
     repo_id: repoId,
     detail_level: { type: 'string', enum: ['summary', 'detail'], description: 'Defaults to summary; detail returns full migration evidence.' },
@@ -136,7 +145,7 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
   }, ['repo_id']),
   definition('repository_remove', 'Soft-remove a repository while retaining audit history.', {
     repo_id: repoId,
-  }, ['repo_id'], true),
+  }, ['repo_id']),
   definition('repository_workbench', 'Return Workbench state or invoke one bounded Thin Harness operation without adding top-level MCP tools. Prefer batch_execute for multi-step status→search→read→diff or read→patch→check flows so ChatGPT pays one routing/receipt ownership cycle.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repository-scoped operations.' },
@@ -152,38 +161,6 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
       additionalProperties: true,
     },
   }),
-
-
-
-  definition('repository_goal_list', 'List durable repository goals stored inside the checkout.', {
-    repo_id: repoId,
-    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-  }, [], true),
-  definition('repository_goal_upsert', 'Create or update one durable repository goal for repeated assistant workflows.', {
-    repo_id: repoId,
-    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-    id: { type: 'string' },
-    title: { type: 'string' },
-    status: { type: 'string', enum: ['active', 'paused', 'done'] },
-    checks: { type: 'array', items: { type: 'string' } },
-    notes: { type: 'string' },
-  }, []),
-  definition('repository_stuck_diagnose', 'Diagnose likely repository workflow blockers from Git state and registered goals.', {
-    repo_id: repoId,
-    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-  }, [], true),
-  definition('repository_goal_run', 'Run one durable repository goal iteration, optionally executing its configured checks and recording a goal-run artifact.', {
-    repo_id: repoId,
-    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-    goal_id: { type: 'string', description: 'Goal id. Defaults to the first active goal.' },
-    run_checks: { type: 'boolean', description: 'When true, execute configured checks. Defaults to diagnosis-only.' },
-  }, []),
-  definition('repository_goal_runs', 'List recent repository goal-run artifacts.', {
-    repo_id: repoId,
-    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
-    limit: { type: 'number' },
-  }, [], true),
-
   definition('repository_git_status', 'Return a structured Git status snapshot for the selected repository checkout.', {
     repo_id: repoId,
     checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple local clones.' },
@@ -270,7 +247,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 local command through Full Access, Goal delegation, or a resumable approval request. Legacy preview-token callers remain compatible.', {
+  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.' },
@@ -316,23 +293,56 @@ export interface RepositoryToolCallerContext {
   controllerInstanceId?: string;
 }
 
+function claimedExplicitWork(
+  controllerHome: string,
+  repoId: string,
+  caller: RepositoryToolCallerContext | undefined,
+  requestedWorkId: string,
+) {
+  if (!caller?.principalId?.trim()) return undefined;
+  const work = getWorkContract({ controllerHome, repoId }, requestedWorkId);
+  if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${requestedWorkId}`);
+  const owner = getControllerSession({ controllerHome, repoId }, requestedWorkId);
+  if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${requestedWorkId}`);
+  if ((owner.principalId?.trim() || owner.controllerId) !== caller.principalId.trim()) throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${requestedWorkId}`);
+  return work;
+}
+
+function assertNoBoundExecutionSessionMutation(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  caller?: RepositoryToolCallerContext,
+): void {
+  if (!caller?.principalId?.trim() || !caller.sessionId?.trim()) return;
+  const executionSession = readExecutionSession(controllerHome, {
+    sessionId: caller.sessionId,
+    principalId: caller.principalId,
+    controllerInstanceId: caller.controllerInstanceId,
+  });
+  const workId = executionSession?.activeWorkId?.trim();
+  if (!workId || executionSession?.activeRepositoryId !== repository.repoId) return;
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  if (!work) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
+  if (isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+  }
+  throw new Error(`WORK_ATTRIBUTION_REQUIRED: ${work.workId}; active execution session mutations must pass work_id explicitly`);
+}
+
 function claimedSessionWorkId(
   controllerHome: string,
   repository: ReturnType<typeof resolveRepositorySelection>,
   caller?: RepositoryToolCallerContext,
   explicitWorkId?: unknown,
 ): string | undefined {
-  if (!caller?.principalId?.trim()) return undefined;
   const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
   if (requestedWorkId) {
-    const work = getWorkContract({ controllerHome, repoId: repository.repoId }, requestedWorkId);
-    if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${requestedWorkId}`);
+    const work = claimedExplicitWork(controllerHome, repository.repoId, caller, requestedWorkId);
+    if (!work) return undefined;
     if (work.checkoutId && work.checkoutId !== repository.activeCheckoutId) throw new Error(`WORK_CHECKOUT_MISMATCH: ${requestedWorkId}:${repository.activeCheckoutId}`);
-    const owner = getControllerSession({ controllerHome, repoId: repository.repoId }, requestedWorkId);
-    if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${requestedWorkId}`);
-    if ((owner.principalId?.trim() || owner.controllerId) !== caller.principalId.trim()) throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${requestedWorkId}`);
     return requestedWorkId;
   }
+  if (!caller?.principalId?.trim()) return undefined;
   if (caller.sessionId?.trim()) {
     const executionSession = readExecutionSession(controllerHome, {
       sessionId: caller.sessionId,
@@ -342,8 +352,11 @@ function claimedSessionWorkId(
     const workId = executionSession?.activeWorkId?.trim();
     if (workId && executionSession?.activeRepositoryId === repository.repoId && (!executionSession.activeCheckoutId || executionSession.activeCheckoutId === repository.activeCheckoutId)) {
       const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+      if (work && isTerminalWorkContractStatus(work.status)) {
+        throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+      }
       const owner = getControllerSession({ controllerHome, repoId: repository.repoId }, workId);
-      if (work && !isTerminalWorkContractStatus(work.status) && owner?.sessionId === caller.sessionId && (owner.principalId?.trim() || owner.controllerId) === caller.principalId.trim()) return workId;
+      if (work && owner?.sessionId === caller.sessionId && (owner.principalId?.trim() || owner.controllerId) === caller.principalId.trim()) return workId;
     }
   }
   const principal = caller.principalId.trim();
@@ -356,7 +369,7 @@ function claimedSessionWorkId(
   return undefined;
 }
 
-function claimedSessionEditBinding(
+export function claimedSessionEditBinding(
   controllerHome: string,
   repository: ReturnType<typeof resolveRepositorySelection>,
   caller?: RepositoryToolCallerContext,
@@ -376,8 +389,52 @@ function claimedSessionEditBinding(
   };
 }
 
-function activeWorkflowRawDefaultMergeBlocked(repository: ReturnType<typeof resolveRepositorySelection>, workId: string | undefined, command: unknown): boolean {
-  if (!workId || !repository.defaultBranch) return false;
+function safePatchEditBinding(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  caller: RepositoryToolCallerContext | undefined,
+  args: Record<string, unknown>,
+): EditSessionBinding | undefined {
+  const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (explicitWorkId) return claimedSessionEditBinding(controllerHome, repository, caller, explicitWorkId);
+  const sessionId = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  if (sessionId) {
+    const existingWorkId = getEditSession(repository.canonicalRoot, sessionId).workId?.trim();
+    return existingWorkId
+      ? claimedSessionEditBinding(controllerHome, repository, caller, existingWorkId)
+      : undefined;
+  }
+  assertNoBoundExecutionSessionMutation(controllerHome, repository, caller);
+  return undefined;
+}
+
+function resolveRepositorySelectionForClaimedWork(
+  controllerHome: string,
+  args: Record<string, unknown>,
+  repoIdValue: string,
+  caller?: RepositoryToolCallerContext,
+): 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({
+    repoId: repoIdValue || undefined,
+    checkoutId: checkoutId || undefined,
+    controllerHome,
+    allowSoleRepository: true,
+  });
+  if (!explicitWorkId || checkoutId) return repository;
+  const work = claimedExplicitWork(controllerHome, repository.repoId, caller, explicitWorkId);
+  if (!work?.checkoutId || work.checkoutId === repository.activeCheckoutId) return repository;
+  return resolveRepositorySelection({
+    repoId: repository.repoId,
+    checkoutId: work.checkoutId,
+    controllerHome,
+    allowSoleRepository: true,
+  });
+}
+
+function rawDefaultBranchMergeCommand(repository: ReturnType<typeof resolveRepositorySelection>, command: unknown): boolean {
+  if (!repository.defaultBranch) return false;
   const checkout = repository.checkouts.find((entry) => entry.checkoutId === repository.activeCheckoutId);
   if (checkout?.branch !== repository.defaultBranch) return false;
   const normalized = normalizeRepositoryCommand(command);
@@ -417,13 +474,11 @@ function resolveRepositoryCommandTarget(
       workspace: { workspaceId: target.workspaceId, root: target.canonicalRoot, registered: false },
     };
   }
-  const repository = resolveRepositorySelection({
-    repoId: repoIdValue || undefined,
-    checkoutId: checkoutId || undefined,
-    controllerHome,
-    allowSoleRepository: true,
-  });
-  const workId = claimedSessionWorkId(controllerHome, repository, caller, args.work_id);
+  const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
+  const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  const workId = explicitWorkId
+    ? claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId)
+    : undefined;
   return {
     repository,
     executionIdentity: {
@@ -523,6 +578,33 @@ 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;
@@ -545,6 +627,7 @@ 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;
@@ -572,10 +655,14 @@ function compactProcessCommandPayload(input: {
       ...(input.workspace ? { workspace: input.workspace } : {}),
       ...(input.processId ? { processId: input.processId } : {}),
       ...(completed ? { exitCode: input.exitCode ?? (ok ? 0 : 1) } : {}),
+      // A running default response otherwise loses its only dependency-bound
+      // continuation advice when the detailed Process record is omitted.
+      ...(!completed ? { next: input.next } : {}),
       stdout: output.stdout ?? '',
       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 = {
@@ -623,6 +710,7 @@ function compactProcessCommandPayload(input: {
       }
       : {}),
     durableSideEffects: effects,
+    ...(input.guidance ? { guidance: input.guidance, suggestedOperation: 'rh_context' } : {}),
     next: input.next,
     detailLevel: 'detail',
   };
@@ -664,10 +752,33 @@ export async function callRepositoryTool(
   args: Record<string, unknown>,
   caller?: RepositoryToolCallerContext,
 ): Promise<RepositoryToolResult | undefined> {
-  if (!name.startsWith('repository_')) return undefined;
+  if (!name.startsWith('repository_') && name !== 'read_repository_file') return undefined;
   try {
     const repoIdValue = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
     switch (name) {
+      case 'read_repository_file': {
+        const repository = resolveRepositorySelection({
+          repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+          checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+          controllerHome,
+          allowSoleRepository: true,
+        });
+        const path = String(args.path ?? '').trim();
+        if (!path) throw new Error('REPOSITORY_PATH_REQUIRED: path is required');
+        const session = caller?.sessionId
+          ? { sessionId: caller.sessionId, repoId: repository.repoId, checkoutId: repository.activeCheckoutId }
+          : undefined;
+        const range = readRepositoryRange(
+          repository.canonicalRoot,
+          getMcpPolicy('controller', { repoRoot: repository.canonicalRoot }),
+          path,
+          typeof args.start_line === 'number' ? args.start_line : 1,
+          typeof args.end_line === 'number' ? args.end_line : 200,
+          session,
+        );
+        const redacted = redactMcpText(range.content);
+        return result({ ...range, content: redacted.text, redactions: redacted.redactions });
+      }
       case 'repository_register': {
         const startedAt = performance.now();
         const registerInput = {
@@ -824,38 +935,6 @@ export async function callRepositoryTool(
           checkout_id: typeof args.checkout_id === 'string' ? args.checkout_id : payload.checkout_id,
         });
       }
-
-
-
-      case 'repository_goal_list': {
-        const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
-        return result({ repoId: repository.repoId, checkoutId: repository.activeCheckoutId, registry: readRepositoryGoalRegistry(repository) });
-      }
-      case 'repository_goal_upsert': {
-        const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
-        return result({ repoId: repository.repoId, checkoutId: repository.activeCheckoutId, ...upsertRepositoryGoal(repository, { id: args.id, title: args.title, status: args.status, checks: args.checks, notes: args.notes }) as unknown as Record<string, unknown> });
-      }
-      case 'repository_stuck_diagnose': {
-        const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
-        return result({ diagnosis: diagnoseRepositoryStuckState(repository) });
-      }
-
-      case 'repository_goal_run': {
-        const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
-        const ran = withControllerLock(
-          controllerHome,
-          { scope: 'repository', repoId: repository.repoId },
-          'mcp:repository_goal_run',
-          () => runRepositoryGoal(repository, { goalId: args.goal_id, runChecks: args.run_checks }),
-          60_000,
-        );
-        return result({ repoId: repository.repoId, checkoutId: repository.activeCheckoutId, ...ran as unknown as Record<string, unknown> });
-      }
-      case 'repository_goal_runs': {
-        const repository = resolveRepositorySelection({ repoId: repoIdValue || undefined, checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome, allowSoleRepository: true });
-        const limit = typeof args.limit === 'number' ? args.limit : typeof args.limit === 'string' ? Number(args.limit) : undefined;
-        return result({ repoId: repository.repoId, checkoutId: repository.activeCheckoutId, runs: listRepositoryGoalRuns(repository, limit) });
-      }
       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
@@ -917,13 +996,8 @@ export async function callRepositoryTool(
         });
       }
       case 'repository_safe_patch_apply': {
-        const repository = resolveRepositorySelection({
-          repoId: repoIdValue || undefined,
-          checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
-          controllerHome,
-          allowSoleRepository: true,
-        });
-        const binding = claimedSessionEditBinding(controllerHome, repository, caller, args.work_id);
+        const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
+        const binding = safePatchEditBinding(controllerHome, repository, caller, args);
         const applied = withControllerLock(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
@@ -1022,10 +1096,16 @@ export async function callRepositoryTool(
         });
       }
       case 'repository_command_execute': {
+        const explorationGuidance = fragmentedRepositoryExplorationGuidance(args.command);
         const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
         const { repository, executionIdentity } = target;
-        if (activeWorkflowRawDefaultMergeBlocked(repository, executionIdentity.workId, args.command)) {
-          throw new Error(`WORK_DELIVERY_REQUIRES_FINALIZE: ${executionIdentity.workId} must pass Work verification and use rh_work finalize before default-branch integration`);
+        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`);
         }
         const timeoutMs = typeof args.timeout_ms === 'number'
           ? args.timeout_ms
@@ -1052,16 +1132,33 @@ export async function callRepositoryTool(
         const forceDurable = fromDurableWorker
           || args.mode === 'durable'
           || args.force_durable === true;
-        const routingDecision = routeExecution({
-          operation: 'repository_command_execute',
-          mode: forceDurable ? 'durable' : args.mode === 'fast' ? 'fast' : 'auto',
-          command: args.command as string | string[] | undefined,
-          timeoutMs,
-          background: forceDurable && (args.background === true || args.async === true),
-          defaultBranch: repository.defaultBranch,
-          approvalContinuation: typeof args.approval_request_id === 'string'
-            || typeof args.approval_token === 'string',
-        });
+        // 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.
+        const routingDecision = forceDurable
+          ? routeExecution({
+              operation: 'repository_command_execute',
+              mode: 'durable',
+              timeoutMs,
+              background: args.background === true || args.async === true,
+            })
+          : {
+              mode: 'fast' as const,
+              reasons: ['repository_command_process_runtime_authoritative'],
+              risk: 'unknown' as const,
+              estimatedClass: 'unknown' as const,
+              requiresIsolation: false,
+              requiresRecovery: false,
+              suggestedOperation: undefined,
+              effects: {
+                readsWorkspace: true,
+                mutatesWorkspace: true,
+                mutatesGitRefs: false,
+                remoteWrite: false,
+              },
+            };
         // Unified Process Runtime for local commands (Direct/Managed) when not forced durable.
         // Ephemeral workspaces cannot persist a recoverable async Process handle,
         // so their async requests remain promotion-required below.
@@ -1072,7 +1169,43 @@ export async function callRepositoryTool(
               defaultBranch: repository.defaultBranch,
               timeoutMs,
             });
-            if (routeClass.route === 'process_direct' || routeClass.route === 'process_managed') {
+            if (routeClass.route === 'reject') {
+              return result({
+                accepted: false,
+                mode: 'reject',
+                path: routeClass.reason,
+                route: 'reject',
+                status: 'rejected',
+                repoId: repository.repoId,
+                checkoutId: repository.activeCheckoutId,
+                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.'
+                  : 'Repository command execution was rejected by Process Runtime routing policy.',
+                suggestedOperation: routeClass.reason === 'standalone_recovery_lifecycle_required'
+                  ? 'Use the standalone Forge Recovery connector.'
+                  : routingDecision.suggestedOperation,
+                durableSideEffects: {
+                  executionJobCount: 0,
+                  localJobCount: 0,
+                  workerSpawnCount: 0,
+                  projectionUpdateCount: 0,
+                },
+              });
+            }
+            if (routeClass.route === 'durable' && target.workspace) {
+              return result({
+                accepted: false,
+                mode: 'durable',
+                path: 'ephemeral_workspace_promotion_required',
+                repoId: repository.repoId,
+                checkoutId: repository.activeCheckoutId,
+                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',
+              });
+            }
+            if (routeClass.route === 'process_direct' || routeClass.route === 'process_managed' || routeClass.route === 'durable') {
               const processResult = await executeRepositoryCommandViaProcessRuntime({
                 controllerHome,
                 repository,
@@ -1147,13 +1280,14 @@ 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.'
                       : 'Bounded ephemeral workspace execution completed without Process record / Lease / Local Job / ExecutionJob / Worker.'
                     : processResult.route === 'process_direct' || completed
                       ? 'Process Runtime completed without Local Job / ExecutionJob / Worker.'
-                      : `Process Runtime is managing ${handle?.processId}; poll process_get/process_wait instead of creating a Local Job.`,
+                      : `Process Runtime is managing ${handle?.processId}. Continue independent work; use process_get only if an observation can change the next decision, then join with process_wait when this result becomes a dependency. Do not re-run or periodically poll.`,
                   detailLevel,
                 });
                 payload.status = status;
@@ -1270,6 +1404,12 @@ export async function callRepositoryTool(
           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.',
+          externalEffect: {
+            outcome: 'not_started',
+            ambiguousFailureOutcome: 'outcome_unknown',
+            replayPolicy: 'never_auto_retry',
+            reconciliation: 'After an ambiguous dispatch failure, inspect the remote ref/registry/release state before deciding whether to retry.',
+          },
         });
       }
       case 'repository_batch_execute': {