@moretea-labs/forge 1.7.2 → 1.8.0

package/src/cli/commands/recovery.ts

@@ -1,9 +1,22 @@
 import { createHash, randomBytes } from 'crypto';
+import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
-import { isAbsolute, resolve } from 'path';
+import { hostname } from 'os';
+import { isAbsolute, join, resolve } from 'path';
 import { Command } from 'commander';
-import { readMcpServiceOAuthPassphrase } from '../mcp/auth';
-import { resolveControllerHome } from '../repositories/controller-home';
+import { readMcpServiceOAuthPassphrase } from '../../../adapters/mcp/auth';
+import {
+  openAiSecureTunnelConnectArgs,
+  openAiSecureTunnelStatusArgs,
+  parseOpenAiSecureTunnelRuntimeStatus,
+  type OpenAiSecureTunnelRuntimeObservation,
+} from '../../../adapters/mcp/tunnels/openai-secure-tunnel';
+import { findRegisteredRepositoryByCheckoutRoot } from '../repositories/registry';
+import {
+  resolveControllerHome,
+  rollbackStoppedControllerHomeAuthorityRelocation,
+  type StoppedControllerHomeAuthorityRelocation,
+} from '../repositories/controller-home';
 import { FORGE_VERSION } from '../../version';
 import {
   RECOVERY_GATEWAY_LABEL,
@@ -16,11 +29,16 @@ import {
 } from '../../runtime/standalone-recovery/installer';
 import {
   RECOVERY_TOOLS,
+  RECOVERY_VERIFIER_OAUTH_CLIENT_ID,
+  RECOVERY_VERIFIER_OAUTH_CLIENT_NAME,
+  RECOVERY_VERIFIER_OAUTH_REDIRECT_URI,
 } from '../../runtime/standalone-recovery/entry';
 import {
   activateRuntimeRelease,
+  defaultPrimaryRuntimeServiceConfig,
   loadRecoveryConfig,
   recoverPrimaryRuntime,
+  recoveryMachineIdentity,
   restartPrimaryConnector,
   restartPrimaryRuntime,
   restartRecoveryGateway,
@@ -28,12 +46,25 @@ import {
   rollbackPrevious,
   runtimeStatus,
   verifyStableRuntime,
+  type OpenAiSecureTunnelServiceConfig,
   type PrimaryConnectorServiceConfig,
+  type RecoveryMachineIdentity,
   type PublicTunnelServiceConfig,
+  type RecoveryTunnelServiceConfig,
+  type SystemdUserRecoveryTunnelServiceConfig,
 } from '../../runtime/standalone-recovery/core';
 import { readRecoveryRuntimeIdentity } from '../../runtime/standalone-recovery/release';
+import {
+  assertRecoveryControllerHomeMigrationReady,
+  recoveryControllerHomeMigrationPreflight,
+  runLinuxControllerHomeMigrationRequest,
+  scheduleLinuxControllerHomeMigration,
+  type RecoveryControllerHomeMigrationPreflight,
+} from '../../runtime/standalone-recovery/controller-home-migration';
 import { configureCodegraph, ensureCodegraph } from '../tools/codegraph';
 import { isProcessAlive } from '../../runtime/shared/process-tree';
+import { systemdUserServicePid, systemdUserUnitName, systemdUserUnitPath } from '../controller/systemd-user';
+import { installWindowsHostRecoveryPlugin } from '../../runtime/plugins/windows-host-recovery-install';
 
 function output(value: unknown, json = true): void {
   console.log(json ? JSON.stringify(value, null, 2) : String(value));
@@ -55,15 +86,80 @@ function launchdService(label?: string, plistPath?: string, role = 'RECOVERY_TUN
   return { platform: 'launchd', label, ...(plistPath ? { plistPath } : {}) };
 }
 
+function systemdRecoveryTunnelService(unitName?: string): SystemdUserRecoveryTunnelServiceConfig | undefined {
+  if (!unitName) return undefined;
+  const normalized = systemdUserUnitName(unitName);
+  if (!/^[A-Za-z0-9_.@-]{1,180}\.service$/.test(normalized)) throw new Error('RECOVERY_TUNNEL_SYSTEMD_UNIT_INVALID');
+  return { platform: 'systemd-user', unitName: normalized };
+}
+
+export function recoveryOpenAiTunnelDefaultAlias(
+  controllerHome: string,
+  platform: NodeJS.Platform = process.platform,
+  host = hostname(),
+): string {
+  const suffix = createHash('sha256').update(`${host}\0${platform}\0${resolve(controllerHome)}`).digest('hex').slice(0, 12);
+  return `forge-recovery-${suffix}`;
+}
+
+export function assertDistinctRecoveryOpenAiTunnelIdentity(
+  recovery: RecoveryTunnelServiceConfig | undefined,
+  primary: PublicTunnelServiceConfig | undefined,
+): void {
+  if (recovery?.platform !== 'openai-secure-tunnel' || primary?.platform !== 'openai-secure-tunnel') return;
+  if (recovery.alias === primary.alias) throw new Error('RECOVERY_OPENAI_TUNNEL_ALIAS_CONFLICT');
+  if (recovery.tunnelId === primary.tunnelId) throw new Error('RECOVERY_OPENAI_TUNNEL_ID_CONFLICT');
+}
+
+function openAiTunnelService(input: {
+  tunnelId?: string;
+  alias?: string;
+  runtimeApiKeyRef?: string;
+  profile?: string;
+  profileDir?: string;
+  adminProfile?: string;
+  mcpServerUrl: string;
+  defaultAlias: string;
+  role: string;
+}): OpenAiSecureTunnelServiceConfig | undefined {
+  const supplied = Boolean(input.tunnelId || input.alias || input.runtimeApiKeyRef || input.profile || input.profileDir || input.adminProfile);
+  if (!supplied) return undefined;
+  if (!input.tunnelId) throw new Error(`${input.role}_OPENAI_TUNNEL_ID_REQUIRED`);
+  if (input.profileDir && !isAbsolute(input.profileDir)) throw new Error(`${input.role}_OPENAI_PROFILE_DIR_ABSOLUTE_REQUIRED`);
+  const service: OpenAiSecureTunnelServiceConfig = {
+    platform: 'openai-secure-tunnel',
+    alias: input.alias?.trim() || input.defaultAlias,
+    tunnelId: input.tunnelId.trim(),
+    mcpServerUrl: input.mcpServerUrl,
+    runtimeApiKeyRef: input.runtimeApiKeyRef?.trim(),
+    profile: input.profile?.trim(),
+    profileDir: input.profileDir ? resolve(input.profileDir) : undefined,
+    adminProfile: input.adminProfile?.trim(),
+  };
+  try { openAiSecureTunnelConnectArgs(service); } catch (error) {
+    throw new Error(`${input.role}_${error instanceof Error ? error.message : 'OPENAI_TUNNEL_CONFIG_INVALID'}`);
+  }
+  return service;
+}
+
+
+export { recoveryControllerHomeMigrationPreflight };
+export type { RecoveryControllerHomeMigrationPreflight };
+
 export interface RecoveryConnectorDependencies {
+  platform?: NodeJS.Platform;
   pathExists?: (path: string) => boolean;
   launchdPid?: (role: 'gateway' | 'watchdog') => number | undefined;
+  systemdPid?: (role: 'gateway' | 'watchdog') => number | undefined;
   tunnelLaunchdPid?: (label: string) => number | undefined;
+  tunnelSystemdPid?: (unitName: string) => number | undefined;
+  openAiTunnelStatus?: (service: OpenAiSecureTunnelServiceConfig) => OpenAiSecureTunnelRuntimeObservation;
   processAlive?: (pid: number) => boolean;
 }
 
 export interface RecoveryConnectorDescriptor {
   name: 'Forge Recovery';
+  identity: RecoveryMachineIdentity;
   transport: 'streamable_http';
   url: string;
   public: boolean;
@@ -78,9 +174,23 @@ export interface RecoveryConnectorDescriptor {
   };
   healthUrl: string;
   services: {
-    gateway: { label: string; plistInstalled: boolean; running: boolean; pid?: number };
-    watchdog: { label: string; plistInstalled: boolean; running: boolean; pid?: number };
-    tunnel: { configured: boolean; label?: string; plistInstalled: boolean; restartSafe: boolean; running: boolean; pid?: number };
+    gateway: { label: string; platform: 'launchd' | 'systemd-user'; serviceInstalled: boolean; plistInstalled: boolean; running: boolean; pid?: number };
+    watchdog: { label: string; platform: 'launchd' | 'systemd-user'; serviceInstalled: boolean; plistInstalled: boolean; running: boolean; pid?: number };
+    tunnel: {
+      configured: boolean;
+      platform?: 'launchd' | 'systemd-user' | 'openai-secure-tunnel';
+      label?: string;
+      unitName?: string;
+      alias?: string;
+      tunnelId?: string;
+      serviceInstalled?: boolean;
+      plistInstalled: boolean;
+      restartSafe: boolean;
+      running: boolean;
+      healthy?: boolean;
+      ready?: boolean;
+      pid?: number;
+    };
   };
   tools: string[];
   warnings: string[];
@@ -100,25 +210,66 @@ export function recoveryConnectorDescriptor(
   const passphraseConfigured = Boolean(readMcpServiceOAuthPassphrase(home));
   const gatewayIdentity = readRecoveryRuntimeIdentity(home, 'gateway');
   const watchdogIdentity = readRecoveryRuntimeIdentity(home, 'watchdog');
+  const platform = dependencies.platform ?? process.platform;
+  const servicePlatform: 'launchd' | 'systemd-user' = platform === 'linux' ? 'systemd-user' : 'launchd';
   const pathExists = dependencies.pathExists ?? existsSync;
   const launchdPid = dependencies.launchdPid ?? recoveryLaunchdPid;
+  const systemdPid = dependencies.systemdPid ?? ((role: 'gateway' | 'watchdog') => systemdUserServicePid(role === 'gateway' ? RECOVERY_GATEWAY_LABEL : RECOVERY_WATCHDOG_LABEL));
+  const managedPid = (role: 'gateway' | 'watchdog') => servicePlatform === 'systemd-user' ? systemdPid(role) : launchdPid(role);
   const processAlive = dependencies.processAlive ?? isProcessAlive;
-  const tunnelService = config.recoveryTunnelService?.platform === 'launchd' ? config.recoveryTunnelService : undefined;
+  const configuredTunnel = config.recoveryTunnelService;
+  const tunnelService = configuredTunnel?.platform === 'launchd' ? configuredTunnel : undefined;
+  const systemdTunnelService = configuredTunnel?.platform === 'systemd-user' ? configuredTunnel : undefined;
+  const openAiTunnelService = configuredTunnel?.platform === 'openai-secure-tunnel' ? configuredTunnel : undefined;
   const tunnelContract = tunnelService ? inspectRecoveryTunnelLaunchdContract(tunnelService) : undefined;
   const tunnelLaunchdPid = tunnelService
     ? (dependencies.tunnelLaunchdPid ?? recoveryLaunchdServicePid)(tunnelService.label)
     : undefined;
   const tunnelPlistInstalled = Boolean(tunnelContract?.plistPath && pathExists(tunnelContract.plistPath));
-  const tunnelRestartSafe = Boolean(tunnelContract?.restartSafe);
-  const tunnelRunning = Boolean(tunnelLaunchdPid && processAlive(tunnelLaunchdPid));
+  const systemdTunnelUnitName = systemdTunnelService?.unitName.trim();
+  const systemdTunnelIdentityValid = Boolean(systemdTunnelUnitName && /^[A-Za-z0-9_.@-]{1,180}\.service$/.test(systemdTunnelUnitName));
+  const systemdTunnelInstalled = Boolean(systemdTunnelIdentityValid && pathExists(systemdUserUnitPath(systemdTunnelUnitName!)));
+  const systemdTunnelPid = systemdTunnelIdentityValid
+    ? (dependencies.tunnelSystemdPid ?? ((unitName: string) => systemdUserServicePid(unitName)))(systemdTunnelUnitName!)
+    : undefined;
+  const openAiTunnelStatus = openAiTunnelService
+    ? (dependencies.openAiTunnelStatus ?? ((service: OpenAiSecureTunnelServiceConfig) => {
+        const status = spawnSync('tunnel-client', openAiSecureTunnelStatusArgs(service.alias, service), {
+          encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000,
+        });
+        return parseOpenAiSecureTunnelRuntimeStatus(status.stdout || '{}', { alias: service.alias, tunnelId: service.tunnelId, mcpServerUrl: service.mcpServerUrl });
+      }))(openAiTunnelService)
+    : undefined;
+  let openAiRestartSafe = false;
+  if (openAiTunnelService) {
+    try { openAiSecureTunnelConnectArgs(openAiTunnelService); openAiRestartSafe = true; } catch { openAiRestartSafe = false; }
+  }
+  const tunnelRestartSafe = openAiTunnelService
+    ? openAiRestartSafe
+    : systemdTunnelService
+      ? systemdTunnelIdentityValid && systemdTunnelInstalled
+      : Boolean(tunnelContract?.restartSafe);
+  const tunnelRunning = openAiTunnelService
+    ? openAiTunnelStatus?.running === true
+    : systemdTunnelService
+      ? Boolean(systemdTunnelPid && processAlive(systemdTunnelPid))
+      : Boolean(tunnelLaunchdPid && processAlive(tunnelLaunchdPid));
+  const tunnelHealthy = openAiTunnelService ? openAiTunnelStatus?.healthy === true : tunnelRunning;
+  const tunnelReady = openAiTunnelService ? openAiTunnelStatus?.ok === true : tunnelRestartSafe && tunnelRunning;
   const gatewayPlistInstalled = pathExists(authority.gatewayLaunchAgent);
   const watchdogPlistInstalled = pathExists(authority.watchdogLaunchAgent);
-  const gatewayLaunchdPid = launchdPid('gateway');
-  const watchdogLaunchdPid = launchdPid('watchdog');
+  const gatewayServiceInstalled = servicePlatform === 'systemd-user'
+    ? pathExists(systemdUserUnitPath(RECOVERY_GATEWAY_LABEL))
+    : gatewayPlistInstalled;
+  const watchdogServiceInstalled = servicePlatform === 'systemd-user'
+    ? pathExists(systemdUserUnitPath(RECOVERY_WATCHDOG_LABEL))
+    : watchdogPlistInstalled;
+  const gatewayManagedPid = managedPid('gateway');
+  const watchdogManagedPid = managedPid('watchdog');
   const gatewayRunning = Boolean(
     gatewayIdentity
-    && gatewayLaunchdPid
-    && gatewayIdentity.pid === gatewayLaunchdPid
+    && gatewayManagedPid
+    && gatewayIdentity.pid === gatewayManagedPid
     && processAlive(gatewayIdentity.pid)
     && authority.current
     && gatewayIdentity.releaseRevision === authority.current.releaseRevision
@@ -126,33 +277,40 @@ export function recoveryConnectorDescriptor(
   );
   const watchdogRunning = Boolean(
     watchdogIdentity
-    && watchdogLaunchdPid
-    && watchdogIdentity.pid === watchdogLaunchdPid
+    && watchdogManagedPid
+    && watchdogIdentity.pid === watchdogManagedPid
     && processAlive(watchdogIdentity.pid)
     && authority.current
     && watchdogIdentity.releaseRevision === authority.current.releaseRevision
     && watchdogIdentity.manifestSha256 === authority.current.manifestSha256,
   );
-  const installed = Boolean(authority.current && gatewayPlistInstalled && watchdogPlistInstalled);
+  const installed = Boolean(authority.current && gatewayServiceInstalled && watchdogServiceInstalled);
   const publicEndpoint = Boolean(configuredUrl?.startsWith('https://'));
   const warnings: string[] = [];
   if (!authority.current) warnings.push('No current immutable Forge Recovery release is installed. Run forge recovery install.');
-  if (!gatewayPlistInstalled || !watchdogPlistInstalled) warnings.push('Forge Recovery launchd services are not fully installed. Run forge recovery install.');
+  if (!gatewayServiceInstalled || !watchdogServiceInstalled) warnings.push(`Forge Recovery ${servicePlatform} services are not fully installed. Run forge recovery install.`);
   if (!gatewayRunning || !watchdogRunning) warnings.push('Forge Recovery Gateway or Watchdog is not running on the current Recovery release.');
-  if (!configuredUrl) warnings.push('Recovery is loopback-only. Configure --recovery-public-url and a dedicated tunnel service before adding it to ChatGPT.');
-  else if (!publicEndpoint) warnings.push('ChatGPT Recovery Connector requires an HTTPS public endpoint.');
-  else if (!tunnelService) warnings.push('A dedicated Forge Recovery tunnel service is not configured.');
-  else if (!tunnelPlistInstalled) warnings.push('The dedicated Forge Recovery tunnel plist is not installed.');
-  else if (!tunnelRestartSafe) warnings.push('The dedicated Forge Recovery tunnel plist must use RunAtLoad=true and unconditional KeepAlive=true.');
-  else if (!tunnelRunning) warnings.push('The dedicated Forge Recovery tunnel service is not running.');
+  if (!configuredTunnel) warnings.push('Recovery is loopback-only. Configure a dedicated OpenAI Secure MCP Tunnel or an HTTPS tunnel service before adding it to ChatGPT.');
+  else if (openAiTunnelService) {
+    if (!tunnelRestartSafe) warnings.push('The dedicated OpenAI Recovery tunnel must use a valid alias, tunnel id, loopback MCP endpoint, and env:/file: runtime API key reference.');
+    else if (!tunnelRunning) warnings.push(`The dedicated OpenAI Recovery tunnel runtime ${openAiTunnelService.alias} is not running.`);
+    else if (!tunnelHealthy || !tunnelReady) warnings.push(`The dedicated OpenAI Recovery tunnel runtime ${openAiTunnelService.alias} is not healthy and ready.`);
+  } else if (!configuredUrl) warnings.push('The configured Recovery tunnel requires --recovery-public-url.');
+  else if (!publicEndpoint) warnings.push('ChatGPT Recovery Connector requires an HTTPS public endpoint for managed public tunnels.');
+  else if (systemdTunnelService && !systemdTunnelInstalled) warnings.push(`The dedicated Forge Recovery systemd-user tunnel unit ${systemdTunnelUnitName ?? systemdTunnelService.unitName} is not installed.`);
+  else if (systemdTunnelService && !tunnelRunning) warnings.push(`The dedicated Forge Recovery systemd-user tunnel unit ${systemdTunnelUnitName} is not running.`);
+  else if (!systemdTunnelService && !tunnelPlistInstalled) warnings.push('The dedicated Forge Recovery tunnel plist is not installed.');
+  else if (!systemdTunnelService && !tunnelRestartSafe) warnings.push('The dedicated Forge Recovery tunnel plist must use RunAtLoad=true and unconditional KeepAlive=true.');
+  else if (!systemdTunnelService && !tunnelRunning) warnings.push('The dedicated Forge Recovery tunnel service is not running.');
   if (!passphraseConfigured) warnings.push('MCP OAuth passphrase is not configured. Run forge mcp setup chatgpt first.');
 
   return {
     name: 'Forge Recovery',
+    identity: recoveryMachineIdentity(config, { platform }),
     transport: 'streamable_http',
     url,
     public: publicEndpoint,
-    readyForChatGPT: installed && gatewayRunning && watchdogRunning && tunnelRestartSafe && tunnelRunning && publicEndpoint && passphraseConfigured,
+    readyForChatGPT: installed && gatewayRunning && watchdogRunning && tunnelReady && (openAiTunnelService ? true : publicEndpoint) && passphraseConfigured,
     installed,
     currentRelease: authority.current?.releaseRevision,
     previousRelease: authority.previous?.releaseRevision,
@@ -165,23 +323,32 @@ export function recoveryConnectorDescriptor(
     services: {
       gateway: {
         label: RECOVERY_GATEWAY_LABEL,
+        platform: servicePlatform,
+        serviceInstalled: gatewayServiceInstalled,
         plistInstalled: gatewayPlistInstalled,
         running: gatewayRunning,
         ...(gatewayIdentity ? { pid: gatewayIdentity.pid } : {}),
       },
       watchdog: {
         label: RECOVERY_WATCHDOG_LABEL,
+        platform: servicePlatform,
+        serviceInstalled: watchdogServiceInstalled,
         plistInstalled: watchdogPlistInstalled,
         running: watchdogRunning,
         ...(watchdogIdentity ? { pid: watchdogIdentity.pid } : {}),
       },
       tunnel: {
-        configured: Boolean(tunnelService),
+        configured: Boolean(configuredTunnel),
+        ...(configuredTunnel ? { platform: configuredTunnel.platform } : {}),
         ...(tunnelService ? { label: tunnelService.label } : {}),
+        ...(systemdTunnelService ? { unitName: systemdTunnelUnitName ?? systemdTunnelService.unitName } : {}),
+        ...(openAiTunnelService ? { alias: openAiTunnelService.alias, tunnelId: openAiTunnelService.tunnelId } : {}),
+        serviceInstalled: openAiTunnelService ? openAiRestartSafe : systemdTunnelService ? systemdTunnelInstalled : tunnelPlistInstalled,
         plistInstalled: tunnelPlistInstalled,
         restartSafe: tunnelRestartSafe,
         running: tunnelRunning,
-        ...(tunnelLaunchdPid ? { pid: tunnelLaunchdPid } : {}),
+        ...(openAiTunnelService ? { healthy: tunnelHealthy, ready: tunnelReady } : {}),
+        ...(systemdTunnelPid ? { pid: systemdTunnelPid } : tunnelLaunchdPid ? { pid: tunnelLaunchdPid } : {}),
       },
     },
     tools: RECOVERY_TOOLS.map((tool) => tool.name),
@@ -189,6 +356,12 @@ export function recoveryConnectorDescriptor(
   };
 }
 
+export function recoveryConnectorHasExternalTransport(
+  connector: Pick<RecoveryConnectorDescriptor, 'public' | 'services'>,
+): boolean {
+  return connector.public || connector.services.tunnel.platform === 'openai-secure-tunnel';
+}
+
 export interface RecoveryConnectorVerificationDependencies {
   fetcher?: typeof fetch;
   random?: (size: number) => Buffer;
@@ -203,7 +376,15 @@ export interface RecoveryConnectorVerificationResult {
     authorizationMetadata: { ok: boolean; status?: number };
     protectedResourceMetadata: { ok: boolean; status?: number };
     unauthenticatedChallenge: { ok: boolean; status?: number };
-    oauthPkce: { ok: boolean; registrationStatus?: number; authorizationStatus?: number; tokenStatus?: number };
+    oauthPkce: {
+      ok: boolean;
+      registrationStatus?: number;
+      authorizationStatus?: number;
+      tokenStatus?: number;
+      clientOwner?: 'recovery_verifier';
+      clientReused?: boolean;
+      credentialRetirement?: 'shared_recovery_token_not_individually_revocable';
+    };
     mcp: {
       ok: boolean;
       initializeStatus?: number;
@@ -224,7 +405,25 @@ function jsonObject(value: unknown): Record<string, unknown> {
 }
 
 async function responseJson(response: Response): Promise<Record<string, unknown>> {
-  try { return jsonObject(await response.json()); } catch { return {}; }
+  try {
+    const text = await response.text();
+    if (!text.trim()) return {};
+    if (/text\/event-stream/i.test(response.headers.get('content-type') ?? '')) {
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.startsWith('data:')) continue;
+        try {
+          const payload = jsonObject(JSON.parse(line.slice('data:'.length).trim()));
+          if (Object.keys(payload).length > 0) return payload;
+        } catch {
+          // Ignore non-JSON SSE fields and keep looking for the MCP data event.
+        }
+      }
+      return {};
+    }
+    return jsonObject(JSON.parse(text));
+  } catch {
+    return {};
+  }
 }
 
 export async function verifyRecoveryConnector(
@@ -250,7 +449,9 @@ export async function verifyRecoveryConnector(
   });
 
   if (!connector.readyForChatGPT) failures.push(...connector.warnings.map((warning) => `readiness: ${warning}`));
-  if (!connector.public) failures.push('readiness: Recovery Connector does not have an HTTPS public endpoint.');
+  if (!recoveryConnectorHasExternalTransport(connector)) {
+    failures.push('readiness: Recovery Connector has neither an HTTPS public endpoint nor a dedicated OpenAI Secure MCP Tunnel.');
+  }
 
   const origin = new URL(connector.url).origin;
   try {
@@ -325,12 +526,13 @@ export async function verifyRecoveryConnector(
     failures.push('oauthPkce: MCP OAuth passphrase is not configured.');
   } else {
     try {
-      const redirectUri = 'http://127.0.0.1/forge-recovery-oauth-callback';
+      const redirectUri = RECOVERY_VERIFIER_OAUTH_REDIRECT_URI;
       const registration = await request(`${origin}/recovery/oauth/register`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({
-          client_name: 'Forge Recovery Verification',
+          client_id: RECOVERY_VERIFIER_OAUTH_CLIENT_ID,
+          client_name: RECOVERY_VERIFIER_OAUTH_CLIENT_NAME,
           redirect_uris: [redirectUri],
           grant_types: ['authorization_code'],
           response_types: ['code'],
@@ -339,7 +541,11 @@ export async function verifyRecoveryConnector(
       });
       const registrationBody = await responseJson(registration);
       const clientId = typeof registrationBody.client_id === 'string' ? registrationBody.client_id : '';
-      if (registration.status !== 201 || !clientId) throw new Error(`dynamic registration HTTP ${registration.status}`);
+      const clientOwner = registrationBody.forge_client_owner;
+      const clientReused = registrationBody.forge_client_reused === true;
+      if (registration.status !== 201 || clientId !== RECOVERY_VERIFIER_OAUTH_CLIENT_ID || clientOwner !== 'recovery_verifier') {
+        throw new Error(`dynamic verifier registration HTTP ${registration.status}`);
+      }
 
       const verifier = random(32).toString('base64url');
       const challenge = createHash('sha256').update(verifier).digest('base64url');
@@ -388,8 +594,16 @@ export async function verifyRecoveryConnector(
         registrationStatus: registration.status,
         authorizationStatus: authorization.status,
         tokenStatus: tokenResponse.status,
+        clientOwner: 'recovery_verifier',
+        clientReused,
+        // Recovery MCP currently uses one configured shared bearer token, so
+        // there is no verifier-specific credential that can be revoked without
+        // revoking Recovery itself. The reserved client slot keeps verifier
+        // registration state bounded across success and failure loops.
+        credentialRetirement: 'shared_recovery_token_not_individually_revocable',
       };
 
+      let mcpSessionId: string | undefined;
       const rpc = async (id: number | undefined, method: string, params?: Record<string, unknown>) => {
         const response = await request(connector.url, {
           method: 'POST',
@@ -398,53 +612,84 @@ export async function verifyRecoveryConnector(
             accept: 'application/json, text/event-stream',
             'content-type': 'application/json',
             'mcp-protocol-version': '2025-06-18',
+            ...(mcpSessionId ? { 'mcp-session-id': mcpSessionId } : {}),
           },
           body: JSON.stringify({ jsonrpc: '2.0', ...(id === undefined ? {} : { id }), method, ...(params ? { params } : {}) }),
         });
-        if (method === 'notifications/initialized') return { response, result: {} as Record<string, unknown> };
+        if (method === 'notifications/initialized') {
+          if (response.status !== 202) throw new Error(`${method} HTTP ${response.status}`);
+          return { response, result: {} as Record<string, unknown> };
+        }
         const body = await responseJson(response);
         const rpcError = jsonObject(body.error);
         if (response.status !== 200 || Object.keys(rpcError).length > 0) {
           throw new Error(`${method} HTTP ${response.status}${typeof rpcError.message === 'string' ? `: ${rpcError.message}` : ''}`);
         }
+        if (method === 'initialize') {
+          const returnedSessionId = response.headers.get('mcp-session-id')?.trim();
+          if (!returnedSessionId) throw new Error('initialize HTTP 200: Mcp-Session-Id missing');
+          mcpSessionId = returnedSessionId;
+        }
         return { response, result: jsonObject(body.result) };
       };
-
-      const initialized = await rpc(11, 'initialize', {
-        protocolVersion: '2025-06-18',
-        capabilities: {},
-        clientInfo: { name: 'forge-recovery-verifier', version: FORGE_VERSION },
-      });
-      const initializedNotification = await rpc(undefined, 'notifications/initialized');
-      const listed = await rpc(12, 'tools/list');
-      const tools = Array.isArray(listed.result.tools)
-        ? listed.result.tools.map((tool) => jsonObject(tool).name).filter((name): name is string => typeof name === 'string')
-        : [];
-      const expectedTools = RECOVERY_TOOLS.map((tool) => tool.name);
-      const runtimeStatusCall = await rpc(13, 'tools/call', { name: 'runtime_status', arguments: {} });
-      const listReleasesCall = await rpc(14, 'tools/call', { name: 'list_releases', arguments: {} });
-      const initializedResult = initialized.result;
-      const serverInfo = jsonObject(initializedResult.serverInfo);
-      const mcpOk = initialized.response.status === 200
-        && initializedNotification.response.status === 202
-        && initializedResult.protocolVersion === '2025-06-18'
-        && serverInfo.name === 'forge-standalone-recovery'
-        && serverInfo.version === FORGE_VERSION
-        && JSON.stringify(tools) === JSON.stringify(expectedTools)
-        && runtimeStatusCall.response.status === 200
-        && listReleasesCall.response.status === 200;
-      probes.mcp = {
-        ok: mcpOk,
-        initializeStatus: initialized.response.status,
-        initializedNotificationStatus: initializedNotification.response.status,
-        protocolVersion: typeof initializedResult.protocolVersion === 'string' ? initializedResult.protocolVersion : undefined,
-        serverName: typeof serverInfo.name === 'string' ? serverInfo.name : undefined,
-        serverVersion: typeof serverInfo.version === 'string' ? serverInfo.version : undefined,
-        tools,
-        runtimeStatusCall: runtimeStatusCall.response.status === 200,
-        listReleasesCall: listReleasesCall.response.status === 200,
+      const closeMcpSession = async (): Promise<void> => {
+        const sessionId = mcpSessionId;
+        if (!sessionId) return;
+        mcpSessionId = undefined;
+        try {
+          await request(connector.url, {
+            method: 'DELETE',
+            headers: {
+              authorization: `Bearer ${accessToken}`,
+              accept: 'application/json, text/event-stream',
+              'mcp-protocol-version': '2025-06-18',
+              'mcp-session-id': sessionId,
+            },
+          });
+        } catch {
+          // Session cleanup is best-effort and must not hide the verifier result.
+        }
       };
-      if (!mcpOk) failures.push('mcp: initialize, Forge version, tool surface, or read-only calls did not match the Recovery contract.');
+
+      try {
+        const initialized = await rpc(11, 'initialize', {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'forge-recovery-verifier', version: FORGE_VERSION },
+        });
+        const initializedNotification = await rpc(undefined, 'notifications/initialized');
+        const listed = await rpc(12, 'tools/list');
+        const tools = Array.isArray(listed.result.tools)
+          ? listed.result.tools.map((tool) => jsonObject(tool).name).filter((name): name is string => typeof name === 'string')
+          : [];
+        const expectedTools = RECOVERY_TOOLS.map((tool) => tool.name);
+        const runtimeStatusCall = await rpc(13, 'tools/call', { name: 'runtime_status', arguments: {} });
+        const listReleasesCall = await rpc(14, 'tools/call', { name: 'list_releases', arguments: {} });
+        const initializedResult = initialized.result;
+        const serverInfo = jsonObject(initializedResult.serverInfo);
+        const mcpOk = initialized.response.status === 200
+          && initializedNotification.response.status === 202
+          && initializedResult.protocolVersion === '2025-06-18'
+          && serverInfo.name === 'forge-standalone-recovery'
+          && serverInfo.version === FORGE_VERSION
+          && JSON.stringify(tools) === JSON.stringify(expectedTools)
+          && runtimeStatusCall.response.status === 200
+          && listReleasesCall.response.status === 200;
+        probes.mcp = {
+          ok: mcpOk,
+          initializeStatus: initialized.response.status,
+          initializedNotificationStatus: initializedNotification.response.status,
+          protocolVersion: typeof initializedResult.protocolVersion === 'string' ? initializedResult.protocolVersion : undefined,
+          serverName: typeof serverInfo.name === 'string' ? serverInfo.name : undefined,
+          serverVersion: typeof serverInfo.version === 'string' ? serverInfo.version : undefined,
+          tools,
+          runtimeStatusCall: runtimeStatusCall.response.status === 200,
+          listReleasesCall: listReleasesCall.response.status === 200,
+        };
+        if (!mcpOk) failures.push('mcp: initialize, Forge version, tool surface, or read-only calls did not match the Recovery contract.');
+      } finally {
+        await closeMcpSession();
+      }
     } catch (error) {
       failures.push(`oauthPkce/mcp: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -534,7 +779,7 @@ export function buildRecoveryCommand(): Command {
         recoveryPublicUrl: current.recoveryPublicUrl,
         recoveryTunnelService: current.recoveryTunnelService,
         primaryPublicTunnelService: current.primaryPublicTunnelService,
-        primaryRuntimeService: current.primaryRuntimeService ?? { platform: 'launchd' },
+        primaryRuntimeService: current.primaryRuntimeService ?? defaultPrimaryRuntimeServiceConfig(),
         primaryConnectorService,
       });
       const refreshed = loadRecoveryConfig(home);
@@ -620,6 +865,92 @@ export function buildRecoveryCommand(): Command {
       if (!result.ok) process.exitCode = 1;
     });
 
+  command.command('migrate-controller-home')
+    .description('Transactionally relocate Forge Controller Home on Linux/WSL through an independent transient systemd worker')
+    .requiredOption('--from <path>', 'Current Controller Home authority')
+    .requiredOption('--controller-home <path>', 'Destination user-level Controller Home')
+    .option('--archive-suffix <suffix>', 'Stable suffix for an authority-free destination shell archive')
+    .option('--timeout-ms <ms>', 'Overall migration transaction timeout in milliseconds', '240000')
+    .action(async (opts: { from: string; controllerHome: string; archiveSuffix?: string; timeoutMs: string }) => {
+      if (process.platform !== 'linux') throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_LINUX_ONLY');
+      const timeoutMs = Number(opts.timeoutMs);
+      if (!Number.isInteger(timeoutMs) || timeoutMs < 30_000 || timeoutMs > 900_000) {
+        throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_TIMEOUT_INVALID');
+      }
+      const scheduled = scheduleLinuxControllerHomeMigration({
+        sourceHome: resolve(opts.from),
+        destinationHome: resolveControllerHome(opts.controllerHome),
+        ...(opts.archiveSuffix ? { archiveSuffix: opts.archiveSuffix } : {}),
+        timeoutMs,
+      });
+      output({
+        status: 'migration_scheduled',
+        operationId: scheduled.request.operationId,
+        sourceHome: scheduled.request.sourceHome,
+        destinationHome: scheduled.request.destinationHome,
+        workerUnit: scheduled.request.workerUnit,
+        receiptPath: scheduled.request.receiptPath,
+        logPath: scheduled.request.logPath,
+        preflight: scheduled.preflight,
+      });
+    });
+
+  command.command('migrate-controller-home-worker')
+    .description('Internal Linux/WSL transient worker for a durable Controller Home migration request')
+    .requiredOption('--request <path>', 'Durable migration request written before service cutover')
+    .action(async (opts: { request: string }) => {
+      if (process.platform !== 'linux') throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_LINUX_ONLY');
+      const receipt = await runLinuxControllerHomeMigrationRequest(resolve(opts.request));
+      // A durable terminal receipt, including failed-after-rollback, is a completed worker transaction.
+      // Only an unhandled process failure before a terminal receipt should trigger systemd Restart=on-failure.
+      output(receipt);
+    });
+
+  command.command('rollback-controller-home-migration')
+    .description('Rollback a stopped Controller Home relocation before any writer is restarted')
+    .requiredOption('--from <path>', 'Original Controller Home path')
+    .requiredOption('--controller-home <path>', 'Relocated user-level Controller Home path')
+    .option('--archived-destination-home <path>', 'Archived authority-free destination shell returned by migration')
+    .action(async (opts: { from: string; controllerHome: string; archivedDestinationHome?: string }) => {
+      if (process.platform !== 'linux') throw new Error('RECOVERY_CONTROLLER_HOME_MIGRATION_LINUX_ONLY');
+      const sourceHome = resolve(opts.from);
+      const destinationHome = resolveControllerHome(opts.controllerHome);
+      const preflight = recoveryControllerHomeMigrationPreflight(destinationHome, sourceHome);
+      if (preflight.liveOwners.length > 0) {
+        throw new Error(`RECOVERY_CONTROLLER_HOME_MIGRATION_OWNERS_LIVE: ${preflight.liveOwners.map((entry) => `${entry.label}:${entry.pid}`).join(',')}`);
+      }
+      const relocation: StoppedControllerHomeAuthorityRelocation = {
+        migrated: true,
+        sourceHome,
+        destinationHome,
+        ...(opts.archivedDestinationHome ? { archivedDestinationHome: resolve(opts.archivedDestinationHome) } : {}),
+      };
+      rollbackStoppedControllerHomeAuthorityRelocation(relocation);
+      output({ status: 'rolled_back', relocation });
+    });
+
+  command.command('windows-host-register')
+    .description('Register the Windows-host Recovery provider using discovered or explicitly bound host paths')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .option('--rescue-root <path>', 'Override the local Recovery helper root')
+    .option('--recovery-script-host <path>', 'Host-visible path to ForgeRecovery.ps1')
+    .option('--recovery-script-windows <path>', 'Windows path to ForgeRecovery.ps1')
+    .option('--powershell-host <path>', 'Host-visible path to powershell.exe')
+    .option('--powershell-windows <path>', 'Windows path to powershell.exe')
+    .option('--disabled', 'Register the provider disabled')
+    .action((opts) => {
+      const result = installWindowsHostRecoveryPlugin({
+        controllerHome: resolveControllerHome(opts.controllerHome),
+        rescueRoot: opts.rescueRoot,
+        recoveryScriptHostPath: opts.recoveryScriptHost,
+        recoveryScriptWindowsPath: opts.recoveryScriptWindows,
+        powershellHostPath: opts.powershellHost,
+        powershellWindowsPath: opts.powershellWindows,
+        enabled: opts.disabled !== true,
+      });
+      output({ status: 'registered', ...result });
+    });
+
   command.command('install')
     .description('Build and activate the independent Forge Recovery Gateway and Watchdog release')
     .requiredOption('--controller-home <path>', 'Explicit Controller Home')
@@ -628,11 +959,25 @@ export function buildRecoveryCommand(): Command {
     .option('--recovery-public-url <url>', 'Dedicated Forge Recovery MCP public URL')
     .option('--recovery-tunnel-service-label <label>', 'Dedicated Recovery tunnel launchd label')
     .option('--recovery-tunnel-service-plist <path>', 'Absolute Recovery tunnel launchd plist path')
+    .option('--recovery-tunnel-systemd-unit <unit>', 'Dedicated Recovery systemd --user tunnel unit (Linux only)')
+    .option('--recovery-openai-tunnel-id <id>', 'Dedicated Recovery OpenAI Secure MCP Tunnel id')
+    .option('--recovery-openai-tunnel-alias <alias>', 'Dedicated Recovery tunnel-client runtime alias (default: machine-specific forge-recovery-<id>)')
+    .option('--recovery-openai-runtime-api-key-ref <ref>', 'Recovery tunnel runtime API key reference (env:NAME or file:/absolute/path)')
+    .option('--recovery-openai-profile <profile>', 'Optional tunnel-client runtime profile name for Recovery')
+    .option('--recovery-openai-profile-dir <path>', 'Optional absolute tunnel-client profile directory for Recovery')
+    .option('--recovery-openai-admin-profile <profile>', 'Optional tunnel-client admin profile used for Recovery runtime connect')
     .option('--primary-connector-service-label <label>', 'Primary OAuth/Connector launchd label managed by standalone Recovery')
     .option('--primary-connector-service-plist <path>', 'Absolute primary OAuth/Connector launchd plist path')
     .option('--primary-connector-local-url <url>', 'Local primary OAuth/Connector MCP endpoint used to distinguish Connector from tunnel failures')
     .option('--primary-tunnel-service-label <label>', 'Primary public MCP tunnel launchd label managed by standalone Recovery')
     .option('--primary-tunnel-service-plist <path>', 'Absolute primary public MCP tunnel launchd plist path')
+    .option('--primary-openai-tunnel-id <id>', 'Primary OpenAI Secure MCP Tunnel id managed by Recovery')
+    .option('--primary-openai-tunnel-alias <alias>', 'Primary tunnel-client runtime alias (default: forge)')
+    .option('--primary-openai-runtime-api-key-ref <ref>', 'Primary tunnel runtime API key reference (env:NAME or file:/absolute/path)')
+    .option('--primary-openai-profile <profile>', 'Optional tunnel-client runtime profile name for primary Forge')
+    .option('--primary-openai-profile-dir <path>', 'Optional absolute tunnel-client profile directory for primary Forge')
+    .option('--primary-openai-admin-profile <profile>', 'Optional tunnel-client admin profile used for primary runtime connect')
+    .option('--primary-runtime-source-root <path>', 'Stable canonical/package source used by Recovery for future Runtime staging')
     .option('--stage-only', 'Build and canary the Recovery release without activating services')
     .action(async (opts: {
       controllerHome: string;
@@ -641,36 +986,104 @@ export function buildRecoveryCommand(): Command {
       recoveryPublicUrl?: string;
       recoveryTunnelServiceLabel?: string;
       recoveryTunnelServicePlist?: string;
+      recoveryTunnelSystemdUnit?: string;
+      recoveryOpenaiTunnelId?: string;
+      recoveryOpenaiTunnelAlias?: string;
+      recoveryOpenaiRuntimeApiKeyRef?: string;
+      recoveryOpenaiProfile?: string;
+      recoveryOpenaiProfileDir?: string;
+      recoveryOpenaiAdminProfile?: string;
       primaryConnectorServiceLabel?: string;
       primaryConnectorServicePlist?: string;
       primaryConnectorLocalUrl?: string;
       primaryTunnelServiceLabel?: string;
       primaryTunnelServicePlist?: string;
+      primaryOpenaiTunnelId?: string;
+      primaryOpenaiTunnelAlias?: string;
+      primaryOpenaiRuntimeApiKeyRef?: string;
+      primaryOpenaiProfile?: string;
+      primaryOpenaiProfileDir?: string;
+      primaryOpenaiAdminProfile?: string;
+      primaryRuntimeSourceRoot?: string;
       stageOnly?: boolean;
     }) => {
       const home = resolveControllerHome(opts.controllerHome);
       const port = Number(opts.port);
       if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('RECOVERY_PORT_INVALID');
-      const recoveryTunnelService = launchdService(opts.recoveryTunnelServiceLabel, opts.recoveryTunnelServicePlist, 'RECOVERY_TUNNEL') as PublicTunnelServiceConfig | undefined;
-      const primaryConnectorBase = launchdService(opts.primaryConnectorServiceLabel, opts.primaryConnectorServicePlist, 'RECOVERY_PRIMARY_CONNECTOR') as PrimaryConnectorServiceConfig | undefined;
+      const recoveryLaunchdTunnel = launchdService(opts.recoveryTunnelServiceLabel, opts.recoveryTunnelServicePlist, 'RECOVERY_TUNNEL') as PublicTunnelServiceConfig | undefined;
+      const recoverySystemdTunnel = systemdRecoveryTunnelService(opts.recoveryTunnelSystemdUnit);
+      if (recoveryLaunchdTunnel && process.platform === 'linux') throw new Error('RECOVERY_TUNNEL_LAUNCHD_UNSUPPORTED_ON_LINUX');
+      if (recoverySystemdTunnel && process.platform !== 'linux') throw new Error('RECOVERY_TUNNEL_SYSTEMD_UNSUPPORTED_ON_THIS_PLATFORM');
+      const recoveryLocalMcpUrl = `http://127.0.0.1:${port}/recovery/mcp`;
+      const recoveryOpenAiTunnel = openAiTunnelService({
+        tunnelId: opts.recoveryOpenaiTunnelId,
+        alias: opts.recoveryOpenaiTunnelAlias,
+        runtimeApiKeyRef: opts.recoveryOpenaiRuntimeApiKeyRef,
+        profile: opts.recoveryOpenaiProfile,
+        profileDir: opts.recoveryOpenaiProfileDir,
+        adminProfile: opts.recoveryOpenaiAdminProfile,
+        mcpServerUrl: recoveryLocalMcpUrl,
+        defaultAlias: recoveryOpenAiTunnelDefaultAlias(home),
+        role: 'RECOVERY',
+      });
+      const recoveryTunnelOwners = [recoveryLaunchdTunnel, recoverySystemdTunnel, recoveryOpenAiTunnel].filter(Boolean);
+      if (recoveryTunnelOwners.length > 1) throw new Error('RECOVERY_TUNNEL_OWNER_CONFLICT');
+      const recoveryTunnelService: RecoveryTunnelServiceConfig | undefined = recoveryOpenAiTunnel ?? recoverySystemdTunnel ?? recoveryLaunchdTunnel;
+
+      const primaryConnectorLaunchd = launchdService(opts.primaryConnectorServiceLabel, opts.primaryConnectorServicePlist, 'RECOVERY_PRIMARY_CONNECTOR') as PrimaryConnectorServiceConfig | undefined;
       const primaryConnectorLocalUrl = endpoint(opts.primaryConnectorLocalUrl, 'RECOVERY_PRIMARY_CONNECTOR_LOCAL_URL');
-      if (primaryConnectorLocalUrl && !primaryConnectorBase) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LABEL_REQUIRED_FOR_LOCAL_URL');
-      const primaryConnectorService = primaryConnectorBase
-        ? { ...primaryConnectorBase, ...(primaryConnectorLocalUrl ? { localMcpUrl: primaryConnectorLocalUrl } : {}) }
-        : undefined;
-      const primaryPublicTunnelService = launchdService(opts.primaryTunnelServiceLabel, opts.primaryTunnelServicePlist, 'RECOVERY_PRIMARY_TUNNEL') as PublicTunnelServiceConfig | undefined;
+      let primaryConnectorService: PrimaryConnectorServiceConfig | undefined;
+      if (process.platform === 'linux') {
+        if (primaryConnectorLaunchd) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LAUNCHD_UNSUPPORTED_ON_LINUX');
+        primaryConnectorService = primaryConnectorLocalUrl ? { platform: 'systemd-user', localMcpUrl: primaryConnectorLocalUrl } : undefined;
+      } else {
+        if (primaryConnectorLocalUrl && !primaryConnectorLaunchd) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LABEL_REQUIRED_FOR_LOCAL_URL');
+        primaryConnectorService = primaryConnectorLaunchd
+          ? { ...primaryConnectorLaunchd, ...(primaryConnectorLocalUrl ? { localMcpUrl: primaryConnectorLocalUrl } : {}) }
+          : undefined;
+      }
+
+      const primaryLaunchdTunnel = launchdService(opts.primaryTunnelServiceLabel, opts.primaryTunnelServicePlist, 'RECOVERY_PRIMARY_TUNNEL') as PublicTunnelServiceConfig | undefined;
+      const primaryOpenAiTunnel = primaryConnectorLocalUrl ? openAiTunnelService({
+        tunnelId: opts.primaryOpenaiTunnelId,
+        alias: opts.primaryOpenaiTunnelAlias,
+        runtimeApiKeyRef: opts.primaryOpenaiRuntimeApiKeyRef,
+        profile: opts.primaryOpenaiProfile,
+        profileDir: opts.primaryOpenaiProfileDir,
+        adminProfile: opts.primaryOpenaiAdminProfile,
+        mcpServerUrl: primaryConnectorLocalUrl,
+        defaultAlias: 'forge',
+        role: 'RECOVERY_PRIMARY',
+      }) : undefined;
+      const primaryOpenAiOptionsSupplied = Boolean(opts.primaryOpenaiTunnelId || opts.primaryOpenaiTunnelAlias || opts.primaryOpenaiRuntimeApiKeyRef || opts.primaryOpenaiProfile || opts.primaryOpenaiProfileDir || opts.primaryOpenaiAdminProfile);
+      if (primaryOpenAiOptionsSupplied && !primaryConnectorLocalUrl) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LOCAL_URL_REQUIRED_FOR_OPENAI_TUNNEL');
+      if (primaryLaunchdTunnel && primaryOpenAiTunnel) throw new Error('RECOVERY_PRIMARY_TUNNEL_OWNER_CONFLICT');
+      const primaryPublicTunnelService = primaryOpenAiTunnel ?? primaryLaunchdTunnel;
       if (primaryPublicTunnelService && !primaryConnectorService) throw new Error('RECOVERY_PRIMARY_CONNECTOR_REQUIRED_FOR_PRIMARY_TUNNEL');
+      assertDistinctRecoveryOpenAiTunnelIdentity(recoveryTunnelService, primaryPublicTunnelService);
+
       const recoveryPublicUrl = endpoint(opts.recoveryPublicUrl, 'RECOVERY_PUBLIC_URL');
-      if (Boolean(recoveryTunnelService) !== Boolean(recoveryPublicUrl)) {
-        throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
-      }
+      if (recoveryOpenAiTunnel && recoveryPublicUrl) throw new Error('RECOVERY_OPENAI_TUNNEL_PUBLIC_URL_CONFLICT');
+      if ((recoveryLaunchdTunnel || recoverySystemdTunnel) && !recoveryPublicUrl) throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
+      if (!recoveryTunnelService && recoveryPublicUrl) throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
+
       const packageRoot = resolve(import.meta.dir, '..', '..', '..');
+      const primaryRuntimeSourceRoot = opts.primaryRuntimeSourceRoot ? resolve(opts.primaryRuntimeSourceRoot) : packageRoot;
+      const primaryRuntimeSourceRepository = findRegisteredRepositoryByCheckoutRoot(primaryRuntimeSourceRoot, home);
+      if (!opts.stageOnly && !primaryRuntimeSourceRepository) {
+        throw new Error(`RECOVERY_PRIMARY_RUNTIME_SOURCE_REPOSITORY_NOT_REGISTERED: ${primaryRuntimeSourceRoot}`);
+      }
+      if (!opts.stageOnly && /[\\/]\.forge[\\/]managed-worktrees[\\/]/.test(primaryRuntimeSourceRoot)) {
+        throw new Error('RECOVERY_PRIMARY_RUNTIME_SOURCE_ROOT_DURABLE_REQUIRED');
+      }
       const result = await installStandaloneRecovery({
         controllerHome: home,
-        repoRoot: packageRoot,
+        repoRoot: primaryRuntimeSourceRoot,
+        ...(primaryRuntimeSourceRepository ? { primaryRuntimeSourceRepositoryId: primaryRuntimeSourceRepository.repoId } : {}),
         sourceRoot: packageRoot,
         port,
         stageOnly: opts.stageOnly === true,
+        primaryRuntimeService: defaultPrimaryRuntimeServiceConfig(),
         publicMcpUrl: endpoint(opts.publicMcpUrl, 'PUBLIC_MCP_URL'),
         recoveryPublicUrl,
         recoveryTunnelService,