@moretea-labs/forge 1.7.1 → 1.8.0

package/adapters/controller-process/binding-store.ts

@@ -0,0 +1,34 @@
+import { withControllerLock } from '../../src/cli/repositories/locks';
+import { readControlPlaneRecord, writeControlPlaneRecord } from '../../src/runtime/control-plane/persistence/sqlite-store';
+import type { ControllerBinding, ControllerType } from '../../packages/kernel/controller/api/index';
+
+const NAMESPACE = 'process_controller_binding';
+export type ProcessControllerType = Exclude<ControllerType, 'chatgpt' | 'human'>;
+
+export interface ProcessControllerBindingPayload {
+  schemaVersion: 1; bindingId: string; repoId: string; workId: string; sessionId: string;
+  controllerType: ProcessControllerType; executable?: string; launchArgs: string[]; handoffId?: string; launchReservationMs?: number;
+  createdAt: string; updatedAt: string;
+}
+
+function bindingId(repoId: string, workId: string, controllerType: ProcessControllerType): string {
+  return `process-controller:${controllerType}:${repoId}:${workId}`;
+}
+
+export function upsertProcessControllerBinding(
+  options: { controllerHome: string; repoId: string; now?: () => string },
+  input: Omit<ProcessControllerBindingPayload, 'schemaVersion' | 'bindingId' | 'repoId' | 'createdAt' | 'updatedAt'>,
+): { binding: ControllerBinding; payload: ProcessControllerBindingPayload } {
+  const id = bindingId(options.repoId, input.workId, input.controllerType);
+  return withControllerLock(options.controllerHome, { scope: 'task', repoId: options.repoId, taskId: `process-controller-binding-${input.workId}` }, `process-controller-binding:${id}`, () => {
+    const current = readControlPlaneRecord<ProcessControllerBindingPayload>(options.controllerHome, NAMESPACE, options.repoId, id);
+    const at = options.now?.() ?? new Date().toISOString();
+    const payload: ProcessControllerBindingPayload = { ...input, schemaVersion: 1, bindingId: id, repoId: options.repoId, createdAt: current?.value.createdAt ?? at, updatedAt: at };
+    writeControlPlaneRecord(options.controllerHome, { namespace: NAMESPACE, scope: options.repoId, key: id, schemaVersion: 1, value: payload, action: current ? 'process_controller_binding_update' : 'process_controller_binding_create', expectedRevision: current?.revision ?? null });
+    return { binding: { bindingId: id, hostKind: input.controllerType, adapterRef: id }, payload };
+  });
+}
+
+export function getProcessControllerBindingPayload(options: { controllerHome: string; repoId: string }, adapterRef: string) {
+  return readControlPlaneRecord<ProcessControllerBindingPayload>(options.controllerHome, NAMESPACE, options.repoId, adapterRef)?.value;
+}

package/adapters/controller-process/controller-host.ts

@@ -0,0 +1,26 @@
+import type { ControllerBinding, ControllerHost, ControllerRoundContext } from '../../packages/kernel/controller/api/index';
+import { launchSuperController } from '../../src/runtime/control-plane/launcher/thin-launcher';
+import { getProcessControllerBindingPayload } from './binding-store';
+
+export function createProcessControllerHost(options: { controllerHome: string; repoId: string; repoRoot: string }): ControllerHost {
+  return {
+    async resume(binding: ControllerBinding, roundContext: ControllerRoundContext) {
+      if (binding.hostKind === 'chatgpt' || binding.hostKind === 'human') return { accepted: false, reason: `CONTROLLER_HOST_KIND_MISMATCH:${binding.hostKind}` };
+      const payload = getProcessControllerBindingPayload(options, binding.adapterRef);
+      if (!payload || payload.bindingId !== binding.bindingId || payload.workId !== roundContext.workId || payload.controllerType !== binding.hostKind) {
+        return { accepted: false, reason: `PROCESS_CONTROLLER_BINDING_NOT_FOUND:${binding.bindingId}` };
+      }
+      const continuationPrompt = [
+        `Continue exact Forge Work ${roundContext.workId}.`,
+        `Controller round authority: controller_authority_id=${roundContext.authorityId}; relay_scope_id=${roundContext.relayScopeId}.`,
+        roundContext.continuationHint?.trim() ?? '',
+      ].filter(Boolean).join(' ');
+      const launched = await launchSuperController({ work: options, handoff: options }, {
+        controllerType: payload.controllerType, executable: payload.executable, args: payload.launchArgs,
+        workId: roundContext.workId, handoffId: payload.handoffId, launchReservationMs: payload.launchReservationMs,
+        continuationPrompt, cwd: options.repoRoot,
+      });
+      return { accepted: true, dispatchId: launched.pid !== undefined ? String(launched.pid) : undefined };
+    },
+  };
+}

package/adapters/mcp/access-mode.ts

@@ -0,0 +1,132 @@
+import { existsSync } from 'fs';
+import {
+  loadMcpServiceLocalConfig,
+  mcpControllerHomeLocalConfigPath,
+  mcpLocalConfigPath,
+  type McpLocalConfig,
+  writeMcpServiceLocalConfig,
+} from './auth';
+import type { McpToolset } from './types';
+import {
+  migrateControllerToolsetConfig,
+  normalizeConfiguredMcpToolset,
+  resolveControllerToolsetSelection,
+} from './toolset-selection';
+import {
+  isAccessMode,
+  type AccessMode,
+} from '../../src/runtime/control-plane/governance/access-policy';
+
+export type ControllerAccessConfigSource =
+  | 'controller_home.access_mode'
+  | 'repo_local_fallback.access_mode'
+  | 'controller_home.legacy_toolset'
+  | 'repo_local_fallback.legacy_toolset'
+  | 'default';
+
+export interface ControllerAccessState {
+  configuredAccessMode: AccessMode;
+  effectiveAccessMode: AccessMode;
+  /** Selected schema profile; access mode never changes this value. */
+  effectiveToolset: McpToolset;
+  source: ControllerAccessConfigSource;
+  lastAppliedAt?: string;
+  exposureRevision: number;
+  configPathSource: 'controller_home' | 'repo_local_fallback' | 'default';
+  legacyToolset?: McpToolset;
+  schemaStableAcrossAccessModes: true;
+}
+
+export interface ResolveControllerAccessStateInput {
+  controllerHome: string;
+  repoRoot?: string;
+  toolsetOverride?: McpToolset;
+  toolsetLocked?: boolean;
+}
+
+export interface PersistControllerAccessModeResult {
+  configPath: string;
+  config: McpLocalConfig;
+  state: ControllerAccessState;
+}
+
+export function accessModeForLegacyToolset(toolset: McpToolset): AccessMode {
+  return toolset === 'core' ? 'request' : 'full_access';
+}
+
+/** Retained for compatibility only; access mode no longer changes schema. */
+export function legacyToolsetForAccessMode(_mode: AccessMode): McpToolset {
+  return 'core';
+}
+
+function configLocation(controllerHome: string, repoRoot?: string): 'controller_home' | 'repo_local_fallback' | 'default' {
+  if (existsSync(mcpControllerHomeLocalConfigPath(controllerHome))) return 'controller_home';
+  if (repoRoot && existsSync(mcpLocalConfigPath(repoRoot))) return 'repo_local_fallback';
+  return 'default';
+}
+
+function normalizedRevision(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
+  return Math.max(0, Math.trunc(value));
+}
+
+export function resolveControllerAccessState(input: ResolveControllerAccessStateInput): ControllerAccessState {
+  const location = configLocation(input.controllerHome, input.repoRoot);
+  const config = loadMcpServiceLocalConfig(input.controllerHome, input.repoRoot);
+  const lastAppliedAt = typeof config?.accessModeUpdatedAt === 'string' && config.accessModeUpdatedAt.trim()
+    ? config.accessModeUpdatedAt
+    : undefined;
+  const exposureRevision = normalizedRevision(config?.accessModeRevision);
+  const rawLegacyToolset = normalizeConfiguredMcpToolset(config?.toolset);
+  const selectedToolset = resolveControllerToolsetSelection(config, input.toolsetOverride);
+  const configuredAccessMode = isAccessMode(config?.accessMode)
+    ? config.accessMode
+    : rawLegacyToolset
+      ? accessModeForLegacyToolset(rawLegacyToolset)
+      : 'full_access';
+  const source: ControllerAccessConfigSource = isAccessMode(config?.accessMode)
+    ? (location === 'controller_home' ? 'controller_home.access_mode' : 'repo_local_fallback.access_mode')
+    : rawLegacyToolset
+      ? (location === 'controller_home' ? 'controller_home.legacy_toolset' : 'repo_local_fallback.legacy_toolset')
+      : 'default';
+  return {
+    configuredAccessMode,
+    effectiveAccessMode: configuredAccessMode,
+    effectiveToolset: selectedToolset.toolset,
+    source,
+    lastAppliedAt,
+    exposureRevision,
+    configPathSource: location,
+    legacyToolset: rawLegacyToolset,
+    schemaStableAcrossAccessModes: true,
+  };
+}
+
+export function persistControllerAccessMode(
+  controllerHome: string,
+  mode: AccessMode,
+  repoRoot?: string,
+): PersistControllerAccessModeResult {
+  const existing = loadMcpServiceLocalConfig(controllerHome, repoRoot) ?? {};
+  const accessModeUpdatedAt = new Date().toISOString();
+  const accessModeRevision = normalizedRevision(existing.accessModeRevision) + 1;
+  const migratedToolset = migrateControllerToolsetConfig(existing);
+  const config: McpLocalConfig = {
+    ...existing,
+    version: Math.max(existing.version ?? 1, 2),
+    profile: existing.profile ?? 'controller',
+    accessMode: mode,
+    accessModeUpdatedAt,
+    accessModeRevision,
+    // Access changes preserve an explicit profile and migrate the old implicit
+    // Advanced label to Core; they never expand or shrink schema themselves.
+    toolset: migratedToolset.toolset,
+    toolsetExplicit: migratedToolset.toolsetExplicit,
+  };
+  const configPath = writeMcpServiceLocalConfig(controllerHome, config);
+  return {
+    configPath,
+    config,
+    state: resolveControllerAccessState({ controllerHome, repoRoot }),
+  };
+}

package/adapters/mcp/audit.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'crypto';
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { redactMcpText } from './redaction';
+import type { McpAuditEntry } from './types';
+
+export function hashMcpInput(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+export function mcpAuditLogPath(repoRoot: string): string {
+  return join(repoRoot, '.ai', 'harness', 'mcp', 'audit.log');
+}
+
+export function writeMcpAuditEntry(repoRoot: string, entry: McpAuditEntry): void {
+  const logPath = mcpAuditLogPath(repoRoot);
+  mkdirSync(dirname(logPath), { recursive: true });
+  const safeEntry = {
+    ...entry,
+    error: entry.error ? redactMcpText(entry.error).text : undefined,
+  };
+  appendFileSync(logPath, `${JSON.stringify(safeEntry)}\n`, 'utf-8');
+}
+
+export function tryWriteMcpAuditEntry(repoRoot: string, entry: McpAuditEntry): boolean {
+  try {
+    writeMcpAuditEntry(repoRoot, entry);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}

package/adapters/mcp/auth.ts

@@ -0,0 +1,407 @@
+import { randomBytes } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { resolveControllerHome } from '../../src/cli/repositories/controller-home';
+import type { AccessMode } from '../../src/runtime/control-plane/governance/access-policy';
+import type { McpToolset } from './types';
+
+export interface McpLocalConfig {
+  version?: number;
+  /** Semantic Forge instance reference. Endpoint/tunnel rotation must not change it. */
+  identity?: {
+    forgeInstanceId?: string;
+  };
+  repo?: string;
+  server?: {
+    host?: string;
+    port?: number;
+    transport?: string;
+  };
+  auth?: {
+    mode?: string;
+    tokenFile?: string;
+    oauthFile?: string;
+  };
+  chatgpt?: {
+    serverName?: string;
+    endpoint?: string;
+    /** Loopback ChatGPT Connector endpoint. Authorization is transport-specific: Secure Tunnel authority or public HTTPS OAuth. */
+    localEndpoint?: string;
+  };
+  profile?: string;
+  toolset?: 'facade' | 'core' | 'advanced' | 'full';
+  /** Compatibility marker retained for previously persisted toolset choices. */
+  toolsetExplicit?: boolean;
+  accessMode?: AccessMode;
+  accessModeUpdatedAt?: string;
+  accessModeRevision?: number;
+  devMode?: {
+    agentRunner?: boolean;
+    allowedAgents?: string[];
+    timeoutMs?: number;
+    maxTimeoutMs?: number;
+  };
+  localController?: {
+    enabled?: boolean;
+    mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
+    host?: string;
+    port?: number;
+    autoOpen?: boolean;
+  };
+}
+
+export type McpRuntimeStatus = 'starting' | 'running' | 'degraded' | 'stopped';
+export type McpRuntimeTunnelMode = 'none' | 'quick' | 'named' | 'tailscale';
+
+export interface McpRuntimeState {
+  version: 1;
+  repo: string;
+  startedAt: string;
+  updatedAt: string;
+  status: McpRuntimeStatus;
+  tunnelMode: McpRuntimeTunnelMode;
+  generation?: string;
+  source?: {
+    repoId: string;
+    checkoutId: string;
+    repoRoot: string;
+    canonicalRoot: string;
+    branch: string | null;
+    commit?: string;
+    releaseRevision?: string;
+    defaultBranch: string;
+    defaultBranchCommit?: string;
+    dirty: boolean;
+    observedAt: string;
+  };
+  server: {
+    endpoint: string;
+    pid?: number;
+    generation?: string;
+    running: boolean;
+    healthy: boolean;
+    restartCount: number;
+    lastStartAt?: string;
+    lastHealthyAt?: string;
+    lastExitAt?: string;
+    lastExit?: string;
+    profile?: string;
+    toolSurface?: string;
+    schemaVersion?: number;
+    forgeVersion?: string;
+    toolSurfaceFingerprint?: string;
+    runtimeToolSurfaceFingerprint?: string;
+    toolset?: 'facade' | 'core' | 'advanced' | 'full';
+    configuredAccessMode?: AccessMode;
+    effectiveAccessMode?: AccessMode;
+    effectiveToolset?: McpToolset;
+    accessModeSource?: string;
+    accessModeLastAppliedAt?: string;
+    exposureRevision?: number;
+    toolCount?: number;
+    repoId?: string;
+    defaultTimeoutMs?: number;
+    maxTimeoutMs?: number;
+    healthMismatch?: string;
+  };
+  localController?: {
+    endpoint: string;
+    running: boolean;
+    mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
+    pid?: number;
+    startedAt?: string;
+    generation?: string;
+    error?: string;
+  };
+  tunnel?: {
+    pid?: number;
+    running: boolean;
+    healthy?: boolean;
+    restartCount: number;
+    name?: string;
+    publicEndpoint?: string;
+    lastUrlChangeAt?: string;
+    lastHealthyAt?: string;
+    lastStartAt?: string;
+    lastExitAt?: string;
+    lastExit?: string;
+    connectorNeedsReconnect?: boolean;
+  };
+  recentErrors?: Array<{
+    at: string;
+    source: 'server' | 'tunnel' | 'health' | 'config' | 'local-controller';
+    message: string;
+  }>;
+}
+
+export type McpHttpAuthMode = 'oauth' | 'bearer' | 'none';
+
+export function mcpLocalConfigPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.local.json');
+}
+
+export function mcpTokenPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.tokens.json');
+}
+
+export function mcpOAuthPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.oauth.json');
+}
+
+export function mcpOAuthTokenStorePath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.oauth-tokens.json');
+}
+
+export function mcpRuntimeStatePath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.runtime.json');
+}
+
+function mcpControllerHomePath(controllerHome: string, filename: string): string {
+  return join(resolveControllerHome(controllerHome), 'mcp', filename);
+}
+
+export function mcpControllerHomeLocalConfigPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.local.json');
+}
+
+export function mcpControllerHomeTokenPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.tokens.json');
+}
+
+export function mcpControllerHomeOAuthPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.oauth.json');
+}
+
+export function mcpControllerHomeOAuthTokenStorePath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.oauth-tokens.json');
+}
+
+export function mcpServiceOAuthTokenStorePath(controllerHome: string): string {
+  return mcpControllerHomeOAuthTokenStorePath(resolveControllerHome(controllerHome));
+}
+
+export function mcpServiceOAuthTokenStoreFallbackPaths(_controllerHome: string, _legacyRepoRoot?: string): string[] {
+  return [];
+}
+
+export function mcpControllerHomeRuntimeStatePath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.runtime.json');
+}
+
+function controllerHomeMcpPaths(controllerHome: string): string[] {
+  return [
+    mcpControllerHomeLocalConfigPath(controllerHome),
+    mcpControllerHomeLocalConfigPath(controllerHome),
+    mcpControllerHomeTokenPath(controllerHome),
+    mcpControllerHomeOAuthPath(controllerHome),
+    mcpControllerHomeOAuthTokenStorePath(controllerHome),
+    mcpControllerHomeRuntimeStatePath(controllerHome),
+  ];
+}
+
+export interface McpRuntimeAuthority {
+  authority: 'controller-home' | 'legacy';
+  path: string;
+  controllerHomePresent: boolean;
+  legacyPresent: boolean;
+  warning?: string;
+}
+
+export function controllerHomeHasAuthoritativeMcpState(controllerHome: string): boolean {
+  return controllerHomeMcpPaths(controllerHome).some((path) => existsSync(path));
+}
+
+export function resolveMcpRuntimeAuthority(
+  controllerHome: string,
+  legacyRepoRoot: string | undefined,
+  kind: 'local-config' | 'runtime-state',
+): McpRuntimeAuthority {
+  const home = resolveControllerHome(controllerHome);
+  const legacyPath = kind === 'local-config'
+    ? (legacyRepoRoot ? mcpLocalConfigPath(legacyRepoRoot) : undefined)
+    : (legacyRepoRoot ? mcpRuntimeStatePath(legacyRepoRoot) : undefined);
+  const legacyPresent = Boolean(legacyPath && existsSync(legacyPath));
+  const controllerHomePresent = controllerHomeHasAuthoritativeMcpState(home);
+  return {
+    authority: 'controller-home',
+    path: kind === 'local-config' ? mcpControllerHomeLocalConfigPath(home) : mcpControllerHomeRuntimeStatePath(home),
+    controllerHomePresent,
+    legacyPresent,
+    warning: legacyPresent
+      ? 'Repository-local MCP state is ignored; Controller Home is authoritative.'
+      : undefined,
+  };
+}
+
+function readJsonFile<T>(path: string): T | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as T;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeJsonFile(path: string, value: unknown): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return path;
+}
+
+export function loadMcpLocalConfig(repoRoot: string): McpLocalConfig | null {
+  const path = mcpLocalConfigPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as McpLocalConfig;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function loadMcpRuntimeState(repoRoot: string): McpRuntimeState | null {
+  const path = mcpRuntimeStatePath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as McpRuntimeState;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function loadMcpServiceLocalConfig(controllerHome: string, _legacyRepoRoot?: string): McpLocalConfig | null {
+  return readJsonFile<McpLocalConfig>(mcpControllerHomeLocalConfigPath(resolveControllerHome(controllerHome)));
+}
+
+export function loadMcpServiceRuntimeState(controllerHome: string, _legacyRepoRoot?: string): McpRuntimeState | null {
+  return readJsonFile<McpRuntimeState>(mcpControllerHomeRuntimeStatePath(resolveControllerHome(controllerHome)));
+}
+
+export function writeMcpLocalConfig(repoRoot: string, config: McpLocalConfig): string {
+  return writeJsonFile(mcpLocalConfigPath(repoRoot), config);
+}
+
+export function writeMcpServiceLocalConfig(controllerHome: string, config: McpLocalConfig): string {
+  return writeJsonFile(mcpControllerHomeLocalConfigPath(resolveControllerHome(controllerHome)), config);
+}
+
+export function writeMcpRuntimeState(repoRoot: string, state: McpRuntimeState): string {
+  const path = mcpRuntimeStatePath(repoRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return path;
+}
+
+export function writeMcpServiceRuntimeState(controllerHome: string, state: McpRuntimeState): string {
+  return writeJsonFile(mcpControllerHomeRuntimeStatePath(controllerHome), state);
+}
+
+export function readMcpBearerToken(repoRoot: string): string | null {
+  if (process.env.FORGE_MCP_TOKEN?.trim()) return process.env.FORGE_MCP_TOKEN.trim();
+  const path = mcpTokenPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { bearerToken?: unknown };
+    return typeof parsed.bearerToken === 'string' && parsed.bearerToken.trim().length > 0 ? parsed.bearerToken.trim() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function ensureMcpBearerToken(repoRoot: string): { token: string; path: string; changed: boolean } {
+  const path = mcpTokenPath(repoRoot);
+  const existing = readMcpBearerToken(repoRoot);
+  if (existing) return { token: existing, path, changed: false };
+
+  const token = randomBytes(32).toString('base64url');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ version: 1, bearerToken: token }, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return { token, path, changed: true };
+}
+
+export function readMcpServiceBearerToken(controllerHome: string, _legacyRepoRoot?: string): string | null {
+  if (process.env.FORGE_MCP_TOKEN?.trim()) return process.env.FORGE_MCP_TOKEN.trim();
+  const parsed = readJsonFile<{ bearerToken?: unknown }>(mcpControllerHomeTokenPath(controllerHome));
+  if (typeof parsed?.bearerToken === 'string' && parsed.bearerToken.trim().length > 0) return parsed.bearerToken.trim();
+  return null;
+}
+
+export function ensureMcpControllerHomeBearerToken(controllerHome: string): { token: string; path: string; changed: boolean } {
+  const path = mcpControllerHomeTokenPath(controllerHome);
+  const existing = readMcpServiceBearerToken(controllerHome);
+  if (existing) return { token: existing, path, changed: false };
+
+  const token = randomBytes(32).toString('base64url');
+  writeJsonFile(path, { version: 1, bearerToken: token });
+  return { token, path, changed: true };
+}
+
+export function writeMcpControllerHomeBearerToken(controllerHome: string, token: string): { path: string } {
+  const trimmed = token.trim();
+  if (!trimmed) throw new Error('MCP_BEARER_TOKEN_EMPTY');
+  const path = mcpControllerHomeTokenPath(controllerHome);
+  writeJsonFile(path, { version: 1, bearerToken: trimmed });
+  return { path };
+}
+
+export function syncMcpControllerHomeBearerToken(
+  targetControllerHome: string,
+  sourceControllerHome: string,
+  _legacyRepoRoot?: string,
+): { path: string; changed: boolean } {
+  const source = readMcpServiceBearerToken(sourceControllerHome)
+    ?? ensureMcpControllerHomeBearerToken(sourceControllerHome).token;
+  const targetPath = mcpControllerHomeTokenPath(targetControllerHome);
+  const target = readMcpServiceBearerToken(targetControllerHome);
+  if (target === source) return { path: targetPath, changed: false };
+  writeMcpControllerHomeBearerToken(targetControllerHome, source);
+  return { path: targetPath, changed: true };
+}
+
+export function parseMcpHttpAuthMode(value: string | undefined): McpHttpAuthMode {
+  const mode = (value ?? 'oauth').trim().toLowerCase();
+  if (mode === 'oauth' || mode === 'bearer' || mode === 'none') return mode;
+  throw new Error(`invalid --auth "${value}" (expected: oauth, bearer, none)`);
+}
+
+export function readMcpOAuthPassphrase(repoRoot: string): string | null {
+  if (process.env.FORGE_MCP_OAUTH_PASSPHRASE?.trim()) {
+    return process.env.FORGE_MCP_OAUTH_PASSPHRASE.trim();
+  }
+  const path = mcpOAuthPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { passphrase?: unknown };
+    return typeof parsed.passphrase === 'string' && parsed.passphrase.trim().length > 0 ? parsed.passphrase.trim() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function ensureMcpOAuthPassphrase(repoRoot: string): { passphrase: string; path: string; changed: boolean } {
+  const path = mcpOAuthPath(repoRoot);
+  const existing = readMcpOAuthPassphrase(repoRoot);
+  if (existing) return { passphrase: existing, path, changed: false };
+
+  const passphrase = randomBytes(24).toString('base64url');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ version: 1, passphrase }, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return { passphrase, path, changed: true };
+}
+
+export function readMcpServiceOAuthPassphrase(controllerHome: string, _legacyRepoRoot?: string): string | null {
+  if (process.env.FORGE_MCP_OAUTH_PASSPHRASE?.trim()) {
+    return process.env.FORGE_MCP_OAUTH_PASSPHRASE.trim();
+  }
+  const parsed = readJsonFile<{ passphrase?: unknown }>(mcpControllerHomeOAuthPath(resolveControllerHome(controllerHome)));
+  return typeof parsed?.passphrase === 'string' && parsed.passphrase.trim().length > 0 ? parsed.passphrase.trim() : null;
+}
+
+export function ensureMcpControllerHomeOAuthPassphrase(controllerHome: string): { passphrase: string; path: string; changed: boolean } {
+  const path = mcpControllerHomeOAuthPath(resolveControllerHome(controllerHome));
+  const existing = readMcpServiceOAuthPassphrase(controllerHome);
+  if (existing) return { passphrase: existing, path, changed: false };
+
+  const passphrase = randomBytes(24).toString('base64url');
+  writeJsonFile(path, { version: 1, passphrase });
+  return { passphrase, path, changed: true };
+}