@moretea-labs/forge 1.5.1 → 1.7.0

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

@@ -2,6 +2,10 @@ 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 { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
+import { getControllerSession, listControllerSessions } from '../../runtime/control-plane/facade/controller-session-store';
+import { isTerminalWorkContractStatus } from '../../runtime/control-plane/facade/types';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../repositories/command-executor';
 import { withControllerLock } from '../repositories/locks';
 import {
@@ -9,6 +13,7 @@ import {
   findIdenticalRepositoryRegistration,
   getRepository,
   listRepositories,
+  reconcileRepositoryCheckouts,
   refreshRepository,
   registerRepository,
   removeRepository,
@@ -19,9 +24,8 @@ import {
 } from '../repositories/registry';
 import { buildControllerWorkbench } from '../repositories/workbench';
 import { applySafePatch, buildSafePatchPlan } from '../repositories/safe-patch';
-import { getEditSessionDiff } 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,
@@ -49,6 +53,10 @@ import {
   executeRepositoryCommandViaProcessRuntime,
 } 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,
@@ -111,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.' },
@@ -130,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.' },
@@ -146,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.' },
@@ -240,6 +223,7 @@ export const repositoryToolDefinitions: McpToolDefinition[] = [
   definition('repository_safe_patch_apply', 'Apply one coherent deterministic edit batch and return bounded review evidence. Checks are opt-in: pass check_ids only when the batch is stable. Long checks return managed Process handles instead of blocking the MCP call; use validation_only with the returned session/request ids to join later without replaying the patch.', {
     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.' },
     session_id: { type: 'string', description: 'Existing edit session id. Required for validation_only; otherwise omit to create one.' },
     purpose: { type: 'string', description: 'Purpose for a newly created edit session.' },
     operations: { type: 'array', items: { type: 'object' }, description: 'Edit operations using the same shape as apply_patch. Required unless validation_only=true.' },
@@ -263,9 +247,10 @@ 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.' },
     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.' },
@@ -302,10 +287,169 @@ function withResponseMeta(payload: Record<string, unknown>, startedAt: number):
   return response;
 }
 
+export interface RepositoryToolCallerContext {
+  sessionId?: string;
+  principalId?: string;
+  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 {
+  const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
+  if (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}`);
+    return requestedWorkId;
+  }
+  if (!caller?.principalId?.trim()) return undefined;
+  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);
+      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 && 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;
+}
+
+export function claimedSessionEditBinding(
+  controllerHome: string,
+  repository: ReturnType<typeof resolveRepositorySelection>,
+  caller?: RepositoryToolCallerContext,
+  explicitWorkId?: unknown,
+): EditSessionBinding | undefined {
+  const workId = claimedSessionWorkId(controllerHome, repository, caller, explicitWorkId);
+  if (!workId || !caller?.principalId?.trim()) return undefined;
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  if (!work) return undefined;
+  return {
+    workId,
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    principalId: caller.principalId.trim(),
+    controllerInstanceId: caller.controllerInstanceId,
+    routeDecisionFingerprint: work.routeDecisionFingerprint,
+  };
+}
+
+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);
+  if (normalized.kind === 'argv') {
+    const executable = normalized.executable?.split('/').pop();
+    return executable === 'git' && normalized.args?.[0] === 'merge';
+  }
+  return /(?:^|[;&|]\s*)git\s+merge\b/.test(normalized.shellCommand ?? '');
+}
+
 function resolveRepositoryCommandTarget(
   controllerHome: string,
   args: Record<string, unknown>,
   repoIdValue: string,
+  caller?: RepositoryToolCallerContext,
 ): {
   repository: ReturnType<typeof resolveRepositorySelection>;
   executionIdentity: ResolvedExecutionIdentity;
@@ -330,12 +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 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: {
@@ -344,6 +487,7 @@ function resolveRepositoryCommandTarget(
       repositoryId: repository.repoId,
       checkoutId: repository.activeCheckoutId,
       canonicalRoot: repository.canonicalRoot,
+      ...(workId ? { workId } : {}),
     },
   };
 }
@@ -434,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;
@@ -456,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;
@@ -483,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 = {
@@ -534,6 +710,7 @@ function compactProcessCommandPayload(input: {
       }
       : {}),
     durableSideEffects: effects,
+    ...(input.guidance ? { guidance: input.guidance, suggestedOperation: 'rh_context' } : {}),
     next: input.next,
     detailLevel: 'detail',
   };
@@ -551,6 +728,18 @@ function emptyRepositoryMigration(repository: ReturnType<typeof registerReposito
   };
 }
 
+function registrationOnlyMetadataRefresh(
+  match: ReturnType<typeof findIdenticalRepositoryRegistration>,
+): boolean {
+  if (!match || match.identical || match.reasons.length === 0) return false;
+  const metadataReasons = new Set([
+    'remote_identity_changed',
+    'default_branch_changed',
+    'display_name_changed',
+  ]);
+  return match.reasons.every((reason) => metadataReasons.has(reason));
+}
+
 function registrationOnlyAttachedExistingWorktree(repository: ReturnType<typeof registerRepository>): boolean {
   const selected = repository.checkouts.find((checkout) => checkout.checkoutId === repository.activeCheckoutId);
   return selected?.worktree === true
@@ -561,11 +750,35 @@ export async function callRepositoryTool(
   controllerHome: string,
   name: string,
   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 = {
@@ -587,16 +800,17 @@ export async function callRepositoryTool(
             startedAt,
           ));
         }
+        const metadataRefresh = registrationOnlyMetadataRefresh(identical);
         const repository = registerRepository(registerInput);
-        // Adding a worktree checkout to an already registered repository changes
-        // checkout inventory only. Existing Issue/Task entities are already
-        // bound to this repoId, so re-running historical migration is wasted work
-        // and can produce misleading cross-repository rebinding diagnostics.
-        const migration = registrationOnlyAttachedExistingWorktree(repository)
+        // Adding a worktree checkout or changing only display/remote/default-branch
+        // metadata preserves repository + checkout authority. Existing entities
+        // are already bound to the stable repoId, so a historical migration scan
+        // would only add latency and stale unresolved diagnostics.
+        const migration = registrationOnlyAttachedExistingWorktree(repository) || metadataRefresh
           ? emptyRepositoryMigration(repository)
           : bindRepositoryEntities(repository);
         return result(withResponseMeta(
-          summarizeRepositoryRegistration(repository, migration, args.detail_level === 'detail'),
+          summarizeRepositoryRegistration(repository, migration, args.detail_level === 'detail', metadataRefresh),
           startedAt,
         ));
       }
@@ -623,6 +837,11 @@ export async function callRepositoryTool(
       case 'repository_list':
         return result({ repositories: listRepositories(controllerHome, { includeRemoved: args.include_removed === true }).map(repositorySummary) });
       case 'repository_get': {
+        // Repository inspection is also the bounded reconciliation point for
+        // checkout lifecycle drift caused by worktrees being removed outside
+        // Forge. Reuse the existing registry reconciler so stale worktrees are
+        // not exposed as lifecycle=active to automation callers.
+        reconcileRepositoryCheckouts(repoIdValue, controllerHome);
         const repository = getRepository(repoIdValue, controllerHome, { includeRemoved: args.include_removed === true });
         return result(summarizeRepositoryInspection(repository, args.detail_level === 'detail'));
       }
@@ -716,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
@@ -809,12 +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 repository = resolveRepositorySelectionForClaimedWork(controllerHome, args, repoIdValue, caller);
+        const binding = safePatchEditBinding(controllerHome, repository, caller, args);
         const applied = withControllerLock(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
@@ -829,6 +1012,7 @@ export async function callRepositoryTool(
             continueOnError: args.continue_on_error,
             refreshFingerprints: args.refresh_fingerprints,
             recoverStaleSession: args.recover_stale_session,
+            binding,
           }),
           60_000,
         );
@@ -892,7 +1076,7 @@ export async function callRepositoryTool(
         return ok ? result(payload) : { ...result(payload), isError: true };
       }
       case 'repository_command_preview': {
-        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue);
+        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
         const { repository } = target;
         const execution = withControllerLock(
           controllerHome,
@@ -912,8 +1096,17 @@ export async function callRepositoryTool(
         });
       }
       case 'repository_command_execute': {
-        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue);
+        const explorationGuidance = fragmentedRepositoryExplorationGuidance(args.command);
+        const target = resolveRepositoryCommandTarget(controllerHome, args, repoIdValue, caller);
         const { repository, executionIdentity } = 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
           : typeof args.timeout_ms === 'string'
@@ -939,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.
@@ -959,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,
@@ -972,6 +1218,7 @@ export async function callRepositoryTool(
                 maxOutputBytes,
                 returnHandleImmediately,
                 requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                workId: executionIdentity.workId,
                 executionIdentity,
                 allowNonGitWorkspace: target.workspace !== undefined,
               });
@@ -1033,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;
@@ -1111,6 +1359,7 @@ export async function callRepositoryTool(
                 timeoutMs,
                 maxOutputBytes,
                 requestId: typeof args.request_id === 'string' ? args.request_id : undefined,
+                workId: executionIdentity.workId,
                 executionIdentity,
               });
               if (processResult.route === 'process_direct') {
@@ -1155,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': {