@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -2,9 +2,9 @@ import { bindRepositoryEntities } from '../repositories/entity-migration';
 import { bootstrapLocalProject, diagnoseLatestLocalProjectSource } from '../repositories/local-project-onboarding';
 import { resolveEphemeralWorkspaceTarget } from '../repositories/ephemeral-workspace';
 import type { ResolvedExecutionIdentity } from '../../runtime/control-plane/execution/execution-identity';
-import { readExecutionSession } from '../../runtime/control-plane/execution/session-store';
+import { assertNoBoundExecutionSessionMutation, resolveClaimedRepositoryWorkId, resolveExplicitClaimedRepositoryWork, type RepositoryWorkAttributionCaller } from '../../runtime/control-plane/execution/repository-work-attribution';
 import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
-import { getControllerSession, listControllerSessions } from '../../runtime/control-plane/facade/controller-session-store';
+import { assertWorkPathsWithinScope } from '../../runtime/control-plane/execution/work-path-scope';
 import { isTerminalWorkContractStatus } from '../../runtime/control-plane/facade/types';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../repositories/command-executor';
 import { withControllerLock } from '../repositories/locks';
@@ -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,
@@ -54,8 +53,12 @@ import {
   executeRepositoryCommandViaProcessRuntime,
 } from '../../runtime/execution/process-runtime/command-facade';
 import { assessWorkMode, parseExplicitTaskMode } from '../controller/work-mode';
+import { classifyRepositoryCommand } from '../repositories/command-classifier';
 import { normalizeRepositoryCommand } from '../repositories/command-normalization';
-import type { CallToolResult, McpToolDefinition } from './tools';
+import { readRepositoryRange } from '../repository/inspector';
+import { getMcpPolicy } from './policy';
+import { redactMcpText } from './redaction';
+import type { CallToolResult, McpToolDefinition } from './tool-contract';
 import {
   boundUtf8,
   compactCommandOutput,
@@ -117,6 +120,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 +146,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 +162,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 +248,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.' },
@@ -310,59 +288,15 @@ function withResponseMeta(payload: Record<string, unknown>, startedAt: number):
   return response;
 }
 
-export interface RepositoryToolCallerContext {
-  sessionId?: string;
-  principalId?: string;
-  controllerInstanceId?: string;
-}
+export type RepositoryToolCallerContext = RepositoryWorkAttributionCaller;
 
-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}`);
-    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.sessionId?.trim()) {
-    const executionSession = readExecutionSession(controllerHome, {
-      sessionId: caller.sessionId,
-      principalId: caller.principalId,
-      controllerInstanceId: caller.controllerInstanceId,
-    });
-    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);
-      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;
-    }
-  }
-  const principal = caller.principalId.trim();
-  const candidates = listControllerSessions({ controllerHome, repoId: repository.repoId })
-    .filter((owner) => (owner.principalId?.trim() || owner.controllerId) === principal)
-    .map((owner) => ({ owner, work: getWorkContract({ controllerHome, repoId: repository.repoId }, owner.workId) }))
-    .filter((entry): entry is { owner: ReturnType<typeof listControllerSessions>[number]; work: NonNullable<ReturnType<typeof getWorkContract>> } => Boolean(entry.work && !isTerminalWorkContractStatus(entry.work.status) && (!entry.work.checkoutId || entry.work.checkoutId === repository.activeCheckoutId)));
-  if (candidates.length === 1) return candidates[0].work.workId;
-  if (candidates.length > 1) throw new Error(`WORK_ATTRIBUTION_AMBIGUOUS: principal ${principal} owns ${candidates.length} active Works on checkout ${repository.activeCheckoutId}`);
-  return undefined;
-}
-
-function claimedSessionEditBinding(
+export function claimedSessionEditBinding(
   controllerHome: string,
   repository: ReturnType<typeof resolveRepositorySelection>,
   caller?: RepositoryToolCallerContext,
   explicitWorkId?: unknown,
 ): EditSessionBinding | undefined {
-  const workId = claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId);
+  const workId = resolveClaimedRepositoryWorkId(controllerHome, repository, caller, explicitWorkId);
   if (!workId || !caller?.principalId?.trim()) return undefined;
   const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
   if (!work) return undefined;
@@ -376,8 +310,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 = 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,
+  });
+}
+
+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);
@@ -388,6 +366,32 @@ function activeWorkflowRawDefaultMergeBlocked(repository: ReturnType<typeof reso
   return /(?:^|[;&|]\s*)git\s+merge\b/.test(normalized.shellCommand ?? '');
 }
 
+interface HistoricalReadOnlyWorkContext {
+  workId: string;
+  status: string;
+  mode: 'historical_read_only_observation';
+  attribution: 'not_active_work';
+}
+
+function historicalReadOnlyWorkContext(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  args: Record<string, unknown>,
+): HistoricalReadOnlyWorkContext | undefined {
+  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;
+  const classification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
+  if (classification.risk !== 'readonly') return undefined;
+  return {
+    workId: work.workId,
+    status: work.status,
+    mode: 'historical_read_only_observation',
+    attribution: 'not_active_work',
+  };
+}
+
 function resolveRepositoryCommandTarget(
   controllerHome: string,
   args: Record<string, unknown>,
@@ -397,6 +401,7 @@ function resolveRepositoryCommandTarget(
   repository: ReturnType<typeof resolveRepositorySelection>;
   executionIdentity: ResolvedExecutionIdentity;
   workspace?: { workspaceId: string; root: string; registered: false };
+  historicalWorkContext?: HistoricalReadOnlyWorkContext;
 } {
   const workspaceRoot = typeof args.workspace_root === 'string' ? args.workspace_root.trim() : '';
   const checkoutId = typeof args.checkout_id === 'string' ? args.checkout_id.trim() : '';
@@ -417,13 +422,38 @@ function resolveRepositoryCommandTarget(
       workspace: { workspaceId: target.workspaceId, root: target.canonicalRoot, registered: false },
     };
   }
-  const repository = resolveRepositorySelection({
+  // A terminal Work no longer owns mutation or checkout authority. An exact
+  // terminal work_id may still accompany a read-only observation immediately
+  // after finalize, so preserve it as explicit historical context while
+  // executing against the caller-selected/current repository checkout. Any
+  // non-read-only command continues through claimed Work resolution and fails
+  // closed for terminal attribution.
+  const selectedRepository = resolveRepositorySelection({
     repoId: repoIdValue || undefined,
     checkoutId: checkoutId || undefined,
     controllerHome,
     allowSoleRepository: true,
   });
-  const workId = claimedSessionWorkId(controllerHome, repository, caller, args.work_id);
+  const historicalWorkContext = historicalReadOnlyWorkContext(controllerHome, selectedRepository, args);
+  if (historicalWorkContext) {
+    return {
+      repository: selectedRepository,
+      executionIdentity: {
+        schemaVersion: 1,
+        authority: 'repository',
+        repositoryId: selectedRepository.repoId,
+        checkoutId: selectedRepository.activeCheckoutId,
+        canonicalRoot: selectedRepository.canonicalRoot,
+      },
+      historicalWorkContext,
+    };
+  }
+
+  const repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
+  const explicitWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  const workId = explicitWorkId
+    ? resolveClaimedRepositoryWorkId(controllerHome, repository, caller, explicitWorkId)
+    : undefined;
   return {
     repository,
     executionIdentity: {
@@ -523,6 +553,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;
@@ -533,6 +590,7 @@ function compactProcessCommandPayload(input: {
   repoId: string;
   checkoutId?: string;
   workspace?: { workspaceId: string; root: string; registered: false };
+  historicalWorkContext?: HistoricalReadOnlyWorkContext;
   processId?: string;
   process?: unknown;
   completed?: boolean;
@@ -545,6 +603,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;
@@ -570,12 +629,17 @@ function compactProcessCommandPayload(input: {
       repoId: input.repoId,
       ...(input.checkoutId ? { checkoutId: input.checkoutId } : {}),
       ...(input.workspace ? { workspace: input.workspace } : {}),
+      ...(input.historicalWorkContext ? { historicalWorkContext: input.historicalWorkContext } : {}),
       ...(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 = {
@@ -606,6 +670,7 @@ function compactProcessCommandPayload(input: {
     repoId: input.repoId,
     ...(input.checkoutId ? { checkoutId: input.checkoutId } : {}),
     ...(input.workspace ? { workspace: input.workspace } : {}),
+    ...(input.historicalWorkContext ? { historicalWorkContext: input.historicalWorkContext } : {}),
     ...(input.processId ? { processId: input.processId } : {}),
     ok: input.ok,
     exitCode: input.exitCode,
@@ -623,6 +688,7 @@ function compactProcessCommandPayload(input: {
       }
       : {}),
     durableSideEffects: effects,
+    ...(input.guidance ? { guidance: input.guidance, suggestedOperation: 'rh_context' } : {}),
     next: input.next,
     detailLevel: 'detail',
   };
@@ -664,10 +730,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 +913,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 +974,18 @@ 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);
+        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 },
@@ -1022,10 +1084,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 { repository, executionIdentity, historicalWorkContext } = target;
+        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 +1120,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 +1157,50 @@ 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 processRequestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+              if (executionIdentity.workId && !processRequestId) {
+                throw new Error(
+                  `WORK_PROCESS_REQUEST_ID_REQUIRED: ${executionIdentity.workId}; `
+                  + 'Work-attributed Process Runtime commands require a stable request_id so reconnect/retry can resume the original Process without duplicate execution.',
+                );
+              }
               const processResult = await executeRepositoryCommandViaProcessRuntime({
                 controllerHome,
                 repository,
@@ -1084,7 +1212,7 @@ export async function callRepositoryTool(
                   : typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : undefined,
                 maxOutputBytes,
                 returnHandleImmediately,
-                requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                requestId: processRequestId || undefined,
                 workId: executionIdentity.workId,
                 executionIdentity,
                 allowNonGitWorkspace: target.workspace !== undefined,
@@ -1139,6 +1267,7 @@ export async function callRepositoryTool(
                   repoId: repository.repoId,
                   checkoutId: repository.activeCheckoutId,
                   workspace: target.workspace,
+                  historicalWorkContext,
                   processId: handle?.processId,
                   process: detailLevel === 'detail' ? handle : undefined,
                   completed,
@@ -1147,13 +1276,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 +1400,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': {