@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/standalone-recovery/installer.ts

@@ -1,20 +1,19 @@
 import { createHash, randomUUID } from 'crypto';
 import {
   chmodSync,
-  closeSync,
   copyFileSync,
   existsSync,
   lstatSync,
   mkdirSync,
-  openSync,
   readFileSync,
   readdirSync,
   renameSync,
   rmSync,
   writeFileSync,
 } from 'fs';
-import { dirname, join, resolve } from 'path';
+import { dirname, join, relative, resolve } from 'path';
 import { runProcess, type ProcessRunResult } from '../../effects/process-runner';
+import { resolveBunExecutable } from '../shared/process-environment';
 import {
   installLaunchAgent,
   launchAgentPath,
@@ -23,9 +22,16 @@ import {
   type SafeHandoffResult,
 } from '../../cli/controller/launch-agents';
 import { isProcessAlive } from '../shared/process-tree';
+import {
+  installSystemdUserUnit,
+  systemdUserAvailable,
+  systemdUserServicePid,
+  type SystemdUserUnitInput,
+} from '../../cli/controller/systemd-user';
 import { FORGE_VERSION } from '../../version';
-import { initializeStandaloneRecovery, loadRecoveryConfig, type PrimaryConnectorServiceConfig, type PrimaryRuntimeServiceConfig, type PublicTunnelServiceConfig, type RecoveryConfig } from './core';
+import { initializeStandaloneRecovery, loadRecoveryConfig, type LaunchdPrimaryConnectorServiceConfig, type LaunchdPublicTunnelServiceConfig, type PrimaryConnectorServiceConfig, type PrimaryRuntimeServiceConfig, type PublicTunnelServiceConfig, type RecoveryConfig, type RecoveryTunnelServiceConfig } from './core';
 import { RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
+import { acquireRecoveryOperationLock } from './operation-lock';
 export { RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
 import {
   RECOVERY_RELEASE_BINARIES,
@@ -129,14 +135,24 @@ export interface RecoveryActivationVerification {
   healthStatus?: number;
 }
 
+
+export interface RecoveryServiceHandoffResult {
+  platform: 'launchd' | 'systemd-user';
+  serviceRegistered: boolean;
+  pidReady: boolean;
+  portReady: boolean;
+  servicePath?: string;
+  pid?: number;
+  launchd?: SafeHandoffResult;
+}
 export interface RecoveryActivationResult {
   release: RecoveryReleaseDescriptor;
   previous?: RecoveryReleaseDescriptor;
   migratedLegacy?: RecoveryReleaseDescriptor;
   noOp?: boolean;
   handoff?: {
-    gateway: SafeHandoffResult;
-    watchdog: SafeHandoffResult;
+    gateway: RecoveryServiceHandoffResult;
+    watchdog: RecoveryServiceHandoffResult;
   };
   verification: RecoveryActivationVerification;
   rollback?: {
@@ -153,10 +169,14 @@ export interface RecoveryInstallResult {
 }
 
 export interface RecoveryInstallerDependencies {
+  platform?: NodeJS.Platform;
+  systemdEnv?: NodeJS.ProcessEnv;
+  systemdAvailable?: typeof systemdUserAvailable;
+  installSystemdUnit?: typeof installSystemdUserUnit;
   now?: () => number;
   uuid?: () => string;
   compileBinary?: (input: { sourceRoot: string; outputPath: string }) => ProcessRunResult;
-  runCanary?: (input: { binaryPath: string; controllerHome: string; role?: RecoveryRuntimeRole }) => ProcessRunResult;
+  runCanary?: (input: { binaryPath: string; controllerHome: string; productVersion: string; role?: RecoveryRuntimeRole }) => ProcessRunResult;
   installAgent?: typeof installLaunchAgent;
   handoff?: typeof safeLaunchdHandoff;
   verify?: (input: {
@@ -175,6 +195,28 @@ function sha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
 
+function recoverySourceProductVersion(sourceRoot: string): string {
+  const packagePath = join(resolve(sourceRoot), 'package.json');
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as { version?: unknown };
+    const version = typeof parsed.version === 'string' ? parsed.version.trim() : '';
+    if (version && version !== '0.0.0-unknown') return version;
+  } catch {
+    // Fall through to one explicit release-build error.
+  }
+  throw new Error(`RECOVERY_RELEASE_PRODUCT_VERSION_INVALID: ${packagePath}`);
+}
+
+function recoveryReleaseProductVersion(release: RecoveryReleaseDescriptor): string {
+  const bound = release.productVersion?.trim();
+  if (bound) return bound;
+  // Compatibility for Recovery releases created before productVersion became
+  // manifest-bound. Prefer their exact recorded source package when it still
+  // exists; only the legacy fallback may inherit the current process version.
+  try { return recoverySourceProductVersion(release.sourceRoot); } catch { /* legacy/retired source */ }
+  return FORGE_VERSION;
+}
+
 function gitText(root: string, args: string[]): string {
   const result = runProcess('git', ['-C', root, ...args], { timeoutMs: 15_000, maxOutputBytes: 128 * 1024 });
   if (!result.ok) throw new Error(`RECOVERY_RELEASE_GIT_FAILED: ${result.stderr || result.stdout || result.error}`.slice(0, 2_000));
@@ -190,9 +232,20 @@ export function recoverySourceIdentity(sourceRoot: string): RecoverySourceIdenti
   return { sourceCommit, releaseRevision: sourceCommit, cleanWorkspace: true, sourceRoot: root };
 }
 
+export function resolveRecoveryCompilerExecutable(
+  execPath: string = process.execPath,
+  env: NodeJS.ProcessEnv = process.env,
+  accountHome?: string,
+): string {
+  const configured = env.FORGE_BUN_BIN?.trim();
+  if (configured) return configured;
+  return accountHome === undefined
+    ? resolveBunExecutable(execPath, env)
+    : resolveBunExecutable(execPath, env, accountHome);
+}
+
 function defaultCompileBinary(input: { sourceRoot: string; outputPath: string }): ProcessRunResult {
-  const configured = process.env.FORGE_BUN_BIN?.trim();
-  const bun = configured || (process.versions.bun && /(?:^|\/)bun(?:$|-)/.test(process.execPath) ? process.execPath : 'bun');
+  const bun = resolveRecoveryCompilerExecutable();
   return runProcess(bun, [
     'build',
     join(input.sourceRoot, 'src/runtime/standalone-recovery/entry.ts'),
@@ -202,14 +255,14 @@ function defaultCompileBinary(input: { sourceRoot: string; outputPath: string })
   ], { cwd: input.sourceRoot, timeoutMs: 180_000, maxOutputBytes: 512 * 1024 });
 }
 
-function defaultRunCanary(input: { binaryPath: string; controllerHome: string; role?: RecoveryRuntimeRole }): ProcessRunResult {
+function defaultRunCanary(input: { binaryPath: string; controllerHome: string; productVersion: string; role?: RecoveryRuntimeRole }): ProcessRunResult {
   const args = input.role
     ? [input.role, RECOVERY_RELEASE_ROLE_CANARY_ARG, '--controller-home', input.controllerHome]
     : ['status', '--controller-home', input.controllerHome];
   return runProcess(input.binaryPath, args, {
     timeoutMs: 30_000,
     maxOutputBytes: 128 * 1024,
-    env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin', FORGE_BUILD_VERSION: FORGE_VERSION },
+    env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin', FORGE_BUILD_VERSION: input.productVersion },
     replaceEnv: true,
   });
 }
@@ -225,6 +278,7 @@ export function stageRecoveryRelease(input: {
   sourceRoot: string;
 }, dependencies: RecoveryInstallerDependencies = {}): StagedRecoveryRelease {
   const identity = recoverySourceIdentity(input.sourceRoot);
+  const productVersion = recoverySourceProductVersion(identity.sourceRoot);
   const now = dependencies.now ?? Date.now;
   const uuid = dependencies.uuid ?? randomUUID;
   const releasesRoot = recoveryReleasesRoot(input.controllerHome);
@@ -247,6 +301,7 @@ export function stageRecoveryRelease(input: {
       schemaVersion: 1,
       ...identity,
       builtAt: new Date(now()).toISOString(),
+      productVersion,
       artifacts: completeArtifacts(staging),
     });
     const runCanary = dependencies.runCanary ?? defaultRunCanary;
@@ -260,6 +315,7 @@ export function stageRecoveryRelease(input: {
       const canaryResult = runCanary({
         binaryPath: canary.binaryPath,
         controllerHome: resolve(input.controllerHome),
+        productVersion,
         role: canary.role,
       });
       if (!canaryResult.ok) {
@@ -331,16 +387,45 @@ export function captureLegacyRecoveryRelease(
   return release;
 }
 
+export function recoverySystemdUserUnitInput(
+  controllerHome: string,
+  role: RecoveryRuntimeRole,
+  env: NodeJS.ProcessEnv = process.env,
+  productVersion: string = FORGE_VERSION,
+): SystemdUserUnitInput {
+  const binary = role === 'gateway' ? 'forge-recovery-gateway' : 'forge-recovery-watchdog';
+  return {
+    description: role === 'gateway' ? 'Forge Standalone Recovery Gateway' : 'Forge Standalone Recovery Watchdog',
+    executable: join(recoveryCurrentPath(controllerHome), binary),
+    args: [role, '--controller-home', resolve(controllerHome)],
+    environment: {
+      PATH: env.PATH?.trim() || '/usr/bin:/bin:/usr/sbin:/sbin',
+      FORGE_BUILD_VERSION: productVersion,
+      // Recovery can be running from its own compiled binary. Never let that
+      // binary become the interpreter for the primary OAuth Connector after a
+      // Controller Home cutover; preserve the explicit package executable.
+      FORGE_CONNECTOR_EXECUTABLE: env.FORGE_CONNECTOR_EXECUTABLE?.trim() || process.execPath,
+    },
+    restart: 'always',
+    restartSec: 5,
+  };
+}
+
+function recoverySystemdLabel(role: RecoveryRuntimeRole): string {
+  return role === 'gateway' ? RECOVERY_GATEWAY_LABEL : RECOVERY_WATCHDOG_LABEL;
+}
+
 function recoveryPlist(input: {
   label: string;
   executable: string;
   command: RecoveryRuntimeRole;
   controllerHome: string;
   logPath: string;
+  productVersion: string;
 }): string {
   const xml = (value: string) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
   const argumentsList = [
-    '/usr/bin/env', '-i', 'PATH=/usr/bin:/bin:/usr/sbin:/sbin', `FORGE_BUILD_VERSION=${FORGE_VERSION}`, `FORGE_CONNECTOR_EXECUTABLE=${process.execPath}`,
+    '/usr/bin/env', '-i', 'PATH=/usr/bin:/bin:/usr/sbin:/sbin', `FORGE_BUILD_VERSION=${input.productVersion}`, `FORGE_CONNECTOR_EXECUTABLE=${process.execPath}`,
     input.executable, input.command, '--controller-home', input.controllerHome,
   ];
   return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${xml(input.label)}</string><key>ProgramArguments</key><array>${argumentsList.map((argument) => `<string>${xml(argument)}</string>`).join('')}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>ThrottleInterval</key><integer>5</integer><key>StandardOutPath</key><string>${xml(input.logPath)}</string><key>StandardErrorPath</key><string>${xml(input.logPath)}</string></dict></plist>\n`;
@@ -375,7 +460,7 @@ export async function verifyRecoveryReleaseActivation(input: {
   config: RecoveryConfig;
   expectedRelease: RecoveryReleaseDescriptor;
   timeoutMs?: number;
-}, dependencies: Pick<RecoveryInstallerDependencies, 'servicePid'> = {}): Promise<RecoveryActivationVerification> {
+}, dependencies: Pick<RecoveryInstallerDependencies, 'servicePid' | 'platform' | 'systemdEnv'> = {}): Promise<RecoveryActivationVerification> {
   const deadline = Date.now() + (input.timeoutMs ?? 60_000);
   let last: RecoveryActivationVerification = {
     ok: false,
@@ -391,16 +476,21 @@ export async function verifyRecoveryReleaseActivation(input: {
     const gateway = readRecoveryRuntimeIdentity(input.controllerHome, 'gateway');
     const watchdog = readRecoveryRuntimeIdentity(input.controllerHome, 'watchdog');
     const observedPids: Partial<Record<RecoveryRuntimeRole, number>> = {};
-    const servicePid = dependencies.servicePid ?? ((_controllerHome: string, role: RecoveryRuntimeRole) => recoveryLaunchdPid(role));
+    const platform = dependencies.platform ?? process.platform;
+    const servicePid = dependencies.servicePid ?? ((_controllerHome: string, role: RecoveryRuntimeRole) => (
+      platform === 'linux'
+        ? systemdUserServicePid(recoverySystemdLabel(role), dependencies.systemdEnv ?? process.env)
+        : recoveryLaunchdPid(role)
+    ));
     for (const [role, identity] of [['gateway', gateway], ['watchdog', watchdog]] as const) {
       const managedPid = servicePid(input.controllerHome, role);
-      if (!managedPid) failures.push(`${role} launchd PID is unavailable`);
+      if (!managedPid) failures.push(`${role} service-owner PID is unavailable`);
       else observedPids[role] = managedPid;
       if (input.expectedRelease.legacy) continue;
       if (!identity) failures.push(`${role} runtime identity missing`);
       else {
         if (!isProcessAlive(identity.pid)) failures.push(`${role} PID ${identity.pid} is not alive`);
-        if (managedPid !== undefined && identity.pid !== managedPid) failures.push(`${role} runtime identity PID does not match launchd PID`);
+        if (managedPid !== undefined && identity.pid !== managedPid) failures.push(`${role} runtime identity PID does not match service-owner PID`);
         if (identity.releasePath !== input.expectedRelease.releasePath) failures.push(`${role} release path mismatch`);
         if (identity.releaseRevision !== input.expectedRelease.releaseRevision) failures.push(`${role} release revision mismatch`);
         if (identity.manifestSha256 !== input.expectedRelease.manifestSha256) failures.push(`${role} manifest hash mismatch`);
@@ -412,8 +502,9 @@ export async function verifyRecoveryReleaseActivation(input: {
         signal: AbortSignal.timeout(3_000),
       });
       healthStatus = response.status;
-      const health = await response.json() as { status?: unknown; releaseRevision?: unknown; manifestSha256?: unknown };
+      const health = await response.json() as { status?: unknown; version?: unknown; releaseRevision?: unknown; manifestSha256?: unknown };
       if (response.status !== 200 || health.status !== 'ok') failures.push(`gateway health HTTP ${response.status}`);
+      if (input.expectedRelease.productVersion && health.version !== input.expectedRelease.productVersion) failures.push('gateway health product version mismatch');
       if (!input.expectedRelease.legacy || health.releaseRevision !== undefined) {
         if (health.releaseRevision !== input.expectedRelease.releaseRevision) failures.push('gateway health release revision mismatch');
       }
@@ -437,79 +528,17 @@ export async function verifyRecoveryReleaseActivation(input: {
   return last;
 }
 
-interface RecoveryReleaseLockRecord {
-  schemaVersion?: 1;
-  pid: number;
-  instanceId: string;
-  processStartTime?: string;
-  acquiredAt: string;
-  action?: string;
-}
-
-function processStartTime(pid: number): string | undefined {
-  const result = runProcess('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], { timeoutMs: 2_000, maxOutputBytes: 4_096 });
-  return result.ok ? result.stdout.trim() || undefined : undefined;
-}
-
-function readRecoveryReleaseLock(path: string): RecoveryReleaseLockRecord | undefined {
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8')) as RecoveryReleaseLockRecord;
-    return Number.isInteger(parsed.pid) && typeof parsed.instanceId === 'string' && typeof parsed.acquiredAt === 'string'
-      ? parsed
-      : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function recoveryReleaseLockOwnerAlive(lock: RecoveryReleaseLockRecord): boolean {
-  if (!isProcessAlive(lock.pid)) return false;
-  if (!lock.processStartTime) return true;
-  const observed = processStartTime(lock.pid);
-  return observed === undefined || observed === lock.processStartTime;
-}
-
 function acquireRecoveryReleaseLock(controllerHome: string): { path: string; instanceId: string; close: () => void } {
-  const path = join(recoveryRoot(controllerHome), 'locks', 'operation.lock');
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const instanceId = `recovery-release-${randomUUID()}`;
-  const record: RecoveryReleaseLockRecord = {
-    schemaVersion: 1,
-    pid: process.pid,
-    instanceId,
-    processStartTime: processStartTime(process.pid),
-    acquiredAt: new Date().toISOString(),
+  const attempt = acquireRecoveryOperationLock({
+    controllerHome,
     action: 'install_recovery_release',
-  };
-  let fd: number | undefined;
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      fd = openSync(path, 'wx', 0o600);
-      writeFileSync(fd, JSON.stringify(record));
-      break;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
-      const existing = readRecoveryReleaseLock(path);
-      if (!existing) throw new Error('RECOVERY_OPERATION_LOCK_UNCERTAIN');
-      if (recoveryReleaseLockOwnerAlive(existing)) throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
-      const latest = readRecoveryReleaseLock(path);
-      if (!latest || latest.instanceId !== existing.instanceId || recoveryReleaseLockOwnerAlive(latest)) {
-        if (attempt === 1) throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
-        continue;
-      }
-      try { writeFileSync(`${path}.stale-${Date.now()}-${existing.instanceId}`, readFileSync(path)); } catch { /* evidence best effort */ }
-      rmSync(path, { force: true });
-    }
-  }
-  if (fd === undefined) throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
+    instanceIdPrefix: 'recovery-release-',
+  });
+  if (!attempt.acquired) throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
   return {
-    path,
-    instanceId,
-    close: () => {
-      closeSync(fd);
-      const current = readRecoveryReleaseLock(path);
-      if (current?.instanceId === instanceId) rmSync(path, { force: true });
-    },
+    path: attempt.handle.path,
+    instanceId: attempt.handle.record.instanceId,
+    close: attempt.handle.close,
   };
 }
 
@@ -518,8 +547,53 @@ async function handoffRecoveryServices(input: {
   config: RecoveryConfig;
   expectedRelease: RecoveryReleaseDescriptor;
   dependencies: RecoveryInstallerDependencies;
-}): Promise<{ gateway: SafeHandoffResult; watchdog: SafeHandoffResult; verification: RecoveryActivationVerification }> {
-  if (process.platform !== 'darwin' && !input.dependencies.handoff) throw new Error('RECOVERY_RELEASE_ACTIVATION_REQUIRES_MACOS');
+}): Promise<{ gateway: RecoveryServiceHandoffResult; watchdog: RecoveryServiceHandoffResult; verification: RecoveryActivationVerification }> {
+  const platform = input.dependencies.platform ?? process.platform;
+  if (platform === 'linux' && !input.dependencies.handoff) {
+    const env = input.dependencies.systemdEnv ?? process.env;
+    const available = input.dependencies.systemdAvailable ?? systemdUserAvailable;
+    if (!available(env)) throw new Error('RECOVERY_SYSTEMD_USER_UNAVAILABLE');
+    const installUnit = input.dependencies.installSystemdUnit ?? installSystemdUserUnit;
+    const gatewayPath = installUnit({
+      unitName: RECOVERY_GATEWAY_LABEL,
+      unit: recoverySystemdUserUnitInput(input.controllerHome, 'gateway', env, recoveryReleaseProductVersion(input.expectedRelease)),
+      env,
+      errorPrefix: 'RECOVERY_SYSTEMD_INSTALL_FAILED',
+    });
+    const watchdogPath = installUnit({
+      unitName: RECOVERY_WATCHDOG_LABEL,
+      unit: recoverySystemdUserUnitInput(input.controllerHome, 'watchdog', env, recoveryReleaseProductVersion(input.expectedRelease)),
+      env,
+      errorPrefix: 'RECOVERY_SYSTEMD_INSTALL_FAILED',
+    });
+    const verification = await (input.dependencies.verify
+      ?? ((verifyInput) => verifyRecoveryReleaseActivation(verifyInput, input.dependencies)))({
+      controllerHome: input.controllerHome,
+      config: input.config,
+      expectedRelease: input.expectedRelease,
+    });
+    if (!verification.ok) throw new Error(`RECOVERY_RELEASE_VERIFICATION_FAILED: ${verification.failures.join('; ')}`);
+    return {
+      gateway: {
+        platform: 'systemd-user',
+        serviceRegistered: true,
+        pidReady: Boolean(verification.gatewayPid),
+        portReady: verification.healthStatus === 200,
+        servicePath: gatewayPath,
+        pid: verification.gatewayPid,
+      },
+      watchdog: {
+        platform: 'systemd-user',
+        serviceRegistered: true,
+        pidReady: Boolean(verification.watchdogPid),
+        portReady: true,
+        servicePath: watchdogPath,
+        pid: verification.watchdogPid,
+      },
+      verification,
+    };
+  }
+  if (platform !== 'darwin' && !input.dependencies.handoff) throw new Error(`RECOVERY_RELEASE_ACTIVATION_UNSUPPORTED_PLATFORM: ${platform}`);
   const uid = (input.dependencies.uid ?? (() => typeof process.getuid === 'function' ? process.getuid() : Number.NaN))();
   if (!Number.isInteger(uid)) throw new Error('RECOVERY_LAUNCHD_UID_UNAVAILABLE');
   const domain = `gui/${uid}`;
@@ -533,8 +607,9 @@ async function handoffRecoveryServices(input: {
     mkdirSync(auditRoot, { recursive: true, mode: 0o700 });
     const gatewayPath = join(generatedRoot, `${RECOVERY_GATEWAY_LABEL}.plist`);
     const watchdogPath = join(generatedRoot, `${RECOVERY_WATCHDOG_LABEL}.plist`);
-    writeFileSync(gatewayPath, recoveryPlist({ label: RECOVERY_GATEWAY_LABEL, executable: join(recoveryCurrentPath(input.controllerHome), 'forge-recovery-gateway'), command: 'gateway', controllerHome: resolve(input.controllerHome), logPath: join(auditRoot, 'gateway.log') }), { mode: 0o600 });
-    writeFileSync(watchdogPath, recoveryPlist({ label: RECOVERY_WATCHDOG_LABEL, executable: join(recoveryCurrentPath(input.controllerHome), 'forge-recovery-watchdog'), command: 'watchdog', controllerHome: resolve(input.controllerHome), logPath: join(auditRoot, 'watchdog.log') }), { mode: 0o600 });
+    const productVersion = recoveryReleaseProductVersion(input.expectedRelease);
+    writeFileSync(gatewayPath, recoveryPlist({ label: RECOVERY_GATEWAY_LABEL, executable: join(recoveryCurrentPath(input.controllerHome), 'forge-recovery-gateway'), command: 'gateway', controllerHome: resolve(input.controllerHome), logPath: join(auditRoot, 'gateway.log'), productVersion }), { mode: 0o600 });
+    writeFileSync(watchdogPath, recoveryPlist({ label: RECOVERY_WATCHDOG_LABEL, executable: join(recoveryCurrentPath(input.controllerHome), 'forge-recovery-watchdog'), command: 'watchdog', controllerHome: resolve(input.controllerHome), logPath: join(auditRoot, 'watchdog.log'), productVersion }), { mode: 0o600 });
     return {
       gateway: installAgent(gatewayPath, RECOVERY_GATEWAY_LABEL).path,
       watchdog: installAgent(watchdogPath, RECOVERY_WATCHDOG_LABEL).path,
@@ -542,7 +617,7 @@ async function handoffRecoveryServices(input: {
   })();
   const currentPid = input.dependencies.currentPid ?? defaultCurrentPid;
   const handoff = input.dependencies.handoff ?? safeLaunchdHandoff;
-  const gateway = await handoff({
+  const gatewayLaunchd = await handoff({
     label: RECOVERY_GATEWAY_LABEL,
     plistPath: generated.gateway,
     domain,
@@ -551,10 +626,10 @@ async function handoffRecoveryServices(input: {
     maxBootoutWaitMs: 20_000,
     maxBootstrapRetry: 3,
   });
-  if (!gateway.serviceRegistered || !gateway.pidWaitClean || !gateway.portWaitClean) {
+  if (!gatewayLaunchd.serviceRegistered || !gatewayLaunchd.pidWaitClean || !gatewayLaunchd.portWaitClean) {
     throw new Error('RECOVERY_GATEWAY_HANDOFF_FAILED');
   }
-  const watchdog = await handoff({
+  const watchdogLaunchd = await handoff({
     label: RECOVERY_WATCHDOG_LABEL,
     plistPath: generated.watchdog,
     domain,
@@ -562,7 +637,7 @@ async function handoffRecoveryServices(input: {
     maxBootoutWaitMs: 20_000,
     maxBootstrapRetry: 3,
   });
-  if (!watchdog.serviceRegistered || !watchdog.pidWaitClean) throw new Error('RECOVERY_WATCHDOG_HANDOFF_FAILED');
+  if (!watchdogLaunchd.serviceRegistered || !watchdogLaunchd.pidWaitClean) throw new Error('RECOVERY_WATCHDOG_HANDOFF_FAILED');
   const verification = await (input.dependencies.verify
     ?? ((verifyInput) => verifyRecoveryReleaseActivation(verifyInput, input.dependencies)))({
     controllerHome: input.controllerHome,
@@ -570,13 +645,18 @@ async function handoffRecoveryServices(input: {
     expectedRelease: input.expectedRelease,
   });
   if (!verification.ok) throw new Error(`RECOVERY_RELEASE_VERIFICATION_FAILED: ${verification.failures.join('; ')}`);
-  return { gateway, watchdog, verification };
+  return {
+    gateway: { platform: 'launchd', serviceRegistered: gatewayLaunchd.serviceRegistered, pidReady: gatewayLaunchd.pidWaitClean, portReady: gatewayLaunchd.portWaitClean, servicePath: generated.gateway, launchd: gatewayLaunchd },
+    watchdog: { platform: 'launchd', serviceRegistered: watchdogLaunchd.serviceRegistered, pidReady: watchdogLaunchd.pidWaitClean, portReady: watchdogLaunchd.portWaitClean, servicePath: generated.watchdog, launchd: watchdogLaunchd },
+    verification,
+  };
 }
 
 function sameRecoveryReleasePayload(left: RecoveryReleaseDescriptor, right: RecoveryReleaseDescriptor): boolean {
   return left.releaseRevision === right.releaseRevision
     && left.sourceCommit === right.sourceCommit
     && left.cleanWorkspace === right.cleanWorkspace
+    && left.productVersion === right.productVersion
     && RECOVERY_RELEASE_BINARIES.every((binary) => left.artifacts[binary].sha256 === right.artifacts[binary].sha256);
 }
 
@@ -647,7 +727,7 @@ export interface RecoveryTunnelLaunchdContract {
 }
 
 function inspectLaunchdRestartContract(
-  service: Pick<PublicTunnelServiceConfig | PrimaryConnectorServiceConfig, 'platform' | 'label' | 'plistPath'>,
+  service: { platform: 'launchd'; label: string; plistPath?: string },
   allowConditionalKeepAlive: boolean,
 ): RecoveryTunnelLaunchdContract {
   const plistPath = service.plistPath ?? launchAgentPath(service.label);
@@ -670,31 +750,50 @@ function inspectLaunchdRestartContract(
 }
 
 export function inspectRecoveryTunnelLaunchdContract(
-  service: Pick<PublicTunnelServiceConfig | PrimaryConnectorServiceConfig, 'platform' | 'label' | 'plistPath'>,
+  service: LaunchdPublicTunnelServiceConfig,
 ): RecoveryTunnelLaunchdContract {
   return inspectLaunchdRestartContract(service, false);
 }
 
 export function inspectPrimaryConnectorLaunchdContract(
-  service: Pick<PrimaryConnectorServiceConfig, 'platform' | 'label' | 'plistPath'>,
+  service: LaunchdPrimaryConnectorServiceConfig,
 ): RecoveryTunnelLaunchdContract {
   return inspectLaunchdRestartContract(service, true);
 }
 
 export function inspectPrimaryPublicTunnelLaunchdContract(
-  service: Pick<PublicTunnelServiceConfig, 'platform' | 'label' | 'plistPath'>,
+  service: LaunchdPublicTunnelServiceConfig,
 ): RecoveryTunnelLaunchdContract {
   return inspectLaunchdRestartContract(service, true);
 }
 
+function pathInside(parent: string, candidate: string): boolean {
+  const rel = relative(resolve(parent), resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/') && !rel.startsWith('\\'));
+}
+
+function assertDurablePrimaryRuntimeSourceRoot(controllerHome: string, sourceRoot: string, env: NodeJS.ProcessEnv = process.env): void {
+  const root = resolve(sourceRoot);
+  const normalizedSegments = root.replace(/\\/g, '/').split('/').filter(Boolean);
+  const explicitWorktreeHome = env.FORGE_WORKTREE_HOME?.trim();
+  const underExplicitWorktreeHome = explicitWorktreeHome ? pathInside(explicitWorktreeHome, root) : false;
+  if (normalizedSegments.includes('managed-worktrees') || underExplicitWorktreeHome) {
+    throw new Error(`RECOVERY_PRIMARY_RUNTIME_SOURCE_ROOT_DURABLE_REQUIRED: ${root}`);
+  }
+  if (pathInside(resolve(controllerHome, 'managed-worktrees'), root)) {
+    throw new Error(`RECOVERY_PRIMARY_RUNTIME_SOURCE_ROOT_DURABLE_REQUIRED: ${root}`);
+  }
+}
+
 export async function installStandaloneRecovery(input: {
   controllerHome: string;
   repoRoot: string;
+  primaryRuntimeSourceRepositoryId?: string;
   sourceRoot?: string;
   port?: number;
   publicMcpUrl?: string;
   recoveryPublicUrl?: string;
-  recoveryTunnelService?: PublicTunnelServiceConfig;
+  recoveryTunnelService?: RecoveryTunnelServiceConfig;
   primaryPublicTunnelService?: PublicTunnelServiceConfig;
   primaryRuntimeService?: PrimaryRuntimeServiceConfig;
   primaryConnectorService?: PrimaryConnectorServiceConfig;
@@ -702,6 +801,12 @@ export async function installStandaloneRecovery(input: {
 }, dependencies: RecoveryInstallerDependencies = {}): Promise<RecoveryInstallResult> {
   const controllerHome = resolve(input.controllerHome);
   const sourceRoot = resolve(input.sourceRoot ?? input.repoRoot);
+  const primaryRuntimeSourceRoot = resolve(input.repoRoot);
+  const primaryRuntimeSourceRepositoryId = input.primaryRuntimeSourceRepositoryId?.trim();
+  if (!input.stageOnly) {
+    assertDurablePrimaryRuntimeSourceRoot(controllerHome, primaryRuntimeSourceRoot);
+    if (!primaryRuntimeSourceRepositoryId) throw new Error('RECOVERY_PRIMARY_RUNTIME_SOURCE_REPOSITORY_ID_REQUIRED');
+  }
   if (input.recoveryTunnelService?.platform === 'launchd') {
     const tunnelContract = inspectRecoveryTunnelLaunchdContract(input.recoveryTunnelService);
     if (!tunnelContract.plistInstalled) {
@@ -729,17 +834,20 @@ export async function installStandaloneRecovery(input: {
       throw new Error('RECOVERY_PRIMARY_CONNECTOR_LAUNCHD_RESTART_CONTRACT_REQUIRED: RunAtLoad=true and KeepAlive=true or KeepAlive.SuccessfulExit=false');
     }
   }
+  const staged = stageRecoveryRelease({ controllerHome, sourceRoot }, dependencies);
+  if (input.stageOnly) {
+    return { controllerHome, staged, config: loadRecoveryConfig(controllerHome) };
+  }
   const config = initializeStandaloneRecovery(controllerHome, input.port ?? 8787, {
     ...(input.publicMcpUrl ? { publicMcpUrl: input.publicMcpUrl } : {}),
     ...(input.recoveryPublicUrl ? { recoveryPublicUrl: input.recoveryPublicUrl } : {}),
     ...(input.recoveryTunnelService ? { recoveryTunnelService: input.recoveryTunnelService } : {}),
     ...(input.primaryPublicTunnelService ? { primaryPublicTunnelService: input.primaryPublicTunnelService } : {}),
     ...(input.primaryRuntimeService ? { primaryRuntimeService: input.primaryRuntimeService } : {}),
-    primaryRuntimeSourceRoot: resolve(input.repoRoot),
+    primaryRuntimeSourceRoot,
+    ...(primaryRuntimeSourceRepositoryId ? { primaryRuntimeSourceRepositoryId } : {}),
     ...(input.primaryConnectorService ? { primaryConnectorService: input.primaryConnectorService } : {}),
   });
-  const staged = stageRecoveryRelease({ controllerHome, sourceRoot }, dependencies);
-  if (input.stageOnly) return { controllerHome, staged, config };
   const activated = await activateRecoveryRelease({ controllerHome, config, candidate: staged.release }, dependencies);
   return { controllerHome, staged, activated, config };
 }