oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/host-service/model-discovery-guardian.mjs

@@ -0,0 +1,40 @@
+// Discovery-only POSIX group anchor. Never accept a PID or group number from
+// the parent. The guardian remains a member until its final group signal.
+import { spawn } from 'node:child_process';
+let started = false;
+let stopping = false;
+let deadline;
+const send = (message) => {
+  if (process.connected) process.send(message, () => {});
+};
+process.on('SIGTERM', () => {});
+function cleanup() {
+  if (stopping) return;
+  stopping = true;
+  clearTimeout(deadline);
+  try {
+    process.kill(0, 'SIGTERM');
+    setTimeout(() => process.kill(0, 'SIGKILL'), 300);
+  } catch (error) {
+    send({ type: 'control_error', code: error.code });
+    process.exit(1);
+  }
+}
+process.on('disconnect', cleanup);
+process.on('message', (message) => {
+  if (message?.type === 'cleanup') return cleanup();
+  if (message?.type !== 'start' || started || stopping) return;
+  started = true;
+  clearTimeout(deadline);
+  try {
+    const child = spawn(message.command, message.args, { stdio: [0, 1, 2] });
+    child.once('spawn', () => send({ type: 'root_spawn' }));
+    child.once('error', (error) => send({ type: 'root_error', code: error.code, message: error.message }));
+    child.once('exit', (code, signal) => send({ type: 'root_exit', code, signal }));
+  } catch (error) {
+    send({ type: 'root_error', code: error.code, message: error.message });
+  }
+});
+// No provider is launched before the parent has established the channel.
+deadline = setTimeout(cleanup, 5000);
+send({ type: 'ready' });

package/host-service/model-discovery-process.mjs

@@ -0,0 +1,141 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { fileURLToPath } from 'node:url';
+
+// Read-only fixture diagnostics. Process-table rows are never signal authority.
+export function readDiscoveryProcessTable() {
+  return execFileSync('ps', ['-axo', 'pid=,ppid=,pgid=,lstart=,stat='], {
+    encoding: 'utf8', env: { ...process.env, LC_ALL: 'C' },
+  }).trim().split('\n').filter(Boolean).map((line) => {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.{24})\s+(\S+)/);
+    if (!m) throw new Error('model_discovery_process_identity_unavailable');
+    return { pid: +m[1], ppid: +m[2], group: +m[3], generation: m[4], state: m[5] };
+  });
+}
+const owners = new WeakMap();
+function incomplete(reason, extra = {}) {
+  const error = new Error('Model discovery cleanup cannot prove complete descendant absence');
+  error.code = 'model_discovery_cleanup_failed';
+  error.details = { process_cleanup: { status: 'unknown', proof_scope: 'anchored_process_group_only', reason, survivor_count: null, ...extra } };
+  return error;
+}
+
+export function ownDiscoveryProcess(proc) {
+  return owners.get(proc) || { cleanup: async () => { throw incomplete('no_guardian_authority'); } };
+}
+
+export function spawnDiscoveryProcess(command, args, options = {}, transport = spawn) {
+  const { signal, ...spawnOptions } = options;
+  const guardian = transport(process.execPath, [fileURLToPath(new URL('./model-discovery-guardian.mjs', import.meta.url))], {
+    ...spawnOptions, detached: true, stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+  });
+  const proc = new EventEmitter();
+  // Provider bytes never pass through IPC and the provider does not inherit
+  // the private control descriptor. Root lifecycle is forwarded separately.
+  Object.assign(proc, { stdin: guardian.stdin, stdout: guardian.stdout, stderr: guardian.stderr });
+  let exited = false, ready = false, lost = false, rootSpawned = false, rootFailed = false;
+  let closing = false, terminal = false, controlFailed = false;
+  let cleanupPromise, resolveExit;
+  const exit = new Promise((resolve) => { resolveExit = resolve; });
+  const emitError = (error) => {
+    if (terminal) return;
+    terminal = true;
+    clearTimeout(startup);
+    proc.emit('error', error);
+  };
+  const emitExit = (code, exitSignal) => {
+    if (terminal) return;
+    terminal = true;
+    proc.emit('exit', code, exitSignal);
+  };
+  const controlLost = (cause) => {
+    const unexpected = !closing && !terminal;
+    controlFailed ||= unexpected || Boolean(cause);
+    lost = true;
+    closing = true;
+    if (unexpected) {
+      const error = new Error('Model discovery guardian control lost', { cause });
+      error.code = 'model_discovery_guardian_control_lost';
+      emitError(error);
+    }
+    // The guardian's disconnect handler owns shutdown; never use its PID.
+    if (guardian.connected) guardian.disconnect();
+  };
+  const send = (message) => {
+    if (exited || lost || !guardian.connected) return false;
+    try {
+      guardian.send(message, (error) => { if (error) controlLost(error); });
+      return !lost;
+    } catch (error) { controlLost(error); return false; }
+  };
+  const abort = () => {
+    closing = true;
+    send({ type: 'cleanup' });
+    const error = new Error('Model discovery aborted'); error.name = 'AbortError'; error.code = 'ABORT_ERR';
+    emitError(error);
+  };
+  const startup = setTimeout(() => {
+    closing = true;
+    send({ type: 'cleanup' });
+    const error = new Error('Model discovery guardian startup timed out');
+    error.code = 'model_discovery_guardian_startup_timeout';
+    emitError(error);
+  }, 5000);
+  guardian.on('message', (message) => {
+    if (message?.type === 'ready' && !ready) {
+      ready = true; clearTimeout(startup);
+      if (closing || terminal || lost || exited) return;
+      if (signal?.aborted) return abort();
+      send({ type: 'start', command, args });
+    } else if (message?.type === 'root_spawn') rootSpawned = true;
+    else if (message?.type === 'root_error') {
+      rootFailed = true;
+      const error = new Error(message.message); error.code = message.code; emitError(error);
+    } else if (message?.type === 'root_exit') emitExit(message.code, message.signal);
+    else if (message?.type === 'control_error') controlLost(new Error('Guardian shutdown failed'));
+  });
+  guardian.once('error', (error) => { lost = true; controlFailed = true; emitError(error); });
+  guardian.once('disconnect', () => { if (!lost) controlLost(); });
+  for (const stream of [proc.stdin, proc.stdout, proc.stderr]) {
+    stream?.on('error', emitError);
+  }
+  guardian.once('exit', (code, exitSignal) => {
+    exited = true; clearTimeout(startup); signal?.removeEventListener('abort', abort);
+    resolveExit({ code, signal: exitSignal });
+    if (!closing) emitExit(code, exitSignal);
+  });
+  signal?.addEventListener('abort', abort, { once: true });
+  owners.set(proc, { cleanup() {
+    return cleanupPromise ||= (async () => {
+      closing = true;
+      const requested = send({ type: 'cleanup' });
+      proc.stdin?.end();
+      let timer;
+      const ended = await Promise.race([exit, new Promise((resolve) => { timer = setTimeout(() => resolve(null), 2000); })]);
+      clearTimeout(timer); clearTimeout(startup); signal?.removeEventListener('abort', abort);
+      if (!ended) {
+        // Disconnect triggers the guardian's own shutdown. Never fall back to
+        // guardian.kill(), process.kill(savedPid), or a sampled process table.
+        if (guardian.connected) guardian.disconnect();
+        throw incomplete('guardian_shutdown_unconfirmed');
+      }
+      if (rootFailed && !rootSpawned && requested && !controlFailed && ended.signal === 'SIGKILL') return { status: 'not_spawned', proof_scope: 'provider_spawn_failed' };
+      throw incomplete(requested && !controlFailed && ended.signal === 'SIGKILL' ? 'detached_descendants_unprovable' : 'guardian_control_lost', {
+        guardian_reaped: true, group_shutdown_requested: requested && !controlFailed, root_spawned: rootSpawned,
+      });
+    })();
+  } });
+  return proc;
+}
+
+// Catalog/protocol outcome and cleanup evidence are independent. Callers attach
+// this bounded diagnostic to either their valid result or original error.
+export async function collectDiscoveryCleanup(owner) {
+  try { return await owner.cleanup(); }
+  catch (error) {
+    return error.details?.process_cleanup || {
+      status: 'failed', proof_scope: 'unknown',
+      reason: 'cleanup_diagnostic_unavailable', survivor_count: null,
+    };
+  }
+}

package/host-service/onboard-lifecycle-status.mjs

@@ -0,0 +1,28 @@
+function normalizeString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function resolveOnboardLifecycleObservation(payload, expectedOperationId) {
+  const operation =
+    payload?.update_operation && typeof payload.update_operation === "object"
+      ? payload.update_operation
+      : payload?.operation && typeof payload.operation === "object"
+        ? payload.operation
+        : null;
+  const operationId = normalizeString(
+    operation?.operation_id || payload?.operation_id
+  );
+  if (operationId && operationId !== expectedOperationId) {
+    throw new Error(
+      `another lifecycle operation replaced ${expectedOperationId}: ${operationId}`
+    );
+  }
+  return {
+    operation_id: operationId,
+    status:
+      normalizeString(operation?.status) ||
+      normalizeString(payload?.operation_status) ||
+      normalizeString(payload?.status) ||
+      "unknown",
+  };
+}

package/host-service/onboard.mjs

@@ -0,0 +1,479 @@
+#!/usr/bin/env node
+
+import { readSetupInputFile } from "./setup-input-file.mjs";
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  buildCloudApiUrl,
+  getConfigPath,
+  readCloudIdentity,
+  readConfig,
+  readRawConfigSource,
+  resolveCloudBackendStage,
+  resolveCloudBackendUrl,
+  writeConfig,
+} from "./config.mjs";
+import { resolveOnboardLifecycleObservation } from "./onboard-lifecycle-status.mjs";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const setupScript =
+  process.env.OYSTERUN_ONBOARD_SETUP_SCRIPT ||
+  join(repoRoot, "host-service", "setup.mjs");
+const releaseServiceScript =
+  process.env.OYSTERUN_ONBOARD_RELEASE_SERVICE_SCRIPT ||
+  join(repoRoot, "tool_scripts", "oysterun_release_service.sh");
+const stagedRecoveryScript =
+  process.env.OYSTERUN_ONBOARD_STAGED_RECOVERY_SCRIPT ||
+  join(repoRoot, "host-service", "cli", "run-staged-lifecycle-recovery.mjs");
+
+const SUCCESSFUL_LIFECYCLE_STATUSES = new Set([
+  "restart_complete",
+  "update_complete",
+]);
+const FAILED_LIFECYCLE_STATUSES = new Set([
+  "update_recovery_required",
+  "restart_recovery_required",
+  "native_abi_mismatch",
+  "runtime_validation_failed",
+  "config_compatibility_failed",
+  "activation_failed",
+  "preparation_failed",
+  "staging_install_failed",
+  "restart_schedule_failed",
+  "post_restart_health_failed",
+  "rollback_failed",
+  "failed",
+  "install_failed",
+  "version_mismatch",
+]);
+
+function normalizeString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function parseArgs(argv) {
+  const options = {
+    packageChanged: false,
+    updateRequired: false,
+    repairRequired: false,
+    channel: "latest",
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--package-changed") options.packageChanged = true;
+    else if (arg === "--update-required") options.updateRequired = true;
+    else if (arg === "--repair-required") options.repairRequired = true;
+    else if (arg === "--setup-input-file") {
+      options.setupInputFile=argv[++index];
+      if (!options.setupInputFile || options.setupInputFile.startsWith("--")) throw new Error("--setup-input-file requires an absolute path");
+    }
+    else if (arg === "--channel") options.channel = argv[++index] || "";
+    else throw new Error(`unknown onboard argument: ${arg}`);
+  }
+  if (
+    !new Set(["latest", "beta"]).has(options.channel) &&
+    !/^exact:[0-9A-Za-z.+-]+$/.test(options.channel)
+  ) {
+    throw new Error("--channel must be latest, beta, or exact:<version>");
+  }
+  if (options.updateRequired && options.repairRequired) {
+    throw new Error("--update-required and --repair-required cannot be combined");
+  }
+  return options;
+}
+
+function run(command, args, { capture = false, allowFailure = false, setupInputDescriptor } = {}) {
+  const childEnv = { ...process.env };
+  delete childEnv.OYSTERUN_SETUP_INPUT_FD;
+  delete childEnv.OYSTERUN_SETUP_INPUT_NEXT_FD;
+  if (setupInputDescriptor !== undefined) childEnv.OYSTERUN_SETUP_INPUT_FD = "3";
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    env: {
+      ...childEnv,
+      OYSTERUN_BOOTSTRAP_NODE_BIN: process.execPath,
+      OYSTERUN_NODE_BIN: process.execPath,
+      PATH: `${dirname(process.execPath)}:${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}`,
+    },
+    encoding: capture ? "utf8" : undefined,
+    stdio: setupInputDescriptor !== undefined ? ["inherit", "inherit", "inherit", setupInputDescriptor] : capture ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  if (result.error) throw result.error;
+  if (!allowFailure && (result.status ?? 1) !== 0) {
+    const detail = capture
+      ? String(result.stderr || result.stdout || "").trim()
+      : "";
+    throw new Error(
+      `command failed (${result.status ?? 1}): ${command}${
+        detail ? `: ${detail}` : ""
+      }`
+    );
+  }
+  return result;
+}
+
+function service(command, args = [], options = {}) {
+  return run(releaseServiceScript, [command, ...args], options);
+}
+
+function parseKeyValueStatus(output) {
+  const status = {};
+  for (const line of String(output || "").split(/\r?\n/)) {
+    const match = line.match(/^([a-z_]+)=(.*)$/);
+    if (match) status[match[1]] = match[2].trim();
+  }
+  return status;
+}
+
+function readServiceStatus() {
+  const result = service("status", [], { capture: true, allowFailure: true });
+  if ((result.status ?? 1) !== 0) {
+    return {
+      available: false,
+      healthy: false,
+      running: false,
+      managed: false,
+      authenticated: false,
+      raw: {},
+    };
+  }
+  const raw = parseKeyValueStatus(result.stdout);
+  const pid = raw.pid && raw.pid !== "-" ? raw.pid : null;
+  const healthy = raw.health === "yes";
+  const managed = raw.loaded === "yes" && Boolean(pid);
+  let authenticated = false;
+
+  // A Host installed by an older Oysterun release can still be healthy while
+  // its process is absent from the current service manager's PID/label view.
+  // Prove that such a listener is this user's Host through the loopback-only
+  // service-control token before treating it as running. An unrelated process
+  // with a /health endpoint remains untrusted and is never stopped or adopted.
+  if (healthy && !managed) {
+    const control = service("lifecycle-status", [], {
+      capture: true,
+      allowFailure: true,
+    });
+    authenticated =
+      (control.status ?? 1) === 0 &&
+      Boolean(parseJsonOutput(control.stdout));
+  }
+  return {
+    available: true,
+    healthy,
+    running: managed || authenticated,
+    managed,
+    authenticated,
+    raw,
+  };
+}
+
+function readLifecycleStatus() {
+  const result = service("lifecycle-status", [], {
+    capture: true,
+    allowFailure: true,
+  });
+  return (result.status ?? 1) === 0 ? parseJsonOutput(result.stdout) : null;
+}
+
+function recoverRetainedLifecycleWithStagedDriver() {
+  run(process.execPath, [stagedRecoveryScript]);
+}
+
+function isConfigReady(raw, identity) {
+  const port = Number(raw.port);
+  const common =
+    Number.isInteger(port) &&
+    port > 0 &&
+    normalizeString(raw.dashboard_password_hash) &&
+    normalizeString(raw.dashboard_user) &&
+    normalizeString(raw.default_browse_path);
+  if (!common) return false;
+  if (raw.connection_mode === "direct") {
+    return Boolean(
+      normalizeString(raw.direct_host_url) ||
+        normalizeString(raw.public_base_url)
+    );
+  }
+  return Boolean(
+    normalizeString(raw.managed_endpoint) &&
+      normalizeString(identity.device_id || identity.host_id) &&
+      normalizeString(identity.device_token || identity.host_credential)
+  );
+}
+
+function parseJsonOutput(value) {
+  try {
+    return JSON.parse(String(value || ""));
+  } catch {
+    return null;
+  }
+}
+
+function wait(ms) {
+  return new Promise((resolveWait) => setTimeout(resolveWait, ms));
+}
+
+async function waitForLifecycle(operationId) {
+  const timeoutMs = Number(
+    process.env.OYSTERUN_ONBOARD_LIFECYCLE_TIMEOUT_MS || 180_000
+  );
+  const pollMs = Number(process.env.OYSTERUN_ONBOARD_POLL_MS || 1_000);
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = "unavailable";
+  while (Date.now() < deadline) {
+    const result = service("lifecycle-status", [], {
+      capture: true,
+      allowFailure: true,
+    });
+    if ((result.status ?? 1) === 0) {
+      const payload = parseJsonOutput(result.stdout);
+      if (payload) {
+        const observation = resolveOnboardLifecycleObservation(
+          payload,
+          operationId
+        );
+        lastStatus = observation.status;
+        if (SUCCESSFUL_LIFECYCLE_STATUSES.has(lastStatus)) return payload;
+        if (FAILED_LIFECYCLE_STATUSES.has(lastStatus)) {
+          throw new Error(
+            payload.safe_message ||
+              `Host lifecycle did not complete successfully (${lastStatus})`
+          );
+        }
+      }
+    }
+    await wait(pollMs);
+  }
+  throw new Error(
+    `timed out waiting for Host lifecycle ${operationId} (last status: ${lastStatus})`
+  );
+}
+
+async function restartThroughLifecycle() {
+  const result = service("restart", ["--restore-sessions"], {
+    capture: true,
+  });
+  const payload = parseJsonOutput(result.stdout);
+  const operationId = normalizeString(payload?.operation_id);
+  if (!operationId) {
+    throw new Error("Host lifecycle restart did not return an operation ID");
+  }
+  console.log(`  Host lifecycle operation: ${operationId}`);
+  await waitForLifecycle(operationId);
+}
+
+async function runLifecycleMutation(command, args = []) {
+  const result = service(command, args, { capture: true });
+  const payload = parseJsonOutput(result.stdout);
+  const operationId = normalizeString(payload?.operation_id);
+  if (!operationId) {
+    throw new Error(`Host lifecycle ${command} did not return an operation ID`);
+  }
+  console.log(`  Host lifecycle operation: ${operationId}`);
+  await waitForLifecycle(operationId);
+}
+
+async function waitForLocalHealth() {
+  const timeoutMs = Number(process.env.OYSTERUN_ONBOARD_HEALTH_TIMEOUT_MS || 90_000);
+  const pollMs = Number(process.env.OYSTERUN_ONBOARD_POLL_MS || 1_000);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const status = readServiceStatus();
+    if (status.healthy && status.running) return status;
+    await wait(pollMs);
+  }
+  throw new Error("Oysterun Host did not become healthy before the onboarding timeout");
+}
+
+async function verifyManagedRoute(config, identity) {
+  if (config.connection_mode === "direct") return;
+  const endpoint = normalizeString(config.managed_endpoint);
+  const token = normalizeString(identity.device_token || identity.host_credential);
+  if (!endpoint || !token) {
+    throw new Error("Managed Host identity or endpoint is incomplete");
+  }
+  const backendUrl = resolveCloudBackendUrl(config);
+  const backendStage = resolveCloudBackendStage(config);
+  const timeoutMs = Number(process.env.OYSTERUN_ONBOARD_ROUTE_TIMEOUT_MS || 90_000);
+  const pollMs = Number(process.env.OYSTERUN_ONBOARD_POLL_MS || 1_000);
+  const deadline = Date.now() + timeoutMs;
+  let lastReason = "Managed Endpoint status was unavailable";
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(
+        buildCloudApiUrl(
+          backendUrl,
+          "/api/connectivity/host/route",
+          backendStage
+        ),
+        {
+          headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+          signal: AbortSignal.timeout(Math.min(10_000, Math.max(1, deadline - Date.now()))),
+        }
+      );
+      if (response.ok) {
+        const route = await response.json();
+        if (
+          route?.healthy === true &&
+          route?.status === "healthy" &&
+          normalizeString(route?.managed_endpoint) === endpoint
+        ) {
+          const publicHealth = await fetch(`${endpoint.replace(/\/+$/, "")}/health`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(Math.min(10_000, Math.max(1, deadline - Date.now()))),
+          });
+          if (publicHealth.ok) return;
+          lastReason = `Managed Endpoint health returned HTTP ${publicHealth.status}`;
+        } else {
+          lastReason = `Managed route status is ${route?.status || "unknown"}`;
+        }
+      } else {
+        lastReason = `Managed route verification returned HTTP ${response.status}`;
+      }
+    } catch (error) {
+      lastReason = error?.message || String(error);
+    }
+    await wait(pollMs);
+  }
+  throw new Error(`${lastReason}; onboarding is resumable with the same install command`);
+}
+
+function runSetup({ deferServiceActivation = false, setupInputFile } = {}) {
+  run(process.execPath, [
+    setupScript,
+    "--release-setup",
+    ...(setupInputFile ? ["--setup-input-file",setupInputFile] : []),
+    ...(deferServiceActivation ? ["--defer-service-activation"] : []),
+  ], { setupInputDescriptor: process.env.OYSTERUN_SETUP_INPUT_FD !== undefined ? Number(process.env.OYSTERUN_SETUP_INPUT_NEXT_FD) : undefined });
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const configPath = getConfigPath();
+  let raw = existsSync(configPath) ? readRawConfigSource() : {};
+  let identity = readCloudIdentity();
+  const hadReadyConfig = isConfigReady(raw, identity);
+  if (!hadReadyConfig || options.setupInputFile || process.env.OYSTERUN_SETUP_INPUT_FD !== undefined) readSetupInputFile({file: options.setupInputFile, configDir: dirname(configPath), unattended: !process.stdin.isTTY});
+  if (process.env.OYSTERUN_SETUP_INPUT_FD !== undefined && !/^\d+$/.test(process.env.OYSTERUN_SETUP_INPUT_NEXT_FD || "")) throw new Error("Missing internal setup input handoff descriptor");
+  const initialService = readServiceStatus();
+  const setupActivationDeferred =
+    !hadReadyConfig && initialService.healthy && initialService.running;
+
+  if (!hadReadyConfig) {
+    console.log("Completing Oysterun Host configuration...");
+    runSetup({ deferServiceActivation: setupActivationDeferred, setupInputFile: options.setupInputFile });
+    raw = readRawConfigSource();
+    identity = readCloudIdentity();
+    if (!isConfigReady(raw, identity)) {
+      throw new Error("Host setup returned without a complete configuration and identity");
+    }
+  } else {
+    console.log(`Existing Oysterun Host found at ${configPath}; preserving it.`);
+  }
+
+  let before = readServiceStatus();
+  let retainedLifecycle =
+    before.healthy && before.running
+      ? readLifecycleStatus()
+      : null;
+  if (
+    options.updateRequired &&
+    retainedLifecycle?.blocking === true &&
+    retainedLifecycle?.next_safe_action === "restore_and_restart"
+  ) {
+    console.log(
+      "Restoring the retained last working Host with the verified staged lifecycle driver..."
+    );
+    recoverRetainedLifecycleWithStagedDriver();
+    await waitForLocalHealth();
+    before = readServiceStatus();
+    retainedLifecycle =
+      before.healthy && before.running ? readLifecycleStatus() : null;
+  }
+  if (
+    before.healthy &&
+    before.running &&
+    !options.updateRequired &&
+    !options.repairRequired &&
+    !options.packageChanged &&
+    !setupActivationDeferred &&
+    retainedLifecycle?.blocking === true
+  ) {
+    throw new Error(
+      "An Oysterun lifecycle transaction is still blocking onboarding. Run oysterun service:lifecycle-status and follow that operation's reported safe next action, or wait for its completion before rerunning this install command."
+    );
+  }
+  if (
+    (hadReadyConfig || setupActivationDeferred) &&
+    options.updateRequired &&
+    before.healthy &&
+    before.running
+  ) {
+    if (!new Set(["latest", "beta"]).has(options.channel)) {
+      throw new Error("a running Host update requires a latest or beta channel");
+    }
+    console.log(`Updating through the ${options.channel} restore-aware Host lifecycle...`);
+    await runLifecycleMutation("update", ["--channel", options.channel]);
+  } else if (
+    (hadReadyConfig || setupActivationDeferred) &&
+    options.repairRequired &&
+    before.healthy &&
+    before.running
+  ) {
+    console.log("Repairing through the restore-aware Host lifecycle...");
+    await runLifecycleMutation("repair");
+  } else if (
+    (hadReadyConfig || setupActivationDeferred) &&
+    options.packageChanged &&
+    before.healthy &&
+    before.running
+  ) {
+    console.log("Applying the installed package through the restore-aware Host lifecycle...");
+    await restartThroughLifecycle();
+  } else if (setupActivationDeferred && before.healthy && before.running) {
+    console.log("Applying completed Host configuration through the restore-aware lifecycle...");
+    await restartThroughLifecycle();
+  } else if (!before.healthy || !before.running) {
+    console.log("Starting the Oysterun Host service...");
+    const runtimeIdentityExists = existsSync(
+      join(dirname(configPath), "node-npm-runtime-identity.json")
+    );
+    service(
+      options.packageChanged && !before.running
+        ? "install"
+        : before.raw.loaded === "yes" || runtimeIdentityExists
+          ? "start"
+          : "install"
+    );
+  }
+
+  await waitForLocalHealth();
+  const config = readConfig();
+  identity = readCloudIdentity();
+  await verifyManagedRoute(config, identity);
+  writeConfig({ oysterun_update_channel: options.channel });
+
+  console.log("\nOysterun is ready.");
+  console.log(`Config: ${configPath}`);
+  console.log(
+    `${config.connection_mode === "direct" ? "Direct Host" : "Managed Host"}: ${
+      config.connection_mode === "direct"
+        ? config.direct_host_url || config.public_base_url
+        : config.managed_endpoint
+    }`
+  );
+  console.log(
+    hadReadyConfig
+      ? "Existing Cloud identity and settings were preserved."
+      : "Host configuration, Cloud identity, service health, and endpoint were verified."
+  );
+}
+
+main().catch((error) => {
+  console.error(`Oysterun onboarding failed: ${error.message}`);
+  process.exitCode = 1;
+});