@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/mcp/runtime-gateway/context-pack-sidecar.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import type { McpPolicy, McpProfileName } from '../types';
+import { buildControllerContextPackAsync } from '../../../src/cli/controller/context-pack';
+import type { ControllerContextPackOptions } from '../../../src/cli/controller/context/types';
+import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from '../../../src/runtime/execution/process-runtime/canary';
+import { closeCodeGraphReadProviderSessions } from '../../../src/runtime/context/codegraph-read-provider';
+
+interface ContextPackEnvelope {
+  schemaVersion: 1;
+  repoRoot: string;
+  policy: McpPolicy;
+  options: ControllerContextPackOptions;
+}
+
+function profile(value: unknown): McpProfileName {
+  if (value === 'planner' || value === 'executor' || value === 'orchestrator' || value === 'controller') return value;
+  throw new Error('CONTEXT_PACK_POLICY_PROFILE_INVALID');
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new Error('CONTEXT_PACK_POLICY_GLOBS_INVALID');
+  }
+  return value.map(String);
+}
+
+function policy(value: unknown): McpPolicy {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('CONTEXT_PACK_POLICY_INVALID');
+  const input = value as Record<string, unknown>;
+  const execution = input.execution;
+  if (!execution || typeof execution !== 'object' || Array.isArray(execution)) throw new Error('CONTEXT_PACK_POLICY_EXECUTION_INVALID');
+  const e = execution as Record<string, unknown>;
+  const maxFileBytes = Number(input.maxFileBytes);
+  if (!Number.isFinite(maxFileBytes) || maxFileBytes <= 0) throw new Error('CONTEXT_PACK_POLICY_MAX_FILE_BYTES_INVALID');
+  return {
+    profile: profile(input.profile),
+    readGlobs: stringList(input.readGlobs),
+    writeGlobs: stringList(input.writeGlobs),
+    denyGlobs: stringList(input.denyGlobs),
+    maxFileBytes,
+    execution: {
+      fixedWorkflowCheck: e.fixedWorkflowCheck === true,
+      codexRunner: e.codexRunner === true,
+      agentRunner: e.agentRunner === true,
+      allowedAgents: Array.isArray(e.allowedAgents)
+        ? e.allowedAgents.filter((entry): entry is 'codex' | 'claude' => entry === 'codex' || entry === 'claude')
+        : [],
+      runnerTimeoutMs: Number(e.runnerTimeoutMs) || 0,
+      runnerMaxTimeoutMs: Number(e.runnerMaxTimeoutMs) || 0,
+    },
+  };
+}
+
+export async function runContextPackSidecar(
+  argv = process.argv.slice(2),
+  input = readFileSync(0, 'utf8'),
+): Promise<number> {
+  if (argv.includes(PROCESS_RUNTIME_RELEASE_CANARY_ARG)) {
+    process.stdout.write('forge context-pack release canary\n');
+    return 0;
+  }
+  const envelope = JSON.parse(input) as ContextPackEnvelope;
+  if (envelope.schemaVersion !== 1 || typeof envelope.repoRoot !== 'string' || !envelope.repoRoot.trim()) {
+    throw new Error('CONTEXT_PACK_REQUEST_INVALID');
+  }
+  try {
+    const pack = await buildControllerContextPackAsync(
+      resolve(envelope.repoRoot),
+      policy(envelope.policy),
+      envelope.options && typeof envelope.options === 'object' ? envelope.options : {},
+    );
+    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, pack })}\n`);
+    return 0;
+  } finally {
+    // The Context Pack async path may reuse a CodeGraph session for progressive
+    // waves. This process is intentionally disposable, so do not inherit the
+    // normal 30-second provider idle lifetime.
+    await closeCodeGraphReadProviderSessions();
+  }
+}
+
+if (import.meta.main) {
+  try {
+    process.exitCode = await runContextPackSidecar();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/adapters/mcp/runtime-gateway/controller-authority-adapter.ts

@@ -0,0 +1,206 @@
+import { randomUUID } from 'crypto';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  assertControllerInvocationAuthority,
+  assertControllerRoundInvocationAuthority,
+  bindControllerOwnershipForInvocation,
+  controllerInvocationAuthorityMatches,
+  controllerTerminalizationAuthorityForInvocation,
+  terminalCleanupAuthorityForInvocation,
+} from '../../../src/runtime/control-plane/execution/controller-authority-recovery';
+import { currentControllerInstanceId } from '../../../src/runtime/control-plane/execution/session-store';
+import { observeRuntimeStatus } from '../../../src/runtime/root/status';
+import { chatgptControllerRoundRecoveryAuthorized } from '../../../src/runtime/root/controller-round-composition';
+import {
+  getControllerSession,
+  type ControllerRoundRelayRecord,
+  type ControllerTerminalizationAuthority,
+} from '../../../packages/kernel/controller/api/index';
+
+export interface RuntimeIdentitySnapshot {
+  releaseId?: string;
+  artifactIdentity?: string;
+  runtimeCommit?: string;
+  buildCommit?: string;
+  startedAt?: string;
+  runtimeInstanceId?: string;
+  controllerInstanceId?: string;
+  endpoint?: string;
+  running?: boolean;
+  ready?: boolean;
+  reasonCodes?: string[];
+  toolset?: string;
+  profile?: string;
+}
+
+export function runtimeIdentitySnapshot(ctx: MultiRepositoryMcpToolContext): RuntimeIdentitySnapshot {
+  const observation = observeRuntimeStatus(ctx.controllerHome);
+  const snapshot = observation.snapshot;
+  return {
+    releaseId: snapshot?.releaseId,
+    artifactIdentity: snapshot?.artifactIdentity,
+    startedAt: snapshot?.startedAt,
+    runtimeInstanceId: snapshot?.runtimeInstanceId,
+    controllerInstanceId: snapshot?.runtimeInstanceId,
+    endpoint: snapshot?.endpoint,
+    running: observation.running,
+    ready: observation.ready,
+    reasonCodes: observation.reasonCodes,
+    toolset: ctx.toolset,
+    profile: ctx.policy.profile,
+  };
+}
+
+export function authenticatedFacadeControllerIdentity(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+  options: { allowTransportSessionRollover?: boolean } = {},
+): { controllerId: string; principalId: string; sessionId: string; transportSessionId?: string; controllerAuthorityId?: string; authorityViaSessionCompatibility?: boolean; controllerInstanceId: string; controllerType: 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human' } {
+  const principalId = ctx.principalId?.trim();
+  const transportSessionId = ctx.sessionId?.trim();
+  const requestedControllerId = typeof args.controller_id === 'string' ? args.controller_id.trim() : '';
+  const requestedSessionId = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  const requestedAuthorityId = typeof args.controller_authority_id === 'string' ? args.controller_authority_id.trim() : '';
+  if (!principalId) {
+    // Preserve the bounded legacy stdio contract when no authenticated
+    // transport identity exists at all. Modern MCP requests carry a principal
+    // without a protocol session and reach the principal guard below; an
+    // unauthenticated legacy request must not silently mint one.
+    if (!transportSessionId && !requestedSessionId) {
+      throw new Error('CONTROLLER_AUTHENTICATED_SESSION_REQUIRED: reconnect or provide session_id through the authenticated MCP transport');
+    }
+    throw new Error('CONTROLLER_AUTHENTICATED_PRINCIPAL_REQUIRED: use an authenticated MCP transport');
+  }
+  // Legacy MCP sessions remain replaceable transport bindings. Modern MCP has no
+  // protocol session, so a fresh request-scoped execution binding is minted when
+  // the caller does not provide an explicit compatibility carrier. Durable Work
+  // authority is never derived from this request binding.
+  const sessionId = transportSessionId || requestedSessionId || `mcp_request_${randomUUID().replace(/-/g, '')}`;
+  const transportRolloverRequested = Boolean(
+    transportSessionId
+    && requestedSessionId
+    && requestedSessionId !== transportSessionId,
+  );
+  if (transportRolloverRequested && options.allowTransportSessionRollover !== true) {
+    throw new Error('CONTROLLER_TRANSPORT_SESSION_ROLLOVER_NOT_ALLOWED: this operation must use the current authenticated transport session or an explicit controller_authority_id');
+  }
+  const compatibilityAuthorityId = (!transportSessionId && requestedSessionId ? requestedSessionId : '')
+    || (transportRolloverRequested ? requestedSessionId : '');
+  const controllerAuthorityId = requestedAuthorityId || compatibilityAuthorityId;
+  const authorityViaSessionCompatibility = !requestedAuthorityId && Boolean(compatibilityAuthorityId);
+  if (requestedControllerId && requestedControllerId !== principalId) {
+    throw new Error('CONTROLLER_ID_CONTEXT_MISMATCH: controller_id must match the authenticated principal');
+  }
+  const requestedControllerType = typeof args.controller_type === 'string' && ['chatgpt', 'codex', 'claude', 'grok', 'human'].includes(args.controller_type)
+    ? args.controller_type as 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human'
+    : undefined;
+  const transportControllerType = ctx.controllerType;
+  if (transportControllerType && requestedControllerType && requestedControllerType !== transportControllerType) {
+    throw new Error('CONTROLLER_TYPE_CONTEXT_MISMATCH: controller_type must match the authenticated transport provider');
+  }
+  return {
+    controllerId: principalId,
+    principalId,
+    sessionId,
+    ...(transportSessionId ? { transportSessionId } : {}),
+    ...(controllerAuthorityId ? { controllerAuthorityId } : {}),
+    ...(authorityViaSessionCompatibility ? { authorityViaSessionCompatibility: true } : {}),
+    controllerType: transportControllerType ?? requestedControllerType ?? 'chatgpt',
+    controllerInstanceId: ctx.controllerInstanceId?.trim() || currentControllerInstanceId(),
+  };
+}
+
+export function dispatchedChatgptRelayAuthorizesStaleControllerRecovery(
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  relay: ControllerRoundRelayRecord | undefined,
+  controllerType: 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human',
+): boolean {
+  return controllerType === 'chatgpt' && chatgptControllerRoundRecoveryAuthorized(store, workId, relay);
+}
+
+export function assertFacadeControllerRoundAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerRoundRelayRecord | undefined {
+  // A frozen client may carry its explicit controller authority through the
+  // bounded `session_id` compatibility carrier. Resolving that carrier is not an
+  // authorization shortcut: `assertControllerRoundInvocationAuthority` still owns
+  // the exact principal/Work/round comparison below.
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
+  return assertControllerRoundInvocationAuthority({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+  });
+}
+
+export function sessionlessFacadeControllerAuthorityMatches(
+  owner: NonNullable<ReturnType<typeof getControllerSession>> | undefined,
+  identity: { transportSessionId?: string; controllerAuthorityId?: string },
+): boolean {
+  return controllerInvocationAuthorityMatches(owner, identity);
+}
+
+export function assertSessionlessFacadeControllerAuthority(
+  owner: NonNullable<ReturnType<typeof getControllerSession>> | undefined,
+  identity: { transportSessionId?: string; controllerAuthorityId?: string },
+  workId: string,
+): void {
+  assertControllerInvocationAuthority(owner, identity, workId);
+}
+
+export function bindFacadeControllerOwnership(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  identity: ReturnType<typeof authenticatedFacadeControllerIdentity>,
+  options: { allowClaimIfMissing?: boolean; leaseMs?: number; relayScopeId?: string } = {},
+) {
+  return bindControllerOwnershipForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: options.relayScopeId,
+    runtime: runtimeIdentitySnapshot(ctx),
+    allowClaimIfMissing: options.allowClaimIfMissing,
+    leaseMs: options.leaseMs,
+  });
+}
+
+export function currentFacadeTerminalizationAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerTerminalizationAuthority {
+  // Frozen clients may carry an exact controller authority through the bounded
+  // `session_id` compatibility carrier; the terminalization authority check below
+  // still owns the exact owner/Work/revision comparison.
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
+  return controllerTerminalizationAuthorityForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+    runtime: runtimeIdentitySnapshot(ctx),
+  });
+}
+
+export function currentTerminalCleanupAuthority(
+  ctx: MultiRepositoryMcpToolContext,
+  store: { controllerHome: string; repoId: string },
+  workId: string,
+  args: Record<string, unknown>,
+): ControllerTerminalizationAuthority {
+  const identity = authenticatedFacadeControllerIdentity(ctx, args, { allowTransportSessionRollover: true });
+  return terminalCleanupAuthorityForInvocation({
+    ...store,
+    workId,
+    identity,
+    relayScopeId: typeof args.relay_scope_id === 'string' ? args.relay_scope_id.trim() : undefined,
+  });
+}

package/adapters/mcp/runtime-gateway/core-capability-adapter.ts

@@ -0,0 +1,258 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { callRepositoryTool } from '../tool-mapping/repository-tools';
+import { commitSelectedPaths, selectedPathDiff, stageSelectedPaths } from '../../../src/cli/repositories/selected-path-actions';
+import { deliverWork } from '../../../src/runtime/control-plane/execution/work-delivery-service';
+import { validateWork } from '../../../src/runtime/control-plane/execution/work-operation-service';
+import { startOrResumeSession } from './execution-tools';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+import { callWorkflowSupervisorAdapter } from './workflow-supervisor-adapter';
+import {
+  claimControllerRoundSession,
+  getControllerRoundRelay,
+  releaseObservedControllerSession,
+  submitControllerRoundDisposition,
+  type ControllerRoundDisposition,
+} from '../../../packages/kernel/controller/api/index';
+import { recoverControllerAuthority } from '../../../src/runtime/control-plane/execution/controller-authority-recovery';
+import { authenticatedFacadeControllerIdentity, runtimeIdentitySnapshot } from './controller-authority-adapter';
+import { readControllerConnectionSnapshot, repairControllerConnection } from '../../../src/runtime/control-plane/facade/controller-connection';
+import { readLocalConversationProviderStatus, sendLocalConversation } from '../../../src/runtime/control-plane/launcher/local-conversation-controller';
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+export async function callCoreCapabilityAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (name !== 'capability_execute') return undefined;
+  const capabilityId = typeof args.capability_id === 'string' ? args.capability_id.trim() : '';
+  const action = typeof args.action === 'string' ? args.action.trim() : '';
+  const input = object(args.arguments);
+
+  try {
+    if (capabilityId === 'controller.connection') {
+      if (action === 'get') return result({ ...readControllerConnectionSnapshot(ctx.controllerHome) });
+      if (action === 'repair_connector') return result(repairControllerConnection(ctx.controllerHome));
+      return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.connection action: ${action || '<empty>'}` } }, true);
+    }
+    if (capabilityId === 'controller.local_conversation') {
+      if (action === 'status') return result({ ...readLocalConversationProviderStatus() });
+      if (action === 'send') {
+        const conversationId = typeof input.conversation_id === 'string' ? input.conversation_id.trim() : '';
+        const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
+        const providerSessionId = typeof input.provider_session_id === 'string' ? input.provider_session_id.trim() : undefined;
+        const timeoutMs = typeof input.timeout_ms === 'number' ? input.timeout_ms : undefined;
+        const requestedRepoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
+        const repository = requestedRepoId ? selected(ctx, args) : undefined;
+        return result({ ...await sendLocalConversation({
+          controllerHome: ctx.controllerHome,
+          conversationId,
+          prompt,
+          providerSessionId,
+          repoId: repository?.repoId,
+          timeoutMs,
+        }) });
+      }
+      return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.local_conversation action: ${action || '<empty>'}` } }, true);
+    }
+    if (capabilityId === 'controller.workflow_supervisor') {
+      const forwarded = await callWorkflowSupervisorAdapter(ctx, 'supervisor_task', {
+        ...input,
+        operation: action,
+        request_id: typeof args.request_id === 'string' ? args.request_id.trim() : '',
+        ...(typeof args.repo_id === 'string' && args.repo_id.trim() ? { repo_id: args.repo_id.trim() } : {}),
+      });
+      return forwarded ?? result({ error: { code: 'CORE_CAPABILITY_ROUTE_UNAVAILABLE', message: 'Workflow Supervisor capability route is unavailable.' } }, true);
+    }
+    if (capabilityId === 'controller.round_recovery') {
+      if (action !== 'recover_and_dispose') {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported controller.round_recovery action: ${action || '<empty>'}` } }, true);
+      }
+      if (input.user_directed !== true) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_USER_REQUIRED: user_directed=true is required.');
+      const workId = typeof input.work_id === 'string' ? input.work_id.trim() : '';
+      const recoveryReason = typeof input.recovery_reason === 'string' ? input.recovery_reason.trim() : '';
+      const disposition = typeof input.disposition === 'string' ? input.disposition.trim() as ControllerRoundDisposition : undefined;
+      const handoffId = typeof input.handoff_id === 'string' ? input.handoff_id.trim() : undefined;
+      if (!workId) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_WORK_REQUIRED');
+      if (!recoveryReason) throw new Error('WORK_CONTROLLER_AUTHORITY_RECOVERY_REASON_REQUIRED');
+      if (!disposition || !['continue_immediately', 'wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
+        throw new Error('CONTROLLER_RELAY_DISPOSITION_INVALID');
+      }
+      if (disposition === 'wait_for_user' && !handoffId) throw new Error('CONTROLLER_RELAY_WAIT_FOR_USER_HANDOFF_REQUIRED');
+
+      const repository = selected(ctx, args);
+      const store = { controllerHome: ctx.controllerHome, repoId: repository.repoId };
+      const before = getControllerRoundRelay(store, workId);
+      if (!before) throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_RELAY_REQUIRED: ${workId}`);
+      const identity = authenticatedFacadeControllerIdentity(ctx, {});
+      const recovered = recoverControllerAuthority({
+        controllerHome: ctx.controllerHome,
+        repoId: repository.repoId,
+        repositoryActiveCheckoutId: repository.activeCheckoutId,
+        workId,
+        requestedBy: 'user',
+        recoveryReason,
+        identity,
+        runtime: runtimeIdentitySnapshot(ctx),
+        leaseMs: 60_000,
+      });
+      if (!('relay' in recovered)) throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_RELAY_REQUIRED: ${workId}`);
+      if (before.providerDispatchEffectId && recovered.relay.providerDispatchEffectId !== before.providerDispatchEffectId) {
+        throw new Error(`WORK_CONTROLLER_AUTHORITY_RECOVERY_EFFECT_CHANGED: ${workId}`);
+      }
+
+      const claimed = claimControllerRoundSession(store, {
+        workId,
+        relayWorkId: workId,
+        sessionClaim: {
+          workId,
+          controllerId: identity.controllerId,
+          controllerType: identity.controllerType,
+          sessionId: identity.sessionId,
+          principalId: identity.principalId,
+          controllerInstanceId: identity.controllerInstanceId,
+          leaseMs: 60_000,
+        },
+      });
+      if (!claimed.relay || claimed.relay.status !== 'claimed') throw new Error(`CONTROLLER_RELAY_ROUND_NOT_CLAIMED: ${claimed.relay?.status ?? 'missing'}`);
+
+      let disposed;
+      let releaseResult;
+      try {
+        disposed = submitControllerRoundDisposition(store, {
+          workId,
+          identity: {
+            controllerId: claimed.session.controllerId,
+            controllerType: claimed.session.controllerType,
+            principalId: claimed.session.principalId?.trim() || claimed.session.controllerId,
+            controllerInstanceId: claimed.session.controllerInstanceId?.trim() || '',
+            sessionId: claimed.session.sessionId,
+          },
+          disposition,
+          relayScopeId: recovered.relay.relayScopeId,
+          requirementId: recovered.relay.requirementId,
+          ...(handoffId ? { handoffId } : {}),
+          reason: recoveryReason,
+        });
+      } finally {
+        releaseResult = releaseObservedControllerSession(store, {
+          workId,
+          actor: `controller-round-recovery:${identity.controllerId}`,
+          owner: claimed.session,
+        });
+      }
+      if (!releaseResult?.allowed) throw new Error(`WORK_CONTROLLER_RELEASE_FENCED: ${workId}:${releaseResult?.reason ?? 'unknown'}`);
+      const after = getControllerRoundRelay(store, workId);
+      return result({
+        repoId: repository.repoId,
+        workId,
+        authorityRecovered: true,
+        claimed: true,
+        disposition,
+        dispositionStatus: disposed.status,
+        relayScopeId: disposed.relayScopeId,
+        ownerReleased: true,
+        providerDispatchEffectId: after?.providerDispatchEffectId,
+        providerDispatchEffectPreserved: before.providerDispatchEffectId === after?.providerDispatchEffectId,
+        providerRedispatched: false,
+      });
+    }
+    if (capabilityId === 'repository.direct_edit') {
+      const toolName = action === 'plan'
+        ? 'repository_safe_patch_plan'
+        : action === 'apply'
+          ? 'repository_safe_patch_apply'
+          : undefined;
+      if (!toolName) {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.direct_edit action: ${action || '<empty>'}` } }, true);
+      }
+      const workId = action === 'apply' && typeof input.work_id === 'string' ? input.work_id.trim() : '';
+      const callerSession = workId && (!ctx.sessionId || !ctx.principalId || !ctx.controllerInstanceId)
+        ? startOrResumeSession(ctx)
+        : undefined;
+      const forwarded = await callRepositoryTool(ctx.controllerHome, toolName, {
+        ...input,
+        ...(typeof args.repo_id === 'string' && args.repo_id.trim() ? { repo_id: args.repo_id.trim() } : {}),
+        ...(typeof args.checkout_id === 'string' && args.checkout_id.trim() ? { checkout_id: args.checkout_id.trim() } : {}),
+      }, {
+        sessionId: callerSession?.sessionId ?? ctx.sessionId,
+        principalId: callerSession?.principalId ?? ctx.principalId,
+        controllerInstanceId: callerSession?.controllerInstanceId ?? ctx.controllerInstanceId,
+      });
+      return forwarded ?? result({
+        error: { code: 'CORE_CAPABILITY_ROUTE_UNAVAILABLE', message: 'Repository direct-edit capability route is unavailable.' },
+      }, true);
+    }
+    if (capabilityId === 'repository.validation') {
+      if (action !== 'validate_work') {
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.validation action: ${action || '<empty>'}` } }, true);
+      }
+      const repository = selected(ctx, args);
+      const sessionId = typeof input.session_id === 'string' && input.session_id.trim()
+        ? input.session_id.trim()
+        : startOrResumeSession(ctx).sessionId;
+      return result(await validateWork(ctx, {
+        ...input,
+        session_id: sessionId,
+        repo_id: repository.repoId,
+        request_id: typeof args.request_id === 'string' ? args.request_id.trim() : '',
+      }));
+    }
+    if (capabilityId !== 'repository.git') {
+      return result({ error: { code: 'CORE_CAPABILITY_UNSUPPORTED', message: `Unsupported core capability: ${capabilityId || '<empty>'}` } }, true);
+    }
+    const repository = selected(ctx, args);
+    switch (action) {
+      case 'diff_paths':
+        return result({
+          ...selectedPathDiff(repository, {
+            paths: input.paths,
+            staged: input.staged === true,
+            maxBytes: typeof input.max_bytes === 'number' ? input.max_bytes : undefined,
+          }),
+        });
+      case 'stage_paths': {
+        const staged = stageSelectedPaths(ctx.controllerHome, repository, { paths: input.paths });
+        return result({
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          ...staged,
+        }, staged.execution.ok !== true);
+      }
+      case 'commit_paths': {
+        const committed = commitSelectedPaths(ctx.controllerHome, repository, {
+          paths: input.paths,
+          message: input.message,
+        });
+        return result({
+          repoId: repository.repoId,
+          checkoutId: repository.activeCheckoutId,
+          ...committed,
+        }, Boolean(committed.error));
+      }
+      case 'deliver_work': {
+        const sessionId = typeof input.session_id === 'string' && input.session_id.trim()
+          ? input.session_id.trim()
+          : startOrResumeSession(ctx).sessionId;
+        const delivered = await deliverWork(ctx, {
+          ...input,
+          session_id: sessionId,
+          repo_id: repository.repoId,
+        });
+        return result(delivered);
+      }
+      default:
+        return result({ error: { code: 'CORE_CAPABILITY_ACTION_UNSUPPORTED', message: `Unsupported repository.git action: ${action || '<empty>'}` } }, true);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const structuredCode = /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1];
+    return result({ error: { code: structuredCode ?? 'CORE_CAPABILITY_FAILED', message } }, true);
+  }
+}