@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/transports/oauth-http.ts

@@ -0,0 +1,322 @@
+import { timingSafeEqual } from 'crypto';
+import express, { type Express, type NextFunction, type Request, type Response } from 'express';
+import type { OAuthClientInformationFull } from '@modelcontextprotocol/server';
+import { clientRegistrationHandler, redirectUriMatches, revocationHandler, tokenHandler } from '@modelcontextprotocol/server-legacy/auth';
+import type { McpLocalConfig } from '../auth';
+import { createMcpOAuthProvider } from '../oauth';
+
+export function getConfiguredPublicOrigin(config: McpLocalConfig | null): string | undefined {
+  const configured = process.env.FORGE_MCP_PUBLIC_ORIGIN?.trim();
+  if (configured) {
+    try {
+      return new URL(configured).origin;
+    } catch (_error) {
+      // Fall through to service or legacy config.
+    }
+  }
+  const endpoint = config?.chatgpt?.endpoint?.trim();
+  if (!endpoint) return undefined;
+  try {
+    return new URL(endpoint).origin;
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+export function getPublicOrigin(req: Request, configuredOrigin: string | undefined): string {
+  if (configuredOrigin) return configuredOrigin;
+  const proto = (req.headers['x-forwarded-proto'] as string | undefined) ?? 'https';
+  const host = (req.headers['x-forwarded-host'] as string | undefined) ?? req.headers.host ?? '127.0.0.1:8765';
+  return `${proto}://${host}`;
+}
+
+export function isAllowedMcpOAuthRedirectUri(redirectUri: string): boolean {
+  try {
+    const url = new URL(redirectUri);
+    if (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) return true;
+    return url.protocol === 'https:'
+      && (url.origin === 'https://chatgpt.com' || url.origin === 'https://chat.openai.com')
+      && url.pathname.startsWith('/connector/oauth/');
+  } catch (_error) {
+    return false;
+  }
+}
+
+function isRegisteredRedirectUri(redirectUri: string, client: { redirect_uris?: string[] }): boolean {
+  return (client.redirect_uris ?? []).some((registered) => redirectUriMatches(redirectUri, registered));
+}
+
+function isRegisteredExternalHttpsRedirectUri(redirectUri: string, client: { redirect_uris?: string[] }): boolean {
+  try {
+    const url = new URL(redirectUri);
+    return url.protocol === 'https:' && !url.username && !url.password && isRegisteredRedirectUri(redirectUri, client);
+  } catch (_error) {
+    return false;
+  }
+}
+
+function isSafeOAuthFallbackRedirectUri(redirectUri: string): boolean {
+  try {
+    const url = new URL(redirectUri);
+    if (url.username || url.password) return false;
+    if (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) return true;
+    return url.protocol === 'https:';
+  } catch (_error) {
+    return false;
+  }
+}
+
+function oauthAuthorizeParamSource(req: Request): Record<string, unknown> {
+  if (req.method === 'POST' && req.body && typeof req.body === 'object' && !Buffer.isBuffer(req.body)) {
+    return req.body as Record<string, unknown>;
+  }
+  return req.query as Record<string, unknown>;
+}
+
+function readOAuthAuthorizeString(source: Record<string, unknown>, key: string): string {
+  const value = source[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function isIncompleteOAuthAuthorizeRequest(source: Record<string, unknown>): boolean {
+  const clientId = readOAuthAuthorizeString(source, 'client_id');
+  const responseType = readOAuthAuthorizeString(source, 'response_type');
+  const codeChallenge = readOAuthAuthorizeString(source, 'code_challenge');
+  const redirectUri = readOAuthAuthorizeString(source, 'redirect_uri');
+  const hasRedirectContext = Boolean(redirectUri) || Boolean(clientId);
+  return !clientId || !responseType || !codeChallenge || !hasRedirectContext;
+}
+
+function incompleteOAuthAuthorizeResponseBody() {
+  return {
+    error: 'invalid_request' as const,
+    error_description: 'OAuth authorization request is incomplete. Required: client_id, response_type, code_challenge, and a usable redirect context (redirect_uri or a registered client).',
+    message: 'This endpoint expects a complete OAuth authorization request (PKCE). Non-OAuth MCP clients should use /mcp-bearer with Authorization: Bearer <token> instead of /authorize.',
+    hint: 'Use POST/GET /mcp-bearer with a forge bearer token for clients that cannot complete OAuth dynamic registration and PKCE.',
+  };
+}
+
+function isOAuthDebugTraceEnabled(): boolean {
+  return process.env.FORGE_MCP_OAUTH_TRACE === '1' || process.env.FORGE_MCP_OAUTH_TRACE === 'true';
+}
+
+const SENSITIVE_OAUTH_FIELDS = new Set(['passphrase', 'code', 'code_verifier', 'client_secret', 'access_token', 'refresh_token', 'token', 'authorization']);
+
+function safeOAuthFieldNames(source: Record<string, unknown>): string[] {
+  return Object.keys(source).filter((key) => !SENSITIVE_OAUTH_FIELDS.has(key.toLowerCase())).sort();
+}
+
+function oauthTrace(req: Request, event: string, extra: Record<string, unknown> = {}): void {
+  if (!isOAuthDebugTraceEnabled()) return;
+  const source = oauthAuthorizeParamSource(req);
+  const userAgent = typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'].split(/[\s/]/)[0] : undefined;
+  console.error(`[forge:mcp-oauth] ${JSON.stringify({
+    event,
+    method: req.method,
+    path: req.path,
+    fieldNames: safeOAuthFieldNames(source),
+    hasClientId: Boolean(readOAuthAuthorizeString(source, 'client_id')),
+    hasRedirectUri: Boolean(readOAuthAuthorizeString(source, 'redirect_uri')),
+    hasCodeChallenge: Boolean(readOAuthAuthorizeString(source, 'code_challenge')),
+    responseType: readOAuthAuthorizeString(source, 'response_type') || undefined,
+    codeChallengeMethod: readOAuthAuthorizeString(source, 'code_challenge_method') || undefined,
+    grantType: readOAuthAuthorizeString(source, 'grant_type') || undefined,
+    hasResource: Boolean(readOAuthAuthorizeString(source, 'resource')),
+    userAgent,
+    ...extra,
+  })}`);
+}
+
+function oauthTraceMiddleware(event: string): (req: Request, res: Response, next: NextFunction) => void {
+  return (req, res, next) => {
+    oauthTrace(req, `${event}:request`);
+    res.once('finish', () => oauthTrace(req, `${event}:response`, { statusCode: res.statusCode }));
+    next();
+  };
+}
+
+function rejectIncompleteOAuthAuthorize(req: Request, res: Response, next: NextFunction): void {
+  const source = oauthAuthorizeParamSource(req);
+  if (isIncompleteOAuthAuthorizeRequest(source)) {
+    oauthTrace(req, 'authorize:incomplete');
+    res.status(400).json(incompleteOAuthAuthorizeResponseBody());
+    return;
+  }
+  oauthTrace(req, 'authorize:complete');
+  next();
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/'/g, '&#39;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function renderPassphrasePage(params: URLSearchParams): string {
+  const hiddenFields = Array.from(params.entries())
+    .filter(([key]) => key !== 'passphrase')
+    .map(([key, value]) => `<input type="hidden" name="${escapeHtmlAttribute(key)}" value="${escapeHtmlAttribute(value)}">`)
+    .join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Authorize forge</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#f6f6f3;color:#1f2328}
+.card{width:min(420px,92vw);background:#fff;border:1px solid #d8d8d0;border-radius:12px;padding:32px;box-shadow:0 12px 40px rgba(0,0,0,.08)}
+h1{font-size:20px;margin:0 0 8px}p{margin:0 0 20px;color:#60666d;line-height:1.45}
+input{width:100%;box-sizing:border-box;border:1px solid #bfc4c9;border-radius:8px;padding:12px;font-size:16px}
+button{width:100%;margin-top:14px;border:0;border-radius:8px;padding:12px;background:#1f2328;color:#fff;font-size:16px;font-weight:600}
+</style></head>
+<body><main class="card">
+<h1>Authorize forge</h1>
+<p>Enter the local MCP passphrase to let this MCP client use this workflow-scoped connector.</p>
+<form method="POST" action="/authorize">
+${hiddenFields}
+<input type="password" name="passphrase" placeholder="Passphrase" autofocus>
+<button type="submit">Authorize</button>
+</form>
+</main></body></html>`;
+}
+
+function requirePassphrase(passphrase: string): (req: Request, res: Response, next: NextFunction) => void {
+  return (req, res, next) => {
+    const provided = typeof req.body?.passphrase === 'string' ? req.body.passphrase : undefined;
+    if (provided) {
+      const a = Buffer.from(provided);
+      const b = Buffer.from(passphrase);
+      if (a.length === b.length && timingSafeEqual(a, b)) {
+        next();
+        return;
+      }
+    }
+    const source = oauthAuthorizeParamSource(req);
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(source)) {
+      if (key !== 'passphrase' && typeof value === 'string') params.set(key, value);
+    }
+    if ([...params.keys()].length === 0 && req.url.includes('?')) {
+      const fromUrl = new URLSearchParams(req.url.slice(req.url.indexOf('?')));
+      for (const [key, value] of fromUrl.entries()) if (key !== 'passphrase') params.set(key, value);
+    }
+    res.type('html').send(renderPassphrasePage(params));
+  };
+}
+
+async function getOrRegisterPublicOAuthClient(
+  provider: ReturnType<typeof createMcpOAuthProvider>,
+  clientId: string,
+  redirectUri: string | undefined,
+  req: Request,
+): Promise<OAuthClientInformationFull | undefined> {
+  const existing = await provider.clientsStore.getClient(clientId);
+  if (existing) return existing as OAuthClientInformationFull;
+  if (!redirectUri || !isSafeOAuthFallbackRedirectUri(redirectUri) || !provider.clientsStore.registerClient) return undefined;
+  oauthTrace(req, 'authorize:auto_register_public_client', {
+    redirectScheme: new URL(redirectUri).protocol,
+    redirectHost: new URL(redirectUri).hostname,
+  });
+  return provider.clientsStore.registerClient({
+    client_id: clientId,
+    client_id_issued_at: Math.floor(Date.now() / 1000),
+    client_name: 'forge OAuth fallback client',
+    redirect_uris: [redirectUri],
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+  } as unknown as Omit<OAuthClientInformationFull, 'client_id' | 'client_id_issued_at'>) as OAuthClientInformationFull;
+}
+
+function oauthAuthorizationHandler(provider: ReturnType<typeof createMcpOAuthProvider>) {
+  return async (req: Request, res: Response) => {
+    const query = req.method === 'POST' ? req.body : req.query;
+    const clientId = typeof query.client_id === 'string' ? query.client_id : '';
+    const responseType = typeof query.response_type === 'string' ? query.response_type : '';
+    const codeChallenge = typeof query.code_challenge === 'string' ? query.code_challenge : '';
+    const codeChallengeMethod = typeof query.code_challenge_method === 'string' ? query.code_challenge_method : '';
+    const state = typeof query.state === 'string' ? query.state : undefined;
+    const scope = typeof query.scope === 'string' ? query.scope : undefined;
+    let redirectUri = typeof query.redirect_uri === 'string' ? query.redirect_uri : undefined;
+    if (responseType !== 'code') {
+      res.status(400).json({ error: 'unsupported_response_type', error_description: 'Only code response type is supported' });
+      return;
+    }
+    if (!codeChallenge || codeChallengeMethod !== 'S256') {
+      res.status(400).json({ error: 'invalid_request', error_description: 'PKCE S256 is required' });
+      return;
+    }
+    const client = await getOrRegisterPublicOAuthClient(provider, clientId, redirectUri, req);
+    if (!client) {
+      res.status(400).json({ error: 'invalid_client', error_description: 'Unknown client_id' });
+      return;
+    }
+    if (!redirectUri && client.redirect_uris.length === 1) redirectUri = client.redirect_uris[0];
+    if (!redirectUri || (!isAllowedMcpOAuthRedirectUri(redirectUri) && !isRegisteredExternalHttpsRedirectUri(redirectUri, client))) {
+      res.status(400).json({ error: 'invalid_request', error_description: 'redirect_uri must be localhost, a ChatGPT connector callback URL, or a registered HTTPS client redirect_uri' });
+      return;
+    }
+    if (!isRegisteredRedirectUri(redirectUri, client)) {
+      res.status(400).json({ error: 'invalid_request', error_description: 'redirect_uri must match a registered client redirect_uri' });
+      return;
+    }
+    await provider.authorize(client as OAuthClientInformationFull, {
+      state,
+      scopes: scope ? scope.split(' ') : [],
+      redirectUri,
+      codeChallenge,
+    }, res);
+  };
+}
+
+export function registerMcpOAuthHttpRoutes(
+  app: Express,
+  provider: ReturnType<typeof createMcpOAuthProvider>,
+  passphrase: string,
+  configuredOrigin: string | undefined,
+): void {
+  app.use('/authorize', express.urlencoded({ extended: false, limit: '10kb' }));
+  app.use('/authorize', oauthTraceMiddleware('authorize'));
+  app.use('/authorize', rejectIncompleteOAuthAuthorize);
+  app.use('/authorize', requirePassphrase(passphrase));
+  app.use('/authorize', oauthAuthorizationHandler(provider));
+  app.use('/token', oauthTraceMiddleware('token'));
+  app.use('/token', tokenHandler({ provider, rateLimit: false }));
+  app.use('/revoke', oauthTraceMiddleware('revoke'));
+  app.use('/revoke', revocationHandler({ provider, rateLimit: false }));
+  app.use('/register', oauthTraceMiddleware('register'));
+  app.use('/register', clientRegistrationHandler({ clientsStore: provider.clientsStore, rateLimit: false }));
+  app.get('/.well-known/oauth-authorization-server', (req, res) => {
+    const origin = getPublicOrigin(req, configuredOrigin);
+    res.json({
+      issuer: origin,
+      authorization_endpoint: `${origin}/authorize`,
+      token_endpoint: `${origin}/token`,
+      revocation_endpoint: `${origin}/revoke`,
+      registration_endpoint: `${origin}/register`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic', 'none'],
+      scopes_supported: ['forge'],
+    });
+  });
+  app.get('/.well-known/openid-configuration', (req, res) => {
+    const origin = getPublicOrigin(req, configuredOrigin);
+    res.json({
+      issuer: origin,
+      authorization_endpoint: `${origin}/authorize`,
+      token_endpoint: `${origin}/token`,
+      registration_endpoint: `${origin}/register`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic', 'none'],
+      scopes_supported: ['forge'],
+    });
+  });
+  const protectedResourceMetadata = (resourcePath: '/mcp' | '/mcp-grok' | '/mcp-bearer') => (req: Request, res: Response): void => {
+    const origin = getPublicOrigin(req, configuredOrigin);
+    res.json({ resource: `${origin}${resourcePath}`, authorization_servers: [origin], scopes_supported: ['forge'], bearer_methods_supported: ['header'] });
+  };
+  app.get('/.well-known/oauth-protected-resource/mcp', protectedResourceMetadata('/mcp'));
+  app.get('/.well-known/oauth-protected-resource/mcp-grok', protectedResourceMetadata('/mcp-grok'));
+  app.get('/.well-known/oauth-protected-resource/mcp-bearer', protectedResourceMetadata('/mcp-bearer'));
+}

package/adapters/mcp/transports/session-registry.ts

@@ -76,6 +76,8 @@ export interface McpSessionSnapshot {
   protected: number;
   activePosts: number;
   activeStreams: number;
+  /** Time since the most recent transport activity among live MCP sessions. */
+  latestActivityAgeMs?: number;
   oldestStreamAgeMs: number;
   oldestPostAgeMs: number;
   recoveryRecommended: boolean;
@@ -445,6 +447,9 @@ export class McpSessionRegistry<
     const reserved = reservations.length;
     const protectedCount = sessions.length - evictable + reserved;
     const capacityAvailable = Math.max(0, this.maximumSessions - sessions.length - reserved);
+    const latestActivityAt = sessions.length > 0
+      ? Math.max(...sessions.map((session) => session.lastActivityAt))
+      : undefined;
     const streamOpenedAt = sessions
       .filter((session) => session.inFlightGets > 0 && session.streamOpenedAt !== undefined)
       .map((session) => session.streamOpenedAt!);
@@ -467,6 +472,7 @@ export class McpSessionRegistry<
       protected: protectedCount,
       activePosts,
       activeStreams,
+      ...(latestActivityAt !== undefined ? { latestActivityAgeMs: Math.max(0, this.now() - latestActivityAt) } : {}),
       oldestStreamAgeMs,
       oldestPostAgeMs,
       recoveryRecommended: !acceptingNewSessions && oldestPostAgeMs >= this.activePostStallMs,

package/adapters/mcp/tunnels/openai-secure-tunnel.ts

@@ -21,6 +21,14 @@ export interface OpenAiSecureTunnelRuntimeStatusPayload {
   profile_path?: string;
   runtime_state?: string;
   error?: string;
+  remote_lookup_attempted?: boolean;
+  remote_error?: string;
+  remote?: unknown;
+  control_plane_poll_health?: { state?: string; reason?: string };
+  local?: {
+    control_plane_poll_health?: { state?: string; reason?: string };
+    log?: { tail?: string };
+  };
 }
 
 export interface OpenAiSecureTunnelRuntimeObservation {
@@ -30,9 +38,13 @@ export interface OpenAiSecureTunnelRuntimeObservation {
   ready: boolean;
   tunnelMatches: boolean;
   endpointMatches: boolean;
+  controlPlaneState: 'ready' | 'degraded' | 'unknown';
+  controlPlaneDetail: string;
   alias: string;
   tunnelId: string;
   observedTunnelId?: string;
+  clientInstanceId?: string;
+  remoteLookupAttempted?: boolean;
   detail: string;
   profilePath?: string;
 }
@@ -90,6 +102,65 @@ export function openAiSecureTunnelConnectArgs(config: OpenAiSecureTunnelRuntimeC
   return args;
 }
 
+function controlPlaneEvidence(value: OpenAiSecureTunnelRuntimeStatusPayload): {
+  state: OpenAiSecureTunnelRuntimeObservation['controlPlaneState'];
+  detail: string;
+  clientInstanceId?: string;
+} {
+  let clientInstanceId: string | undefined;
+  let latestControlPlane: { level?: string; msg?: string; error?: string } | undefined;
+  const tail = value.local?.log?.tail;
+  if (typeof tail === 'string') {
+    for (const line of tail.trim().split('\n').reverse()) {
+      try {
+        const event = JSON.parse(line) as Record<string, unknown>;
+        if (!clientInstanceId && typeof event.client_instance_id === 'string') clientInstanceId = event.client_instance_id;
+        if (!latestControlPlane && event.component === 'controlplane') {
+          latestControlPlane = {
+            level: typeof event.level === 'string' ? event.level : undefined,
+            msg: typeof event.msg === 'string' ? event.msg : undefined,
+            error: typeof event.error === 'string' ? event.error : undefined,
+          };
+        }
+        if (clientInstanceId && latestControlPlane) break;
+      } catch { /* bounded diagnostic tail may contain non-JSON lines */ }
+    }
+  }
+
+  const remoteError = typeof value.remote_error === 'string' ? value.remote_error.trim() : '';
+  if (value.remote_lookup_attempted === true) {
+    if (remoteError) return { state: 'degraded', detail: `remote lookup failed: ${remoteError}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+    if (value.remote && typeof value.remote === 'object') {
+      return { state: 'ready', detail: 'remote tunnel lookup succeeded', ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+  }
+
+  const pollHealth = value.control_plane_poll_health ?? value.local?.control_plane_poll_health;
+  const pollState = pollHealth?.state?.trim().toLowerCase();
+  if (pollState === 'ready' || pollState === 'healthy') {
+    return { state: 'ready', detail: pollHealth?.reason?.trim() || `control-plane poll state is ${pollState}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+  }
+  if (pollState === 'degraded' || pollState === 'error' || pollState === 'failed') {
+    return { state: 'degraded', detail: pollHealth?.reason?.trim() || `control-plane poll state is ${pollState}`, ...(clientInstanceId ? { clientInstanceId } : {}) };
+  }
+
+  if (latestControlPlane) {
+    const message = [latestControlPlane.msg, latestControlPlane.error].filter(Boolean).join(': ');
+    if (/poller recovered|polling operational/i.test(message)) {
+      return { state: 'ready', detail: message, ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+    if (latestControlPlane.level === 'WARN' || latestControlPlane.level === 'ERROR' || /timed out|timeout|deadline|reset by peer|lookup .*i\/o timeout|context canceled/i.test(message)) {
+      return { state: 'degraded', detail: message || 'latest control-plane event is degraded', ...(clientInstanceId ? { clientInstanceId } : {}) };
+    }
+  }
+
+  return {
+    state: 'unknown',
+    detail: pollHealth?.reason?.trim() || 'remote control-plane reachability was not established',
+    ...(clientInstanceId ? { clientInstanceId } : {}),
+  };
+}
+
 export function parseOpenAiSecureTunnelRuntimeStatus(
   stdout: string,
   expected: Pick<OpenAiSecureTunnelRuntimeConfig, 'alias' | 'tunnelId' | 'mcpServerUrl'>,
@@ -105,6 +176,8 @@ export function parseOpenAiSecureTunnelRuntimeStatus(
       ready: false,
       tunnelMatches: false,
       endpointMatches: false,
+      controlPlaneState: 'unknown',
+      controlPlaneDetail: 'status payload was not valid JSON',
       alias: expected.alias,
       tunnelId: expected.tunnelId,
       detail: 'OpenAI tunnel runtime status was not valid JSON',
@@ -115,14 +188,21 @@ export function parseOpenAiSecureTunnelRuntimeStatus(
   const ready = value.ready === true;
   const tunnelMatches = value.tunnel_id === expected.tunnelId;
   const endpointMatches = tunnelRuntimeProfileTargetsEndpoint(value.profile_path, expected.mcpServerUrl);
-  const ok = running && healthy && ready && tunnelMatches && endpointMatches;
+  const controlPlane = controlPlaneEvidence(value);
+  // `process_running` only describes runtimes that tunnel-client supervises
+  // itself. An externally owned service manager (launchd/systemd) reports the
+  // runtime as not running while the tunnel is healthy, reachable, and bound to
+  // the expected identity. Health, readiness, tunnel id, and endpoint binding are
+  // the transport facts; process registry state is diagnostic only.
+  const localReady = healthy && ready && tunnelMatches && endpointMatches;
+  const ok = localReady && controlPlane.state === 'ready';
   const mismatches: string[] = [];
   if (!tunnelMatches && value.tunnel_id) mismatches.push(`tunnel id mismatch (${value.tunnel_id})`);
   if (!endpointMatches && value.profile_path) mismatches.push('runtime profile targets a different MCP endpoint');
-  if (!running) mismatches.push(`runtime is ${value.runtime_state ?? 'not running'}`);
-  if (running && !healthy) mismatches.push('runtime is not healthy');
-  if (running && !ready) mismatches.push('runtime is not ready');
+  if (!healthy) mismatches.push(`runtime is ${value.runtime_state ?? 'not running'}`);
+  if (healthy && !ready) mismatches.push('runtime is not ready');
   if (value.error) mismatches.push(value.error);
+  if (controlPlane.state !== 'ready') mismatches.push(`control plane ${controlPlane.state}: ${controlPlane.detail}`);
   return {
     ok,
     running,
@@ -130,10 +210,14 @@ export function parseOpenAiSecureTunnelRuntimeStatus(
     ready,
     tunnelMatches,
     endpointMatches,
+    controlPlaneState: controlPlane.state,
+    controlPlaneDetail: controlPlane.detail,
     alias: expected.alias,
     tunnelId: expected.tunnelId,
     ...(value.tunnel_id ? { observedTunnelId: value.tunnel_id } : {}),
-    detail: ok ? `managed runtime ${expected.alias} is ready for ${expected.tunnelId}` : (mismatches.join('; ') || 'OpenAI tunnel runtime is not ready'),
+    ...(controlPlane.clientInstanceId ? { clientInstanceId: controlPlane.clientInstanceId } : {}),
+    ...(value.remote_lookup_attempted === undefined ? {} : { remoteLookupAttempted: value.remote_lookup_attempted }),
+    detail: ok ? `managed runtime ${expected.alias} is locally ready and its OpenAI control plane is reachable for ${expected.tunnelId}` : (mismatches.join('; ') || 'OpenAI tunnel runtime is not ready'),
     ...(value.profile_path ? { profilePath: value.profile_path } : {}),
   };
 }

package/adapters/mcp/types.ts

@@ -1,12 +1,6 @@
 export type McpProfileName = 'planner' | 'executor' | 'orchestrator' | 'controller';
 export type McpPathIntent = 'read' | 'write';
 export type McpAgentRunnerName = 'codex' | 'claude';
-/** Controller MCP tools/list exposure profile.
- * - facade: explicit five-tool ChatGPT orchestration surface
- * - core/advanced (default compatibility labels): bounded stable controller surface
- * - full: compatibility mode — all legacy + runtime tools
- */
-export type McpToolset = 'facade' | 'core' | 'advanced' | 'full';
 
 export interface McpPolicy {
   profile: McpProfileName;

package/assets/hooks/lib/session-state.sh

@@ -69,41 +69,3 @@ session_state_read_count() {
 
   printf '%s' "$count"
 }
-
-session_state_codegraph_dir() {
-  printf '%s' ".claude/.codegraph-state"
-}
-
-session_state_codegraph_marker_file() {
-  local key="$1"
-  local suffix="$2"
-  local safe_key
-  safe_key="$(session_state_safe_key "$key")"
-  printf '%s/%s.%s' "$(session_state_codegraph_dir)" "$safe_key" "$suffix"
-}
-
-session_state_mark_codegraph_used() {
-  local key="$1"
-  local marker
-  marker="$(session_state_codegraph_marker_file "$key" "used")"
-  mkdir -p "$(dirname "$marker")"
-  : > "$marker"
-}
-
-session_state_codegraph_used() {
-  local key="$1"
-  [[ -f "$(session_state_codegraph_marker_file "$key" "used")" ]]
-}
-
-session_state_mark_codegraph_nudged() {
-  local key="$1"
-  local marker
-  marker="$(session_state_codegraph_marker_file "$key" "nudged")"
-  mkdir -p "$(dirname "$marker")"
-  : > "$marker"
-}
-
-session_state_codegraph_nudged() {
-  local key="$1"
-  [[ -f "$(session_state_codegraph_marker_file "$key" "nudged")" ]]
-}

package/assets/hooks/post-bash.sh

@@ -121,7 +121,7 @@ broad_command=false
 recommended_next_tool=""
 if post_bash_broad_command "$COMMAND_TEXT"; then
   broad_command=true
-  recommended_next_tool="codegraph_context"
+  recommended_next_tool="rh_context"
 fi
 output_line_count="$(post_bash_output_line_count "$TOOL_OUTPUT")"
 raw_output_bytes="$(post_bash_output_byte_count "$TOOL_OUTPUT")"

package/assets/hooks/post-tool-observer.sh

@@ -41,11 +41,6 @@ duration_ms="${duration_ms:-0}"
 run_id="${run_id:-unknown}"
 session_source="${session_source:-unknown}"
 
-case "$tool_name" in
-  mcp__codegraph__*|codegraph_*)
-    session_state_mark_codegraph_used "$SESSION_KEY" || true
-    ;;
-esac
 
 # An event source is explicit evidence. Inherited host variables are only a
 # fallback for payloads that omit it, such as local compatibility shims.

package/assets/hooks/prompt-guard.sh

@@ -566,59 +566,6 @@ emit_agentic_packaging_hint() {
   fi
 }
 
-resolve_codegraph_bin() {
-  local common_git_dir canonical_root candidate
-  if [[ -x "node_modules/.bin/codegraph" ]]; then
-    printf '%s\n' "node_modules/.bin/codegraph"
-    return 0
-  fi
-
-  # Linked worktrees normally reuse the canonical checkout's dependency tree.
-  # Resolve it before falling back to a user-global CodeGraph installation.
-  common_git_dir="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
-  if [[ -n "$common_git_dir" ]]; then
-    canonical_root="$(dirname "$common_git_dir")"
-    candidate="$canonical_root/node_modules/.bin/codegraph"
-    if [[ -x "$candidate" ]]; then
-      printf '%s\n' "$candidate"
-      return 0
-    fi
-  fi
-
-  command -v codegraph 2>/dev/null || return 1
-}
-
-run_codegraph_init_command() {
-  local codegraph_bin status cursor_dir_existed cursor_rules_dir_existed cursor_rule_existed
-  codegraph_bin="$(resolve_codegraph_bin)" || return 127
-
-  cursor_dir_existed=false
-  cursor_rules_dir_existed=false
-  cursor_rule_existed=false
-  [[ -d ".cursor" ]] && cursor_dir_existed=true
-  [[ -d ".cursor/rules" ]] && cursor_rules_dir_existed=true
-  [[ -e ".cursor/rules/codegraph.mdc" ]] && cursor_rule_existed=true
-
-  set +e
-  CODEGRAPH_NO_DAEMON=1 "$codegraph_bin" init -i .
-  status=$?
-  set -e
-
-  if [[ "$cursor_rule_existed" == "false" && -f ".cursor/rules/codegraph.mdc" ]]; then
-    rm -f ".cursor/rules/codegraph.mdc"
-    [[ "$cursor_rules_dir_existed" == "false" ]] && rmdir ".cursor/rules" 2>/dev/null || true
-    [[ "$cursor_dir_existed" == "false" ]] && rmdir ".cursor" 2>/dev/null || true
-  fi
-
-  return "$status"
-}
-
-emit_codegraph_route_hint() {
-  if pg_fact CODEGRAPH_ROUTE || pg_fact NONTRIVIAL_CODE_TASK; then
-    echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer Forge rh_context/semantic navigation or an already-configured structural provider; do not initialize repo-local .codegraph state from a prompt hook."
-  fi
-}
-
 modern_controller_home_workflow() {
   [[ -f "forge.config.json" ]]
 }
@@ -839,7 +786,6 @@ prompt_guard_engine_call
 if modern_controller_home_workflow; then
   emit_agentic_packaging_hint
   emit_forge_route_hint
-  emit_codegraph_route_hint
   emit_modern_controller_home_guidance
   exit 0
 fi
@@ -858,7 +804,6 @@ fi
 
 emit_agentic_packaging_hint
 emit_forge_route_hint
-emit_codegraph_route_hint
 emit_pending_orchestration_discussion
 
 implement_intent=0

package/assets/partials/04-project-structure.partial.md

@@ -50,7 +50,7 @@
 - Route knowledge sync and handoff retrieval to `gbrain`.
 - Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `.ai/harness/scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `mermaid` from `~/.codex/skills`.
-- CodeGraph is required agent readiness for code navigation; keep `.codegraph/` ignored and use it for P1/P2 discovery, not hook correctness.
+- Code navigation uses bounded ripgrep discovery and explicit language-service symbol navigation; no graph index is required.
 - Treat third-party host skills as optional. Their installation state must not change Forge workflow correctness.
 - Use `docs/reference-configs/agentic-development-flow.md` for routing details and `docs/reference-configs/external-tooling.md` plus `bash .ai/harness/scripts/check-agent-tooling.sh --host both --check-updates` for environment checks.
 - If repo state conflicts with the task, use an isolated `codex/<task-slug>` worktree, validate with Forge `/review`, and merge back to `main` without unrelated dirty changes.

package/assets/partials/07-footer.partial.md

@@ -35,4 +35,4 @@ CLAUDE.md is a routing card. Keep context minimal and load only what the current
 ---
 
 *Template Version: {{TEMPLATE_VERSION}}*
-*Generated by forge@{{SKILL_VERSION}}*
+*Generated by forge@{{FORGE_VERSION}}*