@moretea-labs/forge 1.5.0-rc.1 → 1.5.1

package/src/runtime/control-plane/global-scheduler/scheduler.ts

@@ -28,7 +28,6 @@ import { RepoActorRegistry } from '../repo-actor/registry';
 import { reconcileExecutionJobsAsync } from './reconciliation';
 import { tickSchedules } from '../../workflow/schedules/engine';
 import { tickPortfolioWorkflows } from '../../workflow/portfolio/engine';
-import { tickCampaigns } from '../../workflow/campaigns/engine';
 import { tickGoalLoopsForController } from '../goal-loop';
 import { readJsonFile, writeJsonAtomic } from '../../shared/json-files';
 import { resolveBunExecutable } from '../../shared/process-environment';
@@ -36,6 +35,9 @@ import { isProcessAlive, terminateProcessTree } from '../../shared/process-tree'
 import { readSchedulerWakeSignal, waitForSchedulerWakeSignal } from './wake-signal';
 import { cleanupControllerRuntimeState } from '../runtime-cleanup';
 import { reconcileTerminalWorkCleanups } from '../execution/work-terminal-cleanup';
+import { gcTerminalProcesses } from '../../execution/process-runtime/gc';
+import { reconcilePendingWorkValidations } from '../execution/work-validation-reconciler';
+import { reconcilePendingEditValidations } from '../execution/edit-validation-coordinator';
 import { schedulerDispatchAllowed } from '../facade/work-admission-policy';
 import { rebuildRepositoryProjection, refreshRepositoryProjectionForRepository } from '../../projections/materialized-view';
 import { readRepositoryGitStatusSample, sampleRepositoryGitStatusForRepositories } from '../../projections/git-status-sampler';
@@ -215,7 +217,6 @@ export class GlobalScheduler {
   private readonly fatalOnTickError: boolean;
   private lastScheduleTick = 0;
   private lastPortfolioTick = 0;
-  private lastCampaignTick = 0;
   private lastGoalLoopTick = 0;
   private lastReconcile = 0;
   private lastPersistedAt = 0;
@@ -232,6 +233,10 @@ export class GlobalScheduler {
   private sourceScansAvoided = 0;
   private runtimeCleanup = cleanupControllerRuntimeState;
   private terminalWorkCleanup = reconcileTerminalWorkCleanups;
+  private processGc = gcTerminalProcesses;
+  private workValidationReconcile = reconcilePendingWorkValidations;
+  private editValidationReconcile = reconcilePendingEditValidations;
+  private repositoryList = listRepositories;
   private lastDarwinMemorySampleAt = 0;
   private cachedDarwinAvailableMemoryMb: number | undefined;
   private darwinMemorySampleInFlight: Promise<void> | undefined;
@@ -612,6 +617,7 @@ export class GlobalScheduler {
     this.lastHeartbeatAt = new Date(now).toISOString();
     this.lastTickAt = this.lastHeartbeatAt;
     this.persistState();
+    const repositories = this.repositoryList(this.controllerHome).filter((repo) => repo.enabled && !repo.removedAt);
     if (now - this.lastCleanupAt >= RUNTIME_CLEANUP_INTERVAL_MS) {
       // Advance the interval before cleanup so a failing pass cannot create a
       // tight retry loop on every scheduler tick.
@@ -630,13 +636,32 @@ export class GlobalScheduler {
       } catch (error) {
         console.error('[forge cleanup] terminal Work cleanup failed:', error);
       }
+      if (repositories.length > 0) {
+        const slot = Math.floor(now / RUNTIME_CLEANUP_INTERVAL_MS) % repositories.length;
+        const repo = repositories[slot]!;
+        const result = this.processGc({ controllerHome: this.controllerHome, repoId: repo.repoId });
+        if (!result.ok) console.error('[forge cleanup] Process GC failed:', result.error ?? 'unknown error');
+      }
     }
     if (now - this.lastReconcile >= 5_000) {
       await reconcileExecutionJobsAsync(this.controllerHome);
+      for (const repository of repositories) {
+        const validation = this.workValidationReconcile(this.controllerHome, repository.repoId, 500);
+        if (validation.errors.length > 0) {
+          console.error(
+            `[forge validation] background Work reconciliation reported ${validation.errors.length} error(s) for ${repository.repoId}`,
+          );
+        }
+        const editValidation = await this.editValidationReconcile(this.controllerHome, repository, 200);
+        if (editValidation.errors.length > 0) {
+          console.error(
+            `[forge validation] background EditSession reconciliation reported ${editValidation.errors.length} error(s) for ${repository.repoId}`,
+          );
+        }
+      }
       this.lastReconcile = now;
       this.lastReconcileAt = new Date(now).toISOString();
     }
-    const repositories = listRepositories(this.controllerHome).filter((repo) => repo.enabled && !repo.removedAt);
     const activeJobSnapshot = listActiveExecutionJobs(this.controllerHome);
     const hasActiveWork = activeJobSnapshot.length > 0;
     const sourceScanDue = hasActiveWork || now - this.lastSourceScanAt >= IDLE_REPOSITORY_SCAN_INTERVAL_MS;
@@ -843,12 +868,9 @@ export class GlobalScheduler {
       this.spawnWorker(pending.repoId, pending.jobId);
     }
     // Dispatch is latency-sensitive. Run repository workflow maintenance only
-    // after queued Jobs have had a chance to claim capacity. Campaign and Goal
+    // after queued Jobs have had a chance to claim capacity. Goal
     // state transitions still wake the scheduler immediately when they enqueue work.
-    if (now - this.lastCampaignTick >= 1_000) {
-      tickCampaigns(this.controllerHome, repositories.map((repo) => repo.repoId));
-      this.lastCampaignTick = now;
-    }
+
     if (now - this.lastGoalLoopTick >= 5_000) {
       try {
         tickGoalLoopsForController(

package/src/runtime/control-plane/launcher/chatgpt-work-binding-store.ts

@@ -0,0 +1,114 @@
+import { withControllerLock } from '../../../cli/repositories/locks';
+import { readControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
+
+const NAMESPACE = 'chatgpt_work_conversation_binding';
+
+export interface ChatgptWorkConversationBinding {
+  schemaVersion: 1;
+  repoId: string;
+  workId: string;
+  conversationUrl: string;
+  conversationId: string;
+  localAlias: string;
+  latestBrowserSessionId?: string;
+  createdAt: string;
+  updatedAt: string;
+  lastContinuedAt?: string;
+}
+
+export interface ChatgptWorkBindingStoreOptions {
+  controllerHome: string;
+  repoId: string;
+  now?: () => string;
+}
+
+function nowIso(options: ChatgptWorkBindingStoreOptions): string {
+  return options.now?.() ?? new Date().toISOString();
+}
+
+export function parseChatgptConversationIdentity(value: string): { conversationUrl: string; conversationId: string } {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('CHATGPT_WORK_CONVERSATION_URL_INVALID');
+  }
+  if (url.protocol !== 'https:' || !['chatgpt.com', 'www.chatgpt.com', 'chat.openai.com'].includes(url.hostname)) {
+    throw new Error('CHATGPT_WORK_CONVERSATION_URL_INVALID');
+  }
+  const parts = url.pathname.split('/').filter(Boolean);
+  const c = parts.lastIndexOf('c');
+  const conversationId = c >= 0 ? parts[c + 1]?.trim() : undefined;
+  if (!conversationId) throw new Error('CHATGPT_WORK_CONVERSATION_ID_MISSING');
+  url.protocol = 'https:';
+  url.hostname = 'chatgpt.com';
+  url.search = '';
+  url.hash = '';
+  return { conversationUrl: url.toString(), conversationId };
+}
+
+function record(options: ChatgptWorkBindingStoreOptions, workId: string) {
+  return readControlPlaneRecord<ChatgptWorkConversationBinding>(
+    options.controllerHome,
+    NAMESPACE,
+    options.repoId,
+    workId,
+  );
+}
+
+export function getChatgptWorkConversationBinding(
+  options: ChatgptWorkBindingStoreOptions,
+  workId: string,
+): ChatgptWorkConversationBinding | undefined {
+  return record(options, workId)?.value;
+}
+
+export function bindChatgptWorkConversation(
+  options: ChatgptWorkBindingStoreOptions,
+  input: {
+    workId: string;
+    conversationUrl: string;
+    latestBrowserSessionId?: string;
+    localAlias?: string;
+  },
+): ChatgptWorkConversationBinding {
+  if (!input.workId.trim()) throw new Error('CHATGPT_WORK_BINDING_WORK_REQUIRED');
+  const identity = parseChatgptConversationIdentity(input.conversationUrl);
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `chatgpt-work-binding-${input.workId}` },
+    `chatgpt-work-binding:${input.workId}`,
+    () => {
+      const existing = record(options, input.workId);
+      if (existing && existing.value.conversationId !== identity.conversationId) {
+        throw new Error(`CHATGPT_WORK_CONVERSATION_REBIND_REQUIRED: ${input.workId}:${existing.value.conversationId}`);
+      }
+      const now = nowIso(options);
+      const localAlias = input.localAlias?.trim()
+        || existing?.value.localAlias
+        || `Forge · ${options.repoId} · ${input.workId} · ${identity.conversationId.slice(0, 8)}`;
+      const binding: ChatgptWorkConversationBinding = {
+        schemaVersion: 1,
+        repoId: options.repoId,
+        workId: input.workId,
+        conversationUrl: identity.conversationUrl,
+        conversationId: identity.conversationId,
+        localAlias: localAlias.slice(0, 180),
+        latestBrowserSessionId: input.latestBrowserSessionId ?? existing?.value.latestBrowserSessionId,
+        createdAt: existing?.value.createdAt ?? now,
+        updatedAt: now,
+        lastContinuedAt: now,
+      };
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: options.repoId,
+        key: input.workId,
+        schemaVersion: 1,
+        value: binding,
+        action: existing ? 'chatgpt_work_conversation_continue' : 'chatgpt_work_conversation_bind',
+        expectedRevision: existing?.revision ?? null,
+      });
+      return binding;
+    },
+  );
+}

package/src/runtime/control-plane/launcher/chatgpt-work-continuation.ts

@@ -0,0 +1,175 @@
+import { randomUUID } from 'crypto';
+import { executeBrowserPluginAction, readBrowserPluginConfiguration } from '../../plugins/browser-adapter';
+import { controllerPluginRepository } from '../../plugins/store';
+import { getWorkContract } from '../facade/work-contract-store';
+import {
+  bindChatgptWorkConversation,
+  getChatgptWorkConversationBinding,
+  type ChatgptWorkConversationBinding,
+} from './chatgpt-work-binding-store';
+
+const CONTROLLER_CHATGPT_SESSION_ID = 'forge-chatgpt-supercontroller';
+const CHATGPT_PROMPT_SELECTOR = '[name="prompt-textarea"]';
+const CHATGPT_SEND_KEY = 'Enter';
+const CHATGPT_ALLOWED_DOMAINS = ['chatgpt.com', 'www.chatgpt.com'];
+
+export interface WorkChatgptContinuationInput {
+  controllerHome: string;
+  repoId: string;
+  repoRoot: string;
+  workId: string;
+  prompt: string;
+  title?: string;
+  browserSessionId?: string;
+  conversationUrl?: string;
+  timeoutMs?: number;
+}
+
+export interface WorkChatgptContinuationResult {
+  status: 'dispatched' | 'failed';
+  provider: 'controller-browser';
+  browserSessionId: string;
+  conversationUrl?: string;
+  conversationId?: string;
+  localAlias?: string;
+  resumedFromBinding: boolean;
+  error?: { code: string; message: string };
+}
+
+function requestId(workId: string, actionId: string): string {
+  return `chatgpt-work:${workId}:${actionId}:${randomUUID()}`;
+}
+
+async function controllerBrowserAction(
+  controllerHome: string,
+  workId: string,
+  actionId: string,
+  args: Record<string, unknown>,
+  timeoutMs?: number,
+): Promise<Record<string, unknown>> {
+  const repository = controllerPluginRepository(controllerHome);
+  const repoRoot = repository.canonicalRoot ?? repository.localRoot;
+  if (!repoRoot) throw new Error('CHATGPT_CONTROLLER_BROWSER_ROOT_UNAVAILABLE');
+  return executeBrowserPluginAction({
+    controllerHome,
+    repoId: repository.repoId,
+    repoRoot,
+    pluginId: 'browser',
+    actionId,
+    requestId: requestId(workId, actionId),
+    args,
+    timeoutMs,
+    origin: { surface: 'schedule', actor: 'chatgpt-work-continuation' },
+  });
+}
+
+async function ensureControllerChatgptBrowser(controllerHome: string, workId: string): Promise<void> {
+  const repository = controllerPluginRepository(controllerHome);
+  const repoRoot = repository.canonicalRoot ?? repository.localRoot;
+  if (!repoRoot) throw new Error('CHATGPT_CONTROLLER_BROWSER_ROOT_UNAVAILABLE');
+  const existing = readBrowserPluginConfiguration(repoRoot);
+  const allowedDomains = [...new Set([...existing.allowedDomains, ...CHATGPT_ALLOWED_DOMAINS])];
+  await controllerBrowserAction(controllerHome, workId, 'configure', {
+    enabled: true,
+    ...(!existing.enabled ? {
+      browser_mode: 'attach_preferred',
+      profile_mode: 'repo_local',
+      browser_channel: 'chromium',
+      cdp_attach_fallback: 'fail_closed',
+      native_attach_mode: 'auto',
+      native_browser_candidates: ['chrome'],
+    } : {}),
+    allowed_domains: allowedDomains,
+  });
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function resultUrl(result: Record<string, unknown>): string | undefined {
+  return stringField(result.url)
+    ?? stringField((result.session as Record<string, unknown> | undefined)?.url);
+}
+
+/**
+ * Dispatches a bounded resume prompt to one controller-owned ChatGPT Web tab.
+ * Chat history is transport context only. Forge Work/Plan/evidence remain authoritative.
+ */
+export async function runWorkChatgptContinuation(input: WorkChatgptContinuationInput): Promise<WorkChatgptContinuationResult> {
+  const store = { controllerHome: input.controllerHome, repoId: input.repoId };
+  const existing = getChatgptWorkConversationBinding(store, input.workId);
+  const seedUrl = input.conversationUrl?.trim() || existing?.conversationUrl;
+  const sessionId = input.browserSessionId?.trim() || CONTROLLER_CHATGPT_SESSION_ID;
+  let binding: ChatgptWorkConversationBinding | undefined = existing;
+
+  try {
+    const work = getWorkContract(store, input.workId);
+    if (!work || work.repoId !== input.repoId) {
+      throw new Error(`CHATGPT_WORK_CONTRACT_NOT_FOUND: ${input.repoId}:${input.workId}`);
+    }
+    await ensureControllerChatgptBrowser(input.controllerHome, input.workId);
+    if (seedUrl && !binding) {
+      binding = bindChatgptWorkConversation(store, {
+        workId: input.workId,
+        conversationUrl: seedUrl,
+        latestBrowserSessionId: sessionId,
+        localAlias: input.title,
+      });
+    }
+    const targetUrl = binding?.conversationUrl ?? seedUrl ?? 'https://chatgpt.com/';
+    await controllerBrowserAction(input.controllerHome, input.workId, 'navigate', {
+      session_id: sessionId,
+      url: targetUrl,
+      wait_until: 'domcontentloaded',
+      timeout_ms: input.timeoutMs ?? 60_000,
+      retries: 1,
+    }, input.timeoutMs);
+    await controllerBrowserAction(input.controllerHome, input.workId, 'fill', {
+      session_id: sessionId,
+      selector: CHATGPT_PROMPT_SELECTOR,
+      text: input.prompt,
+      timeout_ms: input.timeoutMs ?? 60_000,
+      post_action_wait_ms: 100,
+    }, input.timeoutMs);
+    const sent = await controllerBrowserAction(input.controllerHome, input.workId, 'press', {
+      session_id: sessionId,
+      selector: CHATGPT_PROMPT_SELECTOR,
+      key: CHATGPT_SEND_KEY,
+      timeout_ms: input.timeoutMs ?? 60_000,
+      post_action_wait_ms: 1_500,
+    }, input.timeoutMs);
+    const observedUrl = resultUrl(sent) ?? targetUrl;
+    if (/\/c\/[^/?#]+/.test(observedUrl)) {
+      binding = bindChatgptWorkConversation(store, {
+        workId: input.workId,
+        conversationUrl: observedUrl,
+        latestBrowserSessionId: sessionId,
+        localAlias: binding?.localAlias ?? input.title,
+      });
+    }
+    return {
+      status: 'dispatched',
+      provider: 'controller-browser',
+      browserSessionId: sessionId,
+      conversationUrl: binding?.conversationUrl ?? observedUrl,
+      conversationId: binding?.conversationId,
+      localAlias: binding?.localAlias,
+      resumedFromBinding: Boolean(existing),
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      provider: 'controller-browser',
+      browserSessionId: sessionId,
+      conversationUrl: binding?.conversationUrl ?? seedUrl,
+      conversationId: binding?.conversationId,
+      localAlias: binding?.localAlias,
+      resumedFromBinding: Boolean(existing),
+      error: {
+        code: error instanceof Error && error.message.includes(':') ? error.message.split(':', 1)[0] : 'CHATGPT_CONTROLLER_BROWSER_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}

package/src/runtime/control-plane/launcher/launch-reservation-store.ts

@@ -0,0 +1,161 @@
+import { randomUUID } from 'crypto';
+import { withControllerLock } from '../../../cli/repositories/locks';
+import {
+  readControlPlaneRecord,
+  writeControlPlaneRecord,
+} from '../persistence/sqlite-store';
+import type { ControllerType } from '../facade/types';
+
+const NAMESPACE = 'external_controller_launch_reservation';
+const DEFAULT_TTL_MS = 2 * 60_000;
+const MAX_TTL_MS = 10 * 60_000;
+
+export interface ExternalControllerLaunchReservation {
+  schemaVersion: 1;
+  repoId: string;
+  workId: string;
+  reservationId: string;
+  controllerType: Exclude<ControllerType, 'human'>;
+  createdAt: string;
+  expiresAt: string;
+  pid?: number;
+  releasedAt?: string;
+  releaseReason?: string;
+}
+
+export interface LaunchReservationStoreOptions {
+  controllerHome: string;
+  repoId: string;
+  now?: () => string;
+}
+
+function nowIso(options: LaunchReservationStoreOptions): string {
+  return options.now?.() ?? new Date().toISOString();
+}
+
+function record(options: LaunchReservationStoreOptions, workId: string) {
+  return readControlPlaneRecord<ExternalControllerLaunchReservation>(
+    options.controllerHome,
+    NAMESPACE,
+    options.repoId,
+    workId,
+  );
+}
+
+function active(value: ExternalControllerLaunchReservation | undefined, at = Date.now()): ExternalControllerLaunchReservation | undefined {
+  if (!value || value.releasedAt) return undefined;
+  return Date.parse(value.expiresAt) > at ? value : undefined;
+}
+
+export function getExternalControllerLaunchReservation(
+  options: LaunchReservationStoreOptions,
+  workId: string,
+): ExternalControllerLaunchReservation | undefined {
+  return active(record(options, workId)?.value);
+}
+
+export function reserveExternalControllerLaunch(
+  options: LaunchReservationStoreOptions,
+  input: {
+    workId: string;
+    controllerType: Exclude<ControllerType, 'human'>;
+    ttlMs?: number;
+  },
+): ExternalControllerLaunchReservation {
+  if (!input.workId.trim()) throw new Error('CONTROLLER_LAUNCH_WORK_REQUIRED');
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-launch-${input.workId}` },
+    `controller-launch-reserve:${input.workId}`,
+    () => {
+      const existing = record(options, input.workId);
+      const current = active(existing?.value);
+      if (current) {
+        throw new Error(`CONTROLLER_LAUNCH_ALREADY_RESERVED: ${input.workId}:${current.reservationId}`);
+      }
+      const createdAt = nowIso(options);
+      const ttlMs = Math.max(5_000, Math.min(input.ttlMs ?? DEFAULT_TTL_MS, MAX_TTL_MS));
+      const reservation: ExternalControllerLaunchReservation = {
+        schemaVersion: 1,
+        repoId: options.repoId,
+        workId: input.workId,
+        reservationId: randomUUID(),
+        controllerType: input.controllerType,
+        createdAt,
+        expiresAt: new Date(Date.parse(createdAt) + ttlMs).toISOString(),
+      };
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: options.repoId,
+        key: input.workId,
+        schemaVersion: 1,
+        value: reservation,
+        action: 'external_controller_launch_reserve',
+        expectedRevision: existing?.revision ?? null,
+      });
+      return reservation;
+    },
+  );
+}
+
+export function attachExternalControllerLaunchPid(
+  options: LaunchReservationStoreOptions,
+  workId: string,
+  reservationId: string,
+  pid: number | undefined,
+): ExternalControllerLaunchReservation {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-launch-${workId}` },
+    `controller-launch-bind:${reservationId}`,
+    () => {
+      const existing = record(options, workId);
+      if (!existing || existing.value.reservationId !== reservationId) {
+        throw new Error(`CONTROLLER_LAUNCH_RESERVATION_STALE: ${workId}:${reservationId}`);
+      }
+      const next = { ...existing.value, ...(pid ? { pid } : {}) };
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: options.repoId,
+        key: workId,
+        schemaVersion: 1,
+        value: next,
+        action: 'external_controller_launch_bind_pid',
+        expectedRevision: existing.revision,
+      });
+      return next;
+    },
+  );
+}
+
+export function releaseExternalControllerLaunchReservation(
+  options: LaunchReservationStoreOptions,
+  workId: string,
+  reservationId: string,
+  reason: string,
+): void {
+  withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-launch-${workId}` },
+    `controller-launch-release:${reservationId}`,
+    () => {
+      const existing = record(options, workId);
+      if (!existing || existing.value.reservationId !== reservationId || existing.value.releasedAt) return;
+      const releasedAt = nowIso(options);
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: options.repoId,
+        key: workId,
+        schemaVersion: 1,
+        value: {
+          ...existing.value,
+          expiresAt: releasedAt,
+          releasedAt,
+          releaseReason: reason.slice(0, 240),
+        },
+        action: 'external_controller_launch_release',
+        expectedRevision: existing.revision,
+      });
+    },
+  );
+}

package/src/runtime/control-plane/launcher/provider-mcp-bootstrap.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'fs';
+import { forgeRuntimeServicePaths, readForgeRuntimeServiceConfig } from '../../root/service';
+import { observeRuntimeStatus, readRuntimeStatusSnapshot } from '../../root/status';
+
+export const FORGE_RUNTIME_MCP_TOKEN_ENV = 'FORGE_RUNTIME_MCP_TOKEN';
+
+export interface ProviderMcpBootstrap {
+  url: string;
+  bearerTokenEnvVar: typeof FORGE_RUNTIME_MCP_TOKEN_ENV;
+  principalId: string;
+  sessionId: string;
+  env: NodeJS.ProcessEnv;
+}
+
+function runtimeMcpUrl(controllerHome: string): string {
+  const observed = observeRuntimeStatus(controllerHome);
+  if (!observed.running || !observed.ready) {
+    throw new Error(`LAUNCHER_RUNTIME_MCP_NOT_READY: ${observed.reasonCodes.join(',') || 'runtime_not_ready'}`);
+  }
+  const snapshot = readRuntimeStatusSnapshot(controllerHome);
+  if (snapshot?.endpoint?.trim()) return snapshot.endpoint.trim();
+  const config = readForgeRuntimeServiceConfig(forgeRuntimeServicePaths(controllerHome).configPath);
+  const host = config.host === '0.0.0.0' || config.host === '::' ? '127.0.0.1' : config.host;
+  const renderedHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  return `http://${renderedHost}:${config.port}/mcp`;
+}
+
+export function resolveProviderMcpBootstrap(
+  controllerHome: string,
+  provider: 'codex',
+  reservationId: string,
+): ProviderMcpBootstrap {
+  const config = readForgeRuntimeServiceConfig(forgeRuntimeServicePaths(controllerHome).configPath);
+  const token = readFileSync(config.authTokenFile, 'utf8').trim();
+  if (!token) throw new Error('LAUNCHER_RUNTIME_MCP_TOKEN_EMPTY');
+  const suffix = reservationId.trim();
+  if (!suffix) throw new Error('LAUNCHER_RESERVATION_ID_REQUIRED');
+  return {
+    url: runtimeMcpUrl(controllerHome),
+    bearerTokenEnvVar: FORGE_RUNTIME_MCP_TOKEN_ENV,
+    principalId: `external:${provider}:${suffix}`,
+    sessionId: `external-session:${provider}:${suffix}`,
+    env: {
+      ...process.env,
+      [FORGE_RUNTIME_MCP_TOKEN_ENV]: token,
+    },
+  };
+}
+
+export function codexMcpConfigArgs(bootstrap: ProviderMcpBootstrap): string[] {
+  const headers = {
+    'X-Forge-Forwarded-Principal-Id': bootstrap.principalId,
+    'X-Forge-Forwarded-Session-Id': bootstrap.sessionId,
+    'X-Forge-Forwarded-Controller-Type': 'codex',
+  };
+  const headerTable = `{${Object.entries(headers)
+    .map(([key, value]) => `${JSON.stringify(key)}=${JSON.stringify(value)}`)
+    .join(',')}}`;
+  return [
+    '-c', `mcp_servers.forge.url=${JSON.stringify(bootstrap.url)}`,
+    '-c', `mcp_servers.forge.bearer_token_env_var=${JSON.stringify(bootstrap.bearerTokenEnvVar)}`,
+    '-c', `mcp_servers.forge.http_headers=${headerTable}`,
+  ];
+}