@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/self_host_runtime.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import {
   cp,
@@ -16,27 +16,44 @@ import {
   writeFile,
 } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
-import { dirname, join, win32 as win32Path } from 'node:path';
+import { basename, dirname, join, win32 as win32Path } from 'node:path';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { banner, sectionTitle } from './utils/ui/layout.mjs';
 import { cyan, dim, green, yellow } from './utils/ui/ansi.mjs';
-import { installService as installManagedService, restartService as restartManagedService, uninstallService as uninstallManagedService } from './utils/service/service_manager.mjs';
+import {
+  installService as installManagedService,
+  restartService as restartManagedService,
+  stopService as stopManagedService,
+  uninstallService as uninstallManagedService,
+} from './utils/service/service_manager.mjs';
 import {
   applyServicePlan,
   buildLaunchdPath,
   buildLaunchdPlistXml,
   buildServiceDefinition,
+  buildWindowsScheduledTaskPowerShellAction,
   planServiceAction,
   renderSystemdServiceUnit,
   renderWindowsScheduledTaskWrapperPs1,
   resolveServiceBackend,
 } from '@happier-dev/cli-common/service';
 import {
+  resolveConfiguredRelayRuntimeBinaryOverride,
+  resolveConfiguredRelayRuntimePaths,
+} from '@happier-dev/cli-common/firstPartyRuntime/relayRuntime';
+import {
+  mergeSelfHostServerEnvText,
   parseEnvText as parseEnvTextShared,
   renderSelfHostServerEnvText as renderSelfHostServerEnvTextShared,
-} from '@happier-dev/cli-common/firstPartyRuntime';
+  resolveSelfHostServerMigrationPlan,
+} from '@happier-dev/cli-common/firstPartyRuntime/selfHostServerEnv';
+import {
+  assertPackagedServerRuntimeClosure,
+  relocateServerRuntimeArtifactClosure,
+} from '@happier-dev/cli-common/firstPartyRuntime/serverRuntimeArtifactLayout';
+import { commandExistsOnPath } from '@happier-dev/cli-common/process';
 import { DEFAULT_MINISIGN_PUBLIC_KEY } from '@happier-dev/release-runtime/minisign';
 import {
   PUBLIC_RELEASE_RING_IDS,
@@ -45,7 +62,7 @@ import {
 } from '@happier-dev/release-runtime/releaseRings';
 import { resolveReleaseAssetBundle } from '@happier-dev/release-runtime/assets';
 import { downloadVerifiedReleaseAssetBundle } from '@happier-dev/release-runtime/verifiedDownload';
-import { planArchiveExtraction } from '@happier-dev/release-runtime/extractPlan';
+import { extractFirstPartyReleaseArchiveToDirectory } from '@happier-dev/release-runtime/archiveExtraction';
 import { fetchFirstGitHubReleaseByTags, fetchGitHubReleaseByTag } from '@happier-dev/release-runtime/github';
 import { findExtractedExecutableByName } from './self_host/findExtractedExecutableByName.mjs';
 import { maybeInstallCompanionCli } from './self_host/install_companion_cli.mjs';
@@ -237,8 +254,7 @@ function commandExists(cmd) {
   const name = String(cmd ?? '').trim();
   if (!name) return false;
   if (process.platform === 'win32') {
-    const result = runCommand('where', [name], { allowFail: true, stdio: 'ignore' });
-    return (result.status ?? 1) === 0;
+    return commandExistsOnPath(name);
   }
   const result = runCommand('sh', ['-lc', `command -v ${name} >/dev/null 2>&1`], { allowFail: true, stdio: 'ignore' });
   return (result.status ?? 1) === 0;
@@ -290,11 +306,6 @@ export function resolveSelfHostReleaseTargets(channel) {
     channel: normalizedChannel,
     serverTag: serverTags[0],
     serverTags,
-    uiWebTags: normalizedChannel === 'stable'
-      ? ['ui-web-stable']
-      : normalizedChannel === 'preview'
-        ? ['ui-web-preview', 'ui-web-stable']
-        : ['ui-web-dev', 'ui-web-preview', 'ui-web-stable'],
   };
 }
 
@@ -335,148 +346,33 @@ export function pickReleaseAsset({ assets, product, os, arch }) {
   };
 }
 
-function resolveSqliteDatabaseFilePath(databaseUrl) {
-  const raw = String(databaseUrl ?? '').trim();
-  if (!raw) return '';
-  if (!raw.startsWith('file:')) return '';
-  try {
-    const url = new URL(raw);
-    if (url.protocol !== 'file:') return '';
-    const pathname = url.pathname || '';
-    // On Windows, URL.pathname can start with /C:/...
-    return pathname.startsWith('/') && /^[A-Za-z]:\//.test(pathname.slice(1))
-      ? pathname.slice(1)
-      : pathname;
-  } catch {
-    const value = raw.slice('file:'.length);
-    return value.startsWith('//') ? value.replace(/^\/+/, '/') : value;
-  }
-}
-
-async function applySelfHostSqliteMigrationsAtInstallTime({ env }) {
-  if (typeof globalThis.Bun === 'undefined') {
-    return { applied: [], skipped: true, reason: 'bun-unavailable' };
-  }
-  const databaseUrl = String(env?.DATABASE_URL ?? '').trim();
-  const migrationsDir = String(env?.HAPPIER_SQLITE_MIGRATIONS_DIR ?? env?.HAPPY_SQLITE_MIGRATIONS_DIR ?? '').trim();
-  if (!databaseUrl || !migrationsDir) {
-    return { applied: [], skipped: true, reason: 'missing-config' };
-  }
-  const dbPath = resolveSqliteDatabaseFilePath(databaseUrl);
-  if (!dbPath) {
-    return { applied: [], skipped: true, reason: 'unsupported-database-url' };
-  }
-  const migrationsInfo = await stat(migrationsDir).catch(() => null);
-  if (!migrationsInfo?.isDirectory()) {
-    return { applied: [], skipped: true, reason: 'migrations-dir-missing' };
-  }
-
-  const mod = await import('bun:sqlite');
-  const Database = mod?.Database;
-  if (!Database) {
-    return { applied: [], skipped: true, reason: 'bun-sqlite-unavailable' };
-  }
-  const db = new Database(dbPath);
-  db.exec(
-    [
-      'CREATE TABLE IF NOT EXISTS _prisma_migrations (',
-      '  id TEXT PRIMARY KEY,',
-      '  checksum TEXT NOT NULL,',
-      '  finished_at DATETIME,',
-      '  migration_name TEXT NOT NULL,',
-      '  logs TEXT,',
-      '  rolled_back_at DATETIME,',
-      '  started_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,',
-      '  applied_steps_count INTEGER NOT NULL DEFAULT 0',
-      ');',
-    ].join('\n'),
-  );
-
-  const tableNamesQuery = db.query(`SELECT name FROM sqlite_master WHERE type='table'`);
-  const appliedQuery = db.query(
-    `SELECT migration_name FROM _prisma_migrations WHERE rolled_back_at IS NULL AND finished_at IS NOT NULL`,
-  );
-  const insertQuery = db.query(
-    `INSERT INTO _prisma_migrations (id, checksum, finished_at, migration_name, applied_steps_count) VALUES (?, ?, CURRENT_TIMESTAMP, ?, 1)`,
-  );
-
-  const applied = new Set(
-    appliedQuery.all().map((row) => String(row?.migration_name ?? '').trim()).filter(Boolean),
-  );
-
-  const existingTables = new Set(
-    tableNamesQuery.all().map((row) => String(row?.name ?? '').trim()).filter(Boolean),
-  );
-  const hasCoreTables =
-    existingTables.has('Account')
-    || existingTables.has('account')
-    || existingTables.has('accounts');
-  const legacyMode = applied.size === 0 && hasCoreTables;
-
-  const isLikelyAlreadyAppliedError = (err) => {
-    const msg = String(err?.message ?? err ?? '').toLowerCase();
-    return msg.includes('already exists') || msg.includes('duplicate column') || msg.includes('duplicate');
-  };
-
-  const entries = await readdir(migrationsDir, { withFileTypes: true }).catch(() => []);
-  const dirs = entries
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .sort((a, b) => a.localeCompare(b));
-
-  const sha256Hex = (input) => createHash('sha256').update(String(input)).digest('hex');
-  const appliedNow = [];
-  for (const name of dirs) {
-    if (applied.has(name)) continue;
-    const sqlPath = join(migrationsDir, name, 'migration.sql');
-    const sql = await readFile(sqlPath, 'utf8').catch(() => '');
-    if (!sql.trim()) continue;
-    const checksum = sha256Hex(sql);
-    db.exec('BEGIN');
-    try {
-      db.exec(sql);
-      insertQuery.run(randomUUID(), checksum, name);
-      db.exec('COMMIT');
-      appliedNow.push(name);
-      applied.add(name);
-    } catch (e) {
-      try {
-        db.exec('ROLLBACK');
-      } catch {
-        // ignore
-      }
-      if (legacyMode && isLikelyAlreadyAppliedError(e)) {
-        db.exec('BEGIN');
-        try {
-          insertQuery.run(randomUUID(), checksum, name);
-          db.exec('COMMIT');
-        } catch (inner) {
-          try {
-            db.exec('ROLLBACK');
-          } catch {
-            // ignore
-          }
-          throw inner;
-        }
-        appliedNow.push(name);
-        applied.add(name);
-        continue;
-      }
-      throw e;
-    }
-  }
-
-  return { applied: appliedNow, skipped: false, reason: 'ok' };
+export async function applySelfHostServerMigrationsAtInstallTime({
+  config,
+  env,
+  runCommandImpl = runCommand,
+}) {
+  const plan = resolveSelfHostServerMigrationPlan({
+    serverBinaryPath: config.serverBinaryPath,
+    env,
+    platform: config.platform ?? process.platform,
+  });
+  if (!plan) return null;
+  return runCommandImpl(plan.command, [...plan.args], {
+    cwd: config.installRoot,
+    env,
+    stdio: 'pipe',
+  });
 }
 
-function resolveConfig({ channel, mode = 'user', platform = process.platform } = {}) {
+export function resolveConfig({ channel, mode = 'user', platform = process.platform } = {}) {
   const defaults = resolveSelfHostDefaults({ platform, mode, channel, homeDir: homedir() });
-  const installRoot = String(process.env.HAPPIER_SELF_HOST_INSTALL_ROOT ?? defaults.installRoot).trim();
-  const binDir = String(process.env.HAPPIER_SELF_HOST_BIN_DIR ?? defaults.binDir).trim();
-  const configDir = String(process.env.HAPPIER_SELF_HOST_CONFIG_DIR ?? defaults.configDir).trim();
-  const dataDir = String(process.env.HAPPIER_SELF_HOST_DATA_DIR ?? defaults.dataDir).trim();
-  const logDir = String(process.env.HAPPIER_SELF_HOST_LOG_DIR ?? defaults.logDir).trim();
-  const serviceName = String(process.env.HAPPIER_SELF_HOST_SERVICE_NAME ?? DEFAULTS.serviceName).trim();
+  const configuredPaths = resolveConfiguredRelayRuntimePaths({ defaults, env: process.env });
+  const installRoot = configuredPaths.installRoot;
+  const binDir = configuredPaths.binDir;
+  const configDir = configuredPaths.configDir;
+  const dataDir = configuredPaths.dataDir;
+  const logDir = configuredPaths.logDir;
+  const serviceName = String(process.env.HAPPIER_SELF_HOST_SERVICE_NAME ?? defaults.serviceName).trim() || defaults.serviceName;
   const serverHost = String(process.env.HAPPIER_SERVER_HOST ?? DEFAULTS.serverHost).trim();
   const serverPort = parsePort(process.env.HAPPIER_SERVER_PORT, DEFAULTS.serverPort);
   const githubRepo = String(process.env.HAPPIER_GITHUB_REPO ?? DEFAULTS.githubRepo).trim();
@@ -660,6 +556,14 @@ export function applyEnvOverridesToEnvText(envText, overrides) {
   return `${lines.join('\n')}\n`;
 }
 
+export function mergeSelfHostServerRuntimeEnvText({ baseEnvText, existingEnvText = '', envOverrides = [] } = {}) {
+  return mergeSelfHostServerEnvText({
+    baseEnvText: String(baseEnvText ?? ''),
+    existingEnvText: String(existingEnvText ?? ''),
+    overrides: Object.fromEntries((Array.isArray(envOverrides) ? envOverrides : []).map(({ key, value }) => [key, value])),
+  });
+}
+
 export function mergeEnvTextWithDefaults(existingText, defaultsText) {
   const existingRaw = String(existingText ?? '');
   const defaultsRaw = String(defaultsText ?? '');
@@ -823,7 +727,6 @@ export function buildSelfHostDoctorChecks(config, { state, commandExists: comman
     { name: 'platform', ok: ['linux', 'darwin', 'windows'].includes(os) },
     { name: 'mode', ok: mode === 'user' || (mode === 'system' && platform !== 'win32') },
     // We verify minisign signatures using the bundled public key + node:crypto, so no external `minisign` dependency.
-    { name: 'tar', ok: commandExistsFn('tar') },
     { name: 'powershell', ok: os === 'windows' ? commandExistsFn('powershell') : true },
     { name: 'systemctl', ok: os === 'linux' ? commandExistsFn('systemctl') : true },
     { name: 'launchctl', ok: os === 'darwin' ? commandExistsFn('launchctl') : true },
@@ -996,7 +899,7 @@ export function buildUpdaterScheduledTaskCreateArgs({ backend, taskName, definit
   const parsedAt = parseDailyAtTime(at);
   const minutesRaw = Number(intervalMinutes);
   const minutes = Number.isFinite(minutesRaw) ? Math.max(15, Math.floor(minutesRaw)) : 1440;
-  const ps = `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "${definition}"`;
+  const ps = buildWindowsScheduledTaskPowerShellAction({ definitionPath: definition });
 
   return [
     '/Create',
@@ -1319,91 +1222,35 @@ async function syncSelfHostSqliteMigrations({ artifactRootDir, targetDir }) {
   return { copied: true, reason: 'ok' };
 }
 
-async function syncSelfHostGeneratedClients({ artifactRootDir, targetDir }) {
-  const root = String(artifactRootDir ?? '').trim();
-  const dest = String(targetDir ?? '').trim();
-  if (!root || !dest) return { copied: false, reason: 'missing-paths' };
-
-  const source = join(root, 'generated');
-  if (!existsSync(source)) return { copied: false, reason: 'missing-source' };
-
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dirname(dest), { recursive: true });
-  await cp(source, dest, { recursive: true });
-  return { copied: true, reason: 'ok' };
-}
-
-async function syncSelfHostNodeModules({ artifactRootDir, targetDir }) {
-  const root = String(artifactRootDir ?? '').trim();
-  const dest = String(targetDir ?? '').trim();
-  if (!root || !dest) return { copied: false, reason: 'missing-paths', copiedEntries: [], missingEntries: [] };
-
-  const sourceRoot = join(root, 'node_modules');
-  if (!existsSync(sourceRoot)) return { copied: false, reason: 'missing-source-root', copiedEntries: [], missingEntries: [] };
-
-  const sidecars = [
-    { sourcePath: join(sourceRoot, '.prisma'), targetPath: join(dest, '.prisma') },
-    { sourcePath: join(sourceRoot, '@prisma'), targetPath: join(dest, '@prisma') },
-  ];
-  const missingEntries = sidecars
-    .filter((sidecar) => !existsSync(sidecar.sourcePath))
-    .map((sidecar) => sidecar.sourcePath);
-  if (missingEntries.length > 0) {
-    return { copied: false, reason: 'incomplete-sidecars', copiedEntries: [], missingEntries };
-  }
-
-  const copiedEntries = [];
-
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dest, { recursive: true });
-  for (const sidecar of sidecars) {
-    await mkdir(dirname(sidecar.targetPath), { recursive: true });
-    await cp(sidecar.sourcePath, sidecar.targetPath, { recursive: true });
-    copiedEntries.push(sidecar.targetPath);
-  }
-
-  return copiedEntries.length > 0
-    ? { copied: true, reason: 'ok', copiedEntries, missingEntries: [] }
-    : { copied: false, reason: 'missing-sidecars', copiedEntries, missingEntries: [] };
-}
-
-function assertSelfHostNodeModulesSync(result) {
-  if (result?.copied) return;
-  const reason = String(result?.reason ?? 'unknown');
-  throw new Error(`[self-host] server runtime is missing packaged node_modules sidecars (${reason})`);
-}
-
 async function stageSelfHostRuntimePayload({ artifactRootDir, stageRootDir }) {
   const stageRoot = String(stageRootDir ?? '').trim();
   if (!stageRoot) {
     throw new Error('[self-host] missing runtime staging directory');
   }
 
-  const sqliteMigrationsDir = join(stageRoot, 'migrations', 'sqlite');
+  await cp(artifactRootDir, stageRoot, { recursive: true });
+  const relocated = await relocateServerRuntimeArtifactClosure({
+    payloadRoot: stageRoot,
+    platform: process.platform,
+  });
+  await assertPackagedServerRuntimeClosure({ runtimeRoot: relocated.runtimeRoot });
+
+  const sqliteMigrationsDir = join(stageRoot, 'managed-data', 'migrations', 'sqlite');
   await syncSelfHostSqliteMigrations({
-    artifactRootDir,
+    artifactRootDir: relocated.runtimeRoot,
     targetDir: sqliteMigrationsDir,
   }).catch(() => {});
 
-  const generatedDir = join(stageRoot, 'generated');
-  const generated = await syncSelfHostGeneratedClients({
-    artifactRootDir,
-    targetDir: generatedDir,
-  });
-  if (!generated.copied) {
-    throw new Error('[self-host] server runtime is missing packaged generated clients');
-  }
-
-  const nodeModulesDir = join(stageRoot, 'node_modules');
-  const nodeModules = await syncSelfHostNodeModules({
-    artifactRootDir,
-    targetDir: nodeModulesDir,
-  });
-  assertSelfHostNodeModulesSync(nodeModules);
+  const embeddedUiDir = join(stageRoot, 'ui-web', 'current');
+  const embeddedUiIndex = await stat(join(embeddedUiDir, 'index.html')).catch(() => null);
 
   return {
-    generatedDir,
-    nodeModulesDir,
+    embeddedUiDir: embeddedUiIndex?.isFile() ? embeddedUiDir : '',
+    generatedDir: join(relocated.runtimeRoot, 'generated'),
+    nodeModulesDir: join(relocated.runtimeRoot, 'node_modules'),
+    prismaDir: join(relocated.runtimeRoot, 'prisma'),
+    runtimeDir: join(relocated.runtimeRoot, 'runtime'),
+    migrationBinaryPath: relocated.migrationBinaryPath || '',
     sqliteMigrationsDir: existsSync(sqliteMigrationsDir) ? sqliteMigrationsDir : '',
   };
 }
@@ -1496,7 +1343,14 @@ async function rollbackFailClosedBinaryPromotionWindow(window) {
   }
 }
 
-async function promoteStagedSelfHostRuntimePayload({ stagedRuntime, config, beforeOnPromoted, onPromoted }) {
+async function promoteStagedSelfHostRuntimePayload({
+  stagedRuntime,
+  config,
+  beforePromote,
+  beforeOnPromoted,
+  onPromoted,
+  afterPromoted,
+}) {
   const promotions = [
     {
       stagedDir: stagedRuntime.sqliteMigrationsDir,
@@ -1510,18 +1364,37 @@ async function promoteStagedSelfHostRuntimePayload({ stagedRuntime, config, befo
       stagedDir: stagedRuntime.nodeModulesDir,
       targetDir: join(dirname(config.serverBinaryPath), 'node_modules'),
     },
+    {
+      stagedDir: stagedRuntime.prismaDir,
+      targetDir: join(dirname(config.serverBinaryPath), 'prisma'),
+    },
+    {
+      stagedDir: stagedRuntime.runtimeDir,
+      targetDir: join(dirname(config.serverBinaryPath), 'runtime'),
+    },
+    {
+      stagedDir: stagedRuntime.migrationBinaryPath,
+      targetDir: stagedRuntime.migrationBinaryPath
+        ? join(dirname(config.serverBinaryPath), basename(stagedRuntime.migrationBinaryPath))
+        : '',
+    },
   ].filter(({ stagedDir }) => {
     const staged = String(stagedDir ?? '').trim();
     return staged && existsSync(staged);
   });
 
-  const binaryPromotionWindow = await prepareFailClosedBinaryPromotionWindow({
-    targetBinaryPath: config.serverBinaryPath,
-    previousBinaryPath: config.serverPreviousBinaryPath,
-  });
-
+  let binaryPromotionWindow = null;
   const promoted = [];
   try {
+    if (typeof beforePromote === 'function') {
+      await beforePromote();
+    }
+
+    binaryPromotionWindow = await prepareFailClosedBinaryPromotionWindow({
+      targetBinaryPath: config.serverBinaryPath,
+      previousBinaryPath: config.serverPreviousBinaryPath,
+    });
+
     for (const promotion of promotions) {
       const target = String(promotion.targetDir ?? '').trim();
       await mkdir(dirname(target), { recursive: true });
@@ -1551,6 +1424,9 @@ async function promoteStagedSelfHostRuntimePayload({ stagedRuntime, config, befo
     if (typeof onPromoted === 'function') {
       await onPromoted();
     }
+    if (typeof afterPromoted === 'function') {
+      await afterPromoted(stagedRuntime);
+    }
     await finalizeFailClosedBinaryPromotionWindow(binaryPromotionWindow);
 
     for (const promotion of promoted) {
@@ -1573,7 +1449,9 @@ export async function installSelfHostBinaryFromBundle({
   config,
   pubkeyFile = resolveMinisignPublicKeyText(process.env),
   userAgent = 'happier-self-host-installer',
+  beforeRuntimePromote,
   beforeBinaryInstall,
+  afterPromote,
 } = {}) {
   const resolvedBundle = bundle;
   const name = String(binaryName ?? '').trim();
@@ -1605,16 +1483,11 @@ export async function installSelfHostBinaryFromBundle({
 
     const extractDir = join(tempDir, 'extract');
     await mkdir(extractDir, { recursive: true });
-    const plan = planArchiveExtraction({
+    await extractFirstPartyReleaseArchiveToDirectory({
       archiveName: downloaded.archiveName,
       archivePath: downloaded.archivePath,
-      destDir: extractDir,
-      os,
+      extractDir,
     });
-    if (!commandExists(plan.requiredCommand)) {
-      throw new Error(`[self-host] ${plan.requiredCommand} is required to extract release artifacts`);
-    }
-    runCommand(plan.command.cmd, plan.command.args, { stdio: 'ignore' });
     const extractedBinary = await findExtractedExecutableByName(extractDir, name);
     if (!extractedBinary) {
       throw new Error('[self-host] failed to locate extracted server binary');
@@ -1629,6 +1502,7 @@ export async function installSelfHostBinaryFromBundle({
     await promoteStagedSelfHostRuntimePayload({
       stagedRuntime,
       config,
+      beforePromote: beforeRuntimePromote,
       beforeOnPromoted: beforeBinaryInstall,
       onPromoted: async () => installBinaryAtomically({
         sourceBinaryPath: extractedBinary,
@@ -1636,6 +1510,9 @@ export async function installSelfHostBinaryFromBundle({
         previousBinaryPath: config.serverPreviousBinaryPath,
         versionedTargetPath: join(config.versionsDir, `${name}-${version}`),
       }),
+      afterPromoted: typeof afterPromote === 'function'
+        ? async (runtime) => afterPromote({ ...runtime, version })
+        : undefined,
     });
     await pruneVersionedDirectories({
       versionsDir: config.versionsDir,
@@ -1653,6 +1530,8 @@ export async function installSelfHostBinaryFromLocalPath({
   sourceBinaryPath,
   binaryName,
   config,
+  beforeRuntimePromote,
+  afterPromote,
 } = {}) {
   const srcPath = String(sourceBinaryPath ?? '').trim();
   const name = String(binaryName ?? '').trim();
@@ -1682,12 +1561,16 @@ export async function installSelfHostBinaryFromLocalPath({
     await promoteStagedSelfHostRuntimePayload({
       stagedRuntime,
       config,
+      beforePromote: beforeRuntimePromote,
       onPromoted: async () => installBinaryAtomically({
         sourceBinaryPath: srcPath,
         targetBinaryPath: config.serverBinaryPath,
         previousBinaryPath: config.serverPreviousBinaryPath,
         versionedTargetPath: join(config.versionsDir, `${name}-${version}`),
       }),
+      afterPromoted: typeof afterPromote === 'function'
+        ? async (runtime) => afterPromote({ ...runtime, version })
+        : undefined,
     });
     await pruneVersionedDirectories({
       versionsDir: config.versionsDir,
@@ -1701,12 +1584,22 @@ export async function installSelfHostBinaryFromLocalPath({
   }
 }
 
-async function installFromRelease({ product, binaryName, config, explicitBinaryPath = '' }) {
+async function installFromRelease({
+  product,
+  binaryName,
+  config,
+  explicitBinaryPath = '',
+  beforeRuntimePromote,
+  beforeBinaryInstall,
+  afterPromote,
+} = {}) {
   if (explicitBinaryPath) {
     return installSelfHostBinaryFromLocalPath({
       sourceBinaryPath: explicitBinaryPath,
       binaryName,
       config,
+      beforeRuntimePromote,
+      afterPromote,
     });
   }
 
@@ -1740,10 +1633,43 @@ async function installFromRelease({ product, binaryName, config, explicitBinaryP
     config,
     pubkeyFile: resolveMinisignPublicKeyText(process.env),
     userAgent: 'happier-self-host-installer',
+    beforeRuntimePromote,
+    beforeBinaryInstall,
+    afterPromote,
   });
   return { version: result.version || resolved.version || String(release?.tag_name ?? '').replace(/^server-v/, ''), source: result.source };
 }
 
+async function stopSelfHostServiceBeforeRuntimePromote({ config }) {
+  const currentEnvText = existsSync(config.configEnvPath)
+    ? await readFile(config.configEnvPath, 'utf-8').catch(() => '')
+    : '';
+  await stopManagedService({
+    platform: config.platform,
+    mode: config.mode,
+    homeDir: homedir(),
+    spec: buildSelfHostServerServiceSpec({ config, envText: currentEnvText }),
+    persistent: true,
+  }).catch(() => {});
+}
+
+export function resolveSelfHostServerInstallFromReleaseParams({
+  product,
+  binaryName,
+  config,
+  env = process.env,
+  ...rest
+} = {}) {
+  const explicitBinaryPath = resolveConfiguredRelayRuntimeBinaryOverride(env);
+  return {
+    product,
+    binaryName,
+    config,
+    ...(explicitBinaryPath ? { explicitBinaryPath } : {}),
+    ...rest,
+  };
+}
+
 async function assertUiWebBundleIsValid(rootDir) {
   const indexPath = join(rootDir, 'index.html');
   const info = await stat(indexPath).catch(() => null);
@@ -1752,124 +1678,37 @@ async function assertUiWebBundleIsValid(rootDir) {
   }
 }
 
-export async function resolveExtractedUiWebBundleRootDir({ extractDir } = {}) {
-  const root = String(extractDir ?? '').trim();
-  if (!root) {
-    throw new Error('[self-host] missing ui web bundle extractDir');
-  }
-
-  // Some archives extract index.html directly into extractDir.
-  try {
-    await assertUiWebBundleIsValid(root);
-    return root;
-  } catch {
-    // continue
-  }
-
-  const roots = await readdir(root).catch(() => []);
-  for (const entry of roots) {
-    const candidate = join(root, entry);
-    const info = await stat(candidate).catch(() => null);
-    if (!info?.isDirectory()) continue;
-    try {
-      await assertUiWebBundleIsValid(candidate);
-      return candidate;
-    } catch {
-      // continue
-    }
+export async function installUiWebFromEmbeddedRuntime({ config, embeddedUiDir, version }) {
+  const sourceDir = String(embeddedUiDir ?? '').trim();
+  const runtimeVersion = String(version ?? '').trim();
+  if (!sourceDir || !existsSync(sourceDir)) {
+    throw new Error('[self-host] managed UI was requested, but the server payload is missing its embedded UI');
   }
+  await assertUiWebBundleIsValid(sourceDir);
 
-  // Preserve the existing missing-index.html error shape, but anchor it to the extraction root
-  // instead of whatever random entry came first (e.g. AppleDouble `._*` files).
-  throw new Error(`[self-host] UI web bundle is missing index.html: ${join(root, 'index.html')}`);
-}
-
-async function installUiWebFromRelease({ config }) {
-  const { uiWebTags: tags } = resolveSelfHostReleaseTargets(config.channel);
-
-  const resolvedRelease = await fetchFirstGitHubReleaseByTags({
-    githubRepo: config.githubRepo,
-    tags,
-    userAgent: 'happier-self-host-installer',
-    githubToken: String(process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? ''),
-  }).catch((e) => {
-    const status = Number(e?.status);
-    if (status === 404) return null;
-    throw e;
-  });
-
-  if (!resolvedRelease) {
-    return {
-      installed: false,
-      version: null,
-      source: null,
-      reason: `ui web release tag not found (${tags.join(', ')})`,
-    };
-  }
-  const { release, tag: channelTag } = resolvedRelease;
   const existingVersionIds = await listVersionedDirectoryIdsNewestFirst({
     versionsDir: config.uiWebVersionsDir,
     entryPrefix: `${config.uiWebProduct}-`,
   });
-
-  const resolved = resolveReleaseAssetBundle({
-    assets: release?.assets,
-    product: config.uiWebProduct,
-    os: config.uiWebOs,
-    arch: config.uiWebArch,
+  const uiVersion = runtimeVersion || `${Date.now()}`;
+  const versionedTargetDir = join(config.uiWebVersionsDir, `${config.uiWebProduct}-${uiVersion}`);
+  const previousVersionId = existingVersionIds.find((candidate) => candidate !== uiVersion) ?? null;
+
+  await rm(versionedTargetDir, { recursive: true, force: true });
+  await mkdir(dirname(versionedTargetDir), { recursive: true });
+  await cp(sourceDir, versionedTargetDir, { recursive: true });
+  await rm(config.uiWebCurrentDir, { recursive: true, force: true }).catch(() => {});
+  await symlink(versionedTargetDir, config.uiWebCurrentDir, config.platform === 'win32' ? 'junction' : 'dir').catch(async () => {
+    await cp(versionedTargetDir, config.uiWebCurrentDir, { recursive: true });
+  });
+  await pruneVersionedDirectories({
+    versionsDir: config.uiWebVersionsDir,
+    entryPrefix: `${config.uiWebProduct}-`,
+    currentVersionId: uiVersion,
+    previousVersionId,
   });
 
-  const tempDir = await mkdtemp(join(tmpdir(), 'happier-self-host-ui-web-'));
-  try {
-    const pubkeyFile = resolveMinisignPublicKeyText(process.env);
-    const downloaded = await downloadVerifiedReleaseAssetBundle({
-      bundle: resolved,
-      destDir: tempDir,
-      pubkeyFile,
-      userAgent: 'happier-self-host-installer',
-    });
-
-    const extractDir = join(tempDir, 'extract');
-    await mkdir(extractDir, { recursive: true });
-    const plan = planArchiveExtraction({
-      archiveName: downloaded.archiveName,
-      archivePath: downloaded.archivePath,
-      destDir: extractDir,
-      os: normalizeOs(config.platform),
-    });
-    if (!commandExists(plan.requiredCommand)) {
-      throw new Error(`[self-host] ${plan.requiredCommand} is required to extract ui web bundle artifacts`);
-    }
-    runCommand(plan.command.cmd, plan.command.args, { stdio: 'ignore' });
-
-	    const roots = await readdir(extractDir).catch(() => []);
-	    if (roots.length === 0) {
-	      throw new Error('[self-host] extracted ui web bundle is empty');
-	    }
-	    const artifactRootDir = await resolveExtractedUiWebBundleRootDir({ extractDir });
-
-	    const version = resolved.version || String(release?.tag_name ?? '').replace(/^ui-web-v/, '') || `${Date.now()}`;
-	    const versionedTargetDir = join(config.uiWebVersionsDir, `${config.uiWebProduct}-${version}`);
-    const previousVersionId = existingVersionIds.find((candidate) => candidate !== version) ?? null;
-    await rm(versionedTargetDir, { recursive: true, force: true });
-    await mkdir(dirname(versionedTargetDir), { recursive: true });
-    await cp(artifactRootDir, versionedTargetDir, { recursive: true });
-
-    await rm(config.uiWebCurrentDir, { recursive: true, force: true }).catch(() => {});
-    await symlink(versionedTargetDir, config.uiWebCurrentDir, config.platform === 'win32' ? 'junction' : 'dir').catch(async () => {
-      await cp(versionedTargetDir, config.uiWebCurrentDir, { recursive: true });
-    });
-    await pruneVersionedDirectories({
-      versionsDir: config.uiWebVersionsDir,
-      entryPrefix: `${config.uiWebProduct}-`,
-      currentVersionId: version,
-      previousVersionId,
-    });
-
-    return { installed: true, version, source: downloaded.source.archiveUrl, tag: channelTag };
-  } finally {
-    await rm(tempDir, { recursive: true, force: true });
-  }
+  return { installed: true, version: uiVersion, source: 'embedded-server-archive' };
 }
 
 async function writeSelfHostState(config, statePatch) {
@@ -1897,6 +1736,214 @@ function buildSelfHostServerServiceSpec({ config, envText }) {
   };
 }
 
+export async function runSelfHostRuntimeMutationWithServiceRecovery({
+  config,
+  mutateRuntime,
+} = {}) {
+  if (typeof mutateRuntime !== 'function') {
+    throw new Error('[self-host] mutateRuntime is required');
+  }
+
+  const previousEnvText = existsSync(config.configEnvPath)
+    ? await readFile(config.configEnvPath, 'utf-8').catch(() => '')
+    : '';
+  const previousEnvExisted = existsSync(config.configEnvPath);
+  const backend = resolveServiceBackend({ platform: config.platform, mode: config.mode });
+  const previousServiceSpec = buildSelfHostServerServiceSpec({ config, envText: previousEnvText });
+  const previousDefinition = buildServiceDefinition({
+    backend,
+    homeDir: homedir(),
+    spec: previousServiceSpec,
+  });
+  const previousDefinitionExisted = existsSync(previousDefinition.path);
+  const previousDefinitionContents = existsSync(previousDefinition.path)
+    ? await readFile(previousDefinition.path, 'utf-8').catch(() => previousDefinition.contents)
+    : previousDefinition.contents;
+
+  try {
+    return await mutateRuntime({
+      beforeRuntimePromote: async () => stopSelfHostServiceBeforeRuntimePromote({ config }),
+    });
+  } catch (error) {
+    if (previousEnvExisted) {
+      await mkdir(dirname(config.configEnvPath), { recursive: true });
+      await writeFile(config.configEnvPath, previousEnvText, 'utf-8');
+    } else {
+      await rm(config.configEnvPath, { force: true }).catch(() => {});
+    }
+    if (previousDefinitionExisted) {
+      await mkdir(dirname(previousDefinition.path), { recursive: true });
+      await writeFile(previousDefinition.path, previousDefinitionContents, 'utf-8');
+    } else {
+      await rm(previousDefinition.path, { force: true }).catch(() => {});
+    }
+    if (previousEnvExisted || previousDefinitionExisted) {
+      await installManagedService({
+        platform: config.platform,
+        mode: config.mode,
+        homeDir: homedir(),
+        spec: previousServiceSpec,
+        persistent: true,
+      }).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+export async function runSelfHostUiWebMutationWithRollback({
+  config,
+  mutateUi,
+} = {}) {
+  if (typeof mutateUi !== 'function') {
+    throw new Error('[self-host] mutateUi is required');
+  }
+
+  const uiCurrentDir = String(config?.uiWebCurrentDir ?? '').trim();
+  const uiVersionsDir = String(config?.uiWebVersionsDir ?? '').trim();
+  const uiProduct = String(config?.uiWebProduct ?? DEFAULTS.uiWebProduct).trim() || DEFAULTS.uiWebProduct;
+  const entryPrefix = `${uiProduct}-`;
+  const previousVersionIds = uiVersionsDir
+    ? await listVersionedDirectoryIdsNewestFirst({
+      versionsDir: uiVersionsDir,
+      entryPrefix,
+    }).catch(() => [])
+    : [];
+  const currentBackupDir = uiCurrentDir && existsSync(uiCurrentDir)
+    ? `${uiCurrentDir}.rollback-${randomUUID()}`
+    : '';
+
+  if (currentBackupDir) {
+    await rename(uiCurrentDir, currentBackupDir);
+  }
+
+  try {
+    const result = await mutateUi();
+    if (currentBackupDir) {
+      await rm(currentBackupDir, { recursive: true, force: true }).catch(() => {});
+    }
+    return result;
+  } catch (error) {
+    if (uiCurrentDir) {
+      await rm(uiCurrentDir, { recursive: true, force: true }).catch(() => {});
+    }
+    if (currentBackupDir && existsSync(currentBackupDir)) {
+      await rename(currentBackupDir, uiCurrentDir).catch(() => {});
+    }
+    if (uiVersionsDir) {
+      const nextVersionIds = await listVersionedDirectoryIdsNewestFirst({
+        versionsDir: uiVersionsDir,
+        entryPrefix,
+      }).catch(() => []);
+      const previousVersionIdSet = new Set(previousVersionIds);
+      for (const versionId of nextVersionIds) {
+        if (previousVersionIdSet.has(versionId)) continue;
+        await rm(join(uiVersionsDir, versionId), { recursive: true, force: true }).catch(() => {});
+      }
+    }
+    if (currentBackupDir) {
+      await rm(currentBackupDir, { recursive: true, force: true }).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+async function performSelfHostPostPromoteSteps({
+  config,
+  embeddedUiDir,
+  runtimeVersion,
+  withUi,
+  envOverrides,
+  autoUpdateMode,
+  autoUpdateEnabled,
+  autoUpdateIntervalMinutes,
+  autoUpdateAt,
+  autoUpdateReconcile,
+}) {
+  const uiResult = withUi
+    ? await runSelfHostUiWebMutationWithRollback({
+      config,
+      mutateUi: async () => installUiWebFromEmbeddedRuntime({
+        config,
+        embeddedUiDir,
+        version: runtimeVersion,
+      }),
+    })
+    : { installed: false, version: null, source: null, reason: 'disabled' };
+  const uiInstalled = Boolean(uiResult?.installed);
+
+  const envText = renderServerEnvFile({
+    port: config.serverPort,
+    host: config.serverHost,
+    dataDir: config.dataDir,
+    filesDir: config.filesDir,
+    dbDir: config.dbDir,
+    uiDir: uiInstalled ? config.uiWebCurrentDir : '',
+    serverBinDir: dirname(config.serverBinaryPath),
+    arch: process.arch,
+    platform: config.platform,
+  });
+  const existingEnvText = existsSync(config.configEnvPath)
+    ? await readFile(config.configEnvPath, 'utf-8').catch(() => '')
+    : '';
+  const envTextWithOverrides = mergeSelfHostServerRuntimeEnvText({
+    baseEnvText: envText,
+    existingEnvText,
+    envOverrides,
+  });
+  await writeFile(config.configEnvPath, envTextWithOverrides, 'utf-8');
+  const installEnv = parseEnvText(envTextWithOverrides);
+  const healthPort = resolveSelfHostEffectiveServerPort({ config, env: installEnv });
+  await applySelfHostServerMigrationsAtInstallTime({ config, env: installEnv }).catch((e) => {
+    throw new Error(`[self-host] failed to apply database migrations at install time: ${String(e?.message ?? e)}`);
+  });
+
+  const serverShimPath = join(config.binDir, config.serverBinaryName);
+  await mkdir(config.binDir, { recursive: true });
+  await rm(serverShimPath, { force: true });
+  await symlink(config.serverBinaryPath, serverShimPath).catch(async () => {
+    await copyFile(config.serverBinaryPath, serverShimPath);
+    await chmod(serverShimPath, 0o755).catch(() => {});
+  });
+
+  const serviceSpec = buildSelfHostServerServiceSpec({ config, envText: envTextWithOverrides });
+  await installManagedService({
+    platform: config.platform,
+    mode: config.mode,
+    homeDir: homedir(),
+    spec: serviceSpec,
+    persistent: true,
+  });
+
+  const healthy = await restartAndCheckHealth({ config, serviceSpec, port: healthPort });
+  if (!healthy) {
+    throw new Error('[self-host] service failed health checks after install');
+  }
+
+  const autoUpdateResult = autoUpdateMode === 'install'
+    ? await installAutoUpdateJob({
+      config: { ...config, autoUpdateAt },
+      enabled: autoUpdateEnabled,
+      intervalMinutes: autoUpdateIntervalMinutes,
+      at: autoUpdateAt,
+    }).catch((e) => ({
+      installed: false,
+      reason: String(e?.message ?? e),
+    }))
+    : autoUpdateReconcile.action === 'install'
+      ? await installAutoUpdateJob({
+        config: { ...config, autoUpdateAt: autoUpdateReconcile.at },
+        enabled: true,
+        intervalMinutes: autoUpdateReconcile.intervalMinutes,
+        at: autoUpdateReconcile.at,
+      }).catch(() => null)
+      : await uninstallAutoUpdateJob({ config }).catch(() => null);
+
+  return {
+    uiResult,
+    autoUpdateResult,
+  };
+}
+
 async function cmdInstall({ channel, mode, argv, json }) {
   if (mode === 'system' && process.platform !== 'win32') {
     assertRoot();
@@ -1914,17 +1961,10 @@ async function cmdInstall({ channel, mode, argv, json }) {
       || parseBoolean(process.env.HAPPIER_WITH_UI, true) === false
       || parseBoolean(process.env.HAPPIER_SELF_HOST_WITH_UI, true) === false);
   const nonInteractive = argvSansEnv.includes('--non-interactive') || parseBoolean(process.env.HAPPIER_NONINTERACTIVE, false);
-  const serverBinaryOverride = String(process.env.HAPPIER_SELF_HOST_SERVER_BINARY ?? '').trim();
 
-  if (normalizeOs(config.platform) !== 'windows' && !commandExists('tar')) {
-    throw new Error('[self-host] tar is required to extract release artifacts');
-  }
   if (normalizeOs(config.platform) === 'windows' && !commandExists('powershell')) {
     throw new Error('[self-host] powershell is required on Windows');
   }
-  if (withUi && !commandExists('tar')) {
-    throw new Error('[self-host] tar is required to extract ui web bundle artifacts');
-  }
   if (normalizeOs(config.platform) === 'linux' && !commandExists('systemctl')) {
     throw new Error('[self-host] systemctl is required on Linux');
   }
@@ -1946,70 +1986,39 @@ async function cmdInstall({ channel, mode, argv, json }) {
   await mkdir(config.uiWebRootDir, { recursive: true });
   await mkdir(config.uiWebVersionsDir, { recursive: true });
 
-  const installResult = await installFromRelease({
-    product: 'happier-server',
-    binaryName: config.serverBinaryName,
+  let postPromoteResult = null;
+  const installResult = await runSelfHostRuntimeMutationWithServiceRecovery({
     config,
-    explicitBinaryPath: serverBinaryOverride,
+    mutateRuntime: async ({ beforeRuntimePromote }) => await installFromRelease(
+      resolveSelfHostServerInstallFromReleaseParams({
+        product: 'happier-server',
+        binaryName: config.serverBinaryName,
+        config,
+        env: process.env,
+        beforeRuntimePromote,
+      afterPromote: async ({ embeddedUiDir, version }) => {
+        postPromoteResult = await performSelfHostPostPromoteSteps({
+          config,
+          embeddedUiDir,
+          runtimeVersion: version,
+            withUi,
+            envOverrides,
+            autoUpdateMode: 'install',
+            autoUpdateEnabled,
+            autoUpdateIntervalMinutes,
+            autoUpdateAt,
+          });
+        },
+      }),
+    ),
   });
 
-  const uiResult = withUi
-    ? await installUiWebFromRelease({ config })
-    : { installed: false, version: null, source: null, reason: 'disabled' };
+  const uiResult = postPromoteResult?.uiResult ?? { installed: false, version: null, source: null, reason: 'disabled' };
   const uiInstalled = Boolean(uiResult?.installed);
-
-	  const envText = renderServerEnvFile({
-	    port: config.serverPort,
-	    host: config.serverHost,
-	    dataDir: config.dataDir,
-    filesDir: config.filesDir,
-    dbDir: config.dbDir,
-    uiDir: uiInstalled ? config.uiWebCurrentDir : '',
-    serverBinDir: dirname(config.serverBinaryPath),
-    arch: process.arch,
-    platform: config.platform,
-  });
-	  const envTextWithOverrides = envOverrides.length ? applyEnvOverridesToEnvText(envText, envOverrides) : envText;
-	  await writeFile(config.configEnvPath, envTextWithOverrides, 'utf-8');
-	  const installEnv = parseEnvText(envTextWithOverrides);
-	  const healthPort = resolveSelfHostEffectiveServerPort({ config, env: installEnv });
-	  if (!parseBoolean(installEnv.HAPPIER_SQLITE_AUTO_MIGRATE ?? installEnv.HAPPY_SQLITE_AUTO_MIGRATE, true)) {
-	    await applySelfHostSqliteMigrationsAtInstallTime({ env: installEnv }).catch((e) => {
-	      throw new Error(`[self-host] failed to apply sqlite migrations at install time: ${String(e?.message ?? e)}`);
-	    });
-	  }
-
-  const serverShimPath = join(config.binDir, config.serverBinaryName);
-  await mkdir(config.binDir, { recursive: true });
-  await rm(serverShimPath, { force: true });
-  await symlink(config.serverBinaryPath, serverShimPath).catch(async () => {
-    await copyFile(config.serverBinaryPath, serverShimPath);
-    await chmod(serverShimPath, 0o755).catch(() => {});
-  });
-
-  const serviceSpec = buildSelfHostServerServiceSpec({ config, envText: envTextWithOverrides });
-	  await installManagedService({
-	    platform: config.platform,
-	    mode: config.mode,
-	    homeDir: homedir(),
-	    spec: serviceSpec,
-	    persistent: true,
-	  });
-
-	  const healthy = await restartAndCheckHealth({ config, serviceSpec, port: healthPort });
-	  if (!healthy) {
-	    throw new Error('[self-host] service failed health checks after install');
-	  }
-
-  const autoUpdateResult = await installAutoUpdateJob({
-    config: { ...config, autoUpdateAt },
-    enabled: autoUpdateEnabled,
-    intervalMinutes: autoUpdateIntervalMinutes,
-    at: autoUpdateAt,
-  }).catch((e) => ({
+  const autoUpdateResult = postPromoteResult?.autoUpdateResult ?? {
     installed: false,
-    reason: String(e?.message ?? e),
-  }));
+    reason: 'missing-post-promote-result',
+  };
 
   const cliResult = await maybeInstallCompanionCli({
     channel,
@@ -2205,71 +2214,33 @@ async function cmdUpdate({ channel, mode, json }) {
   const withUi =
     parseBoolean(process.env.HAPPIER_WITH_UI, true) !== false
     && parseBoolean(process.env.HAPPIER_SELF_HOST_WITH_UI, true) !== false;
-  const installResult = await installFromRelease({
-    product: 'happier-server',
-    binaryName: config.serverBinaryName,
+  let postPromoteResult = null;
+  const installResult = await runSelfHostRuntimeMutationWithServiceRecovery({
     config,
+    mutateRuntime: async ({ beforeRuntimePromote }) => await installFromRelease(
+      resolveSelfHostServerInstallFromReleaseParams({
+        product: 'happier-server',
+        binaryName: config.serverBinaryName,
+        config,
+        env: process.env,
+        beforeRuntimePromote,
+      afterPromote: async ({ embeddedUiDir, version }) => {
+        postPromoteResult = await performSelfHostPostPromoteSteps({
+          config,
+          embeddedUiDir,
+          runtimeVersion: version,
+            withUi,
+            envOverrides: [],
+            autoUpdateMode: 'reconcile',
+            autoUpdateReconcile,
+          });
+        },
+      }),
+    ),
   });
-  const uiResult = withUi
-    ? await installUiWebFromRelease({ config })
-    : { installed: false, version: null, source: null, reason: 'disabled' };
+  const uiResult = postPromoteResult?.uiResult ?? { installed: false, version: null, source: null, reason: 'disabled' };
   const uiInstalled = Boolean(uiResult?.installed);
-
-  const envText = existsSync(config.configEnvPath)
-    ? await readFile(config.configEnvPath, 'utf-8').catch(() => '')
-    : '';
-  const parsedEnv = parseEnvText(envText);
-  const effectivePort = parsePort(parsedEnv.PORT, config.serverPort);
-  const configWithPort = effectivePort === config.serverPort ? config : { ...config, serverPort: effectivePort };
-  const defaultsEnvText = renderServerEnvFile({
-    port: configWithPort.serverPort,
-    host: configWithPort.serverHost,
-    dataDir: configWithPort.dataDir,
-    filesDir: configWithPort.filesDir,
-    dbDir: configWithPort.dbDir,
-    uiDir: uiInstalled ? configWithPort.uiWebCurrentDir : '',
-    serverBinDir: dirname(configWithPort.serverBinaryPath),
-    arch: process.arch,
-    platform: configWithPort.platform,
-  });
-  const nextEnvText = envText ? mergeEnvTextWithDefaults(envText, defaultsEnvText) : defaultsEnvText;
-  await mkdir(configWithPort.configDir, { recursive: true });
-  await writeFile(configWithPort.configEnvPath, nextEnvText, 'utf-8');
-  const nextEnv = parseEnvText(nextEnvText);
-  if (!parseBoolean(nextEnv.HAPPIER_SQLITE_AUTO_MIGRATE ?? nextEnv.HAPPY_SQLITE_AUTO_MIGRATE, true)) {
-    await applySelfHostSqliteMigrationsAtInstallTime({ env: nextEnv }).catch((e) => {
-      throw new Error(`[self-host] failed to apply sqlite migrations at update time: ${String(e?.message ?? e)}`);
-    });
-  }
-
-  const serviceSpec = buildSelfHostServerServiceSpec({ config: configWithPort, envText: nextEnvText });
-  await installManagedService({
-    platform: configWithPort.platform,
-    mode: configWithPort.mode,
-    homeDir: homedir(),
-    spec: serviceSpec,
-    persistent: true,
-  }).catch(() => {});
-  const healthy = await restartAndCheckHealth({ config: configWithPort, serviceSpec });
-  if (!healthy) {
-    if (existsSync(config.serverPreviousBinaryPath)) {
-      await copyFile(config.serverPreviousBinaryPath, config.serverBinaryPath);
-      await chmod(config.serverBinaryPath, 0o755).catch(() => {});
-      await restartAndCheckHealth({ config: configWithPort, serviceSpec });
-    }
-    throw new Error('[self-host] update failed health checks and was rolled back to previous binary');
-  }
-
-  if (autoUpdateReconcile.action === 'install') {
-    await installAutoUpdateJob({
-      config: { ...configWithPort, autoUpdateAt: autoUpdateReconcile.at },
-      enabled: true,
-      intervalMinutes: autoUpdateReconcile.intervalMinutes,
-      at: autoUpdateReconcile.at,
-    }).catch(() => {});
-  } else {
-    await uninstallAutoUpdateJob({ config: configWithPort }).catch(() => {});
-  }
+  const autoUpdateResult = postPromoteResult?.autoUpdateResult ?? null;
 
   await writeSelfHostState(config, {
     channel,
@@ -2465,7 +2436,7 @@ function redactEnvForDisplay(env) {
   return out;
 }
 
-async function cmdConfig({ channel, mode, argv, json }) {
+async function cmdConfig({ channel, mode, argv, json, output }) {
   const args = Array.isArray(argv) ? argv.map(String) : [];
   const sub = pickFirstPositional(args) || 'view';
   const subIndex = args.indexOf(sub);
@@ -2486,6 +2457,7 @@ async function cmdConfig({ channel, mode, argv, json }) {
   if (sub === 'view') {
     printResult({
       json,
+      output,
       data: {
         ok: true,
         channel,
@@ -2594,6 +2566,7 @@ async function cmdConfig({ channel, mode, argv, json }) {
 
     printResult({
       json,
+      output,
       data: {
         ok: true,
         channel,
@@ -2637,6 +2610,15 @@ export function usageText() {
 }
 
 let cachedRelayHostForwardSupport = null;
+const RELAY_HOST_FORWARDABLE_SUBCOMMANDS = new Set(['install', 'status', 'update', 'uninstall']);
+
+export function resolveRelayHostForwardedArgv(argv) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  if (String(args[0] ?? '').trim() === 'update') {
+    args[0] = 'install';
+  }
+  return args;
+}
 
 function shouldAttemptRelayHostForward(env = process.env) {
   const raw = String(env?.HAPPIER_STACK_SELF_HOST_FORWARD ?? '1').trim().toLowerCase();
@@ -2664,9 +2646,14 @@ function resolveRelayHostForwardSupport(env = process.env) {
   return cachedRelayHostForwardSupport;
 }
 
-export async function runSelfHostCli(argv = process.argv.slice(2)) {
-  if (shouldAttemptRelayHostForward(process.env) && resolveRelayHostForwardSupport(process.env)) {
-    const forwarded = spawnSync('happier', ['relay', 'host', ...argv], {
+export async function runSelfHostCli(argv = process.argv.slice(2), { configOutput = process.stdout } = {}) {
+  const parsed = parseSelfHostInvocation(argv);
+  if (
+    RELAY_HOST_FORWARDABLE_SUBCOMMANDS.has(parsed.subcommand)
+    && shouldAttemptRelayHostForward(process.env)
+    && resolveRelayHostForwardSupport(process.env)
+  ) {
+    const forwarded = spawnSync('happier', ['relay', 'host', ...resolveRelayHostForwardedArgv(argv)], {
       env: process.env,
       stdio: 'inherit',
       encoding: 'utf-8',
@@ -2680,7 +2667,6 @@ export async function runSelfHostCli(argv = process.argv.slice(2)) {
     return;
   }
 
-  const parsed = parseSelfHostInvocation(argv);
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
   const channel = normalizeChannel(String(kv.get('--channel') ?? process.env.HAPPIER_CHANNEL ?? 'stable'));
@@ -2728,7 +2714,7 @@ export async function runSelfHostCli(argv = process.argv.slice(2)) {
     return;
   }
   if (parsed.subcommand === 'config') {
-    await cmdConfig({ channel, mode, argv: parsed.rest, json });
+    await cmdConfig({ channel, mode, argv: parsed.rest, json, output: configOutput });
     return;
   }