@moretea-labs/forge 1.7.2 → 1.8.1

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,10 +22,19 @@ import {
   type SafeHandoffResult,
 } from '../../cli/controller/launch-agents';
 import { isProcessAlive } from '../shared/process-tree';
+import {
+  installSystemdUserUnit,
+  systemdUserAvailable,
+  systemdUserServicePid,
+  systemdUserUnitName,
+  systemdUserUnitPath,
+  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 { RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
-export { RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
+import { initializeStandaloneRecovery, loadRecoveryConfig, normalizeRecoveryInstallProfile, recoveryInstallProfileRoles, type LaunchdPrimaryConnectorServiceConfig, type LaunchdPublicTunnelServiceConfig, type PrimaryConnectorServiceConfig, type PrimaryRuntimeServiceConfig, type PublicTunnelServiceConfig, type RecoveryConfig, type RecoveryInstallProfile, type RecoveryTunnelServiceConfig } from './core';
+import { RECOVERY_DAEMON_LABEL, RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
+import { acquireRecoveryOperationLock } from './operation-lock';
+export { RECOVERY_DAEMON_LABEL, RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
 import {
   RECOVERY_RELEASE_BINARIES,
   RECOVERY_RELEASE_ROLE_CANARY_ARG,
@@ -40,6 +48,7 @@ import {
   recoveryPreviousPath,
   recoveryReleasesRoot,
   recoveryRoot,
+  setRecoveryGatewayDraining,
   writeRecoveryReleaseManifest,
   type RecoveryReleaseDescriptor,
   type RecoveryReleaseManifest,
@@ -71,7 +80,7 @@ export function retireStaleRecoveryLaunchAgents(
 ): string[] {
   const generatedRoot = join(recoveryRoot(controllerHome), 'launchd');
   if (!existsSync(generatedRoot)) return [];
-  const activeLabels = new Set([RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL]);
+  const activeLabels = new Set([RECOVERY_DAEMON_LABEL]);
   const retired: string[] = [];
   for (const name of readdirSync(generatedRoot)) {
     if (!name.endsWith('.plist')) continue;
@@ -124,20 +133,28 @@ export interface RecoveryActivationVerification {
   ok: boolean;
   expectedReleaseRevision: string;
   failures: string[];
+  daemonPid?: number;
   gatewayPid?: number;
   watchdogPid?: number;
   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;
-  };
+  handoff?: Partial<Record<RecoveryRuntimeRole, RecoveryServiceHandoffResult>>;
   verification: RecoveryActivationVerification;
   rollback?: {
     release: RecoveryReleaseDescriptor;
@@ -147,22 +164,28 @@ export interface RecoveryActivationResult {
 
 export interface RecoveryInstallResult {
   controllerHome: string;
+  profile: RecoveryInstallProfile;
   staged: StagedRecoveryRelease;
   activated?: RecoveryActivationResult;
   config: RecoveryConfig;
 }
 
 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: {
     controllerHome: string;
     config: RecoveryConfig;
     expectedRelease: RecoveryReleaseDescriptor;
+    profile?: RecoveryInstallProfile;
     timeoutMs?: number;
   }) => Promise<RecoveryActivationVerification>;
   currentPid?: (controllerHome: string, role: RecoveryRuntimeRole) => number | undefined;
@@ -175,6 +198,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 +235,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 +258,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 +281,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,19 +304,20 @@ export function stageRecoveryRelease(input: {
       schemaVersion: 1,
       ...identity,
       builtAt: new Date(now()).toISOString(),
+      productVersion,
       artifacts: completeArtifacts(staging),
     });
     const runCanary = dependencies.runCanary ?? defaultRunCanary;
     const canaries: Array<{ label: string; binaryPath: string; role?: RecoveryRuntimeRole }> = [
       { label: 'primary', binaryPath: primary },
-      { label: 'gateway', binaryPath: join(staging, 'forge-recovery-gateway'), role: 'gateway' },
-      { label: 'watchdog', binaryPath: join(staging, 'forge-recovery-watchdog'), role: 'watchdog' },
+      { label: 'daemon', binaryPath: primary, role: 'daemon' },
     ];
     const canaryDetails: string[] = [];
     for (const canary of canaries) {
       const canaryResult = runCanary({
         binaryPath: canary.binaryPath,
         controllerHome: resolve(input.controllerHome),
+        productVersion,
         role: canary.role,
       });
       if (!canaryResult.ok) {
@@ -331,16 +389,49 @@ 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 === 'daemon' ? 'forge-recovery' : role === 'gateway' ? 'forge-recovery-gateway' : 'forge-recovery-watchdog';
+  return {
+    description: role === 'daemon' ? 'Forge Standalone Recovery' : role === 'gateway' ? 'Forge Standalone Recovery Gateway (legacy)' : 'Forge Standalone Recovery Watchdog (legacy)',
+    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 === 'daemon' ? RECOVERY_DAEMON_LABEL : role === 'gateway' ? RECOVERY_GATEWAY_LABEL : RECOVERY_WATCHDOG_LABEL;
+}
+
+function recoveryRoleServesGateway(role: RecoveryRuntimeRole): boolean {
+  return role === 'daemon' || role === 'gateway';
+}
+
 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`;
@@ -361,7 +452,7 @@ export function recoveryLaunchdServicePid(label: string): number | undefined {
 }
 
 export function recoveryLaunchdPid(role: RecoveryRuntimeRole): number | undefined {
-  return recoveryLaunchdServicePid(role === 'gateway' ? RECOVERY_GATEWAY_LABEL : RECOVERY_WATCHDOG_LABEL);
+  return recoveryLaunchdServicePid(recoverySystemdLabel(role));
 }
 
 function defaultCurrentPid(controllerHome: string, role: RecoveryRuntimeRole): number | undefined {
@@ -374,8 +465,11 @@ export async function verifyRecoveryReleaseActivation(input: {
   controllerHome: string;
   config: RecoveryConfig;
   expectedRelease: RecoveryReleaseDescriptor;
+  profile?: RecoveryInstallProfile;
   timeoutMs?: number;
-}, dependencies: Pick<RecoveryInstallerDependencies, 'servicePid'> = {}): Promise<RecoveryActivationVerification> {
+}, dependencies: Pick<RecoveryInstallerDependencies, 'servicePid' | 'platform' | 'systemdEnv'> = {}): Promise<RecoveryActivationVerification> {
+  const profile = normalizeRecoveryInstallProfile(input.profile ?? input.config.installProfile, 'self-healing');
+  const selectedRoles = new Set(recoveryInstallProfileRoles(profile));
   const deadline = Date.now() + (input.timeoutMs ?? 60_000);
   let last: RecoveryActivationVerification = {
     ok: false,
@@ -388,45 +482,57 @@ export async function verifyRecoveryReleaseActivation(input: {
     if (!current || current.releasePath !== input.expectedRelease.releasePath || current.manifestSha256 !== input.expectedRelease.manifestSha256) {
       failures.push('Recovery current authority does not match expected release');
     }
-    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));
-    for (const [role, identity] of [['gateway', gateway], ['watchdog', watchdog]] as const) {
+    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 of ['daemon', 'gateway', 'watchdog'] as const) {
       const managedPid = servicePid(input.controllerHome, role);
-      if (!managedPid) failures.push(`${role} launchd PID is unavailable`);
+      if (!selectedRoles.has(role)) {
+        if (managedPid) failures.push(`${role} service remains active outside Recovery profile ${profile}`);
+        continue;
+      }
+      const identity = readRecoveryRuntimeIdentity(input.controllerHome, role);
+      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`);
       }
     }
     let healthStatus: number | undefined;
-    try {
-      const response = await fetch(`http://${input.config.gateway?.host ?? '127.0.0.1'}:${input.config.gateway?.port ?? 8787}/health`, {
-        signal: AbortSignal.timeout(3_000),
-      });
-      healthStatus = response.status;
-      const health = await response.json() as { status?: unknown; releaseRevision?: unknown; manifestSha256?: unknown };
-      if (response.status !== 200 || health.status !== 'ok') failures.push(`gateway health HTTP ${response.status}`);
-      if (!input.expectedRelease.legacy || health.releaseRevision !== undefined) {
-        if (health.releaseRevision !== input.expectedRelease.releaseRevision) failures.push('gateway health release revision mismatch');
-      }
-      if (!input.expectedRelease.legacy || health.manifestSha256 !== undefined) {
-        if (health.manifestSha256 !== input.expectedRelease.manifestSha256) failures.push('gateway health manifest hash mismatch');
+    if ([...selectedRoles].some(recoveryRoleServesGateway)) {
+      try {
+        const response = await fetch(`http://${input.config.gateway?.host ?? '127.0.0.1'}:${input.config.gateway?.port ?? 8787}/health`, {
+          signal: AbortSignal.timeout(3_000),
+        });
+        healthStatus = response.status;
+        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');
+        }
+        if (!input.expectedRelease.legacy || health.manifestSha256 !== undefined) {
+          if (health.manifestSha256 !== input.expectedRelease.manifestSha256) failures.push('gateway health manifest hash mismatch');
+        }
+      } catch (error) {
+        failures.push(`gateway health unavailable: ${error instanceof Error ? error.message : String(error)}`);
       }
-    } catch (error) {
-      failures.push(`gateway health unavailable: ${error instanceof Error ? error.message : String(error)}`);
     }
     last = {
       ok: failures.length === 0,
       expectedReleaseRevision: input.expectedRelease.releaseRevision,
       failures,
+      daemonPid: observedPids.daemon,
       gatewayPid: observedPids.gateway,
       watchdogPid: observedPids.watchdog,
       healthStatus,
@@ -437,146 +543,215 @@ export async function verifyRecoveryReleaseActivation(input: {
   return last;
 }
 
-interface RecoveryReleaseLockRecord {
-  schemaVersion?: 1;
-  pid: number;
-  instanceId: string;
-  processStartTime?: string;
-  acquiredAt: string;
-  action?: string;
-}
+export const RECOVERY_RELEASE_LOCK_WAIT_MS = 10 * 60_000;
+export const RECOVERY_RELEASE_LOCK_POLL_MS = 2_000;
 
-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;
+/**
+ * An explicit operator release install must not fail merely because the Recovery
+ * daemon is inside its own bounded autonomous mutation (release step, tunnel
+ * repair, watchdog escalation). Wait for the single writer to finish, then take
+ * the same mutation lock; the lock still guarantees exactly one writer, and the
+ * bounded wait still fails closed if the holder never releases.
+ */
+export async function acquireRecoveryReleaseLock(
+  controllerHome: string,
+  dependencies: {
+    acquire?: typeof acquireRecoveryOperationLock;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    waitMs?: number;
+    report?: (detail: string) => void;
+  } = {},
+): Promise<{ path: string; instanceId: string; close: () => void }> {
+  const acquire = dependencies.acquire ?? acquireRecoveryOperationLock;
+  const sleep = dependencies.sleep ?? ((ms: number) => new Promise<void>((resolveSleep) => setTimeout(resolveSleep, ms)));
+  const now = dependencies.now ?? Date.now;
+  const report = dependencies.report ?? ((detail: string) => process.stderr.write(detail));
+  const deadline = now() + (dependencies.waitMs ?? RECOVERY_RELEASE_LOCK_WAIT_MS);
+  let reported = false;
+  for (;;) {
+    const attempt = acquire({
+      controllerHome,
+      action: 'install_recovery_release',
+      instanceIdPrefix: 'recovery-release-',
+    });
+    if (attempt.acquired) {
+      return {
+        path: attempt.handle.path,
+        instanceId: attempt.handle.record.instanceId,
+        close: attempt.handle.close,
+      };
+    }
+    if (now() >= deadline) {
+      throw new Error(`RECOVERY_OPERATION_LOCK_BUSY: ${attempt.owner.action} pid=${attempt.owner.pid} acquiredAt=${attempt.owner.acquiredAt}`);
+    }
+    if (!reported) {
+      report(
+        `recovery release install waiting for in-flight Recovery mutation: action=${attempt.owner.action} pid=${attempt.owner.pid} acquiredAt=${attempt.owner.acquiredAt}\n`,
+      );
+      reported = true;
+    }
+    await sleep(RECOVERY_RELEASE_LOCK_POLL_MS);
+  }
 }
 
-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 recoveryRoleLabel(role: RecoveryRuntimeRole): string {
+  return recoverySystemdLabel(role);
 }
 
-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(),
-    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 });
+function retireRecoveryRoleService(input: {
+  controllerHome: string;
+  role: RecoveryRuntimeRole;
+  dependencies: RecoveryInstallerDependencies;
+}): void {
+  const platform = input.dependencies.platform ?? process.platform;
+  const label = recoveryRoleLabel(input.role);
+  if (platform === 'linux' && !input.dependencies.handoff) {
+    const env = input.dependencies.systemdEnv ?? process.env;
+    const unit = systemdUserUnitName(label);
+    const unitPath = systemdUserUnitPath(unit, env);
+    const disabled = runProcess('systemctl', ['--user', 'disable', '--now', unit], {
+      env,
+      timeoutMs: 30_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    const detail = `${disabled.stderr}\n${disabled.stdout}`;
+    if (!disabled.ok && !/not loaded|not found|does not exist|not enabled|no files found/i.test(detail)) {
+      throw new Error(`RECOVERY_SYSTEMD_RETIRE_FAILED: ${unit}: ${detail.trim()}`);
     }
+    rmSync(unitPath, { force: true });
+    const reload = runProcess('systemctl', ['--user', 'daemon-reload'], {
+      env,
+      timeoutMs: 30_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (!reload.ok) throw new Error(`RECOVERY_SYSTEMD_DAEMON_RELOAD_FAILED: ${reload.stderr || reload.stdout}`);
+    return;
   }
-  if (fd === undefined) 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 });
-    },
-  };
+  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 runner = input.dependencies.launchctlRunner ?? defaultRecoveryLaunchctl;
+  const target = `gui/${uid}/${label}`;
+  const observed = runner(['print', target]);
+  if (observed.ok) {
+    const bootout = runner(['bootout', target]);
+    if (!bootout.ok && !bootoutAlreadyGone(`${bootout.stderr}\n${bootout.stdout}`)) {
+      throw new Error(`RECOVERY_SERVICE_RETIRE_FAILED: ${label}`);
+    }
+  }
+  rmSync(join(recoveryRoot(input.controllerHome), 'launchd', `${label}.plist`), { force: true });
+  rmSync(launchAgentPath(label), { force: true });
 }
 
 async function handoffRecoveryServices(input: {
   controllerHome: string;
   config: RecoveryConfig;
   expectedRelease: RecoveryReleaseDescriptor;
+  profile: RecoveryInstallProfile;
   dependencies: RecoveryInstallerDependencies;
-}): Promise<{ gateway: SafeHandoffResult; watchdog: SafeHandoffResult; verification: RecoveryActivationVerification }> {
-  if (process.platform !== 'darwin' && !input.dependencies.handoff) throw new Error('RECOVERY_RELEASE_ACTIVATION_REQUIRES_MACOS');
-  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}`;
-  retireStaleRecoveryLaunchAgents(input.controllerHome, uid, input.dependencies.launchctlRunner);
-  const installAgent = input.dependencies.installAgent ?? installLaunchAgent;
-  const generated = (() => {
-    const root = recoveryRoot(input.controllerHome);
-    const generatedRoot = join(root, 'launchd');
-    const auditRoot = join(root, 'audit');
+}): Promise<{ services: Partial<Record<RecoveryRuntimeRole, RecoveryServiceHandoffResult>>; verification: RecoveryActivationVerification }> {
+  const platform = input.dependencies.platform ?? process.platform;
+  const selectedRoles = new Set(recoveryInstallProfileRoles(input.profile));
+  for (const role of ['gateway', 'watchdog'] as const) {
+    if (!selectedRoles.has(role)) retireRecoveryRoleService({ controllerHome: input.controllerHome, role, dependencies: input.dependencies });
+  }
+
+  const services: Partial<Record<RecoveryRuntimeRole, RecoveryServiceHandoffResult>> = {};
+  if (platform === 'linux' && !input.dependencies.handoff) {
+    const env = input.dependencies.systemdEnv ?? process.env;
+    const available = input.dependencies.systemdAvailable ?? systemdUserAvailable;
+    if (selectedRoles.size > 0 && !available(env)) throw new Error('RECOVERY_SYSTEMD_USER_UNAVAILABLE');
+    const installUnit = input.dependencies.installSystemdUnit ?? installSystemdUserUnit;
+    for (const role of recoveryInstallProfileRoles(input.profile)) {
+      const servicePath = installUnit({
+        unitName: recoveryRoleLabel(role),
+        unit: recoverySystemdUserUnitInput(input.controllerHome, role, env, recoveryReleaseProductVersion(input.expectedRelease)),
+        env,
+        errorPrefix: 'RECOVERY_SYSTEMD_INSTALL_FAILED',
+      });
+      services[role] = {
+        platform: 'systemd-user',
+        serviceRegistered: true,
+        pidReady: false,
+        portReady: !recoveryRoleServesGateway(role),
+        servicePath,
+      };
+    }
+  } else {
+    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}`;
+    retireStaleRecoveryLaunchAgents(input.controllerHome, uid, input.dependencies.launchctlRunner);
+    const installAgent = input.dependencies.installAgent ?? installLaunchAgent;
+    const currentPid = input.dependencies.currentPid ?? defaultCurrentPid;
+    const handoff = input.dependencies.handoff ?? safeLaunchdHandoff;
+    const generatedRoot = join(recoveryRoot(input.controllerHome), 'launchd');
+    const auditRoot = join(recoveryRoot(input.controllerHome), 'audit');
     mkdirSync(generatedRoot, { recursive: true, mode: 0o700 });
     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 });
-    return {
-      gateway: installAgent(gatewayPath, RECOVERY_GATEWAY_LABEL).path,
-      watchdog: installAgent(watchdogPath, RECOVERY_WATCHDOG_LABEL).path,
-    };
-  })();
-  const currentPid = input.dependencies.currentPid ?? defaultCurrentPid;
-  const handoff = input.dependencies.handoff ?? safeLaunchdHandoff;
-  const gateway = await handoff({
-    label: RECOVERY_GATEWAY_LABEL,
-    plistPath: generated.gateway,
-    domain,
-    oldPid: currentPid(input.controllerHome, 'gateway'),
-    port: input.config.gateway?.port,
-    maxBootoutWaitMs: 20_000,
-    maxBootstrapRetry: 3,
-  });
-  if (!gateway.serviceRegistered || !gateway.pidWaitClean || !gateway.portWaitClean) {
-    throw new Error('RECOVERY_GATEWAY_HANDOFF_FAILED');
+    const productVersion = recoveryReleaseProductVersion(input.expectedRelease);
+    for (const role of recoveryInstallProfileRoles(input.profile)) {
+      const label = recoveryRoleLabel(role);
+      const generatedPath = join(generatedRoot, `${label}.plist`);
+      writeFileSync(generatedPath, recoveryPlist({
+        label,
+        executable: join(recoveryCurrentPath(input.controllerHome), role === 'daemon' ? 'forge-recovery' : role === 'gateway' ? 'forge-recovery-gateway' : 'forge-recovery-watchdog'),
+        command: role,
+        controllerHome: resolve(input.controllerHome),
+        logPath: join(auditRoot, `${role}.log`),
+        productVersion,
+      }), { mode: 0o600 });
+      const installedPath = installAgent(generatedPath, label).path;
+      const launched = await handoff({
+        label,
+        plistPath: installedPath,
+        domain,
+        oldPid: currentPid(input.controllerHome, role),
+        ...(recoveryRoleServesGateway(role) ? { port: input.config.gateway?.port } : {}),
+        maxBootoutWaitMs: 20_000,
+        maxBootstrapRetry: 3,
+      });
+      if (!launched.serviceRegistered || !launched.pidWaitClean || (recoveryRoleServesGateway(role) && !launched.portWaitClean)) {
+        throw new Error(role === 'daemon' ? 'RECOVERY_DAEMON_HANDOFF_FAILED' : role === 'gateway' ? 'RECOVERY_GATEWAY_HANDOFF_FAILED' : 'RECOVERY_WATCHDOG_HANDOFF_FAILED');
+      }
+      services[role] = {
+        platform: 'launchd',
+        serviceRegistered: launched.serviceRegistered,
+        pidReady: launched.pidWaitClean,
+        portReady: recoveryRoleServesGateway(role) ? launched.portWaitClean : true,
+        servicePath: installedPath,
+        launchd: launched,
+      };
+    }
   }
-  const watchdog = await handoff({
-    label: RECOVERY_WATCHDOG_LABEL,
-    plistPath: generated.watchdog,
-    domain,
-    oldPid: currentPid(input.controllerHome, 'watchdog'),
-    maxBootoutWaitMs: 20_000,
-    maxBootstrapRetry: 3,
-  });
-  if (!watchdog.serviceRegistered || !watchdog.pidWaitClean) throw new Error('RECOVERY_WATCHDOG_HANDOFF_FAILED');
+
   const verification = await (input.dependencies.verify
     ?? ((verifyInput) => verifyRecoveryReleaseActivation(verifyInput, input.dependencies)))({
     controllerHome: input.controllerHome,
     config: input.config,
     expectedRelease: input.expectedRelease,
+    profile: input.profile,
   });
   if (!verification.ok) throw new Error(`RECOVERY_RELEASE_VERIFICATION_FAILED: ${verification.failures.join('; ')}`);
-  return { gateway, watchdog, verification };
+  for (const role of recoveryInstallProfileRoles(input.profile)) {
+    const service = services[role];
+    if (!service) continue;
+    service.pid = role === 'daemon' ? verification.daemonPid : role === 'gateway' ? verification.gatewayPid : verification.watchdogPid;
+    service.pidReady = Boolean(service.pid);
+    if (recoveryRoleServesGateway(role)) service.portReady = verification.healthStatus === 200;
+  }
+  return { services, 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);
 }
 
@@ -587,7 +762,8 @@ export async function activateRecoveryRelease(input: {
 }, dependencies: RecoveryInstallerDependencies = {}): Promise<RecoveryActivationResult> {
   const controllerHome = resolve(input.controllerHome);
   const config = input.config ?? loadRecoveryConfig(controllerHome);
-  const lock = acquireRecoveryReleaseLock(controllerHome);
+  const profile = normalizeRecoveryInstallProfile(config.installProfile, 'self-healing');
+  const lock = await acquireRecoveryReleaseLock(controllerHome);
   const current = readCurrentRecoveryRelease(controllerHome);
   try {
     if (current && sameRecoveryReleasePayload(current, input.candidate)) {
@@ -596,6 +772,7 @@ export async function activateRecoveryRelease(input: {
         controllerHome,
         config,
         expectedRelease: current,
+        profile,
       });
       if (verification.ok) {
         return {
@@ -608,28 +785,37 @@ export async function activateRecoveryRelease(input: {
     }
     const previous = current ?? captureLegacyRecoveryRelease(controllerHome, dependencies);
     const migratedLegacy = previous?.legacy ? previous : undefined;
-    publishRecoveryRelease(controllerHome, input.candidate.releasePath, previous?.releasePath);
-    publishRecoveryCompatibilityLinks(controllerHome);
+    const drainArmed = Boolean(current);
     try {
-      const activated = await handoffRecoveryServices({ controllerHome, config, expectedRelease: input.candidate, dependencies });
-      return { release: input.candidate, previous, migratedLegacy, handoff: { gateway: activated.gateway, watchdog: activated.watchdog }, verification: activated.verification };
-    } catch (activationError) {
-      if (!previous) throw activationError;
-      publishRecoveryRelease(controllerHome, previous.releasePath, input.candidate.releasePath);
+      // The shared operation lock already excludes every Recovery mutation.
+      // Stop new transport admission during handoff; retained read streams are
+      // connections, not effects, and cannot be a second quiescence authority.
+      if (drainArmed) setRecoveryGatewayDraining(controllerHome, true);
+      publishRecoveryRelease(controllerHome, input.candidate.releasePath, previous?.releasePath);
       publishRecoveryCompatibilityLinks(controllerHome);
-      let rollbackResult: Awaited<ReturnType<typeof handoffRecoveryServices>>;
       try {
-        rollbackResult = await handoffRecoveryServices({ controllerHome, config, expectedRelease: previous, dependencies });
-      } catch (rollbackError) {
+        const activated = await handoffRecoveryServices({ controllerHome, config, expectedRelease: input.candidate, profile, dependencies });
+        return { release: input.candidate, previous, migratedLegacy, handoff: activated.services, verification: activated.verification };
+      } catch (activationError) {
+        if (!previous) throw activationError;
+        publishRecoveryRelease(controllerHome, previous.releasePath, input.candidate.releasePath);
+        publishRecoveryCompatibilityLinks(controllerHome);
+        let rollbackResult: Awaited<ReturnType<typeof handoffRecoveryServices>>;
+        try {
+          rollbackResult = await handoffRecoveryServices({ controllerHome, config, expectedRelease: previous, profile, dependencies });
+        } catch (rollbackError) {
+          throw new Error(
+            `RECOVERY_RELEASE_ACTIVATION_FAILED: ${activationError instanceof Error ? activationError.message : String(activationError)}; `
+            + `rollback to ${previous.releaseRevision} failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+          );
+        }
         throw new Error(
-          `RECOVERY_RELEASE_ACTIVATION_FAILED: ${activationError instanceof Error ? activationError.message : String(activationError)}; `
-          + `rollback to ${previous.releaseRevision} failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+          `RECOVERY_RELEASE_ACTIVATION_FAILED_ROLLED_BACK: ${activationError instanceof Error ? activationError.message : String(activationError)}; `
+          + `restored=${previous.releaseRevision}; recovery=${rollbackResult.verification.daemonPid ?? rollbackResult.verification.gatewayPid ?? 'unknown'}`,
         );
       }
-      throw new Error(
-        `RECOVERY_RELEASE_ACTIVATION_FAILED_ROLLED_BACK: ${activationError instanceof Error ? activationError.message : String(activationError)}; `
-        + `restored=${previous.releaseRevision}; gateway=${rollbackResult.verification.gatewayPid ?? 'unknown'}; watchdog=${rollbackResult.verification.watchdogPid ?? 'unknown'}`,
-      );
+    } finally {
+      if (drainArmed) setRecoveryGatewayDraining(controllerHome, false);
     }
   } finally {
     lock.close();
@@ -647,7 +833,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,38 +856,68 @@ 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;
+  profile?: RecoveryInstallProfile;
+  /** @deprecated Compatibility alias for profile=manual without config/service activation. */
   stageOnly?: boolean;
 }, dependencies: RecoveryInstallerDependencies = {}): Promise<RecoveryInstallResult> {
   const controllerHome = resolve(input.controllerHome);
+  const profile = input.stageOnly
+    ? 'manual'
+    : normalizeRecoveryInstallProfile(input.profile, 'self-healing');
   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,19 +945,23 @@ 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, profile: 'manual', staged, config: loadRecoveryConfig(controllerHome) };
+  }
   const config = initializeStandaloneRecovery(controllerHome, input.port ?? 8787, {
+    installProfile: profile,
     ...(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 };
+  return { controllerHome, profile, staged, activated, config };
 }
 
 export function recoveryReleaseAuthoritySnapshot(controllerHome: string): {
@@ -749,6 +969,7 @@ export function recoveryReleaseAuthoritySnapshot(controllerHome: string): {
   previous?: RecoveryReleaseDescriptor;
   currentPath: string;
   previousPath: string;
+  daemonLaunchAgent: string;
   gatewayLaunchAgent: string;
   watchdogLaunchAgent: string;
 } {
@@ -757,6 +978,7 @@ export function recoveryReleaseAuthoritySnapshot(controllerHome: string): {
     previous: readPreviousRecoveryRelease(controllerHome),
     currentPath: recoveryCurrentPath(controllerHome),
     previousPath: recoveryPreviousPath(controllerHome),
+    daemonLaunchAgent: launchAgentPath(RECOVERY_DAEMON_LABEL),
     gatewayLaunchAgent: launchAgentPath(RECOVERY_GATEWAY_LABEL),
     watchdogLaunchAgent: launchAgentPath(RECOVERY_WATCHDOG_LABEL),
   };