@moretea-labs/forge 1.8.0 → 1.8.1

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/assets/plugin-registry.v1.json

@@ -4,12 +4,12 @@
     {
       "id": "desktop_operator",
       "name": "Forge Desktop Operator",
-      "version": "0.3.2",
+      "version": "0.4.5",
       "description": "Native macOS desktop automation provider for Forge.",
       "repository": "https://github.com/moretea-labs/forge-desktop-operator.git",
-      "ref": "v0.3.2",
+      "ref": "v0.4.5",
       "installer": "forge-plugin-install.mjs",
-      "providerVersion": "0.3.2",
+      "providerVersion": "0.4.5",
       "protocolVersion": "1.0",
       "platforms": [
         "darwin"
@@ -17,8 +17,10 @@
       "semanticCapabilities": [
         "computer.observe.v1",
         "computer.input.v1",
+        "computer.console.unlock.v1",
         "computer.capture.v1",
-        "computer.browser_automation.v1"
+        "computer.element.observe.v2",
+        "computer.element.action.v2"
       ]
     },
     {

package/assets/reference-configs/agentic-development-flow.md

@@ -16,6 +16,31 @@ Forge owns the workflow contract. External host skills may improve reasoning qua
 
 Missing external skills must degrade only the named enhancement. Hooks may suggest Forge modes, but must not route correctness through a third-party skill.
 
+## Architecture Migration Delivery Transaction
+
+### Current-Task Lineage Fence
+
+Every controller round has one semantic task lineage. Resolve it from the user's current objective and the exact Work/Requirement/Plan relation before consulting repository-wide status. Global active Work is conflict metadata, not a work queue.
+
+The controller may inspect unrelated active Work only to answer four bounded questions: does it own an overlapping write path, does it hold an authority/resource needed by the current lineage, does it create a merge/release admission blocker, or does it prove the current lineage was superseded by an explicit typed transition? If none apply, the unrelated Work is ignored for the rest of the round.
+
+Never pivot into another Work's implementation, verification, review, release, cleanup, or progress accounting without explicit user intent or an explicit typed lineage transition. This prevents autonomous continuation from turning repository activity into accidental scope expansion.
+
+For Kernel/V2 migrations and similarly cross-cutting work, the primary unit of execution is a coherent delivery slice, not an issue, file, failing check, or incidental symptom.
+
+1. **Batch discovery**: gather the relevant architecture, ownership, runtime, persistence, and evidence facts in one bounded pass.
+2. **Root-cause decision**: identify the owning invariant/module and decide whether new observations are same-root scope or an independent delivery boundary.
+3. **Freeze the slice**: establish one candidate scope and acceptance contract. Same-root discoveries extend this candidate; they do not create sibling Works by default.
+4. **Coherent implementation**: implement the whole slice before broad validation. Use edit-session/savepoint state rather than per-file Git commits.
+5. **Whole-candidate review**: review authority, dependency, migration, lifecycle, recovery, and diff coherence once the implementation is source-complete.
+6. **Validation wave**: run focused behavior checks first, then canonical gates once. After repair, rerun only affected checks unless evidence invalidates the architecture.
+7. **Delivery boundary**: commit/merge once for the coherent candidate, then perform Candidate/canary/release once. Release must not begin while same-delivery source-changing Works remain active.
+8. **Terminal cleanup**: retire superseded Work/Plan/check/release state so the Controller's active inventory represents only real remaining work.
+
+Do not turn concrete incidents into an issue-by-issue patch campaign. Cluster symptoms by architecture owner and invariant before implementation. One-file commits are acceptable only when that file is itself the complete coherent delivery; file count is not the boundary.
+
+If execution exposes a defect in Forge lifecycle machinery, decide whether it is required for the current version to converge safely. If not, record a bounded post-version Plan with the violated invariant, evidence, intended owner, and acceptance criteria, then continue the current release without implementing that machinery refactor.
+
 ## Public CLI Boundary
 
 The user-facing CLI is intentionally smaller than the implementation surface:

package/assets/reference-configs/global-working-rules.md

@@ -9,6 +9,25 @@ Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` a
 - Act as an engineering collaborator: finish the concrete task, verify it, then report conclusion, actual change, reason, verification, and residual risk.
 - Prefer direct execution over repeated confirmation. Stop to ask only when continuing would likely produce output contrary to the user's intent.
 
+## Delivery Transaction Discipline
+
+### Current Task Lineage Isolation
+
+- Select the current task from explicit user intent plus the exact Work/Requirement/Plan lineage. Never treat repository-wide active Work as the current task queue.
+- Global status/inventory exists for conflict, ownership, blocker, and release-admission checks only. Unrelated active Work must not trigger discovery, edits, validation, review, release, cleanup, or progress accounting in the current controller round.
+- Switch tasks only on explicit user intent or an explicit typed lineage transition. Similar files, shared broad Requirements, urgency, or mere visibility in status are not lineage.
+- Report current-task progress from the current lineage only; label unrelated repository activity separately if it materially blocks the task.
+
+For architecture migrations, self-hosting work, and other multi-file system changes, optimize for one bounded delivery transaction instead of repeated micro-lifecycles.
+
+- Batch facts first, decide the root cause/owner once, freeze the delivery scope, implement the coherent candidate, review the whole diff, run one focused validation wave, run canonical gates once, then deliver and clean up.
+- A newly observed symptom or affected file does not justify a new Work. Extend the current candidate when the same architecture invariant/root cause still owns the change; create a sibling Work only for a genuinely independent authority, security boundary, delivery, or architecture decision.
+- Do not use Git commits as scratch savepoints. Prefer Work/edit-session/savepoint state during implementation and one coherent candidate commit at the delivery boundary.
+- Do not repeatedly run baseline checks, broad suites, Candidate builds, canaries, or Runtime activation while source-changing work for the same delivery remains active. Release begins only after the source candidate is frozen.
+- After a check failure, repair the same candidate and rerun the affected check set unless the evidence invalidates the architecture; do not restart the whole lifecycle by default.
+- Retire superseded/covered Work and Plan state promptly. Active lifecycle records must describe real remaining work, not historical debris.
+- When the workflow machinery itself has a design problem, capture a bounded follow-up Plan. If the current version can still converge safely, defer that machinery refactor until after the release instead of expanding the release scope.
+
 ## Progressive Due Diligence
 
 For non-trivial engineering work, do P1/P2/P3 before design decisions or code edits.

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.8.0",
-  "templateVersion": "1.8.0",
+  "version": "1.8.1",
+  "templateVersion": "1.8.1",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {