@moretea-labs/forge 1.7.2 → 1.8.1

package/src/cli/commands/recovery.ts

@@ -1,13 +1,25 @@
 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,
-  RECOVERY_WATCHDOG_LABEL,
+  RECOVERY_DAEMON_LABEL,
   inspectRecoveryTunnelLaunchdContract,
   installStandaloneRecovery,
   recoveryLaunchdPid,
@@ -16,11 +28,17 @@ 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,
+  normalizeRecoveryInstallProfile,
   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,125 @@ 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;
+  launchdPid?: (role: 'daemon') => number | undefined;
+  systemdPid?: (role: 'daemon') => number | undefined;
   tunnelLaunchdPid?: (label: string) => number | undefined;
+  tunnelSystemdPid?: (unitName: string) => number | undefined;
+  openAiTunnelStatus?: (service: OpenAiSecureTunnelServiceConfig) => OpenAiSecureTunnelRuntimeObservation;
   processAlive?: (pid: number) => boolean;
+  processParentPid?: (pid: number) => number | undefined;
+}
+
+function recoveryProcessParentPid(pid: number): number | undefined {
+  if (process.platform === 'win32' || !Number.isInteger(pid) || pid <= 1) return undefined;
+  const result = spawnSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+    encoding: 'utf8',
+    timeout: 2_000,
+    maxBuffer: 8 * 1024,
+  });
+  if (result.status !== 0) return undefined;
+  const parent = Number.parseInt((result.stdout ?? '').trim(), 10);
+  return Number.isInteger(parent) && parent > 0 ? parent : undefined;
+}
+
+/**
+ * launchd may own a tiny wrapper (/usr/bin/env) while Recovery records the
+ * compiled child PID in its runtime identity. Treat only that bounded process
+ * lineage as the same managed service; unrelated live PIDs still fail closed.
+ */
+export function recoveryManagedServiceOwnsRuntimeProcess(
+  managedPid: number | undefined,
+  runtimePid: number | undefined,
+  dependencies: {
+    processAlive?: (pid: number) => boolean;
+    processParentPid?: (pid: number) => number | undefined;
+    maxDepth?: number;
+  } = {},
+): boolean {
+  if (!managedPid || !runtimePid || managedPid <= 0 || runtimePid <= 0) return false;
+  const processAlive = dependencies.processAlive ?? isProcessAlive;
+  if (!processAlive(managedPid) || !processAlive(runtimePid)) return false;
+  if (managedPid === runtimePid) return true;
+  const parentPid = dependencies.processParentPid ?? recoveryProcessParentPid;
+  const maxDepth = Math.max(1, Math.min(Math.trunc(dependencies.maxDepth ?? 8), 32));
+  const visited = new Set<number>([runtimePid]);
+  let current = runtimePid;
+  for (let depth = 0; depth < maxDepth; depth += 1) {
+    const parent = parentPid(current);
+    if (!parent || parent <= 0 || visited.has(parent)) return false;
+    if (parent === managedPid) return true;
+    visited.add(parent);
+    current = parent;
+  }
+  return false;
 }
 
 export interface RecoveryConnectorDescriptor {
   name: 'Forge Recovery';
+  identity: RecoveryMachineIdentity;
   transport: 'streamable_http';
   url: string;
   public: boolean;
@@ -78,9 +219,22 @@ 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 };
+    recovery: { 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[];
@@ -98,61 +252,97 @@ export function recoveryConnectorDescriptor(
   const url = configuredUrl ?? `${localOrigin}/recovery/mcp`;
   const origin = new URL(url).origin;
   const passphraseConfigured = Boolean(readMcpServiceOAuthPassphrase(home));
-  const gatewayIdentity = readRecoveryRuntimeIdentity(home, 'gateway');
-  const watchdogIdentity = readRecoveryRuntimeIdentity(home, 'watchdog');
+  const recoveryIdentity = readRecoveryRuntimeIdentity(home, 'daemon');
+  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: 'daemon') => systemdUserServicePid(RECOVERY_DAEMON_LABEL));
+  const managedPid = () => servicePlatform === 'systemd-user' ? systemdPid('daemon') : launchdPid('daemon');
   const processAlive = dependencies.processAlive ?? isProcessAlive;
-  const tunnelService = config.recoveryTunnelService?.platform === 'launchd' ? config.recoveryTunnelService : undefined;
+  const serviceOwnsRuntimeProcess = (managedPid: number | undefined, runtimePid: number | undefined) =>
+    recoveryManagedServiceOwnsRuntimeProcess(managedPid, runtimePid, {
+      processAlive,
+      processParentPid: dependencies.processParentPid,
+    });
+  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 gatewayPlistInstalled = pathExists(authority.gatewayLaunchAgent);
-  const watchdogPlistInstalled = pathExists(authority.watchdogLaunchAgent);
-  const gatewayLaunchdPid = launchdPid('gateway');
-  const watchdogLaunchdPid = launchdPid('watchdog');
-  const gatewayRunning = Boolean(
-    gatewayIdentity
-    && gatewayLaunchdPid
-    && gatewayIdentity.pid === gatewayLaunchdPid
-    && processAlive(gatewayIdentity.pid)
-    && authority.current
-    && gatewayIdentity.releaseRevision === authority.current.releaseRevision
-    && gatewayIdentity.manifestSha256 === authority.current.manifestSha256,
-  );
-  const watchdogRunning = Boolean(
-    watchdogIdentity
-    && watchdogLaunchdPid
-    && watchdogIdentity.pid === watchdogLaunchdPid
-    && processAlive(watchdogIdentity.pid)
+  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 recoveryPlistInstalled = pathExists(authority.daemonLaunchAgent);
+  const recoveryServiceInstalled = servicePlatform === 'systemd-user'
+    ? pathExists(systemdUserUnitPath(RECOVERY_DAEMON_LABEL))
+    : recoveryPlistInstalled;
+  const recoveryManagedPid = managedPid();
+  const recoveryRunning = Boolean(
+    recoveryIdentity
+    && serviceOwnsRuntimeProcess(recoveryManagedPid, recoveryIdentity.pid)
     && authority.current
-    && watchdogIdentity.releaseRevision === authority.current.releaseRevision
-    && watchdogIdentity.manifestSha256 === authority.current.manifestSha256,
+    && recoveryIdentity.releaseRevision === authority.current.releaseRevision
+    && recoveryIdentity.manifestSha256 === authority.current.manifestSha256,
   );
-  const installed = Boolean(authority.current && gatewayPlistInstalled && watchdogPlistInstalled);
+  const installed = Boolean(authority.current && recoveryServiceInstalled);
   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 (!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 (!recoveryServiceInstalled) warnings.push(`Forge Recovery ${servicePlatform} service is not installed. Run forge recovery install.`);
+  if (!recoveryRunning) warnings.push('Forge Recovery service is not running on the current Recovery release.');
+  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 && recoveryRunning && tunnelReady && (openAiTunnelService ? true : publicEndpoint) && passphraseConfigured,
     installed,
     currentRelease: authority.current?.releaseRevision,
     previousRelease: authority.previous?.releaseRevision,
@@ -163,25 +353,26 @@ export function recoveryConnectorDescriptor(
     },
     healthUrl: `${origin}/recovery/health`,
     services: {
-      gateway: {
-        label: RECOVERY_GATEWAY_LABEL,
-        plistInstalled: gatewayPlistInstalled,
-        running: gatewayRunning,
-        ...(gatewayIdentity ? { pid: gatewayIdentity.pid } : {}),
-      },
-      watchdog: {
-        label: RECOVERY_WATCHDOG_LABEL,
-        plistInstalled: watchdogPlistInstalled,
-        running: watchdogRunning,
-        ...(watchdogIdentity ? { pid: watchdogIdentity.pid } : {}),
+      recovery: {
+        label: RECOVERY_DAEMON_LABEL,
+        platform: servicePlatform,
+        serviceInstalled: recoveryServiceInstalled,
+        plistInstalled: recoveryPlistInstalled,
+        running: recoveryRunning,
+        ...(recoveryIdentity ? { pid: recoveryIdentity.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 +380,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 +400,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 +429,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 +473,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 +550,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 +565,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,6 +618,13 @@ 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',
       };
 
       const rpc = async (id: number | undefined, method: string, params?: Record<string, unknown>) => {
@@ -401,7 +638,13 @@ export async function verifyRecoveryConnector(
           },
           body: JSON.stringify({ jsonrpc: '2.0', ...(id === undefined ? {} : { id }), method, ...(params ? { params } : {}) }),
         });
-        if (method === 'notifications/initialized') return { response, result: {} as Record<string, unknown> };
+        if (response.headers.get('mcp-session-id')?.trim()) {
+          throw new Error(`${method} unexpectedly established transport session state`);
+        }
+        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) {
@@ -444,7 +687,7 @@ export async function verifyRecoveryConnector(
         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.');
+      if (!mcpOk) failures.push('mcp: stateless initialize, Forge version, tool surface, or read-only calls did not match the Recovery contract.');
     } catch (error) {
       failures.push(`oauthPkce/mcp: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -516,6 +759,10 @@ export function buildRecoveryCommand(): Command {
     }) => {
       const home = resolveControllerHome(opts.controllerHome);
       const repoRoot = resolve(opts.repo);
+      const primaryRuntimeSourceRepository = findRegisteredRepositoryByCheckoutRoot(repoRoot, home);
+      if (!primaryRuntimeSourceRepository) {
+        throw new Error(`RECOVERY_PRIMARY_RUNTIME_SOURCE_REPOSITORY_NOT_REGISTERED: ${repoRoot}`);
+      }
       const current = loadRecoveryConfig(home);
       const primaryConnectorBase = launchdService(
         opts.primaryConnectorServiceLabel,
@@ -529,13 +776,15 @@ export function buildRecoveryCommand(): Command {
       const installed = await installStandaloneRecovery({
         controllerHome: home,
         repoRoot,
+        primaryRuntimeSourceRepositoryId: primaryRuntimeSourceRepository.repoId,
         port: current.gateway?.port ?? 8787,
         publicMcpUrl: current.publicMcpUrl,
         recoveryPublicUrl: current.recoveryPublicUrl,
         recoveryTunnelService: current.recoveryTunnelService,
         primaryPublicTunnelService: current.primaryPublicTunnelService,
-        primaryRuntimeService: current.primaryRuntimeService ?? { platform: 'launchd' },
+        primaryRuntimeService: current.primaryRuntimeService ?? defaultPrimaryRuntimeServiceConfig(),
         primaryConnectorService,
+        profile: 'self-healing',
       });
       const refreshed = loadRecoveryConfig(home);
       const runtime = await stageAndActivateConfiguredRuntimeRelease(refreshed);
@@ -620,20 +869,121 @@ 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')
+    .description('Build Forge Recovery artifacts and activate only the explicitly selected persistent Recovery profile')
     .requiredOption('--controller-home <path>', 'Explicit Controller Home')
+    .option('--profile <profile>', 'Recovery install profile: manual, gateway, or self-healing', 'manual')
     .option('--port <port>', 'Loopback Recovery Gateway port', '8787')
     .option('--public-mcp-url <url>', 'Primary Forge MCP public URL')
     .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('--stage-only', 'Build and canary the Recovery release without activating services')
+    .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', 'Compatibility alias: build/canary only and do not mutate installed Recovery config or services')
     .action(async (opts: {
       controllerHome: string;
       port: string;
@@ -641,36 +991,112 @@ 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;
+      profile: string;
       stageOnly?: boolean;
     }) => {
       const home = resolveControllerHome(opts.controllerHome);
+      const profile = normalizeRecoveryInstallProfile(opts.stageOnly ? 'manual' : opts.profile, 'manual');
+      if (opts.stageOnly && opts.profile !== 'manual') throw new Error('RECOVERY_STAGE_ONLY_PROFILE_CONFLICT');
       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 (profile === 'manual' && (recoveryTunnelService || recoveryPublicUrl)) throw new Error('RECOVERY_PROFILE_GATEWAY_REQUIRED');
+      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,
-        sourceRoot: packageRoot,
+        repoRoot: primaryRuntimeSourceRoot,
+        ...(primaryRuntimeSourceRepository ? { primaryRuntimeSourceRepositoryId: primaryRuntimeSourceRepository.repoId } : {}),
+        // The package root is only the CLI's location. A package installation
+        // is not a Git checkout, while the explicitly registered primary
+        // Runtime source is the immutable Recovery release's provenance.
+        sourceRoot: primaryRuntimeSourceRoot,
         port,
+        profile,
         stageOnly: opts.stageOnly === true,
+        primaryRuntimeService: defaultPrimaryRuntimeServiceConfig(),
         publicMcpUrl: endpoint(opts.publicMcpUrl, 'PUBLIC_MCP_URL'),
         recoveryPublicUrl,
         recoveryTunnelService,
@@ -679,6 +1105,7 @@ export function buildRecoveryCommand(): Command {
       });
       output({
         status: opts.stageOnly ? 'staged' : 'installed',
+        profile: result.profile,
         staged: result.staged.release,
         activation: result.activated,
         connector: recoveryConnectorDescriptor(home),