@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,8 +1,11 @@
+import { assertRuntimePerformanceEvidence, measureRuntimePerformance, samePerformanceIdentity, type RuntimePerformanceDependencies, type RuntimePerformanceEvidence, type RuntimePerformanceIdentity } from './performance';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'crypto';
 import { spawn, spawnSync } from 'child_process';
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
-import { basename, dirname, isAbsolute, join, resolve } from 'path';
+import { homedir, hostname } from 'os';
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from 'path';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
+import { resolveBunExecutable } from '../shared/process-environment';
 import { observeRuntimeStatus } from '../root/status';
 import {
   activeRuntimeEntrypoint,
@@ -12,8 +15,19 @@ import {
   inspectForgeRuntimeLaunchAgentContract,
   readForgeRuntimeServiceConfig,
 } from '../root/service';
+import { systemdUserUnitName, systemdUserUnitPath } from '../../cli/controller/systemd-user';
+import {
+  openAiSecureTunnelConnectArgs,
+  openAiSecureTunnelStatusArgs,
+  parseOpenAiSecureTunnelRuntimeStatus,
+  type OpenAiSecureTunnelRuntimeObservation,
+} from '../../../adapters/mcp/tunnels/openai-secure-tunnel';
+import {
+  renderPackageRuntimeSystemdUserService,
+  writePackageRuntimeSystemdUserService,
+} from '../root/package-runtime-service';
 import { loadRuntimeReleaseManifest } from '../root/release-manifest';
-import { assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource, type StagedRuntimeRelease } from '../root/release-materialize';
+import { assertRuntimeReleaseExecutionCanaries, assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource, type RuntimeReleaseExecutionCanaryDependencies, type StagedRuntimeRelease } from '../root/release-materialize';
 import {
   publishRuntimeRelease,
   readRuntimeReleaseAuthority,
@@ -22,7 +36,7 @@ import {
   type RuntimeReleaseAuthority,
 } from '../root/release-store';
 import type { RuntimeReleaseManifest } from '../root/types';
-import { ensurePackageConnectorService, packageConnectorServicePaths, type PackageConnectorReleaseBinding } from '../root/package-connector-service';
+import { ensurePackageConnectorService, packageConnectorAuthMode, packageConnectorServicePaths, type PackageConnectorReleaseBinding } from '../root/package-connector-service';
 import { createRecoveryHttpTransport, type RecoveryHttpTransport } from './http-transport';
 import { observeRecoveryWatchdogHealth } from './watchdog-heartbeat';
 import { RECOVERY_GATEWAY_LABEL, RECOVERY_WATCHDOG_LABEL } from './service-labels';
@@ -32,20 +46,51 @@ import {
   rollbackStoppedRepoLocalControllerHomeStorage,
   type ControllerHomeStorageMigration,
 } from '../../cli/repositories/controller-home';
+import { readCurrentRecoveryRelease } from './release';
+import { recoveryOperationLockPath } from './operation-lock';
+import { RECOVERY_MUTATION_IDENTITY_FIELDS, type RecoveryMutationIdentityArguments } from './mutation-identity-contract';
 
 /** Standalone recovery reads only canonical Runtime observation and whole-release authority. */
-export interface PublicTunnelServiceConfig {
-  platform: 'launchd';
-  label: string;
-  plistPath?: string;
+interface PublicTunnelRecoveryPolicy {
   minimumFailures?: number;
   minimumFailureDurationMs?: number;
   cooldownMs?: number;
   postRestartVerifyTimeoutMs?: number;
 }
 
-export interface PrimaryRuntimeServiceConfig {
+export interface LaunchdPublicTunnelServiceConfig extends PublicTunnelRecoveryPolicy {
   platform: 'launchd';
+  label: string;
+  plistPath?: string;
+}
+
+export interface OpenAiSecureTunnelServiceConfig extends PublicTunnelRecoveryPolicy {
+  platform: 'openai-secure-tunnel';
+  /** Stable tunnel-client runtime identity. Recovery must not repoint another alias. */
+  alias: string;
+  /** Non-secret OpenAI tunnel identity. */
+  tunnelId: string;
+  /** Loopback MCP endpoint owned by the local service behind this tunnel. */
+  mcpServerUrl: string;
+  /** Secret reference only (env:NAME or file:/absolute/path). Recovery never reads the secret. */
+  runtimeApiKeyRef?: string;
+  profile?: string;
+  profileDir?: string;
+  adminProfile?: string;
+}
+
+export type PublicTunnelServiceConfig = LaunchdPublicTunnelServiceConfig | OpenAiSecureTunnelServiceConfig;
+
+export interface SystemdUserRecoveryTunnelServiceConfig extends PublicTunnelRecoveryPolicy {
+  platform: 'systemd-user';
+  /** Exact systemd --user unit owned by the dedicated Recovery public tunnel. */
+  unitName: string;
+}
+
+export type RecoveryTunnelServiceConfig = PublicTunnelServiceConfig | SystemdUserRecoveryTunnelServiceConfig;
+
+export interface PrimaryRuntimeServiceConfig {
+  platform: 'launchd' | 'systemd-user';
   minimumFailures?: number;
   minimumFailureDurationMs?: number;
   restartCooldownMs?: number;
@@ -56,10 +101,7 @@ export interface PrimaryRuntimeServiceConfig {
   postRestartVerifyTimeoutMs?: number;
 }
 
-export interface PrimaryConnectorServiceConfig {
-  platform: 'launchd';
-  label: string;
-  plistPath?: string;
+interface PrimaryConnectorRecoveryPolicy {
   /** Local OAuth MCP endpoint used to distinguish Connector failure from tunnel failure. */
   localMcpUrl?: string;
   minimumFailures?: number;
@@ -69,16 +111,32 @@ export interface PrimaryConnectorServiceConfig {
   postRestartVerifyTimeoutMs?: number;
 }
 
+export interface LaunchdPrimaryConnectorServiceConfig extends PrimaryConnectorRecoveryPolicy {
+  platform: 'launchd';
+  label: string;
+  plistPath?: string;
+}
+
+export interface SystemdPrimaryConnectorServiceConfig extends PrimaryConnectorRecoveryPolicy {
+  platform: 'systemd-user';
+  /** Optional assertion. When present it must equal the package Connector label derived from Controller Home. */
+  label?: string;
+}
+
+export type PrimaryConnectorServiceConfig = LaunchdPrimaryConnectorServiceConfig | SystemdPrimaryConnectorServiceConfig;
+
 export interface RecoveryConfig {
   schemaVersion: 1;
   controllerHome: string;
   publicMcpUrl?: string;
   recoveryPublicUrl?: string;
-  recoveryTunnelService?: PublicTunnelServiceConfig;
+  recoveryTunnelService?: RecoveryTunnelServiceConfig;
   /** Optional public tunnel serving publicMcpUrl; independent from the OAuth Connector process. */
   primaryPublicTunnelService?: PublicTunnelServiceConfig;
   primaryRuntimeService?: PrimaryRuntimeServiceConfig;
   primaryRuntimeSourceRoot?: string;
+  /** Repository Registry authority paired with primaryRuntimeSourceRoot. */
+  primaryRuntimeSourceRepositoryId?: string;
   primaryConnectorService?: PrimaryConnectorServiceConfig;
   mainMcpTokenFile?: string;
   expectedToolFingerprint?: string;
@@ -86,6 +144,75 @@ export interface RecoveryConfig {
   gateway?: { host: string; port: number; bearerTokenFile: string };
 }
 
+export interface RecoveryMachineIdentity {
+  schemaVersion: 1;
+  host: string;
+  platform: NodeJS.Platform;
+  controllerHome: string;
+  recovery: {
+    releaseRevision?: string;
+    manifestSha256?: string;
+  };
+  targetRuntime: {
+    id: string;
+    servicePlatform: 'launchd' | 'systemd-user';
+    serviceLabel: string;
+    activeReleaseId?: string;
+    authorityRevision?: number;
+  };
+}
+
+export function recoveryMachineIdentity(
+  config: RecoveryConfig,
+  dependencies: { host?: string; platform?: NodeJS.Platform } = {},
+): RecoveryMachineIdentity {
+  const controllerHome = resolve(config.controllerHome);
+  const platform = dependencies.platform ?? process.platform;
+  const host = dependencies.host?.trim() || hostname();
+  const recoveryRelease = readCurrentRecoveryRelease(controllerHome);
+  const runtimeAuthority = readRuntimeReleaseAuthority(controllerHome);
+  const servicePlatform = (config.primaryRuntimeService ?? defaultPrimaryRuntimeServiceConfig(platform)).platform;
+  const serviceLabel = forgeRuntimeServicePaths(controllerHome).label;
+  const activeReleaseId = runtimeAuthority?.active.releaseId;
+  return {
+    schemaVersion: 1,
+    host,
+    platform,
+    controllerHome,
+    recovery: {
+      ...(recoveryRelease ? { releaseRevision: recoveryRelease.releaseRevision, manifestSha256: recoveryRelease.manifestSha256 } : {}),
+    },
+    targetRuntime: {
+      id: `${servicePlatform}:${serviceLabel}:${activeReleaseId ?? 'none'}`,
+      servicePlatform,
+      serviceLabel,
+      ...(activeReleaseId ? { activeReleaseId } : {}),
+      ...(runtimeAuthority ? { authorityRevision: runtimeAuthority.revision } : {}),
+    },
+  };
+}
+
+export function recoveryMutationIdentityExpectations(identity: Pick<RecoveryMachineIdentity, 'host' | 'platform' | 'controllerHome' | 'recovery' | 'targetRuntime'>): RecoveryMutationIdentityArguments {
+  return {
+    expected_host: identity.host,
+    expected_platform: identity.platform,
+    expected_controller_home: identity.controllerHome,
+    expected_recovery_release: identity.recovery.releaseRevision ?? 'none',
+    expected_target_runtime: identity.targetRuntime.id,
+  };
+}
+
+export function assertRecoveryMutationIdentity(config: RecoveryConfig, args: Record<string, unknown>): RecoveryMachineIdentity {
+  const identity = recoveryMachineIdentity(config);
+  const expected = recoveryMutationIdentityExpectations(identity);
+  for (const field of RECOVERY_MUTATION_IDENTITY_FIELDS) {
+    const supplied = typeof args[field] === 'string' ? args[field].trim() : '';
+    if (!supplied) throw new Error(`RECOVERY_TARGET_IDENTITY_REQUIRED:${field}`);
+    if (supplied !== expected[field]) throw new Error(`RECOVERY_TARGET_IDENTITY_MISMATCH:${field}`);
+  }
+  return identity;
+}
+
 interface ReleaseEvidence {
   path: string;
   revision: string;
@@ -96,6 +223,7 @@ interface ReleaseEvidence {
   releaseAuthorityRevision?: number;
   releaseFencingTokenSha256?: string;
   attestedAt?: string;
+  performance?: RuntimePerformanceEvidence;
 }
 
 interface KnownGoodStore {
@@ -143,7 +271,7 @@ export interface VerifyResult {
   probes: Record<string, { ok: boolean; detail: string; status?: number; value?: unknown }>;
 }
 
-export interface VerifyStableRuntimeOptions {
+export interface VerifyStableRuntimeOptions extends RuntimeReleaseExecutionCanaryDependencies {
   probeMcpProtocol?: boolean;
 }
 
@@ -281,10 +409,14 @@ function normalizeRecoveryReadOnlyTool(
   return input;
 }
 
+export function defaultPrimaryRuntimeServiceConfig(platform: NodeJS.Platform = process.platform): PrimaryRuntimeServiceConfig {
+  return { platform: platform === 'linux' ? 'systemd-user' : 'launchd' };
+}
+
 const DEFAULT_CONFIG: Omit<RecoveryConfig, 'controllerHome'> = {
   schemaVersion: 1,
   readOnlyTool: { name: STABLE_RECOVERY_READ_ONLY_TOOL.name, arguments: { ...STABLE_RECOVERY_READ_ONLY_TOOL.arguments } },
-  primaryRuntimeService: { platform: 'launchd' },
+  primaryRuntimeService: defaultPrimaryRuntimeServiceConfig(),
 };
 
 function json<T>(path: string): T | undefined {
@@ -292,16 +424,22 @@ function json<T>(path: string): T | undefined {
 }
 
 function writeJson(path: string, value: unknown): void {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  assertStorageHeadroom(path, {
+    operation: 'standalone_recovery_state_write',
+    requiredBytes: Buffer.byteLength(content),
+    reserveBytes: 16 * 1024 * 1024,
+  });
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  writeFileSync(temporary, content, { encoding: 'utf8', mode: 0o600 });
   try { chmodSync(temporary, 0o600); } catch { /* best effort */ }
   renameSync(temporary, path);
 }
 
 function recoveryRoot(config: RecoveryConfig): string { return join(resolve(config.controllerHome), 'recovery'); }
 function statePath(config: RecoveryConfig): string { return join(recoveryRoot(config), 'state', 'known-good.json'); }
-function lockPath(config: RecoveryConfig): string { return join(recoveryRoot(config), 'locks', 'operation.lock'); }
+function lockPath(config: RecoveryConfig): string { return recoveryOperationLockPath(config.controllerHome); }
 function auditPath(config: RecoveryConfig): string { return join(recoveryRoot(config), 'audit', 'recovery.jsonl'); }
 function watchdogDiagnosticPath(config: RecoveryConfig): string { return join(recoveryRoot(config), 'state', 'watchdog-diagnostics.json'); }
 function quarantinePath(config: RecoveryConfig): string { return join(recoveryRoot(config), 'state', 'quarantine.json'); }
@@ -321,7 +459,7 @@ export function saveWatchdogState(config: RecoveryConfig, state: WatchdogState):
   return persisted;
 }
 
-function configuredRecoveryTunnel(config: RecoveryConfig): PublicTunnelServiceConfig | undefined {
+function configuredRecoveryTunnel(config: RecoveryConfig): RecoveryTunnelServiceConfig | undefined {
   return config.recoveryTunnelService;
 }
 
@@ -356,6 +494,7 @@ export function loadRecoveryConfig(controllerHome: string, explicit?: string): R
     ...(loaded.primaryPublicTunnelService ? { primaryPublicTunnelService: loaded.primaryPublicTunnelService } : {}),
     ...(loaded.primaryRuntimeService ? { primaryRuntimeService: loaded.primaryRuntimeService } : {}),
     ...(typeof loaded.primaryRuntimeSourceRoot === 'string' ? { primaryRuntimeSourceRoot: resolve(loaded.primaryRuntimeSourceRoot) } : {}),
+    ...(typeof loaded.primaryRuntimeSourceRepositoryId === 'string' && loaded.primaryRuntimeSourceRepositoryId.trim() ? { primaryRuntimeSourceRepositoryId: loaded.primaryRuntimeSourceRepositoryId.trim() } : {}),
     ...(loaded.primaryConnectorService ? { primaryConnectorService: loaded.primaryConnectorService } : {}),
     ...(typeof loaded.mainMcpTokenFile === 'string' ? { mainMcpTokenFile: loaded.mainMcpTokenFile } : {}),
     ...(typeof loaded.expectedToolFingerprint === 'string' ? { expectedToolFingerprint: loaded.expectedToolFingerprint } : {}),
@@ -454,7 +593,7 @@ function watchdogProbeComponent(name: string): RecoveryWatchdogDiagnosticEvidenc
   if (name === 'active_gateway') return 'gateway';
   if (name === 'recovery_gateway') return 'recovery_gateway';
   if (name === 'recovery_watchdog') return 'recovery_watchdog';
-  if (name === 'recovery_external_http') return 'recovery_tunnel';
+  if (name === 'recovery_external_http' || name === 'recovery_tunnel_runtime') return 'recovery_tunnel';
   return 'public_mcp';
 }
 
@@ -618,9 +757,11 @@ async function withLock<T>(
 }
 
 export async function runtimeStatus(config: RecoveryConfig) {
+  const identity = recoveryMachineIdentity(config);
   const observation = observeRuntimeStatus(config.controllerHome);
   const watchdog = loadWatchdogState(config);
   return {
+    identity,
     ...observation,
     recoveryWatchdog: {
       lastDecision: watchdog.lastDecision,
@@ -648,7 +789,11 @@ async function probe(transport: RecoveryHttpTransport, url: string, timeoutMs =
   } finally { clearTimeout(timer); }
 }
 
-async function probeExternalMcp(transport: RecoveryHttpTransport, url: string): Promise<{ ok: boolean; detail: string; status?: number }> {
+async function probeExternalMcp(
+  transport: RecoveryHttpTransport,
+  url: string,
+  options: { acceptOAuthChallenge?: boolean } = {},
+): Promise<{ ok: boolean; detail: string; status?: number }> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort('RECOVERY_HTTP_TIMEOUT'), 4_000);
   try {
@@ -669,8 +814,13 @@ async function probeExternalMcp(transport: RecoveryHttpTransport, url: string):
       signal: controller.signal,
     });
     const challenge = response.headers['www-authenticate'] ?? '';
-    const ok = response.ok || (response.status === 401 && /\bBearer\b/i.test(challenge));
-    return { ok, detail: ok && response.status === 401 ? 'HTTP 401 OAuth challenge' : `HTTP ${response.status}`, status: response.status };
+    const oauthChallenge = response.status === 401 && /\bBearer\b/i.test(challenge);
+    const acceptsOAuthChallenge = options.acceptOAuthChallenge ?? true;
+    const ok = response.ok || (acceptsOAuthChallenge && oauthChallenge);
+    const detail = oauthChallenge
+      ? acceptsOAuthChallenge ? 'HTTP 401 OAuth challenge' : 'HTTP 401 unexpected OAuth challenge for unauthenticated Connector'
+      : `HTTP ${response.status}`;
+    return { ok, detail, status: response.status };
   } catch (error) {
     return { ok: false, detail: error instanceof Error ? error.message.slice(0, 180) : 'request failed' };
   } finally { clearTimeout(timer); }
@@ -687,6 +837,7 @@ function publicGatewayReadinessEndpoint(endpoint: string): string {
 async function probePublicGatewayReadiness(
   transport: RecoveryHttpTransport,
   endpoint: string,
+  options: { acceptOAuthChallenge?: boolean } = {},
 ): Promise<{ ok: boolean; detail: string; status?: number; value?: unknown }> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort('RECOVERY_HTTP_TIMEOUT'), 4_000);
@@ -707,7 +858,7 @@ async function probePublicGatewayReadiness(
       // initialize response or the expected OAuth Bearer challenge proves the
       // legacy Connector transport is reachable without weakening 5xx/timeout
       // failure handling.
-      const legacy = await probeExternalMcp(transport, endpoint);
+      const legacy = await probeExternalMcp(transport, endpoint, options);
       return { ...legacy, detail: `legacy-mcp ${legacy.detail}` };
     }
     let sessionCapacity: unknown;
@@ -742,6 +893,19 @@ function connectorCapacityRecoveryRecommended(verified: VerifyResult): boolean {
   );
 }
 
+function canonicalRuntimeSafeForTargetedConnectorRecovery(verified: VerifyResult): boolean {
+  // Targeted Connector/public-transport recovery mutates no Runtime release or
+  // Work authority. Use durable Runtime ownership + release/execution evidence
+  // as the safety fence; a single failed HTTP gateway/MCP observation is the
+  // symptom this action may need to repair and must not deadlock the recovery path.
+  return verified.runtime.ok
+    && verified.runtime.running
+    && verified.runtime.ready
+    && !verified.runtime.stale
+    && verified.releases.coherent !== false
+    && verified.probes.runtime_execution_surface?.ok !== false;
+}
+
 function mainToken(config: RecoveryConfig): string | undefined {
   const candidate = config.mainMcpTokenFile ?? join(config.controllerHome, 'mcp', 'mcp.tokens.json');
   const parsed = json<{ bearerToken?: unknown }>(candidate);
@@ -839,6 +1003,146 @@ function runtimeHealthEndpoint(endpoint: string): string {
   return url.toString();
 }
 
+async function observeOpenAiTunnelRuntime(
+  configured: OpenAiSecureTunnelServiceConfig,
+  runCommand: CommandRunner = command,
+): Promise<OpenAiSecureTunnelRuntimeObservation> {
+  let args: string[];
+  try {
+    args = openAiSecureTunnelStatusArgs(configured.alias, configured);
+  } catch (error) {
+    return {
+      ok: false, running: false, healthy: false, ready: false, tunnelMatches: false, endpointMatches: false,
+      alias: configured.alias, tunnelId: configured.tunnelId,
+      detail: error instanceof Error ? error.message : 'OpenAI tunnel runtime configuration is invalid',
+    };
+  }
+  const status = await runCommand('tunnel-client', args, 15_000);
+  if (!status.stdout.trim()) {
+    const local = await observeOpenAiTunnelLocalHealthFallback(configured);
+    if (local) return local;
+    return {
+      ok: false, running: false, healthy: false, ready: false, tunnelMatches: false, endpointMatches: false,
+      alias: configured.alias, tunnelId: configured.tunnelId,
+      detail: status.stderr.trim() || 'OpenAI tunnel runtime status is unavailable',
+    };
+  }
+  return parseOpenAiSecureTunnelRuntimeStatus(status.stdout, {
+    alias: configured.alias, tunnelId: configured.tunnelId, mcpServerUrl: configured.mcpServerUrl,
+  });
+}
+
+/**
+ * tunnel-client's structured status command can itself be delayed by a
+ * control-plane query. When that happens, retain a bounded observation of the
+ * locally supervised runtime instead of treating a live, identity-matched
+ * alias as failed. This reads only the client-owned profile and loopback
+ * health URL; it never creates, repoints, or restarts a tunnel.
+ */
+export async function observeOpenAiTunnelLocalHealthFallback(
+  configured: OpenAiSecureTunnelServiceConfig,
+  options: {
+    request?: (url: string, init: { signal: AbortSignal }) => Promise<{ ok: boolean; status: number }>;
+  } = {},
+): Promise<OpenAiSecureTunnelRuntimeObservation | undefined> {
+  if (!configured.profile?.trim() || !configured.profileDir?.trim()) return undefined;
+  const profilePath = join(configured.profileDir, `${configured.profile}.yaml`);
+  let profile: string;
+  try { profile = readFileSync(profilePath, 'utf8'); } catch { return undefined; }
+  const identityMatches = profile.includes(configured.tunnelId);
+  const endpointMatches = profile.includes(configured.mcpServerUrl);
+  const urlFileMatch = profile.match(/["']?url_file["']?\s*:\s*["']([^"']+)["']/i);
+  if (!urlFileMatch) return undefined;
+  let base: URL;
+  try {
+    base = new URL(readFileSync(urlFileMatch[1].trim(), 'utf8').trim());
+    if (base.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(base.hostname)) return undefined;
+  } catch { return undefined; }
+  const request = options.request ?? ((url: string, init: { signal: AbortSignal }) => fetch(url, init));
+  const probe = async (pathname: '/healthz' | '/readyz'): Promise<boolean> => {
+    const url = new URL(base);
+    url.pathname = pathname;
+    url.search = '';
+    url.hash = '';
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort('RECOVERY_TUNNEL_HEALTH_TIMEOUT'), 4_000);
+    try { return (await request(url.toString(), { signal: controller.signal })).ok; } catch { return false; } finally { clearTimeout(timer); }
+  };
+  const [healthy, ready] = await Promise.all([probe('/healthz'), probe('/readyz')]);
+  const ok = healthy && ready && identityMatches && endpointMatches;
+  const failures: string[] = [];
+  if (!identityMatches) failures.push('profile tunnel id does not match');
+  if (!endpointMatches) failures.push('profile MCP endpoint does not match');
+  if (!healthy) failures.push('local healthz failed');
+  if (!ready) failures.push('local readyz failed');
+  return {
+    ok,
+    running: healthy,
+    healthy,
+    ready,
+    tunnelMatches: identityMatches,
+    endpointMatches,
+    alias: configured.alias,
+    tunnelId: configured.tunnelId,
+    ...(identityMatches ? { observedTunnelId: configured.tunnelId } : {}),
+    detail: ok
+      ? `managed runtime ${configured.alias} is locally healthy and ready for ${configured.tunnelId} (status command unavailable)`
+      : failures.join('; ') || 'OpenAI tunnel local health fallback failed',
+    profilePath,
+  };
+}
+
+async function observeOpenAiRecoveryTunnel(
+  config: RecoveryConfig,
+  runCommand: CommandRunner = command,
+): Promise<OpenAiSecureTunnelRuntimeObservation | undefined> {
+  const configured = configuredRecoveryTunnel(config);
+  if (!configured || configured.platform !== 'openai-secure-tunnel') return undefined;
+  return observeOpenAiTunnelRuntime(configured, runCommand);
+}
+
+async function ensureOpenAiTunnelRuntimeStarted(
+  configured: OpenAiSecureTunnelServiceConfig,
+  runCommand: CommandRunner = command,
+): Promise<{ ok: boolean; attempted: boolean; noOp?: boolean; detail: string; serviceLabel: string; serviceTarget: string }> {
+  const serviceLabel = configured.alias;
+  const serviceTarget = `tunnel-client:${configured.alias}`;
+  const observed = await observeOpenAiTunnelRuntime(configured, runCommand);
+  if (observed.ok) return { ok: true, attempted: false, noOp: true, detail: observed.detail, serviceLabel, serviceTarget };
+  if (observed.observedTunnelId && !observed.tunnelMatches) {
+    return { ok: false, attempted: false, noOp: true, detail: `OpenAI tunnel alias ${configured.alias} is already bound to a different tunnel id`, serviceLabel, serviceTarget };
+  }
+  if (observed.profilePath && !observed.endpointMatches) {
+    return { ok: false, attempted: false, noOp: true, detail: `OpenAI tunnel alias ${configured.alias} is already bound to a different MCP endpoint`, serviceLabel, serviceTarget };
+  }
+  let args: string[];
+  try {
+    args = openAiSecureTunnelConnectArgs({
+      alias: configured.alias,
+      tunnelId: configured.tunnelId,
+      mcpServerUrl: configured.mcpServerUrl,
+      runtimeApiKeyRef: configured.runtimeApiKeyRef,
+      profile: configured.profile,
+      profileDir: configured.profileDir,
+      adminProfile: configured.adminProfile,
+    });
+  } catch (error) {
+    return { ok: false, attempted: false, noOp: true, detail: error instanceof Error ? error.message : 'OpenAI tunnel runtime configuration is invalid', serviceLabel, serviceTarget };
+  }
+  const connected = await runCommand('tunnel-client', args, Math.max(30_000, configured.postRestartVerifyTimeoutMs ?? 20_000));
+  return connected.ok
+    ? { ok: true, attempted: true, detail: `OpenAI Secure MCP Tunnel runtime ${configured.alias} connect dispatched`, serviceLabel, serviceTarget }
+    : { ok: false, attempted: true, detail: `OpenAI Secure MCP Tunnel runtime connect failed: ${connected.stderr || connected.stdout || connected.status}`, serviceLabel, serviceTarget };
+}
+
+async function probeOpenAiRecoveryTunnel(
+  config: RecoveryConfig,
+  runCommand: CommandRunner = command,
+): Promise<{ ok: boolean; detail: string; value?: unknown } | undefined> {
+  const observed = await observeOpenAiRecoveryTunnel(config, runCommand);
+  return observed ? { ok: observed.ok, detail: observed.detail, value: observed } : undefined;
+}
+
 async function probeMcp(config: RecoveryConfig, transport: RecoveryHttpTransport): Promise<Record<string, { ok: boolean; detail: string; value?: unknown }>> {
   const url = config.publicMcpUrl ?? runtimeEndpoint(config);
   if (!url) return { mcp_initialize: { ok: false, detail: 'canonical Runtime MCP endpoint is unavailable' } };
@@ -890,6 +1194,24 @@ async function probeMcp(config: RecoveryConfig, transport: RecoveryHttpTransport
   };
 }
 
+function probeRuntimeExecutionSurface(
+  config: RecoveryConfig,
+  release: ReleaseEvidence | undefined,
+  dependencies: RuntimeReleaseExecutionCanaryDependencies = {},
+): VerifyResult['probes'][string] {
+  if (!release) return { ok: false, detail: 'active immutable Runtime release is unavailable' };
+  try {
+    const surface = assertRuntimeReleaseExecutionCanaries(release.path, config.controllerHome, dependencies);
+    return {
+      ok: true,
+      detail: 'Process Runtime release entries are manifest-attested, executable, and canary-ready',
+      value: { entries: surface.entries.map((entry) => ({ name: entry.name, artifactIdentity: entry.artifactIdentity })) },
+    };
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 export async function verifyStableRuntime(
   config: RecoveryConfig,
   transport = createRecoveryHttpTransport(config.controllerHome),
@@ -912,10 +1234,18 @@ export async function verifyStableRuntime(
   probes.active_gateway = endpoint
     ? await probe(transport, runtimeHealthEndpoint(endpoint))
     : { ok: false, detail: 'canonical Runtime endpoint is unavailable' };
+  probes.runtime_execution_surface = probeRuntimeExecutionSurface(config, active, options);
   if (config.publicMcpUrl) {
     probes.external_mcp_http = await probeExternalMcp(transport, config.publicMcpUrl);
     const connectorReadinessEndpoint = config.primaryConnectorService?.localMcpUrl?.trim() || config.publicMcpUrl;
-    probes.primary_connector_ready = await probePublicGatewayReadiness(transport, connectorReadinessEndpoint);
+    probes.primary_connector_ready = await probePublicGatewayReadiness(transport, connectorReadinessEndpoint, {
+      acceptOAuthChallenge: packageConnectorAuthMode(config.controllerHome) === 'oauth',
+    });
+  }
+  const primaryTunnel = configuredPrimaryPublicTunnel(config);
+  if (primaryTunnel?.platform === 'openai-secure-tunnel') {
+    const observed = await observeOpenAiTunnelRuntime(primaryTunnel);
+    probes.primary_tunnel_runtime = { ok: observed.ok, detail: observed.detail, value: observed };
   }
   const primaryConnectorLocal = await probePrimaryConnectorLocal(config, transport);
   if (primaryConnectorLocal) probes.primary_connector_local = primaryConnectorLocal;
@@ -934,6 +1264,8 @@ export async function verifyStableRuntime(
   };
   const recoveryPublicUrl = configuredRecoveryPublicUrl(config);
   if (recoveryPublicUrl) probes.recovery_external_http = await probeExternalMcp(transport, recoveryPublicUrl);
+  const recoveryTunnelRuntime = await probeOpenAiRecoveryTunnel(config);
+  if (recoveryTunnelRuntime) probes.recovery_tunnel_runtime = recoveryTunnelRuntime;
   if (options.probeMcpProtocol !== false) Object.assign(probes, await probeMcp(config, transport));
   const coreChecks = Object.entries(probes)
     .filter(([name]) => !name.startsWith('recovery_'))
@@ -978,7 +1310,7 @@ export async function verifyStableRuntime(
   return result;
 }
 /** Explicitly records evidence only after the full independent verification passed. */
-function persistVerifiedKnownGood(config: RecoveryConfig, verified: VerifyResult): ReleaseEvidence {
+function persistVerifiedKnownGood(config: RecoveryConfig, verified: VerifyResult, performance: RuntimePerformanceEvidence): ReleaseEvidence {
   const authority = releaseAuthority(config);
     const active = verified.releases.active;
     if (
@@ -992,8 +1324,10 @@ function persistVerifiedKnownGood(config: RecoveryConfig, verified: VerifyResult
     ) {
       throw new Error('RECOVERY_KNOWN_GOOD_ATTESTATION_REQUIRES_FULL_VERIFY_AND_RELEASE_AUTHORITY');
     }
+    assertRuntimePerformanceEvidence(performance, runtimePerformanceIdentity(config));
     const attested: ReleaseEvidence = {
       ...active,
+      performance,
       controllerHome: resolve(config.controllerHome),
       releaseAuthorityRevision: authority.revision,
       releaseFencingTokenSha256: createHash('sha256').update(authority.fencingToken).digest('hex'),
@@ -1014,10 +1348,51 @@ function persistVerifiedKnownGood(config: RecoveryConfig, verified: VerifyResult
   return attested;
 }
 
-export async function attestKnownGood(config: RecoveryConfig): Promise<ReleaseEvidence> {
-  const locked = await withLock(config, { action: 'attest_known_good' }, async () => (
-    persistVerifiedKnownGood(config, await verifyStableRuntime(config))
-  ));
+function runtimePerformanceIdentity(config: RecoveryConfig): RuntimePerformanceIdentity {
+  const authority = releaseAuthority(config);
+  const status = observeRuntimeStatus(config.controllerHome);
+  const snapshot = status.snapshot;
+  if (!authority || !status.running || !status.ready || status.stale || !snapshot
+    || snapshot.releaseId !== authority.active.releaseId
+    || snapshot.artifactIdentity !== authority.active.artifactIdentity) {
+    throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: coherent live Runtime required');
+  }
+  return {
+    releaseId: authority.active.releaseId, authorityRevision: authority.revision,
+    pid: snapshot.pid, runtimeInstanceId: snapshot.runtimeInstanceId, startedAt: snapshot.startedAt,
+  };
+}
+
+export async function attestKnownGood(
+  config: RecoveryConfig,
+  dependencies: RuntimePerformanceDependencies = {},
+): Promise<ReleaseEvidence> {
+  const initialIdentity = runtimePerformanceIdentity(config);
+  const before = await verifyStableRuntime(config);
+  if (!before.ok) throw new Error('RECOVERY_KNOWN_GOOD_ATTESTATION_REQUIRES_FULL_VERIFY_AND_RELEASE_AUTHORITY');
+  const verifiedIdentity = runtimePerformanceIdentity(config);
+  if (!samePerformanceIdentity(initialIdentity, verifiedIdentity)
+    || before.releases.active?.revision !== verifiedIdentity.releaseId) {
+    throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: Runtime or release authority changed during functional verification');
+  }
+
+  // Performance observation is read-only and deliberately stays outside the
+  // single Recovery mutation lock. Runtime/release identity is fenced on every
+  // sample; a concurrent restart/rollback/activation therefore invalidates the
+  // evidence instead of being blocked for the six-minute observation window.
+  const performance = await measureRuntimePerformance(() => {
+    const current = runtimePerformanceIdentity(config);
+    if (!samePerformanceIdentity(verifiedIdentity, current)) {
+      throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: Runtime or release authority changed after functional verification');
+    }
+    return current;
+  }, dependencies);
+
+  const locked = await withLock(config, { action: 'attest_known_good' }, async () => {
+    const verified = await verifyStableRuntime(config);
+    if (!verified.ok) throw new Error('RECOVERY_KNOWN_GOOD_ATTESTATION_REQUIRES_FULL_VERIFY_AND_RELEASE_AUTHORITY');
+    return persistVerifiedKnownGood(config, verified, performance);
+  });
   if (!locked.acquired) throw new Error(recoveryBusyDetail(locked.owner));
   return locked.value;
 }
@@ -1032,9 +1407,6 @@ function quarantine(config: RecoveryConfig, release: ReleaseEvidence | undefined
 async function rollbackPreviousLocked(config: RecoveryConfig, reason: string): Promise<RollbackResult> {
   const before = await verifyStableRuntime(config);
   const active = before.releases.active;
-  if (before.ok && matchingKnownGood(config, active)) {
-    return { ok: true, noOp: true, detail: 'active whole-Runtime release is currently healthy and independently attested known-good', verify: before };
-  }
   if (before.runtime.running) {
     return {
       ok: false,
@@ -1055,6 +1427,19 @@ async function rollbackPreviousLocked(config: RecoveryConfig, reason: string): P
       verify: before,
     };
   }
+  const targetExecution = probeRuntimeExecutionSurface(config, target);
+  if (!targetExecution.ok) {
+    audit(config, 'rollback_refused', {
+      reason: 'attested previous release failed Process Runtime execution canary',
+      targetRevision: target.revision,
+      detail: targetExecution.detail,
+    });
+    return {
+      ok: false,
+      detail: `rollback refused: previous whole-Runtime release failed Process Runtime execution verification: ${targetExecution.detail}`,
+      verify: before,
+    };
+  }
   const operationId = `recovery-rollback-${Date.now()}-${randomUUID().slice(0, 8)}`;
   try {
     const committed = rollbackRuntimeRelease(config.controllerHome, operationId);
@@ -1094,10 +1479,14 @@ export async function reconnectMain(config: RecoveryConfig): Promise<{ ok: boole
   // intentionally a bounded health/reconnect observation, never a rollout.
   const verified = await verifyStableRuntime(config);
   const publicProbe = verified.probes.external_mcp_http;
+  const primaryTunnel = configuredPrimaryPublicTunnel(config);
+  const remoteTransportOk = primaryTunnel?.platform === 'openai-secure-tunnel'
+    ? verified.probes.primary_tunnel_runtime?.ok === true
+    : (publicProbe?.ok === true || publicProbe?.status === 401);
   const ok = verified.probes.active_gateway?.ok === true
     && verified.probes.primary_connector_ready?.ok !== false
-    && (publicProbe?.ok === true || publicProbe?.status === 401);
-  audit(config, 'reconnect_main', { ok, externalStatus: publicProbe?.status });
+    && remoteTransportOk;
+  audit(config, 'reconnect_main', { ok, externalStatus: publicProbe?.status, primaryTunnelPlatform: primaryTunnel?.platform });
   return { ok, detail: ok ? 'canonical Runtime Gateway and primary endpoint are reachable; client session may refresh' : 'primary endpoint remains unavailable; recovery channel remains independent', verify: verified };
 }
 
@@ -1113,14 +1502,19 @@ async function verifyLocalRuntime(
     ...config,
     publicMcpUrl: undefined,
     recoveryPublicUrl: undefined,
+    recoveryTunnelService: undefined,
+    primaryPublicTunnelService: undefined,
     readOnlyTool: { name: STABLE_RECOVERY_READ_ONLY_TOOL.name, arguments: { ...STABLE_RECOVERY_READ_ONLY_TOOL.arguments } },
   }, createRecoveryHttpTransport(config.controllerHome), options);
 }
 
 function isExternalTunnelFailure(config: RecoveryConfig, verified: VerifyResult, localVerify: VerifyResult): boolean {
-  const external = verified.probes.recovery_external_http ?? verified.probes.external_mcp_http;
+  const configured = configuredRecoveryTunnel(config);
   const localRecoveryGatewayHealthy = localVerify.probes.recovery_gateway?.ok ?? true;
-  return Boolean(configuredRecoveryTunnel(config) && configuredRecoveryPublicUrl(config) && localVerify.ok && localRecoveryGatewayHealthy && external?.ok !== true);
+  if (!configured || !localVerify.ok || !localRecoveryGatewayHealthy) return false;
+  if (configured.platform === 'openai-secure-tunnel') return verified.probes.recovery_tunnel_runtime?.ok !== true;
+  const external = verified.probes.recovery_external_http ?? verified.probes.external_mcp_http;
+  return Boolean(configuredRecoveryPublicUrl(config) && external?.ok !== true);
 }
 
 export const WATCHDOG_RUNTIME_STARTUP_GRACE_MS = 60_000;
@@ -1347,6 +1741,23 @@ interface CommandResult { ok: boolean; status: number | null; stdout: string; st
 type CommandRunner = (commandName: string, args: string[], timeoutMs?: number) => Promise<CommandResult>;
 interface LaunchdService { uid: number; domain: string; target: string; label: string; plistPath: string; }
 
+/**
+ * systemd --user does not necessarily inherit the interactive shell PATH.
+ * Recovery owns tunnel repair, so its non-interactive command environment must
+ * still find user-installed runtime tools without adding a second service
+ * owner or accepting an executable path through RPC.
+ */
+export function recoveryCommandPath(
+  inheritedPath = process.env.PATH ?? '',
+  platform: NodeJS.Platform = process.platform,
+  accountHome = homedir(),
+): string {
+  if (platform === 'win32') return inheritedPath;
+  const userBin = join(accountHome, '.local', 'bin');
+  const entries = inheritedPath.split(delimiter).filter(Boolean);
+  return entries.includes(userBin) ? inheritedPath : [userBin, ...entries].join(delimiter);
+}
+
 export interface PublicTunnelRepairDependencies {
   platform?: NodeJS.Platform;
   currentUid?: () => Promise<number | undefined>;
@@ -1359,12 +1770,19 @@ export interface PublicTunnelRepairDependencies {
 
 function command(commandName: string, args: string[], timeoutMs = 10_000, options: { cwd?: string; maxOutputBytes?: number } = {}): Promise<CommandResult> {
   return new Promise((resolveCommand) => {
-    const child = spawn(commandName, args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, cwd: options.cwd });
+    const child = spawn(commandName, args, {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      cwd: options.cwd,
+      env: { ...process.env, PATH: recoveryCommandPath() },
+    });
     const stdout: Buffer[] = [];
     const stderr: Buffer[] = [];
     let size = 0;
     const maxOutputBytes = options.maxOutputBytes ?? 256 * 1024;
     let settled = false;
+    let stopping = false;
     let killTimer: ReturnType<typeof setTimeout> | undefined;
     const finish = (result: CommandResult) => {
       if (settled) return;
@@ -1377,19 +1795,28 @@ function command(commandName: string, args: string[], timeoutMs = 10_000, option
       if (!child.pid || child.exitCode != null) return;
       try { process.kill(child.pid, signalName); } catch { /* Process already exited. */ }
     };
-    const stop = () => {
-      if (child.exitCode != null) return;
+    const stop = (detail: string) => {
+      if (child.exitCode != null || stopping) return;
+      stopping = true;
       signalChild('SIGTERM');
-      killTimer = setTimeout(() => signalChild('SIGKILL'), 1_000);
+      killTimer = setTimeout(() => {
+        signalChild('SIGKILL');
+        finish({
+          ok: false,
+          status: null,
+          stdout: Buffer.concat(stdout).toString('utf8'),
+          stderr: [Buffer.concat(stderr).toString('utf8').trim(), detail].filter(Boolean).join('\n'),
+        });
+      }, 1_000);
     };
-    const timeout = setTimeout(stop, timeoutMs);
+    const timeout = setTimeout(() => stop(`command timed out after ${timeoutMs}ms`), timeoutMs);
     child.stdout.on('data', (chunk: Buffer) => {
       size += chunk.length;
-      if (size <= maxOutputBytes) stdout.push(Buffer.from(chunk)); else stop();
+      if (size <= maxOutputBytes) stdout.push(Buffer.from(chunk)); else stop(`command output exceeded ${maxOutputBytes} bytes`);
     });
     child.stderr.on('data', (chunk: Buffer) => {
       size += chunk.length;
-      if (size <= maxOutputBytes) stderr.push(Buffer.from(chunk)); else stop();
+      if (size <= maxOutputBytes) stderr.push(Buffer.from(chunk)); else stop(`command output exceeded ${maxOutputBytes} bytes`);
     });
     child.once('error', () => finish({ ok: false, status: null, stdout: '', stderr: 'command spawn failed' }));
     child.once('close', (status) => finish({ ok: status === 0, status, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }));
@@ -1430,6 +1857,8 @@ export interface PrimaryRuntimeRecoveryDependencies {
   currentUid?: () => Promise<number | undefined>;
   runCommand?: CommandRunner;
   verifyLocal?: (config: RecoveryConfig) => Promise<VerifyResult>;
+  /** Rebind the independently supervised OAuth Connector after a whole-Runtime release switch. */
+  repairPrimaryConnectorBinding?: (config: RecoveryConfig) => Promise<{ ok: boolean; attempted: boolean; noOp?: boolean; detail: string }>;
   runtimeRunning?: (config: RecoveryConfig) => boolean;
   ensureRuntimeLaunchContract?: (controllerHome: string) => void;
   now?: () => number;
@@ -1445,23 +1874,120 @@ export interface RuntimeReleaseActivationGuard {
   expectedActiveReleaseId?: string | null;
 }
 
-function configuredPrimaryRuntimeService(config: RecoveryConfig): PrimaryRuntimeServiceConfig {
-  return config.primaryRuntimeService ?? { platform: 'launchd' };
+function configuredPrimaryRuntimeService(config: RecoveryConfig, platform: NodeJS.Platform = process.platform): PrimaryRuntimeServiceConfig {
+  return config.primaryRuntimeService ?? defaultPrimaryRuntimeServiceConfig(platform);
 }
 
-function primaryRuntimeLaunchdService(config: RecoveryConfig, uid: number): LaunchdService | undefined {
-  const configured = configuredPrimaryRuntimeService(config);
-  if (configured.platform !== 'launchd') return undefined;
+interface PrimaryRuntimeServiceOwner {
+  platform: 'launchd' | 'systemd-user';
+  target: string;
+  uid: number;
+  launchd?: LaunchdService;
+  unitName?: string;
+  unitPath?: string;
+}
+
+function primaryRuntimeServiceOwner(
+  config: RecoveryConfig,
+  platform: NodeJS.Platform,
+  uid: number | undefined,
+): PrimaryRuntimeServiceOwner | undefined {
+  if (uid === undefined) return undefined;
+  const configured = configuredPrimaryRuntimeService(config, platform);
   const paths = forgeRuntimeServicePaths(config.controllerHome);
-  if (!existsSync(paths.installedPlistPath)) return undefined;
-  const domain = `gui/${uid}`;
-  return {
-    uid,
-    domain,
-    target: `${domain}/${paths.label}`,
-    label: paths.label,
-    plistPath: paths.installedPlistPath,
+  if (platform === 'darwin' && configured.platform === 'launchd') {
+    if (!existsSync(paths.installedPlistPath)) return undefined;
+    const domain = `gui/${uid}`;
+    const launchd: LaunchdService = {
+      uid,
+      domain,
+      target: `${domain}/${paths.label}`,
+      label: paths.label,
+      plistPath: paths.installedPlistPath,
+    };
+    return { platform: 'launchd', target: launchd.target, uid, launchd };
+  }
+  if (platform === 'linux' && configured.platform === 'systemd-user') {
+    const unitName = systemdUserUnitName(paths.label);
+    const unitPath = systemdUserUnitPath(unitName);
+    if (!existsSync(unitPath)) return undefined;
+    return { platform: 'systemd-user', target: unitName, uid, unitName, unitPath };
+  }
+  return undefined;
+}
+
+async function ensurePrimaryRuntimeServiceStarted(
+  owner: PrimaryRuntimeServiceOwner,
+  runCommand: CommandRunner,
+  mode: 'start' | 'restart' = 'start',
+): Promise<{ ok: boolean; detail: string }> {
+  if (owner.platform === 'launchd') return ensureLaunchdServiceStarted(owner.launchd!, runCommand);
+  const action = mode === 'restart' ? 'restart' : 'start';
+  const result = await runCommand('systemctl', ['--user', action, owner.unitName!], 15_000);
+  return result.ok
+    ? { ok: true, detail: owner.target }
+    : { ok: false, detail: `systemd-user ${action} failed: ${result.stderr || result.stdout || result.status}` };
+}
+
+async function stopPrimaryRuntimeServiceOwner(
+  owner: PrimaryRuntimeServiceOwner,
+  runCommand: CommandRunner,
+): Promise<{ ok: boolean; detail: string }> {
+  if (owner.platform === 'launchd') {
+    const stopped = await runCommand('launchctl', ['bootout', owner.launchd!.target], 15_000);
+    const stoppedCleanly = stopped.ok || /not found|no such process|could not find service|service is not loaded/i.test(`${stopped.stderr}\n${stopped.stdout}`);
+    return stoppedCleanly
+      ? { ok: true, detail: owner.target }
+      : { ok: false, detail: `primary Runtime bootout failed: ${stopped.stderr || stopped.stdout || stopped.status}` };
+  }
+  const stopped = await runCommand('systemctl', ['--user', 'stop', owner.unitName!], 15_000);
+  return stopped.ok
+    ? { ok: true, detail: owner.target }
+    : { ok: false, detail: `primary Runtime systemd-user stop failed: ${stopped.stderr || stopped.stdout || stopped.status}` };
+}
+
+async function waitForPrimaryRuntimeServiceStopped(input: {
+  owner: PrimaryRuntimeServiceOwner;
+  timeoutMs: number;
+  now: () => number;
+  wait: (ms: number) => Promise<void>;
+  runCommand: CommandRunner;
+}): Promise<boolean> {
+  if (input.owner.platform === 'launchd') {
+    return waitForLaunchdServiceUnloaded({
+      service: input.owner.launchd!,
+      timeoutMs: input.timeoutMs,
+      now: input.now,
+      wait: input.wait,
+      runCommand: input.runCommand,
+    });
+  }
+  const observe = async () => {
+    const result = await input.runCommand('systemctl', ['--user', 'show', '--property', 'ActiveState', '--value', input.owner.unitName!], 5_000);
+    if (!result.ok) return false;
+    return /^(inactive|failed)$/.test(result.stdout.trim());
   };
+  const deadline = input.now() + input.timeoutMs;
+  while (input.now() < deadline) {
+    if (await observe()) return true;
+    await input.wait(250);
+  }
+  return observe();
+}
+
+function primaryRuntimeServiceContractMatches(config: RecoveryConfig, owner: PrimaryRuntimeServiceOwner): boolean {
+  if (owner.platform === 'launchd') {
+    return inspectForgeRuntimeLaunchAgentContract({
+      controllerHome: config.controllerHome,
+      inspectUserLaunchAgent: true,
+    }).matches;
+  }
+  try {
+    const unit = readFileSync(owner.unitPath!, 'utf8');
+    return unit === renderPackageRuntimeSystemdUserService(config.controllerHome);
+  } catch {
+    return false;
+  }
 }
 
 export interface PrimaryConnectorRecoveryDependencies {
@@ -1479,14 +2005,55 @@ export interface PrimaryConnectorRecoveryDependencies {
   sleep?: (ms: number) => Promise<void>;
 }
 
-function primaryConnectorLaunchdService(config: RecoveryConfig, uid: number): LaunchdService | undefined {
+interface PrimaryConnectorServiceOwner {
+  platform: 'launchd' | 'systemd-user';
+  label: string;
+  target: string;
+  uid: number;
+  launchd?: LaunchdService;
+  unitName?: string;
+  unitPath?: string;
+}
+
+function primaryConnectorServiceOwner(
+  config: RecoveryConfig,
+  platform: NodeJS.Platform,
+  uid: number | undefined,
+): PrimaryConnectorServiceOwner | undefined {
   const configured = config.primaryConnectorService;
-  if (!configured || configured.platform !== 'launchd' || !configured.label.trim()) return undefined;
-  const label = configured.label.trim();
-  const plistPath = resolve(configured.plistPath ?? join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`));
-  if (!existsSync(plistPath)) return undefined;
-  const domain = `gui/${uid}`;
-  return { uid, domain, target: `${domain}/${label}`, label, plistPath };
+  if (!configured || uid === undefined) return undefined;
+  const paths = packageConnectorServicePaths(config.controllerHome);
+  if (configured.platform === 'launchd') {
+    if (platform !== 'darwin' || !configured.label.trim()) return undefined;
+    const label = configured.label.trim();
+    const plistPath = resolve(configured.plistPath ?? join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`));
+    if (!existsSync(plistPath)) return undefined;
+    const domain = `gui/${uid}`;
+    const launchd = { uid, domain, target: `${domain}/${label}`, label, plistPath };
+    return { platform: 'launchd', label, target: launchd.target, uid, launchd };
+  }
+  if (platform !== 'linux') return undefined;
+  if (configured.label?.trim() && configured.label.trim() !== paths.label) return undefined;
+  const unitName = systemdUserUnitName(paths.label);
+  return {
+    platform: 'systemd-user',
+    label: paths.label,
+    target: `systemd-user:${unitName}`,
+    uid,
+    unitName,
+    unitPath: systemdUserUnitPath(paths.label),
+  };
+}
+
+async function ensurePrimaryConnectorServiceStarted(
+  owner: PrimaryConnectorServiceOwner,
+  runCommand: CommandRunner,
+): Promise<{ ok: boolean; detail: string }> {
+  if (owner.platform === 'launchd') return ensureLaunchdServiceStarted(owner.launchd!, runCommand);
+  const restarted = await runCommand('systemctl', ['--user', 'restart', owner.unitName!], 15_000);
+  return restarted.ok
+    ? { ok: true, detail: owner.target }
+    : { ok: false, detail: `systemd-user restart failed: ${restarted.stderr || restarted.stdout || restarted.status}` };
 }
 
 async function probePrimaryConnectorLocal(
@@ -1495,29 +2062,47 @@ async function probePrimaryConnectorLocal(
 ): Promise<{ ok: boolean; detail: string; status?: number } | undefined> {
   const localMcpUrl = config.primaryConnectorService?.localMcpUrl?.trim();
   if (!localMcpUrl) return undefined;
-  return probeExternalMcp(transport, localMcpUrl);
+  return probeExternalMcp(transport, localMcpUrl, {
+    acceptOAuthChallenge: packageConnectorAuthMode(config.controllerHome) === 'oauth',
+  });
 }
 
 function activePackageConnectorReleaseBinding(config: RecoveryConfig): PackageConnectorReleaseBinding | undefined {
   const configured = config.primaryConnectorService;
-  if (!configured || configured.platform !== 'launchd' || !configured.localMcpUrl?.trim()) return undefined;
+  if (!configured || !configured.localMcpUrl?.trim()) return undefined;
   const authority = readRuntimeReleaseAuthority(config.controllerHome);
   if (!authority) return undefined;
   const releaseRoot = dirname(resolve(authority.active.manifestPath));
   const packageRoot = join(releaseRoot, 'package');
   const paths = packageConnectorServicePaths(config.controllerHome);
-  const configuredPlist = resolve(configured.plistPath ?? paths.installedPlistPath);
-  if (configured.label !== paths.label || configuredPlist !== resolve(paths.installedPlistPath)) return undefined;
+  if (configured.platform === 'launchd') {
+    const configuredPlist = resolve(configured.plistPath ?? paths.installedPlistPath);
+    if (configured.label !== paths.label || configuredPlist !== resolve(paths.installedPlistPath)) return undefined;
+  } else if (configured.label?.trim() && configured.label.trim() !== paths.label) {
+    return undefined;
+  }
   if (!existsSync(join(packageRoot, 'src', 'cli', 'index.ts')) || !existsSync(join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs'))) return undefined;
   return { releaseId: authority.active.releaseId, releaseRoot, packageRoot };
 }
 
-async function repairPrimaryConnectorBinding(config: RecoveryConfig): Promise<{ ok: boolean; attempted: boolean; noOp?: boolean; detail: string }> {
+export function resolveRecoveryPackageConnectorExecutable(
+  execPath: string = process.execPath,
+  env: NodeJS.ProcessEnv = process.env,
+  accountHome: string = homedir(),
+): string {
+  return resolveBunExecutable(execPath, env, accountHome);
+}
+
+async function repairPrimaryConnectorBinding(
+  config: RecoveryConfig,
+  platform: NodeJS.Platform = process.platform,
+): Promise<{ ok: boolean; attempted: boolean; noOp?: boolean; detail: string }> {
   const release = activePackageConnectorReleaseBinding(config);
   const endpoint = config.primaryConnectorService?.localMcpUrl?.trim();
   if (!release || !endpoint) return { ok: true, attempted: false, noOp: true, detail: 'primary Connector does not use the canonical package-release binding contract' };
   try {
-    const result = await ensurePackageConnectorService({ release, controllerHome: config.controllerHome, endpoint, platform: 'darwin' });
+    const executable = resolveRecoveryPackageConnectorExecutable();
+    const result = await ensurePackageConnectorService({ release, controllerHome: config.controllerHome, endpoint, executable, platform });
     const attempted = result.reused !== true;
     return {
       ok: true,
@@ -1534,7 +2119,7 @@ async function repairPrimaryConnectorBinding(config: RecoveryConfig): Promise<{
 
 async function probePrimaryConnectorOwnership(
   config: RecoveryConfig,
-  service: LaunchdService,
+  service: PrimaryConnectorServiceOwner,
   runCommand: CommandRunner = command,
 ): Promise<{ ok: boolean; detail: string }> {
   const localMcpUrl = config.primaryConnectorService?.localMcpUrl?.trim();
@@ -1548,11 +2133,18 @@ async function probePrimaryConnectorOwnership(
   } catch {
     return { ok: false, detail: `primary Connector local MCP endpoint has no verifiable TCP port: ${localMcpUrl}` };
   }
-  const printed = await runCommand('launchctl', ['print', service.target], 5_000);
-  const pidMatch = printed.ok ? printed.stdout.match(/\bpid\s*=\s*(\d+)/) : null;
-  const pid = pidMatch ? Number(pidMatch[1]) : undefined;
+  let pid: number | undefined;
+  if (service.platform === 'launchd') {
+    const printed = await runCommand('launchctl', ['print', service.target], 5_000);
+    const pidMatch = printed.ok ? printed.stdout.match(/\bpid\s*=\s*(\d+)/) : null;
+    pid = pidMatch ? Number(pidMatch[1]) : undefined;
+  } else {
+    const shown = await runCommand('systemctl', ['--user', 'show', '--property', 'MainPID', '--value', service.unitName!], 5_000);
+    const parsed = Number(shown.stdout.trim());
+    pid = shown.ok && Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+  }
   if (!pid || !Number.isInteger(pid)) {
-    return { ok: false, detail: `configured primary Connector launchd service has no live pid: ${service.target}` };
+    return { ok: false, detail: `configured primary Connector ${service.platform} service has no live pid: ${service.target}` };
   }
   const listening = await runCommand('lsof', ['-nP', '-a', '-p', String(pid), `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], 5_000);
   const listenerPids = listening.stdout.split(/\s+/).map((value) => Number(value)).filter(Number.isInteger);
@@ -1575,27 +2167,21 @@ export async function restartPrimaryConnector(
   // That probe is expected to be false when this recovery action is needed,
   // so it must not prevent a healthy canonical Runtime from repairing the
   // Connector service.
-  const canonicalRuntimeHealthy = initialLocal.runtime.ok
-    && initialLocal.runtime.running
-    && initialLocal.runtime.ready
-    && !initialLocal.runtime.stale
-    && initialLocal.probes.active_gateway?.ok === true;
+  const canonicalRuntimeHealthy = canonicalRuntimeSafeForTargetedConnectorRecovery(initialLocal);
   if (!canonicalRuntimeHealthy) {
     return {
       ok: false,
       attempted: false,
       noOp: true,
-      detail: 'Canonical Runtime must be locally healthy before the primary Connector is restarted',
+      detail: 'Canonical Runtime ownership/release execution authority must be healthy before the primary Connector is restarted',
       verify: initialLocal,
     };
   }
-  if ((dependencies.platform ?? process.platform) !== 'darwin') {
-    return { ok: false, attempted: false, noOp: true, detail: 'primary Connector restart currently requires the configured macOS launchd service', verify: initialLocal };
-  }
+  const platform = dependencies.platform ?? process.platform;
   const uid = await (dependencies.currentUid ?? currentUid)();
-  const service = uid === undefined ? undefined : primaryConnectorLaunchdService(config, uid);
+  const service = primaryConnectorServiceOwner(config, platform, uid);
   if (!service) {
-    return { ok: false, attempted: false, noOp: true, detail: 'primary Connector launchd service is not configured or installed', verify: initialLocal };
+    return { ok: false, attempted: false, noOp: true, detail: `primary Connector ${config.primaryConnectorService?.platform ?? 'service'} is not configured for ${platform}`, verify: initialLocal };
   }
   const reconnect = dependencies.reconnect ?? reconnectMain;
   const probeConnectorLocal = dependencies.probeConnectorLocal ?? probePrimaryConnectorLocal;
@@ -1607,7 +2193,7 @@ export async function restartPrimaryConnector(
   const timeoutMs = config.primaryConnectorService?.postRestartVerifyTimeoutMs ?? 30_000;
   const locked = await withLock(config, { action: 'restart_primary_connector', requestId: dependencies.requestId }, async () => {
     const tunnelConfigured = Boolean(configuredPrimaryPublicTunnel(config));
-    const repairConnectorBinding = dependencies.repairConnectorBinding ?? repairPrimaryConnectorBinding;
+    const repairConnectorBinding = dependencies.repairConnectorBinding ?? ((candidateConfig: RecoveryConfig) => repairPrimaryConnectorBinding(candidateConfig, platform));
     const bindingRepair = await repairConnectorBinding(config);
     if (bindingRepair.attempted) {
       audit(config, bindingRepair.ok ? 'primary_connector_binding_repaired' : 'primary_connector_binding_repair_failed', { detail: bindingRepair.detail });
@@ -1636,7 +2222,7 @@ export async function restartPrimaryConnector(
     // restart and repair the public hop directly.
     const restartConnector = !localConnector?.ok || !connectorOwnership?.ok || !tunnelConfigured;
     if (restartConnector) {
-      const restarted = await ensureLaunchdServiceStarted(service, runCommand);
+      const restarted = await ensurePrimaryConnectorServiceStarted(service, runCommand);
       if (!restarted.ok) {
         audit(config, 'primary_connector_restart_failed', { serviceTarget: service.target, detail: restarted.detail });
         return { ok: false, attempted: true, detail: restarted.detail, serviceTarget: service.target, verify: initialLocal } satisfies PrimaryConnectorRestartResult;
@@ -1658,7 +2244,7 @@ export async function restartPrimaryConnector(
           ok: false,
           attempted: true,
           detail: localConnector.ok
-            ? 'primary Connector restarted but the configured launchd service does not own its local MCP listener'
+            ? `primary Connector restarted but the configured ${service.platform} service does not own its local MCP listener`
             : 'primary Connector restarted but its local MCP endpoint did not recover before timeout',
           serviceTarget: service.target,
           verify: initialLocal,
@@ -1667,30 +2253,38 @@ export async function restartPrimaryConnector(
     }
 
     observed ??= await reconnect(config);
-    if (!observed.ok && localConnector?.ok && connectorOwnership?.ok && configuredPrimaryPublicTunnel(config)) {
-      const tunnel = primaryPublicTunnelService(config, service.uid);
-      if (tunnel) {
-        const tunnelRestarted = await ensureLaunchdServiceStarted(tunnel, dependencies.runCommand ?? command);
-        if (!tunnelRestarted.ok) {
-          audit(config, 'primary_public_tunnel_restart_failed', { serviceTarget: tunnel.target, detail: tunnelRestarted.detail });
-          return {
-            ok: false,
-            attempted: true,
-            detail: `primary Connector is locally healthy but public tunnel restart failed: ${tunnelRestarted.detail}`,
-            serviceTarget: service.target,
-            verify: observed.verify,
-          } satisfies PrimaryConnectorRestartResult;
+    const primaryTunnel = configuredPrimaryPublicTunnel(config);
+    if (!observed.ok && localConnector?.ok && connectorOwnership?.ok && primaryTunnel) {
+      let tunnelRestarted: { ok: boolean; attempted: boolean; detail: string; serviceTarget: string } | undefined;
+      if (primaryTunnel.platform === 'launchd') {
+        const tunnel = primaryPublicTunnelService(config, service.uid);
+        if (tunnel) {
+          const result = await ensureLaunchdServiceStarted(tunnel, runCommand);
+          tunnelRestarted = { ok: result.ok, attempted: true, detail: result.detail, serviceTarget: tunnel.target };
         }
-        const tunnelDeadline = now() + (configuredPrimaryPublicTunnel(config)?.postRestartVerifyTimeoutMs ?? 20_000);
-        while (!observed.ok && now() < tunnelDeadline) {
-          await wait(1_000);
-          observed = await reconnect(config);
-        }
-        audit(config, observed.ok ? 'primary_public_tunnel_restart_succeeded' : 'primary_public_tunnel_restart_unverified', {
-          serviceTarget: tunnel.target,
-          detail: observed.detail,
-        });
+      } else {
+        tunnelRestarted = await ensureOpenAiTunnelRuntimeStarted(primaryTunnel, runCommand);
+      }
+      if (!tunnelRestarted?.ok) {
+        const detail = tunnelRestarted?.detail ?? 'primary public tunnel service configuration is invalid or unavailable';
+        audit(config, 'primary_public_tunnel_restart_failed', { serviceTarget: tunnelRestarted?.serviceTarget, detail });
+        return {
+          ok: false,
+          attempted: tunnelRestarted?.attempted ?? false,
+          detail: `primary Connector is locally healthy but public tunnel restart failed: ${detail}`,
+          serviceTarget: service.target,
+          verify: observed.verify,
+        } satisfies PrimaryConnectorRestartResult;
       }
+      const tunnelDeadline = now() + (primaryTunnel.postRestartVerifyTimeoutMs ?? 20_000);
+      while (!observed.ok && now() < tunnelDeadline) {
+        await wait(1_000);
+        observed = await reconnect(config);
+      }
+      audit(config, observed.ok ? 'primary_public_tunnel_restart_succeeded' : 'primary_public_tunnel_restart_unverified', {
+        serviceTarget: tunnelRestarted.serviceTarget,
+        detail: observed.detail,
+      });
     } else {
       const deadline = now() + timeoutMs;
       while (!observed.ok && now() < deadline) {
@@ -1909,17 +2503,14 @@ interface PrimaryRuntimeStoppedTransition {
  */
 async function stopPrimaryRuntimeForReleaseTransition(input: {
   config: RecoveryConfig;
-  service: LaunchdService;
+  service: PrimaryRuntimeServiceOwner;
   now: () => number;
   wait: (ms: number) => Promise<void>;
   runCommand: CommandRunner;
   runtimeRunning: (config: RecoveryConfig) => boolean;
 }): Promise<PrimaryRuntimeStoppedTransition> {
-  const stopped = await input.runCommand('launchctl', ['bootout', input.service.target], 15_000);
-  const stoppedCleanly = stopped.ok || /not found|no such process|could not find service|service is not loaded/i.test(`${stopped.stderr}\n${stopped.stdout}`);
-  if (!stoppedCleanly) {
-    return { ok: false, detail: `primary Runtime bootout failed: ${stopped.stderr || stopped.stdout || stopped.status}` };
-  }
+  const stopped = await stopPrimaryRuntimeServiceOwner(input.service, input.runCommand);
+  if (!stopped.ok) return { ok: false, detail: stopped.detail };
   const runtimeStopped = await waitForPrimaryRuntimeState({
     config: input.config,
     expectedRunning: false,
@@ -1928,15 +2519,24 @@ async function stopPrimaryRuntimeForReleaseTransition(input: {
     wait: input.wait,
     runtimeRunning: input.runtimeRunning,
   });
-  if (!runtimeStopped) return { ok: false, detail: 'primary Runtime owner remained live after bounded launchd bootout' };
-  const serviceUnloaded = await waitForLaunchdServiceUnloaded({
-    service: input.service,
+  if (!runtimeStopped) {
+    return { ok: false, detail: `primary Runtime owner remained live after bounded ${input.service.platform} stop` };
+  }
+  const serviceStopped = await waitForPrimaryRuntimeServiceStopped({
+    owner: input.service,
     timeoutMs: 20_000,
     now: input.now,
     wait: input.wait,
     runCommand: input.runCommand,
   });
-  if (!serviceUnloaded) return { ok: false, detail: 'primary Runtime launchd service remained loaded after bounded bootout' };
+  if (!serviceStopped) {
+    return {
+      ok: false,
+      detail: input.service.platform === 'launchd'
+        ? 'primary Runtime launchd service remained loaded after bounded bootout'
+        : 'primary Runtime systemd-user service remained active after bounded stop',
+    };
+  }
 
   let portReleased = await waitForPrimaryRuntimePortReleased({
     config: input.config,
@@ -1959,11 +2559,11 @@ async function stopPrimaryRuntimeForReleaseTransition(input: {
   if (!portReleased) {
     return {
       ok: false,
-      detail: `primary Runtime TCP port remained occupied after bounded launchd bootout: ${staleListenerCleanup?.detail ?? 'listener did not release'}`,
+      detail: `primary Runtime TCP port remained occupied after bounded ${input.service.platform} stop: ${staleListenerCleanup?.detail ?? 'listener did not release'}`,
       staleListenerCleanup,
     };
   }
-  return { ok: true, detail: 'primary Runtime service, owner, and TCP listener are stopped', staleListenerCleanup };
+  return { ok: true, detail: `primary Runtime ${input.service.platform} service, owner, and TCP listener are stopped`, staleListenerCleanup };
 }
 
 async function verifyPrimaryRuntimeAfterStart(input: {
@@ -1996,7 +2596,7 @@ interface PrimaryRuntimeRebindStartResult {
  */
 async function rebindStartAndVerifyPrimaryRuntime(input: {
   config: RecoveryConfig;
-  service: LaunchdService;
+  service: PrimaryRuntimeServiceOwner;
   runCommand: CommandRunner;
   now: () => number;
   wait: (ms: number) => Promise<void>;
@@ -2008,13 +2608,28 @@ async function rebindStartAndVerifyPrimaryRuntime(input: {
   successDetail: string;
 }): Promise<PrimaryRuntimeRebindStartResult> {
   try {
-    const ensureRuntimeLaunchContract = input.ensureRuntimeLaunchContract
-      ?? ((controllerHome: string) => { ensureForgeRuntimeLaunchAgentContract({ controllerHome, installUserLaunchAgent: true }); });
-    ensureRuntimeLaunchContract(input.config.controllerHome);
+    if (input.service.platform === 'launchd') {
+      const ensureRuntimeLaunchContract = input.ensureRuntimeLaunchContract
+        ?? ((controllerHome: string) => { ensureForgeRuntimeLaunchAgentContract({ controllerHome, installUserLaunchAgent: true }); });
+      ensureRuntimeLaunchContract(input.config.controllerHome);
+    } else {
+      const unitPath = writePackageRuntimeSystemdUserService(input.config.controllerHome);
+      if (resolve(unitPath) !== resolve(input.service.unitPath!)) {
+        throw new Error('canonical package Runtime systemd-user unit path changed during Recovery rebind');
+      }
+      for (const args of [
+        ['--user', 'daemon-reload'],
+        ['--user', 'enable', input.service.unitName!],
+      ]) {
+        const result = await input.runCommand('systemctl', args, 15_000);
+        if (!result.ok) throw new Error(`systemctl ${args.join(' ')} failed: ${result.stderr || result.stdout || result.status}`);
+      }
+    }
   } catch (error) {
+    const manager = input.service.platform === 'launchd' ? 'launchd' : 'systemd-user';
     return {
       ok: false,
-      detail: `primary Runtime launchd contract rebuild failed ${input.contractFailureContext ?? 'after release transition'}: ${error instanceof Error ? error.message : String(error)}`,
+      detail: `primary Runtime ${manager} contract rebuild failed ${input.contractFailureContext ?? 'after release transition'}: ${error instanceof Error ? error.message : String(error)}`,
       verify: await input.verifyLocal(input.config),
     };
   }
@@ -2029,7 +2644,7 @@ async function rebindStartAndVerifyPrimaryRuntime(input: {
     };
   }
 
-  const started = await ensureLaunchdServiceStarted(input.service, input.runCommand);
+  const started = await ensurePrimaryRuntimeServiceStarted(input.service, input.runCommand, 'start');
   if (!started.ok) {
     return { ok: false, detail: started.detail, verify: await input.verifyLocal(input.config) };
   }
@@ -2041,7 +2656,7 @@ async function rebindStartAndVerifyPrimaryRuntime(input: {
     verifyLocal: input.verifyLocal,
   });
   if (verify.ok) return { ok: true, detail: input.successDetail, verify };
-  await input.runCommand('launchctl', ['bootout', input.service.target], 15_000);
+  await stopPrimaryRuntimeServiceOwner(input.service, input.runCommand);
   return {
     ok: false,
     detail: 'release transition started a Runtime that failed whole-Runtime verification; service was stopped to prevent a restart loop',
@@ -2056,18 +2671,18 @@ export async function restartPrimaryRuntime(
   const verifyLocal = dependencies.verifyLocal ?? verifyLocalRuntime;
   const initial = await verifyLocal(config);
   if (initial.ok) return { ok: true, attempted: false, noOp: true, detail: 'Canonical Forge Runtime is already healthy', verify: initial };
-  if ((dependencies.platform ?? process.platform) !== 'darwin') {
-    return { ok: false, attempted: false, noOp: true, detail: 'primary Runtime automatic restart currently requires the configured macOS launchd service', verify: initial };
-  }
+  const platform = dependencies.platform ?? process.platform;
   const uid = await (dependencies.currentUid ?? currentUid)();
-  const service = uid === undefined ? undefined : primaryRuntimeLaunchdService(config, uid);
-  if (!service) return { ok: false, attempted: false, noOp: true, detail: 'primary Forge Runtime launchd service is not installed', verify: initial };
+  const service = primaryRuntimeServiceOwner(config, platform, uid);
+  if (!service) {
+    return { ok: false, attempted: false, noOp: true, detail: `primary Forge Runtime ${configuredPrimaryRuntimeService(config, platform).platform} service is not installed for ${platform}`, verify: initial };
+  }
   const now = dependencies.now ?? Date.now;
   const wait = dependencies.sleep ?? sleep;
   const locked = await withLock(config, { action: 'restart_primary_runtime' }, async () => {
     const before = await verifyLocal(config);
     if (before.ok) return { ok: true, attempted: false, noOp: true, detail: 'Canonical Forge Runtime recovered before restart', serviceTarget: service.target, verify: before } satisfies PrimaryRuntimeRestartResult;
-    const started = await ensureLaunchdServiceStarted(service, dependencies.runCommand ?? command);
+    const started = await ensurePrimaryRuntimeServiceStarted(service, dependencies.runCommand ?? command, 'restart');
     if (!started.ok) {
       audit(config, 'primary_runtime_restart_failed', { serviceTarget: service.target, detail: started.detail });
       return { ok: false, attempted: true, detail: started.detail, serviceTarget: service.target, verify: before } satisfies PrimaryRuntimeRestartResult;
@@ -2098,12 +2713,12 @@ export async function recoverPrimaryRuntime(
   const verifyLocal = dependencies.verifyLocal ?? verifyLocalRuntime;
   const initial = await verifyLocal(config);
   if (initial.ok) return { ok: true, attempted: false, noOp: true, detail: 'Canonical Forge Runtime recovered before rollback', verify: initial };
-  if ((dependencies.platform ?? process.platform) !== 'darwin') {
-    return { ok: false, attempted: false, noOp: true, detail: 'automatic whole-Runtime recovery currently requires the configured macOS launchd service', verify: initial };
-  }
+  const platform = dependencies.platform ?? process.platform;
   const uid = await (dependencies.currentUid ?? currentUid)();
-  const service = uid === undefined ? undefined : primaryRuntimeLaunchdService(config, uid);
-  if (!service) return { ok: false, attempted: false, noOp: true, detail: 'primary Forge Runtime launchd service is not installed', verify: initial };
+  const service = primaryRuntimeServiceOwner(config, platform, uid);
+  if (!service) {
+    return { ok: false, attempted: false, noOp: true, detail: `primary Forge Runtime ${configuredPrimaryRuntimeService(config, platform).platform} service is not installed for ${platform}`, verify: initial };
+  }
   const runCommand = dependencies.runCommand ?? command;
   const now = dependencies.now ?? Date.now;
   const wait = dependencies.sleep ?? sleep;
@@ -2151,8 +2766,8 @@ export async function recoverPrimaryRuntime(
       audit(config, 'primary_runtime_recovery_succeeded', { serviceTarget: service.target, rollbackOperationId: rollback.operationId, restoredRelease: restarted.verify.releases.active?.revision });
       return { ok: true, attempted: true, detail: restarted.detail, serviceTarget: service.target, rollback, verify: restarted.verify } satisfies PrimaryRuntimeRecoveryResult;
     }
-    const contractFailure = restarted.detail.startsWith('primary Runtime launchd contract rebuild failed');
-    audit(config, contractFailure ? 'primary_runtime_recovery_launchd_contract_failed' : 'primary_runtime_recovery_unverified', {
+    const contractFailure = /^primary Runtime (launchd|systemd-user) contract rebuild failed/.test(restarted.detail);
+    audit(config, contractFailure ? 'primary_runtime_recovery_service_contract_failed' : 'primary_runtime_recovery_unverified', {
       serviceTarget: service.target,
       rollbackOperationId: rollback.operationId,
       detail: restarted.detail,
@@ -2208,6 +2823,7 @@ function validateRuntimeReleaseCandidate(
   if (identity !== manifest.artifactIdentity) {
     throw new Error(`RUNTIME_RELEASE_CANDIDATE_ARTIFACT_MISMATCH: expected ${manifest.artifactIdentity} observed ${identity}`);
   }
+  assertRuntimeReleaseExecutionCanaries(resolvedManifestPath, config.controllerHome);
   return { manifest, releaseRoot, manifestPath: resolvedManifestPath };
 }
 
@@ -2234,17 +2850,18 @@ export async function activateRuntimeRelease(
     return { ok: false, attempted: false, noOp: true, detail };
   }
   const platform = dependencies.platform ?? process.platform;
-  if (platform !== 'darwin') {
-    return { ok: false, attempted: false, noOp: true, detail: 'Runtime release activation currently requires the configured macOS launchd service' };
-  }
   const uid = await (dependencies.currentUid ?? currentUid)();
-  const service = uid === undefined ? undefined : primaryRuntimeLaunchdService(config, uid);
-  if (!service) return { ok: false, attempted: false, noOp: true, detail: 'primary Forge Runtime launchd service is not installed', verify: await verifyStableRuntime(config) };
+  const service = primaryRuntimeServiceOwner(config, platform, uid);
+  if (!service) {
+    return { ok: false, attempted: false, noOp: true, detail: `primary Forge Runtime ${configuredPrimaryRuntimeService(config, platform).platform} service is not installed for ${platform}`, verify: await verifyStableRuntime(config) };
+  }
   const runCommand = dependencies.runCommand ?? command;
   const now = dependencies.now ?? Date.now;
   const wait = dependencies.sleep ?? sleep;
   const runtimeRunning = dependencies.runtimeRunning ?? ((value: RecoveryConfig) => observeRuntimeStatus(value.controllerHome).running);
   const verifyLocal = dependencies.verifyLocal ?? verifyLocalRuntime;
+  const repairConnectorBinding = dependencies.repairPrimaryConnectorBinding
+    ?? ((value: RecoveryConfig) => repairPrimaryConnectorBinding(value, platform));
   const operationId = `recovery-activate-runtime-${Date.now()}-${randomUUID().slice(0, 8)}`;
   const lockRequestId = guard.requestId?.trim() || operationId;
   const locked = await withLock(config, { action: 'activate_runtime_release', requestId: lockRequestId }, async () => {
@@ -2296,10 +2913,10 @@ export async function activateRuntimeRelease(
         return { ok: false, attempted: false, noOp: true, detail, operationId } satisfies RuntimeReleaseActivationResult;
       }
       return {
-        ok: true,
+        ok: (await repairConnectorBinding(config)).ok,
         attempted: false,
         noOp: true,
-        detail: 'requested Runtime release is already the active whole-Runtime release',
+        detail: 'requested Runtime release is already the active whole-Runtime release; its persistent Connector binding was reconciled',
         operationId,
         verify: await verifyLocal(config),
       } satisfies RuntimeReleaseActivationResult;
@@ -2309,10 +2926,7 @@ export async function activateRuntimeRelease(
       let serviceContractMatches = false;
       if (behaviorEquivalent && !storageMigrationRequired) {
         try {
-          serviceContractMatches = inspectForgeRuntimeLaunchAgentContract({
-            controllerHome: config.controllerHome,
-            inspectUserLaunchAgent: true,
-          }).matches;
+          serviceContractMatches = primaryRuntimeServiceContractMatches(config, service);
         } catch (error) {
           audit(config, 'runtime_release_activation_service_contract_inspection_failed', {
             operationId,
@@ -2337,8 +2951,8 @@ export async function activateRuntimeRelease(
           attempted: false,
           noOp: true,
           detail: verify.ok
-            ? 'candidate Runtime behavior and launchd service contract are identical to the active release; restart skipped'
-            : 'candidate Runtime behavior and launchd service contract are identical to the active release, but the active Runtime is unhealthy',
+            ? 'candidate Runtime behavior and installed service contract are identical to the active release; restart skipped'
+            : 'candidate Runtime behavior and installed service contract are identical to the active release, but the active Runtime is unhealthy',
           operationId,
           verify,
         } satisfies RuntimeReleaseActivationResult;
@@ -2386,45 +3000,81 @@ export async function activateRuntimeRelease(
       audit(config, 'runtime_release_activation_commit_mismatch', { serviceTarget: service.target, operationId });
       return { ok: false, attempted: true, detail, serviceTarget: service.target, verify: await verifyLocal(config) } satisfies RuntimeReleaseActivationResult;
     }
+    // The Connector is independently supervised, but its executable is part of
+    // this immutable Runtime release. Rebind it immediately after publishing
+    // authority and before starting the candidate: full Runtime verification
+    // includes the Connector and must never observe a stale previous release.
+    const candidateConnectorBinding = await repairConnectorBinding(config);
     let storageMigration: ControllerHomeStorageMigration | undefined;
-    const activated = await rebindStartAndVerifyPrimaryRuntime({
-      config,
-      service,
-      runCommand,
-      now,
-      wait,
-      verifyLocal,
-      timeoutMs: configuredPrimaryRuntimeService(config).postRestartVerifyTimeoutMs ?? 60_000,
-      successDetail: 'requested Runtime release started and passed whole-Runtime verification',
-      beforeStart: () => {
-        storageMigration = migrateStoppedRepoLocalControllerHomeStorage(config.controllerHome, platform);
-        if (storageMigration.migrated) {
-          audit(config, 'runtime_controller_home_noindex_migrated', {
-            serviceTarget: service.target,
-            operationId,
-            logicalHome: storageMigration.logicalHome,
-            physicalHome: storageMigration.physicalHome,
-          });
-        }
-      },
-    });
-    let after = activated.verify;
     let activationFailureDetail: string | undefined;
+    let activated: PrimaryRuntimeRebindStartResult;
+    if (!candidateConnectorBinding.ok) {
+      const detail = `persistent Connector binding failed before Runtime activation: ${candidateConnectorBinding.detail}`;
+      activationFailureDetail = detail;
+      audit(config, 'runtime_release_activation_connector_binding_failed', {
+        serviceTarget: service.target,
+        operationId,
+        requestId: lockRequestId,
+        detail: candidateConnectorBinding.detail,
+      });
+      activated = { ok: false, detail, verify: await verifyLocal(config) };
+    } else {
+      activated = await rebindStartAndVerifyPrimaryRuntime({
+        config,
+        service,
+        runCommand,
+        now,
+        wait,
+        verifyLocal,
+        timeoutMs: configuredPrimaryRuntimeService(config).postRestartVerifyTimeoutMs ?? 60_000,
+        successDetail: 'requested Runtime release started and passed whole-Runtime verification',
+        beforeStart: () => {
+          storageMigration = migrateStoppedRepoLocalControllerHomeStorage(config.controllerHome, platform);
+          if (storageMigration.migrated) {
+            audit(config, 'runtime_controller_home_noindex_migrated', {
+              serviceTarget: service.target,
+              operationId,
+              logicalHome: storageMigration.logicalHome,
+              physicalHome: storageMigration.physicalHome,
+            });
+          }
+        },
+      });
+    }
+    let after = activated.verify;
     if (activated.ok && after.releases.active?.revision === candidate.manifest.releaseId) {
-      audit(config, 'runtime_release_activation_succeeded', { serviceTarget: service.target, operationId, requestId: lockRequestId, activeRevision: after.releases.active?.revision, expectedAuthorityRevision: guard.expectedAuthorityRevision, expectedActiveReleaseId: guard.expectedActiveReleaseId, controllerHomeStorageMigrated: storageMigration?.migrated === true });
-      return { ok: true, attempted: true, detail: storageMigration?.migrated ? 'requested Runtime release activated, Controller Home migrated to .noindex storage, and whole-Runtime verification passed' : 'requested Runtime release activated and passed whole-Runtime verification', serviceTarget: service.target, operationId, verify: after } satisfies RuntimeReleaseActivationResult;
+      audit(config, 'runtime_release_activation_succeeded', {
+        serviceTarget: service.target,
+        operationId,
+        requestId: lockRequestId,
+        activeRevision: after.releases.active?.revision,
+        expectedAuthorityRevision: guard.expectedAuthorityRevision,
+        expectedActiveReleaseId: guard.expectedActiveReleaseId,
+        controllerHomeStorageMigrated: storageMigration?.migrated === true,
+        connectorBindingRepaired: candidateConnectorBinding.attempted,
+      });
+      return {
+        ok: true,
+        attempted: true,
+        detail: storageMigration?.migrated
+          ? 'requested Runtime release activated, Controller Home migrated to .noindex storage, persistent Connector rebound, and whole-Runtime verification passed'
+          : 'requested Runtime release activated, persistent Connector rebound, and whole-Runtime verification passed',
+        serviceTarget: service.target,
+        operationId,
+        verify: after,
+      } satisfies RuntimeReleaseActivationResult;
     }
-    if (!activated.ok) {
+    if (!activated.ok && !activationFailureDetail) {
       activationFailureDetail = activated.detail;
-      const auditAction = activated.detail.startsWith('primary Runtime launchd contract rebuild failed')
-        ? 'runtime_release_activation_launchd_contract_failed'
+      const auditAction = /^primary Runtime (launchd|systemd-user) contract rebuild failed/.test(activated.detail)
+        ? 'runtime_release_activation_service_contract_failed'
         : activated.detail.startsWith('release transition pre-start preparation failed')
           ? 'runtime_controller_home_noindex_migration_failed'
           : activated.detail.includes('start')
             ? 'runtime_release_activation_start_failed'
             : 'runtime_release_activation_unverified';
       audit(config, auditAction, { serviceTarget: service.target, operationId, detail: activated.detail });
-    } else {
+    } else if (!activationFailureDetail) {
       activationFailureDetail = `activated Runtime release identity mismatch: expected ${candidate.manifest.releaseId}, observed ${after.releases.active?.revision ?? 'none'}`;
       audit(config, 'runtime_release_activation_commit_mismatch', { serviceTarget: service.target, operationId, detail: activationFailureDetail });
     }
@@ -2473,7 +3123,23 @@ export async function activateRuntimeRelease(
           timeoutMs: configuredPrimaryRuntimeService(config).postRestartVerifyTimeoutMs ?? 60_000,
           successDetail: 'previous whole-Runtime release and SQLite backup restored, restarted, and verified',
         });
-        rollback = { ok: restarted.ok, operationId: rollbackOperationId, detail: restarted.detail, verify: restarted.verify };
+        const connectorBinding = restarted.ok ? await repairConnectorBinding(config) : undefined;
+        if (connectorBinding && !connectorBinding.ok) {
+          audit(config, 'runtime_release_activation_rollback_connector_binding_failed', {
+            serviceTarget: service.target,
+            operationId,
+            rollbackOperationId,
+            detail: connectorBinding.detail,
+          });
+        }
+        rollback = {
+          ok: restarted.ok && (connectorBinding?.ok ?? true),
+          operationId: rollbackOperationId,
+          detail: connectorBinding && !connectorBinding.ok
+            ? `${restarted.detail}; previous persistent Connector binding failed: ${connectorBinding.detail}`
+            : restarted.detail,
+          verify: restarted.verify,
+        };
       } catch (error) {
         rollback = { ok: false, detail: error instanceof Error ? error.message : 'previous whole-Runtime release rollback failed' };
       }
@@ -2519,6 +3185,10 @@ export async function stageAndActivateConfiguredRuntimeRelease(
   if (!sourceRoot) {
     return { ok: false, attempted: false, noOp: true, detail: 'primary Runtime source root is not configured in standalone Recovery' };
   }
+  const sourceRepositoryId = config.primaryRuntimeSourceRepositoryId?.trim();
+  if (!sourceRepositoryId) {
+    return { ok: false, attempted: false, noOp: true, detail: 'primary Runtime source repository id is not configured in standalone Recovery' };
+  }
   // Capture the base before staging. Staging can take long enough for another
   // activation to win; the later publish must prove this base is still current.
   const expectedAuthority = releaseAuthority(config);
@@ -2527,7 +3197,7 @@ export async function stageAndActivateConfiguredRuntimeRelease(
     ...(requestId?.trim() ? { requestId: requestId.trim() } : {}),
   }, async () => {
     try {
-      const staged = (dependencies.stage ?? stageRuntimeReleaseFromCandidateSource)({ controllerHome: config.controllerHome, sourceRoot });
+      const staged = (dependencies.stage ?? stageRuntimeReleaseFromCandidateSource)({ controllerHome: config.controllerHome, sourceRoot, sourceRepositoryId });
       assertRuntimeReleaseFiles(staged);
       return { ok: true as const, staged };
     } catch (error) {
@@ -2570,7 +3240,7 @@ export async function stageAndActivateConfiguredRuntimeRelease(
   };
 }
 
-function tunnelLaunchdService(configured: PublicTunnelServiceConfig | undefined, uid: number): LaunchdService | undefined {
+function tunnelLaunchdService(configured: RecoveryTunnelServiceConfig | undefined, uid: number): LaunchdService | undefined {
   if (!configured || configured.platform !== 'launchd') return undefined;
   if (!/^com\.[A-Za-z0-9._-]{1,180}$/.test(configured.label)) return undefined;
   const plistPath = configured.plistPath;
@@ -2588,6 +3258,14 @@ function recoveryTunnelService(config: RecoveryConfig, uid: number): LaunchdServ
   return tunnelLaunchdService(configuredRecoveryTunnel(config), uid);
 }
 
+function recoverySystemdTunnelUnit(config: RecoveryConfig): string | undefined {
+  const configured = configuredRecoveryTunnel(config);
+  if (!configured || configured.platform !== 'systemd-user') return undefined;
+  const unitName = configured.unitName.trim();
+  if (!/^[A-Za-z0-9_.@-]{1,180}\.service$/.test(unitName)) return undefined;
+  return unitName;
+}
+
 function primaryPublicTunnelService(config: RecoveryConfig, uid: number): LaunchdService | undefined {
   return tunnelLaunchdService(configuredPrimaryPublicTunnel(config), uid);
 }
@@ -2603,54 +3281,146 @@ export async function repairPublicTunnel(config: RecoveryConfig, dependencies: P
   const verifyLocal = dependencies.verifyLocal ?? verifyLocalRuntime;
   const now = dependencies.now ?? Date.now;
   const wait = dependencies.sleep ?? sleep;
+  const runCommand = dependencies.runCommand ?? command;
   const initial = await verify(config);
   const configured = configuredRecoveryTunnel(config);
   if (!configured) return { ok: false, attempted: false, noOp: true, detail: 'public tunnel repair is not configured', verify: initial };
   const localVerify = await verifyLocal(config);
+  const tunnelProbe = configured.platform === 'openai-secure-tunnel'
+    ? initial.probes.recovery_tunnel_runtime
+    : (initial.probes.recovery_external_http ?? initial.probes.external_mcp_http);
   if (!isExternalTunnelFailure(config, initial, localVerify)) {
-    return { ok: (initial.probes.recovery_external_http ?? initial.probes.external_mcp_http)?.ok === true, attempted: false, noOp: true, detail: 'Recovery tunnel repair requires a healthy local runtime and failed Recovery external endpoint', verify: initial, localVerify };
+    return { ok: tunnelProbe?.ok === true, attempted: false, noOp: true, detail: 'Recovery tunnel repair requires a healthy local runtime and failed managed Recovery tunnel', verify: initial, localVerify };
   }
-  if ((dependencies.platform ?? process.platform) !== 'darwin') {
-    return { ok: false, attempted: false, noOp: true, detail: 'public tunnel repair is only supported for explicitly configured launchd services', verify: initial, localVerify };
+
+  let serviceLabel: string;
+  let serviceTarget: string;
+  let launchdService: LaunchdService | undefined;
+  let systemdUnitName: string | undefined;
+  if (configured.platform === 'launchd') {
+    if ((dependencies.platform ?? process.platform) !== 'darwin') {
+      return { ok: false, attempted: false, noOp: true, detail: 'configured launchd public tunnel can only be repaired on macOS', verify: initial, localVerify };
+    }
+    const uid = await (dependencies.currentUid ?? currentUid)();
+    launchdService = uid === undefined ? undefined : recoveryTunnelService(config, uid);
+    if (!launchdService) return { ok: false, attempted: false, noOp: true, detail: 'public tunnel launchd configuration is invalid or unavailable', verify: initial, localVerify };
+    serviceLabel = launchdService.label;
+    serviceTarget = launchdService.target;
+  } else if (configured.platform === 'systemd-user') {
+    if ((dependencies.platform ?? process.platform) !== 'linux') {
+      return { ok: false, attempted: false, noOp: true, detail: 'configured systemd-user public tunnel can only be repaired on Linux', verify: initial, localVerify };
+    }
+    systemdUnitName = recoverySystemdTunnelUnit(config);
+    if (!systemdUnitName) return { ok: false, attempted: false, noOp: true, detail: 'public tunnel systemd-user configuration is invalid', verify: initial, localVerify };
+    const loaded = await runCommand('systemctl', ['--user', 'show', '--property=LoadState', '--value', systemdUnitName], 5_000);
+    if (!loaded.ok || loaded.stdout.trim() !== 'loaded') {
+      return { ok: false, attempted: false, noOp: true, detail: `public tunnel systemd-user unit is not loaded: ${systemdUnitName}`, verify: initial, localVerify };
+    }
+    serviceLabel = systemdUnitName;
+    serviceTarget = systemdUnitName;
+  } else {
+    serviceLabel = configured.alias;
+    serviceTarget = `tunnel-client:${configured.alias}`;
+    const observed = await observeOpenAiRecoveryTunnel(config, runCommand);
+    if (observed?.observedTunnelId && !observed.tunnelMatches) {
+      return { ok: false, attempted: false, noOp: true, detail: `OpenAI tunnel alias ${configured.alias} is already bound to a different tunnel id`, serviceLabel, serviceTarget, verify: initial, localVerify };
+    }
+    if (observed?.profilePath && !observed.endpointMatches) {
+      return { ok: false, attempted: false, noOp: true, detail: `OpenAI tunnel alias ${configured.alias} is already bound to a different MCP endpoint`, serviceLabel, serviceTarget, verify: initial, localVerify };
+    }
   }
-  const uid = await (dependencies.currentUid ?? currentUid)();
-  const service = uid === undefined ? undefined : recoveryTunnelService(config, uid);
-  if (!service) return { ok: false, attempted: false, noOp: true, detail: 'public tunnel launchd configuration is invalid or unavailable', verify: initial, localVerify };
+
   if (!tunnelRepairAllowed(config, now())) {
-    return { ok: false, attempted: false, noOp: true, detail: 'public tunnel repair is in cooldown', serviceLabel: service.label, serviceTarget: service.target, verify: initial, localVerify };
+    return { ok: false, attempted: false, noOp: true, detail: 'public tunnel repair is in cooldown', serviceLabel, serviceTarget, verify: initial, localVerify };
   }
+
   const locked = await withLock(config, { action: 'repair_public_tunnel' }, async () => {
     // Recheck after acquiring ownership so a concurrent watchdog never causes a restart storm.
     const before = await verify(config);
     const localBefore = await verifyLocal(config);
     if (!isExternalTunnelFailure(config, before, localBefore)) {
-      return { ok: (before.probes.recovery_external_http ?? before.probes.external_mcp_http)?.ok === true, attempted: false, noOp: true, detail: 'Recovery tunnel recovered before restart', serviceLabel: service.label, serviceTarget: service.target, verify: before, localVerify: localBefore };
+      const recoveredProbe = configured.platform === 'openai-secure-tunnel'
+        ? before.probes.recovery_tunnel_runtime
+        : (before.probes.recovery_external_http ?? before.probes.external_mcp_http);
+      return { ok: recoveredProbe?.ok === true, attempted: false, noOp: true, detail: 'Recovery tunnel recovered before restart', serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
     }
-    writeJson(publicTunnelRepairStatePath(config), { lastAttemptAt: now(), serviceLabel: service.label });
-    const started = await ensureLaunchdServiceStarted(service, dependencies.runCommand ?? command);
-    if (!started.ok) {
-      audit(config, 'public_tunnel_restart_failed', { serviceLabel: service.label, detail: started.detail });
-      return { ok: false, attempted: true, detail: started.detail, serviceLabel: service.label, serviceTarget: service.target, verify: before, localVerify: localBefore };
+    writeJson(publicTunnelRepairStatePath(config), { lastAttemptAt: now(), serviceLabel, serviceTarget });
+
+    if (configured.platform === 'launchd') {
+      const started = await ensureLaunchdServiceStarted(launchdService!, runCommand);
+      if (!started.ok) {
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail: started.detail });
+        return { ok: false, attempted: true, detail: started.detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
+    } else if (configured.platform === 'systemd-user') {
+      const restarted = await runCommand('systemctl', ['--user', 'restart', systemdUnitName!], 15_000);
+      if (!restarted.ok) {
+        const detail = `systemd-user restart failed: ${restarted.stderr || restarted.stdout || restarted.status}`;
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail });
+        return { ok: false, attempted: true, detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
+    } else {
+      const observed = await observeOpenAiRecoveryTunnel(config, runCommand);
+      if (observed?.observedTunnelId && !observed.tunnelMatches) {
+        const detail = `OpenAI tunnel alias ${configured.alias} changed ownership to ${observed.observedTunnelId}; refusing to repoint it`;
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail });
+        return { ok: false, attempted: false, noOp: true, detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
+      if (observed?.profilePath && !observed.endpointMatches) {
+        const detail = `OpenAI tunnel alias ${configured.alias} targets a different MCP endpoint; refusing to repoint it`;
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail });
+        return { ok: false, attempted: false, noOp: true, detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
+      let args: string[];
+      try {
+        args = openAiSecureTunnelConnectArgs({
+          alias: configured.alias,
+          tunnelId: configured.tunnelId,
+          mcpServerUrl: configured.mcpServerUrl,
+          runtimeApiKeyRef: configured.runtimeApiKeyRef,
+          profile: configured.profile,
+          profileDir: configured.profileDir,
+          adminProfile: configured.adminProfile,
+        });
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : 'OpenAI tunnel runtime configuration is invalid';
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail });
+        return { ok: false, attempted: false, noOp: true, detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
+      const connected = await runCommand('tunnel-client', args, Math.max(30_000, configured.postRestartVerifyTimeoutMs ?? 20_000));
+      if (!connected.ok) {
+        const detail = `OpenAI Secure MCP Tunnel runtime connect failed: ${connected.stderr || connected.stdout || connected.status}`;
+        audit(config, 'public_tunnel_restart_failed', { serviceLabel, serviceTarget, detail });
+        return { ok: false, attempted: true, detail, serviceLabel, serviceTarget, verify: before, localVerify: localBefore };
+      }
     }
+
     const timeoutMs = configured.postRestartVerifyTimeoutMs ?? 20_000;
     const deadline = now() + timeoutMs;
     let after = before;
     while (now() < deadline) {
       await wait(1_000);
+      if (configured.platform === 'openai-secure-tunnel') {
+        const observed = await observeOpenAiRecoveryTunnel(config, runCommand);
+        if (!observed?.ok) continue;
+      }
       after = await verify(config);
-      if ((after.probes.recovery_external_http ?? after.probes.external_mcp_http)?.ok === true) {
-        audit(config, 'public_tunnel_restart_succeeded', { serviceLabel: service.label, serviceTarget: service.target });
-        return { ok: true, attempted: true, detail: 'public tunnel service restarted and external endpoint verified', serviceLabel: service.label, serviceTarget: service.target, verify: after, localVerify: await verifyLocal(config) };
+      const recovered = configured.platform === 'openai-secure-tunnel'
+        ? after.probes.recovery_tunnel_runtime?.ok === true
+        : (after.probes.recovery_external_http ?? after.probes.external_mcp_http)?.ok === true;
+      if (recovered) {
+        audit(config, 'public_tunnel_restart_succeeded', { serviceLabel, serviceTarget });
+        return { ok: true, attempted: true, detail: 'public tunnel service restarted and external tunnel readiness verified', serviceLabel, serviceTarget, verify: after, localVerify: await verifyLocal(config) };
       }
     }
-    audit(config, 'public_tunnel_restart_unverified', { serviceLabel: service.label, serviceTarget: service.target });
-    return { ok: false, attempted: true, detail: 'public tunnel service restarted but external endpoint did not recover before timeout', serviceLabel: service.label, serviceTarget: service.target, verify: after, localVerify: await verifyLocal(config) };
+    after = await verify(config);
+    audit(config, 'public_tunnel_restart_unverified', { serviceLabel, serviceTarget });
+    return { ok: false, attempted: true, detail: 'public tunnel service restarted but external tunnel readiness did not recover before timeout', serviceLabel, serviceTarget, verify: after, localVerify: await verifyLocal(config) };
   });
-  if (!locked.acquired) return { ok: false, attempted: false, noOp: true, detail: recoveryBusyDetail(locked.owner), serviceLabel: service.label, serviceTarget: service.target, verify: initial, localVerify };
+  if (!locked.acquired) return { ok: false, attempted: false, noOp: true, detail: recoveryBusyDetail(locked.owner), serviceLabel, serviceTarget, verify: initial, localVerify };
   return locked.value;
 }
 
-
 export interface RecoveryGatewayRestartResult {
   ok: boolean;
   attempted: boolean;
@@ -2795,7 +3565,7 @@ export function gatewayToken(config: RecoveryConfig): string | undefined {
 export function initializeStandaloneRecovery(
   controllerHome: string,
   port = 8787,
-  extensions: Partial<Pick<RecoveryConfig, 'publicMcpUrl' | 'recoveryPublicUrl' | 'recoveryTunnelService' | 'primaryPublicTunnelService' | 'primaryRuntimeService' | 'primaryRuntimeSourceRoot' | 'primaryConnectorService' | 'readOnlyTool'>> = {},
+  extensions: Partial<Pick<RecoveryConfig, 'publicMcpUrl' | 'recoveryPublicUrl' | 'recoveryTunnelService' | 'primaryPublicTunnelService' | 'primaryRuntimeService' | 'primaryRuntimeSourceRoot' | 'primaryRuntimeSourceRepositoryId' | 'primaryConnectorService' | 'readOnlyTool'>> = {},
 ): RecoveryConfig {
   const root = resolve(controllerHome);
   const tokenPath = join(root, 'recovery', 'config', 'gateway-token.json');
@@ -2902,22 +3672,18 @@ export async function watchdogTick(config: RecoveryConfig, prior: WatchdogState)
   }
   const recoveryHealthy = verified.probes.recovery_gateway?.ok !== false
     && verified.probes.recovery_external_http?.ok !== false;
-  const primaryRuntimeHealthy = localVerify.runtime.ok
-    && localVerify.runtime.running
-    && localVerify.runtime.ready
-    && !localVerify.runtime.stale
-    && localVerify.probes.active_gateway?.ok === true;
+  const primaryRuntimeHealthy = canonicalRuntimeSafeForTargetedConnectorRecovery(localVerify);
   const primaryConnectorConfigured = Boolean(config.primaryConnectorService);
   const primaryConnectorLocalFailed = verified.probes.primary_connector_local?.ok === false;
   const primaryConnectorCapacityFailed = connectorCapacityRecoveryRecommended(verified);
-  const primaryPublicTransportManaged = Boolean(configuredPrimaryPublicTunnel(config));
+  const primaryPublicTunnel = configuredPrimaryPublicTunnel(config);
+  const primaryPublicTransportManaged = Boolean(primaryPublicTunnel);
   const primaryPublicTransportFailed = Boolean(
-    config.publicMcpUrl
-    && primaryRuntimeHealthy
+    primaryRuntimeHealthy
     && !primaryConnectorCapacityFailed
     && (
-      verified.probes.external_mcp_http?.ok === false
-      || verified.probes.primary_connector_ready?.ok === false
+      (primaryPublicTunnel?.platform === 'openai-secure-tunnel' && verified.probes.primary_tunnel_runtime?.ok === false)
+      || (Boolean(config.publicMcpUrl) && (verified.probes.external_mcp_http?.ok === false || verified.probes.primary_connector_ready?.ok === false))
     ),
   );
   const primaryConnectorFailed = Boolean(
@@ -2930,18 +3696,6 @@ export async function watchdogTick(config: RecoveryConfig, prior: WatchdogState)
     ),
   );
   if (primaryRuntimeHealthy && !primaryConnectorFailed && !primaryPublicTransportFailed && recoveryHealthy) {
-    if (fullVerificationPerformed && verified.ok && !matchingKnownGood(config, verified.releases.active)) {
-      try {
-        const attestation = await withLock(config, { action: 'attest_known_good' }, async () => persistVerifiedKnownGood(config, verified));
-        if (!attestation.acquired) {
-          audit(config, 'known_good_attestation_deferred', { reason: recoveryBusyDetail(attestation.owner) });
-        }
-      } catch (error) {
-        audit(config, 'known_good_attestation_deferred', {
-          reason: error instanceof Error ? error.message : 'watchdog known-good attestation failed',
-        });
-      }
-    }
     const stable = recordWatchdogRuntimeHealthy(
       scopeWatchdogStateToRuntimeRelease(scopedPrior, verified.releases.active),
       now,