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

package/tool_scripts/oysterun_continuity_transaction.mjs

@@ -0,0 +1,438 @@
+// Durable continuation of the existing Host Preferences lifecycle runner.
+// Service mutation remains owned by its canonical service-command primitive.
+import { existsSync, mkdirSync, readFileSync, rmSync, renameSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  advanceContinuity, continuityDigest, continuityFailure, continuityReceiptPath, readContinuity,
+  recordContinuityRecovery, writeContinuityAtomic, writeContinuityBytesAtomic, recordContinuityRestartAttempt,
+  qualifyContinuityHost, qualifyContinuitySessions,
+  bindLegacyContinuityConnectionMode,
+} from "../host-service/lifecycle-continuity.mjs";
+import {
+  finalizeContinuityAssets, restoreContinuityAssets, validateContinuityResources, verifyContinuityAssets, digestContinuityPackage,
+} from "../host-service/lifecycle-continuity-assets.mjs";
+import { qualifyLifecycleContinuity } from "../host-service/lifecycle-continuity-runner.mjs";
+import { fetchContinuityObservation, ensureContinuityProbeGrant } from "../host-service/lifecycle-continuity-probe.mjs";
+import { verifyPersistedNodeNpmRuntimeIdentity, resolveNodeNpmRuntimeIdentity } from "../host-service/node-npm-runtime-identity.mjs";
+import { readUpdateOperationState, writeUpdateOperationState, UPDATE_RESTART_RUNNER_LEASE_MS } from "../host-service/update-reminder-state.mjs";
+import { readHostRestartRestoreState } from "../host-service/restart-restore-state.mjs";
+import { releaseHostRestartLoginGate } from "../host-service/host-restart-login-gate.mjs";
+import { projectContinuityOperation } from "../host-service/lifecycle-continuity-projection.mjs";
+import { sanitizeLifecycleDiagnostic } from "../host-service/lifecycle-diagnostics.mjs";
+
+import { prepareCompatibility, readCompatibility } from "../host-service/lifecycle-compatibility.mjs";
+import { renderServiceDefinition } from "../host-service/service-definition-migration.mjs";
+import { bindLegacyObservationConnectionMode } from "../host-service/legacy-continuity-observation.mjs";
+
+export function inspectContinuityListener(port) {
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) throw continuityFailure("host_qualification", "port", "The retained Host port is invalid.");
+  const result = spawnSync(process.platform === "darwin" ? "/usr/sbin/lsof" : "lsof",
+    ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+  if (result.error || ![0, 1].includes(result.status)) throw continuityFailure("host_qualification", "listener_observation", "Cannot inspect the exact Host listener.");
+  return [...new Set(result.stdout.trim().split(/\s+/).filter(Boolean).map(Number))];
+}
+
+export function confirmStoppedContinuityService(receipt) {
+  if (inspectContinuityListener(receipt.baseline.host.port).length !== 0 || process.platform !== "darwin") return false;
+  const stack = receipt.baseline.host.stack;
+  if (!/^[A-Za-z0-9_-]+$/.test(stack || "")) return false;
+  const label = stack === "production" ? "com.oysterun.host" : `com.oysterun.host.${stack}`;
+  const result = spawnSync("/bin/launchctl", ["print", `gui/${process.getuid()}/${label}`], { encoding: "utf8" });
+  // launchctl's explicit service-not-found result, not a network timeout.
+  return !result.error && result.status !== 0 && /Could not find service|service not found/i.test(`${result.stderr}\n${result.stdout}`);
+}
+
+function serviceDefinitionMatchesRetainedDigest(path, retainedDigest) {
+  if (retainedDigest === "absent") return !existsSync(path);
+  return Boolean(retainedDigest) && existsSync(path) &&
+    continuityDigest(readFileSync(path)) === retainedDigest;
+}
+
+function acquireRunner(path, operationId) {
+  const lock = `${path}.runner`;
+  const claim = `${lock}.claim-${randomUUID()}`;
+  mkdirSync(claim, { mode: 0o700 });
+  writeContinuityAtomic(join(claim, "owner.json"), { operation_id: operationId, pid: process.pid });
+  try { renameSync(claim, lock); } catch (error) {
+    rmSync(claim, { recursive: true, force: true });
+    if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
+    const owner = JSON.parse(readFileSync(join(lock, "owner.json"), "utf8"));
+    if (owner.operation_id !== operationId || !Number.isInteger(owner.pid)) throw continuityFailure("runner", "runner_lock", "Runner ownership is ambiguous.");
+    let alive = true;
+    try { process.kill(owner.pid, 0); } catch (error) { if (error.code === "ESRCH") alive = false; else throw error; }
+    if (alive) throw continuityFailure("runner", "runner_active", "This operation already has a live external runner.");
+    rmSync(lock, { recursive: true });
+    return acquireRunner(path, operationId);
+  }
+  return () => rmSync(lock, { recursive: true, force: true });
+}
+
+export async function runContinuityTransaction(args, overrides = {}) {
+  const operation = readUpdateOperationState({ configDir: args.config_dir });
+  const path = args.continuity_path || operation.continuity_path;
+  if (!path || operation.operation_id !== args.operation_id ||
+      path !== continuityReceiptPath(args.config_dir, args.operation_id)) throw continuityFailure("runner", "operation_binding", "Lifecycle operation changed before continuation.");
+  const unlock = acquireRunner(path, args.operation_id);
+  try { return await continueTransaction(args, overrides, path); }
+  catch (error) {
+    const current = readUpdateOperationState({ configDir: args.config_dir });
+    const receipt = readContinuity(path, args.operation_id);
+    if (current.operation_id === args.operation_id && !["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state)) {
+      const failed = recordContinuityRecovery(path, args.operation_id, error);
+      writeUpdateOperationState({ ...current,
+        status: failed.transaction_kind === "restart_only" ? "restart_recovery_required" : "update_recovery_required",
+        running: false, lifecycle_owner_pid: null, runner_pid: null, runner_lease_expires_at: null,
+        continuity_state: failed.state, restart_attempted: failed.restart_attempted,
+        root_failure: { ...failed.first_failure, safe_message: failed.first_failure.message },
+        error: sanitizeLifecycleDiagnostic(error.message), error_redacted: true,
+      }, { configDir: args.config_dir });
+    }
+    throw error;
+  } finally { unlock(); }
+}
+
+async function continueTransaction(args, overrides, path) {
+  const get = () => readContinuity(path, args.operation_id);
+  const baseline = get().baseline.host;
+  if (baseline.config_dir !== resolve(args.config_dir) || baseline.stack !== args.stack ||
+      (baseline.package_root && baseline.package_root !== resolve(args.active_package_root)) ||
+      new URL(args.health_url).origin !== `http://127.0.0.1:${baseline.port}`) throw continuityFailure("runner", "exact_geometry", "Runner arguments differ from the retained Host geometry.");
+  const restartOnly = get().transaction_kind === "restart_only";
+  const observeRaw = overrides.observeContinuity || fetchContinuityObservation;
+  const listeners = overrides.inspectListener || inspectContinuityListener;
+  const readBoundHealth = async () => {
+    if (overrides.readPreRestartHealth) return overrides.readPreRestartHealth({ healthUrl: args.health_url });
+    const response = await fetch(args.health_url, {
+      headers: { Accept: "application/json" }, signal: AbortSignal.timeout(10_000),
+      redirect: "error", cache: "no-store",
+    });
+    if (!response.ok) throw continuityFailure("host_qualification", "legacy_health_status", "Legacy Host health did not return success.");
+    return response.json();
+  };
+  const observe = async (options) => bindLegacyObservationConnectionMode({
+    receipt: get(), observation: await observeRaw(options),
+    inspectListener: listeners, readHealth: readBoundHealth,
+  });
+  const recovering = get().state === "RECOVERY_REQUIRED" || args.restore_before_restart === "1";
+  const identity = recovering
+    ? resolveNodeNpmRuntimeIdentity({ nodeBin: args.node_bin, npmCli: args.npm_cli })
+    : verifyPersistedNodeNpmRuntimeIdentity({ configDir: args.config_dir, nodeBin: args.node_bin, npmCli: args.npm_cli });
+  if (identity.toolchain_identity_digest !== args.identity_digest || identity.toolchain_identity_digest !== get().source.runtime_identity_digest) throw continuityFailure("restart_preflight", "runtime_identity", "Retained Node/npm identity changed.");
+  ensureContinuityProbeGrant(args.config_dir, args.operation_id);
+  const patch = (values) => {
+    const current = readUpdateOperationState({ configDir: args.config_dir });
+    if (current.operation_id !== args.operation_id) throw continuityFailure("runner", "operation_binding", "Lifecycle operation changed while running.");
+    const receipt = get();
+    if (["CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state) && values.running === true) {
+      return writeUpdateOperationState(projectContinuityOperation(current, receipt), { configDir: args.config_dir });
+    }
+    return writeUpdateOperationState({ ...current, ...values,
+      restart_attempted: receipt.restart_attempted,
+      continuity_state: receipt.state,
+      ...(receipt.first_failure ? { root_failure: { ...receipt.first_failure,
+        safe_message: receipt.first_failure.message, observed_at: receipt.first_failure.at } } : {}),
+      error_redacted: true }, { configDir: args.config_dir });
+  };
+  const phase = (stage) => patch({ status: "restart_runner_started", running: true, runner_pid: process.pid,
+    phase: stage === "HOST_QUALIFIED" ? "Verifying Host identity"
+      : stage === "SESSIONS_QUALIFIED" ? "Verifying every Session and committed history"
+        : "Verifying the existing authenticated Host URL",
+    runner_lease_expires_at: new Date(Date.now() + UPDATE_RESTART_RUNNER_LEASE_MS).toISOString() });
+  const runService = async (command, options = {}) => {
+    if (["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(get().state)) {
+      throw continuityFailure("recovery", "terminal_operation", "A completed operation cannot mutate the Host again.");
+    }
+    if (args.recheck_only === "1") throw continuityFailure("recovery", "read_only_recheck", "Requalification cannot restart or restore the Host.");
+    if (overrides.runService) return overrides.runService(command, options);
+    if (!overrides.runCanonicalService) throw continuityFailure("runner", "canonical_service", "Canonical service command primitive is unavailable.");
+    if (["service:start", "service:restart"].includes(command)) {
+      const ps = spawnSync("/bin/ps", ["-axo", "pid=,command="], { encoding: "utf8" });
+      if (ps.status !== 0 || ps.stdout.split("\n").some((line) =>
+        ["synapse_homeserver", "artifacts/spike0", "routec_spike0"].every((part) => line.includes(part)))) throw continuityFailure("restart_preflight", "legacy_cleanup_scope", "Canonical start would include legacy cleanup outside this operation; stop for review.");
+    }
+    return overrides.runCanonicalService({ identity, activeRoot: resolve(args.active_package_root), stack: args.stack,
+      command, operationId: args.operation_id, continuityPath: path, ...options });
+  };
+  const bindLegacyConnectionMode = async () => {
+    const retained = get();
+    if (Object.hasOwn(retained.baseline.host, "connection_mode")) return retained;
+    const origin = new URL(args.health_url).origin;
+    const observation = await observe({
+      configDir: args.config_dir,
+      operationId: args.operation_id,
+      origin,
+    });
+    const pids = listeners(retained.baseline.host.port);
+    const expected = retained.baseline.host;
+    for (const key of ["device_id", "config_dir", "browser_root", "host_folder", "port", "stack", "managed_endpoint", "direct_host_url"]) {
+      if (observation.host?.[key] !== expected[key]) {
+        throw continuityFailure("preparation", `legacy_host_${key}`, `Legacy Host ${key} changed before route-mode binding.`);
+      }
+    }
+    if (pids.length !== 1 || pids[0] !== expected.pid || observation.host?.pid !== expected.pid) {
+      throw continuityFailure("preparation", "legacy_sole_listener", "Legacy route mode requires the retained original Host as sole listener.");
+    }
+    let health;
+    if (overrides.readPreRestartHealth) {
+      health = await overrides.readPreRestartHealth({ healthUrl: args.health_url });
+    } else {
+      const response = await fetch(args.health_url, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(10_000),
+        redirect: "error",
+        cache: "no-store",
+      });
+      if (!response.ok) throw continuityFailure("preparation", "legacy_health_status", "Legacy Host health did not return success.");
+      health = await response.json();
+    }
+    if (!["ok", "degraded"].includes(health?.status) ||
+        health.device_id !== expected.device_id ||
+        !["cloud", "direct"].includes(health.connection_mode)) {
+      throw continuityFailure("preparation", "legacy_health_identity", "Legacy Host health cannot bind the retained route mode.");
+    }
+    return bindLegacyContinuityConnectionMode(path, args.operation_id, health.connection_mode, {
+      pid: expected.pid,
+      device_id: health.device_id,
+      sole_listener: true,
+      observed_at: new Date().toISOString(),
+    });
+  };
+  const qualify = async (rollback, requireRestore) => {
+    const r = get();
+    const bound = rollback ? r.source : r.target;
+    const checkedObserve = async (options) => {
+      const observation = await observe(options);
+      const pids = listeners(r.baseline.host.port);
+      if (pids.length !== 1 || pids[0] !== observation.host.pid) throw continuityFailure("host_qualification", "sole_listener", "The intended Host is not the sole listener on its retained port.");
+      return observation;
+    };
+    return qualifyLifecycleContinuity({ path, operationId: args.operation_id, configDir: args.config_dir,
+      healthUrl: args.health_url, version: bound.version,
+      definitionDigest: rollback && r.compatibility && r.paired_restore_completed_at
+        ? readCompatibility(r.compatibility.descriptor_path).descriptor.definition_sha256
+        : bound.service_definition_sha256 || r.baseline.host.service_definition_sha256,
+      rollback, requireRestore, restartId: r.restart_id || args.restart_id,
+      observe: checkedObserve, timeoutMs: overrides.qualificationTimeoutMs ?? 180_000, onStage: phase });
+  };
+  const terminal = (status, receipt) => {
+    const rolledBack = receipt.state === "ROLLED_BACK_HEALTHY";
+    const result = {
+      status, operation_id: args.operation_id, continuity_path: path,
+      completed_at: new Date().toISOString(), observed_version: rolledBack ? receipt.source.version : receipt.target.version,
+      rollback_available: false, rollback_completed: rolledBack && !restartOnly, restart_attempted: receipt.restart_attempted,
+      operation_cleanup_completed: receipt.state === "CLEANED", root_failure: receipt.first_failure,
+      retained_recovery_assets: receipt.state !== "CLEANED", error_redacted: true,
+    };
+    if (args.result_path) writeContinuityAtomic(args.result_path, result);
+    patch({ status, phase: rolledBack ? restartOnly ? "Restart recovered; original Sessions, history and route verified"
+      : "Previous version, Sessions and route restored; recovery evidence retained"
+      : restartOnly ? "Restarted; all Sessions, history and route verified" : "Updated; all Sessions, history and route verified",
+      running: false, final_observed_version: result.observed_version, terminal_result_status: status,
+      operation_cleanup_completed: result.operation_cleanup_completed, rollback_completed: result.rollback_completed,
+      service_status: "healthy", session_restore_status: "qualified_without_replay",
+      restart_restore_status: receipt.recovery_qualification?.sessions?.restore_required === false ? "not_required" : "consumed",
+      runner_pid: null, runner_lease_expires_at: null, next_safe_action: null,
+      recovery_required_at: null, recovery_reason: null, recovery_boundary: null,
+      error: rolledBack ? receipt.first_failure?.message : null,
+      ...(rolledBack ? { recovery_result: { result: "passed", code: "prior_state_qualified",
+        safe_message: restartOnly ? "Restart recovered with every retained Session, history and authenticated Host route verified."
+          : "Previous package, service, every Session, history and authenticated Host route restored and verified." },
+        rollback_result: { result: restartOnly ? "not_required" : "passed", code: restartOnly ? "same_package_restart_recovered" : "paired_source_restored",
+          safe_message: restartOnly ? "The original package remains installed." : "The receipt-bound prior package and service definition are restored." } } : {}),
+      cleanup_result: { result: receipt.state === "CLEANED" ? "passed" : "incomplete",
+        code: receipt.state === "CLEANED" ? "operation_root_removed" : "operation_root_retained",
+        safe_message: receipt.state === "CLEANED" ? "Committed operation resources were removed." : "Recovery assets remain retained." },
+    });
+    // Publish the same terminal wording and separate login evidence as status/CLI.
+    const current = readUpdateOperationState({ configDir: args.config_dir });
+    writeUpdateOperationState(projectContinuityOperation(current, receipt), { configDir: args.config_dir });
+    return result;
+  };
+  const finalize = () => terminal(restartOnly ? "restart_complete" : "update_complete",
+    finalizeContinuityAssets({ path, operationId: args.operation_id, configDir: args.config_dir, activePackageRoot: args.active_package_root }));
+  if (["COMMITTED", "CLEANED"].includes(get().state) &&
+      (args.restore_before_restart === "1" || args.rollback_before_restart === "1")) throw continuityFailure("recovery", "already_committed", "Rollback is closed after COMMITTED; use the explicit finalize command for cleanup.");
+  if (["COMMITTED", "CLEANED"].includes(get().state)) return finalize();
+  if (get().state === "ROLLED_BACK_HEALTHY") return terminal(restartOnly ? "restart_complete" : "rolled_back", get());
+
+  if (args.recheck_only === "1") {
+    const r = get();
+    const live = await observe({ configDir: args.config_dir, operationId: args.operation_id, origin: new URL(args.health_url).origin });
+    const pids = listeners(r.baseline.host.port);
+    const unchanged = !r.restart_attempted && !r.restart_id && live.host.pid === r.baseline.host.pid;
+    if (r.state !== "RECOVERY_REQUIRED" || pids.length !== 1 || pids[0] !== live.host.pid ||
+        live.host.version !== r.source.version || (!unchanged && !r.paired_restore_completed_at) ||
+        digestContinuityPackage(args.active_package_root) !== r.source.package_tree_sha256 ||
+        !serviceDefinitionMatchesRetainedDigest(r.baseline.host.service_definition_path, r.source.service_definition_sha256)) {
+      throw continuityFailure("recovery", "recheck_identity", "The existing Host is not a proved unchanged or already-restored source; recovery remains protected.");
+    }
+    if (!unchanged) verifyContinuityAssets({ path, operationId: args.operation_id,
+      configDir: args.config_dir, activePackageRoot: args.active_package_root });
+    const proof = await qualify(true, !unchanged);
+    return terminal(restartOnly ? "restart_complete" : "rolled_back",
+      recordContinuityRecovery(path, args.operation_id, new Error(r.first_failure?.message || "Update did not complete"), proof));
+  }
+
+  if (restartOnly && args.recover_restart === "1" && get().state === "RECOVERY_REQUIRED") {
+    try {
+      const r = get();
+      if (digestContinuityPackage(args.active_package_root) !== r.source.package_tree_sha256 ||
+          !serviceDefinitionMatchesRetainedDigest(
+            r.baseline.host.service_definition_path,
+            r.source.service_definition_sha256
+          )) {
+        throw continuityFailure("restart_recovery", "original_package_definition", "Restart recovery requires the exact original package and service definition; retain the original Session snapshot.");
+      }
+      const binding = r.restart_only_snapshot;
+      if (binding?.path !== join(resolve(args.config_dir), "restart-restore-state.json") ||
+          binding.saved_path !== `${path}.restore` || continuityDigest(readFileSync(binding.saved_path)) !== binding.sha256) throw continuityFailure("restart_recovery", "fresh_restore_binding", "The original fresh restart snapshot is unavailable or changed.");
+      const saved = JSON.parse(readFileSync(binding.saved_path, "utf8"));
+      if (saved.state !== "prepared" || saved.restart_id !== r.restart_id) throw continuityFailure("restart_recovery", "fresh_restore_identity", "Restart recovery cannot substitute another Session snapshot.");
+      writeContinuityBytesAtomic(binding.path, readFileSync(binding.saved_path), { mode: binding.mode ?? 0o600 });
+      await runService("service:restart");
+      const proof = await qualify(true, true);
+      return terminal("restart_complete", recordContinuityRecovery(path, args.operation_id,
+        new Error(r.first_failure.message), proof));
+    } catch (error) {
+      recordContinuityRecovery(path, args.operation_id, error);
+      patch({ status: "restart_recovery_required", phase: "Restart recovery failed; original evidence retained",
+        running: false, runner_pid: null, runner_lease_expires_at: null, operation_cleanup_completed: false,
+        error: sanitizeLifecycleDiagnostic(error.message), recovery_boundary: error.code || "restart_recovery_failed" });
+      throw error;
+    }
+  }
+
+  let failure;
+  try {
+    if (args.restore_before_restart === "1" || args.rollback_before_restart === "1" || get().state === "RECOVERY_REQUIRED") {
+      throw continuityFailure("recovery", "recovery_requested", "Continue the retained operation's prior-state recovery.");
+    }
+    if (restartOnly && get().state === "PREPARED") advanceContinuity(path, args.operation_id, "PACKAGE_SWITCHED", { package_unchanged: true });
+    if (get().state === "PREPARED") throw continuityFailure("recovery", "activation_incomplete", "Package activation was interrupted before its durable boundary.");
+    if (get().state === "PACKAGE_SWITCHED") {
+      await bindLegacyConnectionMode();
+      const r = get();
+      if (!r.restart_attempted) {
+        const restore = readHostRestartRestoreState({ configDir: args.config_dir });
+        if (restore?.state !== "prepared" || restore.restart_id !== (r.restart_id || args.restart_id) || restore.stack_name !== args.stack) throw continuityFailure("restart_preflight", "fresh_restore_receipt", "The exact fresh prepared Session receipt is missing.");
+        if (overrides.beforeForwardRestart) await overrides.beforeForwardRestart(r);
+        await runService("service:restart", restartOnly ? {} : {
+          expectedRetainedCurrentHostCwd: join(r.resources.previous_package_root, "host-service"),
+          expectedTargetServiceDefinitionSha256: r.target.service_definition_sha256,
+        });
+      } else {
+        // Crash after the canonical stop/start marker: observe the replacement.
+        // Never repeat the forward restart to paper over an unknown outcome.
+        const observation = await observe({ configDir: args.config_dir, operationId: args.operation_id, origin: new URL(args.health_url).origin });
+        if (observation.host.pid === r.baseline.host.pid || observation.host.version !== r.target.version) throw continuityFailure("restart", "interrupted_restart", "Interrupted restart has no proven replacement Host.");
+      }
+      advanceContinuity(path, args.operation_id, "SERVICE_RESTARTED", { canonical_restart_completed: true });
+    }
+    const finalQualification = await qualify(false, true);
+    // A continuation can requalify an already-written TUNNEL_QUALIFIED
+    // boundary. Preserve the original transition and durably bind the fresh
+    // observation used by this commit, rather than discarding that evidence.
+    advanceContinuity(path, args.operation_id, "COMMITTED", { final_qualification: finalQualification });
+    return finalize();
+  } catch (error) {
+    // Failure during cleanup is a committed cleanup failure, never rollback.
+    if (["COMMITTED", "CLEANED"].includes(get().state)) {
+      patch({ status: "restart_recovery_required", phase: "Qualification committed; cleanup requires continuation",
+        running: false, operation_cleanup_completed: false, runner_pid: null, runner_lease_expires_at: null,
+        error: sanitizeLifecycleDiagnostic(error.message), next_safe_action: "complete_update_and_restart" });
+      throw error;
+    }
+    failure = error;
+    recordContinuityRecovery(path, args.operation_id, error);
+  }
+  patch({ status: restartOnly ? "restart_recovery_required" : "post_restart_health_failed",
+    phase: restartOnly ? "Restart qualification failed; recovery required" : "Target qualification failed; restoring the previous version",
+    running: !restartOnly, error: sanitizeLifecycleDiagnostic(failure.message) });
+  if (restartOnly) {
+    // A same-package restart has no alternate package to exchange. Preserve its
+    // fresh restore authority and report the exact cause for canonical recovery.
+    patch({ running: false, runner_pid: null, runner_lease_expires_at: null,
+      recovery_required_at: new Date().toISOString(), recovery_boundary: "restart_qualification_incomplete",
+      recovery_reason: get().first_failure.message, next_safe_action: null, operation_cleanup_completed: false });
+    throw failure;
+  }
+  try {
+    const r = get();
+    const pids = listeners(r.baseline.host.port);
+    if (pids.length > 1) throw continuityFailure("recovery", "ambiguous_listener", "Recovery found more than one Host listener.");
+    const originalStillLive = pids.length === 1 && pids[0] === r.baseline.host.pid;
+    if (!r.source.definition_snapshot_digest && !r.restart_attempted && originalStillLive &&
+        r.source.package_tree_sha256 && digestContinuityPackage(args.active_package_root) === r.source.package_tree_sha256 &&
+        continuityDigest(readFileSync(r.baseline.host.service_definition_path)) === r.baseline.host.service_definition_sha256) {
+      // PREPARED can be interrupted before the installer retains any assets.
+      // Nothing is exchanged here: prove the complete unchanged prior state.
+      return terminal("rolled_back", recordContinuityRecovery(path, args.operation_id, failure, await qualify(true, false)));
+    }
+    validateContinuityResources(r, args.config_dir, args.active_package_root);
+    prepareCompatibility({ path, operationId: args.operation_id, render: renderServiceDefinition });
+    verifyContinuityAssets({ path, operationId: args.operation_id, configDir: args.config_dir, activePackageRoot: args.active_package_root });
+    const restartPrior = !originalStillLive || existsSync(r.resources.previous_package_root);
+    if (pids.length && !originalStillLive) {
+      const live = await observe({ configDir: args.config_dir, operationId: args.operation_id, origin: new URL(args.health_url).origin });
+      if (r.paired_restore_completed_at && live.host.pid === pids[0] && live.host.version === r.source.version &&
+          digestContinuityPackage(args.active_package_root) === r.source.package_tree_sha256) {
+        // Asset restoration does not prove provider restoration. Retry only
+        // positively failed/exited retained runtimes, never a merely missing
+        // or still-starting provider. Healthy route-only recovery stays read-only.
+        const missing = r.baseline.sessions.filter((row) => !live.sessions.some((seen) => seen.session_id === row.session_id));
+        const failedIds = new Set((live.restore_result?.session_restore?.failed || []).map((row) => row.session_id));
+        const desired = live.desired_session_restore;
+        const exited = desired?.valid === true ? desired.sessions.filter((row) => row.state === "failed") : [];
+        const retryProviders = missing.length > 0 && live.restart_state === "consumed" && live.restart_id === r.restart_id &&
+          missing.every((row) => failedIds.has(row.session_id) || exited.some((seen) =>
+            seen.session_id === row.session_id && ["agent_id", "agent_folder", "provider"].every((key) => seen[key] === row[key])));
+        if (!retryProviders) return terminal("rolled_back", recordContinuityRecovery(path, args.operation_id, failure, await qualify(true, true)));
+        qualifyContinuityHost(r.baseline.host, live.host, { version: r.source.version,
+          runtimeIdentityDigest: r.source.runtime_identity_digest,
+          definitionDigest: r.compatibility ? readCompatibility(r.compatibility.descriptor_path).descriptor.definition_sha256 : r.source.service_definition_sha256 });
+        if ([...live.sessions, ...(desired?.valid === true ? desired.sessions : [])].some((row) => !r.baseline.sessions.some((expected) => expected.session_id === row.session_id))) {
+          throw continuityFailure("recovery", "unexpected_live_session", "An unretained Session appeared; preserve the live Host and stop for a fresh recovery review.");
+        }
+        qualifyContinuitySessions(r.baseline.sessions.filter((row) => live.sessions.some((seen) => seen.session_id === row.session_id)), live.sessions, null, { requireRestore: false, path, operationId: args.operation_id });
+        await runService("service:stop");
+        restoreContinuityAssets({ path, operationId: args.operation_id, configDir: args.config_dir, activePackageRoot: args.active_package_root });
+        await runService("service:start");
+        releaseHostRestartLoginGate({ configDir: args.config_dir, gateId: args.login_gate_id || null,
+          restartId: r.restart_id || args.restart_id, reason: "prior_providers_retried_for_qualification" });
+        return terminal("rolled_back", recordContinuityRecovery(path, args.operation_id, failure, await qualify(true, true)));
+      }
+      if (live.host.pid !== pids[0] || live.host.version !== r.target.version) throw continuityFailure("recovery", "target_process_identity", "Recovery cannot bind the live process to this target.");
+      if (live.sessions.some((row) => !r.baseline.sessions.some((expected) => expected.session_id === row.session_id))) throw continuityFailure("recovery", "unexpected_live_session", "An unretained Session appeared; preserve the live Host and stop for a fresh recovery review.");
+      await runService("service:stop");
+    }
+    if (originalStillLive && restartPrior) {
+      // The retained source inode is now outside activeRoot. A copied package
+      // cannot move the running process's cwd back; restart the exact prior
+      // Host so the next canonical lifecycle preflight remains usable.
+      const live = await observe({ configDir: args.config_dir, operationId: args.operation_id, origin: new URL(args.health_url).origin });
+      if (live.sessions.some((row) => !r.baseline.sessions.some((expected) => expected.session_id === row.session_id))) throw continuityFailure("recovery", "unexpected_live_session", "An unretained Session appeared; preserve the live Host and stop for a fresh recovery review.");
+      recordContinuityRestartAttempt(path, args.operation_id);
+      await runService("service:stop");
+    }
+    if (!pids.length && !(overrides.confirmStoppedService || confirmStoppedContinuityService)(r)) {
+      throw continuityFailure("recovery", "service_stop_unproven", "No listener is present; confirm the exact service job is stopped before offline paired recovery.");
+    }
+    restoreContinuityAssets({ path, operationId: args.operation_id, configDir: args.config_dir, activePackageRoot: args.active_package_root });
+    if (restartPrior) await runService("service:start");
+    releaseHostRestartLoginGate({ configDir: args.config_dir, gateId: args.login_gate_id || null,
+      restartId: get().restart_id || args.restart_id, reason: "prior_host_available_for_qualification" });
+    const proof = await qualify(true, restartPrior);
+    const recovered = recordContinuityRecovery(path, args.operation_id, failure, proof);
+    return terminal("rolled_back", recovered);
+  } catch (error) {
+    recordContinuityRecovery(path, args.operation_id, failure);
+    patch({ status: "rollback_failed", phase: "Recovery incomplete; retained assets require canonical continuation",
+      running: false, terminal_result_status: "rollback_failed", runner_pid: null, runner_lease_expires_at: null,
+      rollback_completed: false, operation_cleanup_completed: false, next_safe_action: "restore_and_restart",
+      recovery_required_at: new Date().toISOString(), recovery_boundary: error.code || "paired_recovery_incomplete",
+      recovery_reason: sanitizeLifecycleDiagnostic(error.message), error: sanitizeLifecycleDiagnostic(error.message) });
+    throw error;
+  }
+}

package/tool_scripts/oysterun_npm_package_manifest.mjs

@@ -7,10 +7,12 @@ export const npmRequiredToolScripts = Object.freeze([
   "restart_oysterun.sh",
   "stop_oysterun.sh",
   "run_oysterun_host.sh",
+  "oysterun_setup_input.sh",
   "oysterun_service_common.sh",
   "preflight_oysterun_restart.sh",
   "stack_dashboard_credentials.mjs",
   "sync_host_stack_config.mjs",
+  "resolve_user_host_port.mjs",
   "routec_stack_readiness.mjs",
   "oysterun_npm_package_manifest.mjs",
   "oysterun_release_receipt_lib.mjs",
@@ -19,10 +21,14 @@ export const npmRequiredToolScripts = Object.freeze([
   "verify_oysterun_runtime.mjs",
   "install_oysterun_update.mjs",
   "oysterun_update_restart_runner.mjs",
+  "oysterun_continuity_transaction.mjs",
+  "test_environment_remote_cloud_deprovision.mjs",
+  "p233_legacy_bootstrap.mjs",
 ]);
 
 export const npmDocsToInclude = Object.freeze([
   "docs/routec/dev/npmjs_publish.md",
+  "docs/routec/dev/p262_setup_input_file.md",
   "docs/routec/dev/npm_native_dependency_install.md",
   "docs/routec/dev/chat_local_link_annotation_pipeline.md",
   "docs/routec/host_setup.md",
@@ -73,11 +79,34 @@ export const npmRequiredPackagePaths = Object.freeze([
   "package.json",
   "README.md",
   "bin/oysterun.mjs",
+  "host-service/complete-cli-uninstall.mjs",
   "host-service/server.mjs",
+  "host-service/onboard.mjs",
+  "host-service/host-port-resolution.mjs",
+  "host-service/installer-recovery-guidance.mjs",
+  "host-service/installer-reinstall-bindings.mjs",
+  "host-service/routec-matrix-storage-paths.mjs",
+  "host-service/legacy-continuity-observation.mjs",
+  "host-service/retained-host-state-holder.mjs",
+  "host-service/stopped-user-host-package.mjs",
+  "host-service/cli/installer-recovery-guidance.mjs",
+  "host-service/cli/assert-installer-reinstall-target.mjs",
+  "host-service/cli/recover-installer-lifecycle.mjs",
+  "tool_scripts/resolve_user_host_port.mjs",
   "host-service/node-npm-runtime-identity.mjs",
   "host-service/host-lifecycle-recovery.mjs",
   "host-service/lifecycle-diagnostics.mjs",
   "host-service/service-definition-migration.mjs",
+  "host-service/lifecycle-continuity.mjs",
+  "host-service/lifecycle-user-path.mjs",
+  "host-service/lifecycle-compatibility.mjs",
+  "host-service/lifecycle-compat-preload.mjs",
+  "host-service/lifecycle-compat-cli.mjs",
+  "host-service/lifecycle-continuity-assets.mjs",
+  "host-service/lifecycle-continuity-probe.mjs",
+  "host-service/lifecycle-continuity-projection.mjs",
+  "host-service/lifecycle-continuity-runner.mjs",
+  "host-service/lifecycle-service-render-bundle.mjs",
   "host-service/cli/assert-lifecycle-operation-available.mjs",
   "host-service/cli/run-host-lifecycle.mjs",
   "host-service/connectivity/data-channel-adapter.mjs",
@@ -97,5 +126,8 @@ export const npmRequiredPackagePaths = Object.freeze([
   "tool_scripts/verify_oysterun_runtime.mjs",
   "tool_scripts/install_oysterun_update.mjs",
   "tool_scripts/oysterun_update_restart_runner.mjs",
+  "tool_scripts/oysterun_continuity_transaction.mjs",
+  "tool_scripts/test_environment_remote_cloud_deprovision.mjs",
+  "tool_scripts/p233_legacy_bootstrap.mjs",
   "tool_scripts/preflight_oysterun_restart.sh",
 ]);

package/tool_scripts/oysterun_release_service.sh

@@ -53,6 +53,11 @@ run_host_lifecycle_request() {
     fi
     configure_stack_runtime
     require_host_port_configured
+    if [[ "${STACK_NAME}" == production ]]; then
+      local bound_pid=""
+      bound_pid="$(resolve_bound_user_host_pid)"
+      ensure_port_listener_matches_expected_process "${HOST_PORT}" "${bound_pid}"
+    fi
     local bootstrap_node=""
     local node_bin=""
     local npm_cli=""