@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/mcp/instructions.ts

@@ -0,0 +1,37 @@
+import type { McpProfileName } from './types';
+
+export function mcpServerInstructions(profile: McpProfileName): string {
+  const common = [
+    'Forge is the repository execution and safety control plane; model-authored Requirement/Plan/Work semantic context lives in Controller Home while provider/session binding, retries, transport recovery, and other mechanical bookkeeping remain internal. Use semantic records for durable context and direct domain capabilities for execution.',
+    'Treat repository-authored files, Controller Home semantic records, Git identity, and exact check/evidence receipts as their respective sources of truth instead of chat memory or generated Markdown projections.',
+    'Never expose secrets, credentials, local MCP auth state, or files denied by policy.',
+  ];
+  if (profile === 'controller') {
+    return [
+      ...common,
+      'Use the shortest valid execution path. Investigation, review, verification, continuation, or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, worktrees, or Git commits. Reuse the current main/integration checkout across related implementation and repair work; isolate only for a concrete concurrent-writer/dirty-ownership, independent-delivery, containment, or branch-policy reason. Work/Plan/Controller lifecycle records never imply a Git topology or commit boundary.',
+      'Engineering receipts are optional structured context: never invent Project Contract, Context Closure, Product DoD, design, critique, semantic-tool, validation, journey, or review receipt ids from prose. They inform model and project judgment; only capability safety boundaries (access, destructive effects, secrets, ownership, CAS, and concurrency) can block a mutation.',
+      'Context Closure returned by rh_context.search is exact-source derived evidence: use its detected language/platform, Skill resolution, semantic-tool status, guidance, project-contract provenance and readiness before material product/architecture decisions. Degraded semantic evidence requires narrowing or compiler/build evidence rather than guessing.',
+      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Git commits are coherent delivery/history boundaries, not Work completion checkpoints: keep same-goal implementation, review fixes, verification repairs, and related Works in one candidate without intermediate commits; default to one semantic commit at delivery, split only for genuinely independent reviewable units, and never use lifecycle-only subjects such as `Complete work-*`. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
+      'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
+      'Self-learning is model-driven, not phrase-driven. Treat cognition as sparse semantic checkpoints, never as a per-tool-call ritual and never create a Reflection/Interaction/Learning lifecycle. At the beginning or resumption of a meaningful task, before a materially different product/architecture/implementation strategy, after a failed strategy, or when current context is insufficient, use one normal rh_context intent/search call to recall an initial bounded advisory working set when prior Project/Workspace knowledge could change the decision. Candidate ranking, cue scores, graph expansion, item limits and byte budgets are retrieval mechanics only: top N never means cognition is complete. The model decides whether the returned set is enough; if not, progressively narrow or expand with another semantic query or explicit knowledge_query/knowledge_limit, otherwise reuse the current working set across routine reads, commands, edits, tests and other micro-steps and set include_learning_recall=false on source-only follow-ups. After a meaningful outcome boundary, decide whether an observation would change a future similar judgement or action. Emit zero learning when it would not. For ordinary successful work, prefer attaching one optional cognition_settlement to the successful tool call that closes that meaningful outcome; it can carry model-authored learning_signals and exact-memory learning_feedback and Forge settles them mechanically after the primary tool result. Do not attach cognition_settlement to routine micro-steps merely because the field exists. Use rh_work learning_record/learning_feedback when there is no natural successful tool boundary, when an explicit standalone learning action is clearer, or when a selected learning batch exceeds one transport envelope. User corrections, discovered root causes, successful shorter paths, review reversals, stable architecture/product/UX patterns and execution outcomes may all become learning when the model judges them reusable. Distill observations into semantic deltas rather than copying source prose: prefer a Project-specific lesson about how to judge/do the work, and write Workspace guidance only when the model explicitly judges the abstraction genuinely cross-project. Forge never decides that from kind, keywords, failure count, repetition count, confidence threshold, or execution codes. learning_signals kind is descriptive open vocabulary; the per-call array bound is only a transport envelope, not an interaction quota, so submit further learning_record batches when the model selected more reusable knowledge than one envelope carries. Forge may associate/consolidate representations and usage mechanically but must not invent a higher-level lesson or cross-scope generalization. Work-bound Controller rounds keep assistant_context_usage as the exact used/rejected feedback channel. Outside Work, do not manufacture a usage lifecycle merely to count feedback. When recalled memory materially helps or is rejected, use learning_feedback with its exact memory address and model-authored irrelevant/stale/contradicted classification. A new correction/contradiction/other learning signal requires genuinely new reusable semantic knowledge, not merely that an old memory was used.',
+      'Minimize mechanically redundant MCP round trips. For an ongoing Forge-controlled task, prefer one rh_status(summary) as the initial controller snapshot: it includes bounded readiness, repository identity, top active Work, active Plans, and pending handoffs. Do not immediately follow it with rh_work(plan_list) or rh_context(list/get) unless the next decision needs details that the snapshot does not contain. Use rh_context(work_id=..., detail_level=summary) for one Work, and request detail/raw or capability hydration only when that extra evidence can change the decision.',
+      'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
+      'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work. Do not call process_wait while useful independent work remains. Use process_get only when a non-blocking observation can change the next decision; when the exact check result becomes a dependency, attach with process_wait (or validation_only with the returned edit-session/validation ids). An attach is transport-bounded: if it returns a running handle, resume useful work and attach again only at a later real dependency boundary, never as periodic polling. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
+      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
+    ].join(' ');
+  }
+  if (profile === 'orchestrator') {
+    return [...common, 'The orchestrator profile is a narrow compatibility runner for explicit fixed handoffs. It is not the primary project-control interface.'].join(' ');
+  }
+  if (profile === 'executor') {
+    return [...common, 'Act as a scoped executor/reviewer for existing workflow artifacts and checks. Do not broaden the task contract.'].join(' ');
+  }
+  return [
+    ...common,
+    'Act as planner/reviewer: use Controller Home Requirement/Plan authority for executable lifecycle; repository documents are only authored product/design/research sources or rebuildable read-only projections, never a second task state machine.',
+    'Do not edit application source through the planner profile. Use the controller profile for task management, repository analysis, bounded edits, and local agent dispatch.',
+  ].join(' ');
+}
+
+export const MCP_SERVER_INSTRUCTIONS = mcpServerInstructions('controller');

package/adapters/mcp/legacy-context.ts

@@ -0,0 +1,18 @@
+import { resolve } from 'path';
+import { resolveRepoPreferredControllerHome } from '../../src/cli/repositories/controller-home';
+import { getMcpPolicy, parseMcpProfile } from './policy';
+import type { McpToolContext } from './tool-mapping/tools';
+import type { McpServerOptions } from './multi-repository';
+
+export function createLegacyMcpToolContext(opts: McpServerOptions): McpToolContext {
+  const repoRoot = resolve(opts.repo?.trim() || '.');
+  return {
+    repoRoot,
+    runtimeControllerHome: resolveRepoPreferredControllerHome(repoRoot, opts.controllerHome),
+    policy: getMcpPolicy(parseMcpProfile(opts.profile ?? 'planner'), { repoRoot }),
+    enableChatgptBrowser: opts.enableChatgptBrowser === true,
+    sessionId: opts.sessionId,
+    principalId: opts.principalId,
+    controllerInstanceId: opts.controllerInstanceId,
+  };
+}

package/adapters/mcp/multi-repository.ts

@@ -0,0 +1,421 @@
+import { loadMcpLocalConfig, loadMcpServiceLocalConfig } from './auth';
+import { getMcpPolicy, parseMcpProfile } from './policy';
+import { buildMcpToolDefinitions, callMcpTool, type CallToolResult, type McpToolContext, type McpToolDefinition } from './tool-mapping/tools';
+import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENT_TIMEOUT_MS, normalizeAgentTimeoutMs } from '../../src/cli/controller/runtime-config';
+import type { McpAgentRunnerName, McpToolset } from './types';
+import { configuredControllerToolset } from './toolset-selection';
+import { realpathSync } from 'fs';
+import { resolve } from 'path';
+import { ensureRepoPreferredControllerHome } from '../../src/cli/repositories/controller-home';
+import { bindRepositoryEntities } from '../../src/cli/repositories/entity-migration';
+import { withControllerLockAsync } from '../../src/cli/repositories/locks';
+import { listRepositories, registerRepository, repositorySummary, resolveRepositorySelection, selectRepositoryCheckout } from '../../src/cli/repositories/registry';
+import { ensureRepositoryRuntimeStorage, type RepositoryRuntimeStorageReport } from '../../src/cli/repositories/runtime-storage';
+import type { RepositoryRecord } from '../../src/cli/repositories/types';
+import {
+  compactErrorMessage,
+  compactRepositoryRef,
+  compactRuntimeStorageRef,
+  RESPONSE_BUDGET,
+} from '../../src/runtime/shared/response-budget';
+
+export interface McpServerOptions {
+  repo?: string;
+  controllerHome?: string;
+  profile?: string;
+  enableChatgptBrowser?: boolean;
+  enableDevRunner?: boolean;
+  devRunnerAgents?: string;
+  devRunnerTimeoutMs?: number;
+  devRunnerMaxTimeoutMs?: number;
+  toolset?: McpToolset | string;
+  sessionId?: string;
+  principalId?: string;
+  controllerType?: McpToolContext['controllerType'];
+  /** Request-scoped host conversation correlation, for example ChatGPT _meta["openai/session"]. */
+  hostConversationSessionId?: string;
+  controllerInstanceId?: string;
+  /** Canonical Runtime source authority. Internal Runtime MCP only; never an execution repository. */
+  runtimeSourceRoot?: string;
+}
+
+export interface MultiRepositoryMcpToolContext extends McpToolContext {
+  controllerHome: string;
+  explicitRepository?: RepositoryRecord;
+  toolset: McpToolset;
+  toolsetLocked: boolean;
+  runtimeSourceRoot?: string;
+}
+
+type ToolResult = CallToolResult;
+
+const EXECUTION_STORAGE_TOOLS = new Set([
+  'begin_edit_session',
+  'apply_edit_operations',
+  'create_edit_savepoint',
+  'rollback_edit_session',
+  'finalize_edit_session',
+  'verify_edit_session',
+  'submit_local_bridge_job',
+  'execute_local_bridge_job',
+]);
+
+const REPOSITORY_LOCKED_TOOLS = new Set([
+  ...EXECUTION_STORAGE_TOOLS,
+  'configure_github_plugin',
+]);
+
+
+export function parseMcpToolset(value: unknown, profile: string): McpToolset {
+  if (profile !== 'controller') return 'full';
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!normalized) return 'advanced';
+  if (normalized === 'facade' || normalized === 'core' || normalized === 'advanced' || normalized === 'full') return normalized;
+  throw new Error(`invalid MCP toolset "${String(value)}" (expected: facade, core, advanced, or full)`);
+}
+
+function repositoryForExplicitPath(path: string, controllerHome: string): RepositoryRecord | undefined {
+  const selectedPath = (() => {
+    try { return realpathSync(path); } catch { return resolve(path); }
+  })();
+  for (const repository of listRepositories(controllerHome, { includeRemoved: true })) {
+    const checkout = repository.checkouts.find((candidate) => {
+      const candidatePath = (() => {
+        try { return realpathSync(candidate.canonicalRoot); } catch { return resolve(candidate.canonicalRoot); }
+      })();
+      return candidatePath === selectedPath && candidate.lifecycle !== 'removed';
+    });
+    if (checkout) return selectRepositoryCheckout(repository, checkout.checkoutId);
+  }
+  return undefined;
+}
+
+function parseBooleanSetting(value: string | undefined): boolean | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return undefined;
+}
+
+function parseAgentList(value: unknown): McpAgentRunnerName[] {
+  const raw = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [];
+  return Array.from(new Set(raw
+    .map((entry) => String(entry).trim().toLowerCase())
+    .filter((entry): entry is McpAgentRunnerName => entry === 'codex' || entry === 'claude')));
+}
+
+export function runtimePolicy(repoRoot: string, opts: McpServerOptions) {
+  const profile = parseMcpProfile(opts.profile ?? 'controller');
+  const config = profile === 'controller' && opts.controllerHome
+    ? loadMcpServiceLocalConfig(opts.controllerHome, repoRoot)
+    : loadMcpLocalConfig(repoRoot);
+  const envDevRunner = parseBooleanSetting(process.env.FORGE_MCP_DEV_RUNNER);
+  const configuredDevRunner = envDevRunner ?? config?.devMode?.agentRunner === true;
+  const devAgentRunner = opts.enableDevRunner === true || configuredDevRunner;
+  const allowedAgents = parseAgentList(
+    opts.devRunnerAgents ?? process.env.FORGE_MCP_DEV_RUNNER_AGENTS ?? config?.devMode?.allowedAgents,
+  );
+  const runnerMaxTimeoutMs = normalizeAgentTimeoutMs(
+    opts.devRunnerMaxTimeoutMs ?? process.env.FORGE_MCP_DEV_RUNNER_MAX_TIMEOUT_MS ?? config?.devMode?.maxTimeoutMs,
+    { defaultMs: MAX_AGENT_TIMEOUT_MS, maxMs: MAX_AGENT_TIMEOUT_MS, label: 'dev runner max timeout' },
+  );
+  const runnerTimeoutMs = normalizeAgentTimeoutMs(
+    opts.devRunnerTimeoutMs ?? process.env.FORGE_MCP_DEV_RUNNER_TIMEOUT_MS ?? config?.devMode?.timeoutMs,
+    { defaultMs: DEFAULT_AGENT_TIMEOUT_MS, maxMs: runnerMaxTimeoutMs, label: 'dev runner timeout' },
+  );
+  return getMcpPolicy(profile, {
+    devAgentRunner,
+    allowedAgents,
+    runnerTimeoutMs,
+    runnerMaxTimeoutMs,
+    repoRoot,
+  });
+}
+
+function injectRepositoryContext(tool: McpToolDefinition): McpToolDefinition {
+  const schema = tool.inputSchema as {
+    type?: unknown;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  if (schema.type !== 'object') return tool;
+  return {
+    ...tool,
+    inputSchema: {
+      ...schema,
+      properties: {
+        repo_id: {
+          type: 'string',
+          description: 'Stable repoId. Required when more than one repository is enabled.',
+        },
+        checkout_id: {
+          type: 'string',
+          description: 'Checkout identity for repositories with multiple local clones.',
+        },
+        ...(schema.properties ?? {}),
+      },
+    },
+  };
+}
+
+export function buildMultiRepositoryToolDefinitions(
+  ctx: MultiRepositoryMcpToolContext,
+): McpToolDefinition[] {
+  return buildMcpToolDefinitions(ctx.policy, {
+    enableChatgptBrowser: ctx.enableChatgptBrowser === true,
+  }).map(injectRepositoryContext);
+}
+
+function errorResult(error: unknown): ToolResult {
+  const message = compactErrorMessage(error);
+  const code = message.includes(':') ? message.slice(0, message.indexOf(':')) : 'TOOL_FAILED';
+  const value = {
+    error: {
+      code,
+      message,
+      retryable: /(?:^|_)(?:502|503|429|ECONNRESET|ETIMEDOUT|EAI_AGAIN)|server_busy|session_capacity|gateway.*unavailable|transient/i.test(message),
+    },
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+    structuredContent: value,
+    isError: true,
+  };
+}
+
+function compactEnvelopePayload(
+  repository: RepositoryRecord,
+  runtimeStorage: RepositoryRuntimeStorageReport,
+): { repoId: string; repository: Record<string, unknown>; runtimeStorage: Record<string, unknown> } {
+  const summary = repositorySummary(repository);
+  return {
+    repoId: repository.repoId,
+    repository: compactRepositoryRef({
+      repoId: summary.repoId,
+      checkoutId: summary.checkoutId,
+      displayName: summary.displayName,
+      defaultBranch: summary.defaultBranch,
+    }),
+    runtimeStorage: compactRuntimeStorageRef({
+      readyForExecution: runtimeStorage.readyForExecution,
+      usesStableRoot: runtimeStorage.usesStableRoot,
+      warningCount: runtimeStorage.warnings.length,
+      warnings: runtimeStorage.warnings,
+    }),
+  };
+}
+
+function withRepositoryEnvelope(
+  result: ToolResult,
+  repository: RepositoryRecord,
+  runtimeStorage: RepositoryRuntimeStorageReport,
+): ToolResult {
+  const envelope = compactEnvelopePayload(repository, runtimeStorage);
+  if (result.structuredContent && typeof result.structuredContent === 'object' && !Array.isArray(result.structuredContent)) {
+    const existing = result.structuredContent as Record<string, unknown>;
+    const omitHeavyEnvelope = existing.omitEnvelope === true
+      || existing.mode === 'process_direct'
+      || existing.route === 'process_direct'
+      || (existing.detailLevel === 'summary' && existing.endpointConfigured !== undefined)
+      || existing.localBridgeSummary === true;
+    // Compact fast-path / status summaries: keep repoId only (no repository/runtimeStorage dump).
+    if (omitHeavyEnvelope) {
+      const { omitEnvelope: _omit, localBridgeSummary: _summary, ...rest } = existing;
+      const structuredContent: Record<string, unknown> = {
+        ...rest,
+        repoId: typeof rest.repoId === 'string' ? rest.repoId : envelope.repoId,
+      };
+      return {
+        ...result,
+        structuredContent,
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+      };
+    }
+    // Avoid re-nesting full repository/runtimeStorage when the tool already
+    // returned a compact or authoritative payload for those keys.
+    const structuredContent: Record<string, unknown> = {
+      ...existing,
+      repoId: typeof existing.repoId === 'string' ? existing.repoId : envelope.repoId,
+      repository: existing.repository && typeof existing.repository === 'object'
+        ? existing.repository
+        : envelope.repository,
+      runtimeStorage: existing.runtimeStorage && typeof existing.runtimeStorage === 'object'
+        ? existing.runtimeStorage
+        : envelope.runtimeStorage,
+    };
+    // Prefer compact JSON without pretty-print bloat for default responses.
+    let text = JSON.stringify(structuredContent);
+    if (Buffer.byteLength(text, 'utf8') > RESPONSE_BUDGET.successBytes && result.isError !== true) {
+      // Keep structuredContent authoritative; only shrink the text channel when oversized.
+      text = JSON.stringify({
+        repoId: structuredContent.repoId,
+        summary: typeof structuredContent.summary === 'string' ? structuredContent.summary : undefined,
+        status: structuredContent.status ?? structuredContent.phase,
+        jobId: structuredContent.jobId,
+        next: structuredContent.next,
+        truncatedTextChannel: true,
+        message: 'Text channel truncated to response budget; use structuredContent or detail APIs.',
+      });
+    }
+    return {
+      ...result,
+      structuredContent,
+      content: [{ type: 'text', text }],
+    };
+  }
+  return {
+    ...result,
+    content: [
+      ...result.content,
+      { type: 'text', text: JSON.stringify(envelope) },
+    ],
+  };
+}
+
+export function repositoryScopedToolArgs(
+  name: string,
+  input: Record<string, unknown>,
+  repository: RepositoryRecord,
+): Record<string, unknown> {
+  // Preserve resolved repository identity for every downstream call. Exact
+  // claimed Work calls are the one exception for checkout injection: when the
+  // caller omitted checkout_id, repository tools must resolve the Work-owned
+  // checkout after validating the authenticated principal instead of inheriting
+  // the repository's currently active checkout.
+  const workOwnedCheckoutResolution = [
+    'repository_command_preview',
+    'repository_command_execute',
+    'repository_safe_patch_apply',
+  ].includes(name)
+    && typeof input.work_id === 'string'
+    && input.work_id.trim().length > 0
+    && !(typeof input.checkout_id === 'string' && input.checkout_id.trim().length > 0);
+  const args: Record<string, unknown> = {
+    ...input,
+    repo_id: repository.repoId,
+  };
+  if (!workOwnedCheckoutResolution) args.checkout_id = repository.activeCheckoutId;
+
+  const github = repository.github;
+  const githubRepo = github ? `${github.owner}/${github.repo}` : undefined;
+  if (githubRepo && ['github_status', 'publish_issue_to_github'].includes(name) && args.repo === undefined) {
+    args.repo = githubRepo;
+  }
+  if (githubRepo && ['dispatch_task', 'launch_issue', 'dispatch_ready_tasks'].includes(name) && args.github_repo === undefined) {
+    args.github_repo = githubRepo;
+  }
+  if (repository.defaultBranch
+    && ['dispatch_task', 'launch_issue', 'dispatch_ready_tasks'].includes(name)
+    && args.base_ref === undefined) {
+    args.base_ref = repository.defaultBranch;
+  }
+  if (name === 'publish_issue_to_github' && github) {
+    if (args.labels === undefined && github.labels?.length) args.labels = [...github.labels];
+    if (args.project_owner === undefined && github.projectOwner) args.project_owner = github.projectOwner;
+    if (args.project_number === undefined && github.projectNumber !== undefined) args.project_number = github.projectNumber;
+  }
+  return args;
+}
+
+export function createMcpToolContext(opts: McpServerOptions): MultiRepositoryMcpToolContext {
+  const controllerHome = ensureRepoPreferredControllerHome(opts.repo, opts.controllerHome);
+  const explicitRepository = opts.repo?.trim()
+    ? repositoryForExplicitPath(opts.repo, controllerHome)
+      ?? (() => {
+        // Fresh registration is an install-time migration boundary. Run the
+        // one-time legacy entity bind here; repeat connects and ordinary reads
+        // never rescan historical state.
+        const repository = registerRepository({ path: opts.repo, controllerHome });
+        bindRepositoryEntities(repository);
+        return repository;
+      })()
+    : undefined;
+  const policyRoot = explicitRepository?.canonicalRoot ?? controllerHome;
+  const policy = runtimePolicy(policyRoot, { ...opts, controllerHome });
+  const config = policy.profile === 'controller'
+    ? loadMcpServiceLocalConfig(controllerHome, explicitRepository?.canonicalRoot)
+    : loadMcpLocalConfig(policyRoot);
+  const toolsetOverride = opts.toolset ?? process.env.FORGE_MCP_TOOLSET;
+  const configuredToolset = policy.profile === 'controller'
+    ? configuredControllerToolset(config)
+    : config?.toolset;
+  const toolset = parseMcpToolset(
+    toolsetOverride ?? configuredToolset,
+    policy.profile,
+  );
+  return {
+    controllerHome,
+    explicitRepository,
+    repoRoot: policyRoot,
+    policy,
+    toolset,
+    toolsetLocked: toolsetOverride !== undefined || configuredToolset !== undefined,
+    enableChatgptBrowser: opts.enableChatgptBrowser === true,
+    sessionId: opts.sessionId,
+    principalId: opts.principalId,
+    controllerType: opts.controllerType,
+    hostConversationSessionId: opts.hostConversationSessionId,
+    controllerInstanceId: opts.controllerInstanceId,
+    runtimeSourceRoot: opts.runtimeSourceRoot,
+  };
+}
+
+export async function callMultiRepositoryTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<ToolResult> {
+  try {
+    const repository = resolveRepositorySelection({
+      repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+      checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined,
+      explicitPath: ctx.explicitRepository?.canonicalRoot,
+      controllerHome: ctx.controllerHome,
+      allowSoleRepository: true,
+    });
+    const scopedArgs = repositoryScopedToolArgs(name, args, repository);
+    const runtimeStorage = ensureRepositoryRuntimeStorage(repository, ctx.controllerHome);
+    if (EXECUTION_STORAGE_TOOLS.has(name) && !runtimeStorage.readyForExecution) {
+      throw new Error(`RUNTIME_STORAGE_NOT_READY: ${runtimeStorage.warnings.join('; ')}`);
+    }
+
+    // Legacy entity migration belongs to writes/registration, never to the
+    // ordinary read hot path (search / read / list / context). Only mutation
+    // tools rebind entities so newly created issues/tasks/sessions stay bound.
+    const rebindEntities = REPOSITORY_LOCKED_TOOLS.has(name);
+    if (rebindEntities) bindRepositoryEntities(repository);
+    const scopedContext: McpToolContext = {
+      repoRoot: repository.canonicalRoot,
+      runtimeControllerHome: ctx.controllerHome,
+      policy: runtimePolicy(repository.canonicalRoot, {
+        profile: ctx.policy.profile,
+        enableChatgptBrowser: ctx.enableChatgptBrowser,
+        enableDevRunner: ctx.policy.execution.agentRunner,
+        devRunnerAgents: ctx.policy.execution.allowedAgents.join(','),
+        devRunnerTimeoutMs: ctx.policy.execution.runnerTimeoutMs,
+        devRunnerMaxTimeoutMs: ctx.policy.execution.runnerMaxTimeoutMs,
+      }),
+      enableChatgptBrowser: ctx.enableChatgptBrowser,
+      sessionId: ctx.sessionId,
+      principalId: ctx.principalId,
+      controllerInstanceId: ctx.controllerInstanceId,
+      repoId: repository.repoId,
+      checkoutId: repository.activeCheckoutId,
+    };
+    const invoke = async () => await callMcpTool(scopedContext, name, scopedArgs) as ToolResult;
+    const result = REPOSITORY_LOCKED_TOOLS.has(name)
+      ? await withControllerLockAsync(
+        ctx.controllerHome,
+        { scope: 'repository', repoId: repository.repoId },
+        `mcp:${name}`,
+        invoke,
+        60_000,
+      )
+      : await invoke();
+    if (rebindEntities) bindRepositoryEntities(repository);
+    return withRepositoryEnvelope(result, repository, runtimeStorage);
+  } catch (error) {
+    return errorResult(error);
+  }
+}