oysterun 1.5.7 → 1.5.8

package/dev/client/web/index.html

@@ -9513,8 +9513,9 @@
                                 class="field-hint"
                                 id="host-restart-default-copy"
                               >
-                                Existing sessions and enabled in-session loops
-                                will be restored after restart.
+                                Existing Sessions will be restored after
+                                restart. Loops remain off; active work is not
+                                replayed.
                               </div>
                               <div
                                 class="host-restart-handoff"
@@ -9877,11 +9878,10 @@
                                 id="host-update-confirmation-warning"
                               >
                                 Oysterun will prepare restore state for existing
-                                sessions and enabled in-session loops before
-                                restarting Host. Active provider replies,
-                                terminal commands, loop turns, and scheduler
-                                work may be marked interrupted and will not be
-                                replayed.
+                                Sessions before restarting Host. Loops remain
+                                off. Active provider replies, terminal commands,
+                                loop turns, and scheduler work may be marked
+                                interrupted and will not be replayed.
                               </div>
                               <div
                                 class="field-hint host-update-confirmation-warning hidden"
@@ -31684,8 +31684,9 @@ Waiting for Claude login output…</pre
       function getOysterunUpdatePhase(update) {
         const operation = update?.update_operation || null;
         if (
-          operation?.status === "update_recovery_required" ||
-          operation?.status === "restart_recovery_required"
+          !operation?.root_failure &&
+          (operation?.status === "update_recovery_required" ||
+            operation?.status === "restart_recovery_required")
         ) {
           return (
             update?.recovery_plan?.user_action?.title ||
@@ -31712,6 +31713,27 @@ Waiting for Claude login output…</pre
             ? `An earlier unfinished update was safely closed after Oysterun ${operation.superseded_by_version} became healthy. Its diagnostic record was kept.`
             : "An earlier unfinished update was safely closed. Its diagnostic record was kept.";
         }
+        const rootFailure = operation.root_failure;
+        if (
+          rootFailure &&
+          typeof rootFailure === "object" &&
+          rootFailure.check &&
+          rootFailure.safe_message
+        ) {
+          const restartText = operation.restart_attempted
+            ? "Host restart was attempted."
+            : "Host restart was not attempted.";
+          const rollbackText = operation.rollback_result?.safe_message || "";
+          const recoveryText = operation.recovery_result?.safe_message || "";
+          const cleanupText = operation.cleanup_result?.safe_message || "";
+          return `Failed check: ${rootFailure.check} (stage: ${
+            rootFailure.stage || "lifecycle"
+          }). ${rootFailure.safe_message} ${restartText}${
+            rollbackText ? ` ${rollbackText}` : ""
+          }${recoveryText ? ` ${recoveryText}` : ""}${
+            cleanupText ? ` ${cleanupText}` : ""
+          }`;
+        }
         if (operation.status === "rolled_back") {
           return operation.final_observed_version
             ? `Update failed safely. Oysterun ${operation.final_observed_version} was restored.`
@@ -45551,7 +45573,7 @@ Waiting for Claude login output…</pre
           ...hostPreferencesState,
           restartLoading: true,
           restartStatus:
-            "Preparing restore state for existing sessions and enabled loops...",
+            "Preparing existing Sessions for restore. Loops will remain off; prompts will not replay...",
           loginQrError: "",
         };
         renderHostPreferences();
@@ -45898,22 +45920,17 @@ Waiting for Claude login output…</pre
           cancelOysterunUpdateConfirmation();
           return;
         }
+        // Freeze the exact version visible in the confirmation, even if a
+        // background check refreshes the surrounding Preferences state.
         const targetVersion =
-          (recoveryConfirmation
-            ? update.update_operation?.target_version ||
-              update.update_operation?.last_working_version
-            : confirmationMode === "beta"
-            ? update.beta_version || update.target_version
-            : update.newest_version || update.latest_version) ||
-          hostPreferencesState.updateConfirmationTargetVersion ||
-          "the newest version";
+          hostPreferencesState.updateConfirmationTargetVersion;
+        const confirmedCurrentVersion =
+          hostPreferencesState.updateConfirmationCurrentVersion;
         hostPreferencesState = {
           ...hostPreferencesState,
           updateConfirmationVisible: false,
           updateConfirmationMode: confirmationMode,
-          updateConfirmationCurrentVersion:
-            update.current_version ||
-            hostPreferencesState.updateConfirmationCurrentVersion,
+          updateConfirmationCurrentVersion: confirmedCurrentVersion,
           updateConfirmationTargetVersion: targetVersion,
           updateRunning: true,
           updateRequestPending: true,
@@ -45937,7 +45954,12 @@ Waiting for Claude login output…</pre
               : confirmationMode === "beta"
               ? "/admin/update-beta-run"
               : "/admin/update-run",
-            recoveryConfirmation ? { kind: confirmationMode } : {}
+            recoveryConfirmation
+              ? { kind: confirmationMode }
+              : {
+                  expected_current_version: confirmedCurrentVersion,
+                  expected_target_version: targetVersion,
+                }
           );
           const normalized =
             confirmationMode === "beta" && !recoveryConfirmation

package/host-service/cli/run-host-lifecycle.mjs

@@ -71,6 +71,16 @@ function printBoundedStatus(payload) {
     target_version: operation.target_version || payload.target_version || null,
     recovery_boundary:
       payload.recovery_boundary || operation.recovery_boundary || null,
+    failed_stage: operation.root_failure?.stage || null,
+    failed_check: operation.root_failure?.check || null,
+    failure_code: operation.root_failure?.code || null,
+    safe_message: operation.root_failure?.safe_message || null,
+    restart_attempted: operation.restart_attempted === true,
+    rollback_result: operation.rollback_result || null,
+    recovery_result: operation.recovery_result || null,
+    cleanup_result: operation.cleanup_result || null,
+    next_safe_action:
+      payload.recovery_plan?.user_action?.kind || operation.next_safe_action || null,
     secret_fields_redacted: true,
   };
   process.stdout.write(`${JSON.stringify(fields, null, 2)}\n`);

package/host-service/host-lifecycle-recovery.mjs

@@ -73,6 +73,7 @@ export function buildHostLifecycleRecoveryPlan({
   currentVersion = null,
   runnerAlive = false,
   supersededEvaluation = null,
+  continuityReceipt = null,
 } = {}) {
   if (!operation?.operation_id) {
     return {
@@ -84,6 +85,37 @@ export function buildHostLifecycleRecoveryPlan({
       host_restarted: false,
     };
   }
+  if (operation.continuity_path) {
+    const r = continuityReceipt;
+    if (r?.operation_id !== operation.operation_id) return {
+      outcome: "owner_action_required", blocking: true, user_action: { ...ACTIONS.export_diagnostics },
+      reason_code: "continuity_receipt_unverified", package_mutated: false, host_restarted: false,
+    };
+    if (["CLEANED", "ROLLED_BACK_HEALTHY"].includes(r.state)) return {
+      outcome: "continuity_terminal", blocking: false, user_action: null, reason_code: null,
+      package_mutated: false, host_restarted: false,
+    };
+    if (operation.running || runnerAlive) return {
+      outcome: "operation_running", blocking: true, user_action: null,
+      reason_code: "lifecycle_owner_active", package_mutated: false, host_restarted: false,
+    };
+    const restartOnly = r.transaction_kind === "restart_only";
+    const committed = r.state === "COMMITTED";
+    const recovery = r.state === "RECOVERY_REQUIRED";
+    const userAction = committed ? {
+      ...ACTIONS.complete_update_and_restart, label: "Finish cleanup", title: "Qualification committed",
+      description: "Host, Sessions, history and the existing route passed. Retained update files can now be cleaned.",
+      confirmation: "Finish this committed operation's cleanup. No additional restart is required.",
+    } : restartOnly ? action("restart_only", "Recover restart", "Restart recovery required",
+      "Retry the existing package with the retained fresh Session restore receipt.",
+      "Restart this Host and verify the original Session roster and history. Active work will not replay.")
+      : recovery ? { ...ACTIONS.restore_and_restart } : { ...ACTIONS.complete_update_and_restart,
+        description: "Continue the exact retained operation and verify Host, Sessions, history and the existing route.",
+        confirmation: "Continue this operation. A completed restart will not be repeated.",
+      };
+    return { outcome: "owner_action_required", blocking: true, user_action: userAction,
+      reason_code: `continuity_${r.state.toLowerCase()}`, package_mutated: false, host_restarted: false };
+  }
   if (operation.running === true || runnerAlive === true) {
     return {
       outcome: "operation_running",

package/host-service/lifecycle-continuity-assets.mjs

@@ -0,0 +1,158 @@
+import {
+  cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync,
+  readlinkSync, renameSync, rmSync, symlinkSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  assertContinuityFinalizable, advanceContinuity, continuityDigest,
+  continuityFailure, readContinuity, writeContinuityAtomic, writeContinuityBytesAtomic,
+} from "./lifecycle-continuity.mjs";
+import { restoreServiceDefinitionSnapshot, inspectServiceDefinition } from "./service-definition-migration.mjs";
+import { removeContinuityProbeGrant } from "./lifecycle-continuity-probe.mjs";
+
+const fail = (check, message) => { throw continuityFailure("retained_assets", check, message); };
+
+// Hash executable bits, relative names, symlink text and every regular file.
+// No symlink is followed, including npm's provider executables.
+export function digestContinuityPackage(root) {
+  if (!existsSync(root) || !lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink()) fail("package_root", "Package root must be a retained regular directory.");
+  const hash = createHash("sha256");
+  const visit = (directory) => {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stat = lstatSync(path);
+      const kind = stat.isSymbolicLink() ? "link" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : null;
+      if (!kind) fail("package_special_file", "Package contains an unsupported special file.");
+      hash.update(JSON.stringify([relative(root, path), kind, stat.mode & 0o777]));
+      if (kind === "file") hash.update(continuityDigest(readFileSync(path)));
+      if (kind === "link") hash.update(JSON.stringify(readlinkSync(path)));
+      if (kind === "directory") visit(path);
+    }
+  };
+  visit(root);
+  return hash.digest("hex");
+}
+
+export function validateContinuityResources(receipt, configDir, activePackageRoot) {
+  const r = receipt.resources;
+  if (!r || !receipt.operation_root || !isAbsolute(receipt.operation_root)) fail("resources_missing", "Operation-owned recovery resources are missing.");
+  const root = resolve(receipt.operation_root);
+  const active = resolve(activePackageRoot);
+  const prefix = resolve(active, "../../..");
+  if (active !== join(prefix, "lib", "node_modules", "oysterun") ||
+      dirname(root) !== prefix || !root.split("/").at(-1).startsWith(".oysterun-update-")) fail("resource_boundary", "Recovery resources escape the exact npm prefix.");
+  const exact = {
+    active_package_root: active,
+    previous_package_root: join(root, "previous-oysterun"),
+    failed_package_root: join(root, "failed-oysterun"),
+    global_lock_path: join(prefix, "lib", "node_modules", ".package-lock.json"),
+    saved_global_lock_path: join(root, "global-package-lock.json"),
+    restart_restore_state_path: join(resolve(configDir), "restart-restore-state.json"),
+    saved_pre_handoff_restart_restore_state_path: join(root, "pre-handoff-restart-restore-state.json"),
+    saved_service_definition_authority_path: join(root, "service-definition-authority.json"),
+    source_service_render_bundle_path: join(root, "source-service-render-bundle.json"),
+    mutation_journal_path: join(root, "update-mutation-journal.json"),
+  };
+  for (const [key, value] of Object.entries(exact)) {
+    if (r[key] !== value) fail("resource_binding", `Recovery ${key} differs from the operation geometry.`);
+  }
+  if (r.service_definition_path !== receipt.baseline.host.service_definition_path ||
+      r.service_definition_authority_path !== join(resolve(configDir), "service-definition-authority.json")) fail("definition_binding", "Recovery definition/authority differs from the retained Host binding.");
+  if (r.service_definition_snapshot_path !== join(root, "service-definition-snapshot.json")) fail("definition_snapshot", "Recovery definition snapshot is outside the operation root.");
+  if (existsSync(root) && (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink())) fail("operation_root", "Recovery root must be a regular directory.");
+  return { ...r, root, active, prefix };
+}
+
+export function retainContinuityFile(path, savedPath) {
+  const existed = existsSync(path);
+  if (existed && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())) fail("regular_snapshot", "Recovery file must be a regular file.");
+  const bytes = existed ? readFileSync(path) : null;
+  if (bytes) writeContinuityBytesAtomic(savedPath, bytes);
+  return { path, saved_path: savedPath, existed, mode: existed ? lstatSync(path).mode & 0o777 : null,
+    sha256: bytes ? continuityDigest(bytes) : null };
+}
+
+function restoreRetainedFile(binding) {
+  if (!binding) fail("file_binding", "Recovery file binding is missing.");
+  if (!binding.existed) { rmSync(binding.path, { force: true }); return; }
+  const bytes = readFileSync(binding.saved_path);
+  if (continuityDigest(bytes) !== binding.sha256) fail("file_digest", "Retained recovery file changed.");
+  writeContinuityBytesAtomic(binding.path, bytes, { mode: binding.mode ?? 0o600 });
+}
+
+// Rollback keeps the original package. A fresh copy is verified before the
+// active tree is exchanged. Repeating this function after either rename is
+// safe; an unknown tree is never deleted to make recovery appear successful.
+export function verifyContinuityAssets({ path, operationId, configDir, activePackageRoot }) {
+  const receipt = readContinuity(path, operationId);
+  if (["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state)) fail("terminal_assets", "Terminal recovery resources cannot be rewritten.");
+  const r = validateContinuityResources(receipt, configDir, activePackageRoot);
+  const sourceHash = receipt.source.package_tree_sha256;
+  if (!sourceHash) fail("source_hash", "Prior package has no retained tree identity.");
+  const activeIsSource = existsSync(r.active) && digestContinuityPackage(r.active) === sourceHash;
+  // Validate the entire pair before the first mutation. A valid package alone
+  // cannot authorize overwriting a changed definition or a missing snapshot.
+  const snapshot = JSON.parse(readFileSync(r.service_definition_snapshot_path, "utf8"));
+  if (continuityDigest(snapshot) !== receipt.source.definition_snapshot_digest || snapshot.definition_path !== r.service_definition_path ||
+      (snapshot.existed && continuityDigest(Buffer.from(snapshot.bytes_base64, "base64")) !== snapshot.sha256)) fail("definition_snapshot_digest", "Prior service definition snapshot changed.");
+  const rendered = { sha256: receipt.target.service_definition_sha256 || "" };
+  if (inspectServiceDefinition({ definitionPath: r.service_definition_path, snapshot, rendered }).state === "unexpected") fail("definition_changed", "Live definition is outside the retained source/target pair.");
+  const bindings = [];
+  for (const key of ["runtime_identity", "service_authority", "global_lock", "fresh_restart_state"]) {
+    const binding = receipt.retained_files?.[key];
+    if (!binding && key === "fresh_restart_state" && !receipt.restart_attempted && activeIsSource) continue;
+    if (!binding) fail("file_binding", `Retained ${key} is missing.`);
+    const expectedPath = key === "runtime_identity" ? join(resolve(configDir), "node-npm-runtime-identity.json")
+      : key === "service_authority" ? r.service_definition_authority_path
+        : key === "global_lock" ? r.global_lock_path : r.restart_restore_state_path;
+    if (binding.path !== expectedPath || dirname(binding.saved_path) !== r.root) fail("file_boundary", "Retained file escapes the operation boundary.");
+    if (existsSync(binding.path) && (!lstatSync(binding.path).isFile() || lstatSync(binding.path).isSymbolicLink())) fail("live_file_kind", "Live recovery destination is not a regular file.");
+    if (binding.existed && (!lstatSync(binding.saved_path).isFile() || lstatSync(binding.saved_path).isSymbolicLink() ||
+        continuityDigest(readFileSync(binding.saved_path)) !== binding.sha256)) fail("file_digest", "Retained recovery file changed.");
+    bindings.push(binding);
+  }
+  const binDir = join(r.prefix, "bin");
+  const link = join(binDir, "oysterun");
+  if (existsSync(link) && !lstatSync(link).isSymbolicLink()) fail("cli_link", "Global CLI path is not the expected symlink.");
+  if (!activeIsSource && (!existsSync(r.previous_package_root) || digestContinuityPackage(r.previous_package_root) !== sourceHash)) fail("source_package_changed", "Retained prior package is missing or changed; recovery assets remain intact.");
+  return { receipt, r, sourceHash, activeIsSource, snapshot, rendered, bindings, binDir, link };
+}
+
+export function restoreContinuityAssets({ path, operationId, configDir, activePackageRoot }) {
+  const { receipt, r, sourceHash, activeIsSource, snapshot, rendered, bindings, binDir, link } = verifyContinuityAssets({ path, operationId, configDir, activePackageRoot });
+  if (!activeIsSource) {
+    const prepared = join(r.root, "restore-oysterun");
+    // This copy is disposable; the receipt-bound original is never consumed.
+    // A crash during cp can therefore be retried without using partial bytes.
+    if (existsSync(prepared) && digestContinuityPackage(prepared) !== sourceHash) rmSync(prepared, { recursive: true });
+    if (!existsSync(prepared)) cpSync(r.previous_package_root, prepared, { recursive: true, dereference: false, verbatimSymlinks: true, preserveTimestamps: true });
+    if (digestContinuityPackage(prepared) !== sourceHash) fail("restore_copy", "Prepared rollback package differs from the retained source.");
+    if (existsSync(r.active)) {
+      if (existsSync(r.failed_package_root)) fail("ambiguous_active_package", "Both an active target and failed target already exist; retain both for recovery review.");
+      renameSync(r.active, r.failed_package_root);
+    }
+    renameSync(prepared, r.active);
+  }
+  mkdirSync(binDir, { recursive: true });
+  rmSync(link, { force: true });
+  symlinkSync(relative(binDir, join(r.active, "bin", "oysterun.mjs")), link);
+  restoreServiceDefinitionSnapshot({ definitionPath: r.service_definition_path, snapshot, rendered });
+  for (const binding of bindings) restoreRetainedFile(binding);
+  writeContinuityAtomic(path, { ...receipt, paired_restore_completed_at: new Date().toISOString() });
+  return { passed: true, source_package_sha256: sourceHash, version: receipt.source.version };
+}
+
+export function finalizeContinuityAssets({ path, operationId, configDir, activePackageRoot }) {
+  const receipt = assertContinuityFinalizable(path, operationId);
+  if (receipt.operation_root) {
+    const r = validateContinuityResources(receipt, configDir, activePackageRoot);
+    rmSync(r.root, { recursive: true, force: true });
+  }
+  removeContinuityProbeGrant(configDir, operationId);
+  if (receipt.restart_only_snapshot) {
+    if (receipt.restart_only_snapshot.saved_path !== `${path}.restore`) fail("restart_snapshot_boundary", "Restart snapshot is outside its exact operation path.");
+    rmSync(receipt.restart_only_snapshot.saved_path, { force: true });
+  }
+  return receipt.state === "CLEANED" ? receipt : advanceContinuity(path, operationId, "CLEANED", { recovery_assets_removed: true });
+}

package/host-service/lifecycle-continuity-probe.mjs

@@ -0,0 +1,97 @@
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
+import { continuityFailure, continuityReceiptPath, readContinuity, writeContinuityAtomic } from "./lifecycle-continuity.mjs";
+
+// This grant authenticates one read-only operation observation. It cannot
+// authenticate dashboard mutations, Matrix reads, Session control or login.
+export const CONTINUITY_PROBE_ENDPOINT = "/admin/lifecycle-qualification";
+export function continuityProbeGrantPath(configDir, operationId) {
+  return `${continuityReceiptPath(configDir, operationId)}.probe`;
+}
+
+export function createContinuityProbeGrant(configDir, operationId) {
+  const path = continuityProbeGrantPath(configDir, operationId);
+  if (existsSync(path)) throw continuityFailure("preparation", "probe_exists", "Lifecycle route grant already exists.");
+  writeContinuityAtomic(path, {
+    operation_id: operationId, token: randomBytes(32).toString("base64url"),
+    expires_at: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(),
+  });
+}
+
+function readGrant(configDir, operationId) {
+  const path = continuityProbeGrantPath(configDir, operationId);
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+    throw continuityFailure("route_probe", "private_grant", "Lifecycle route grant must be a private regular file.");
+  }
+  const grant = JSON.parse(readFileSync(path, "utf8"));
+  if (grant.operation_id !== operationId || typeof grant.token !== "string" || !Number.isFinite(Date.parse(grant.expires_at)) || Date.parse(grant.expires_at) <= Date.now()) {
+    throw continuityFailure("route_probe", "expired_grant", "Lifecycle route grant is missing, expired or mismatched.");
+  }
+  return grant;
+}
+
+// Only an already bound local controller may renew this read-only grant. The
+// HTTP verifier never renews it; offline recovery does not need a live Host.
+export function ensureContinuityProbeGrant(configDir, operationId) {
+  const receipt = readContinuity(continuityReceiptPath(configDir, operationId), operationId);
+  if (["CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state)) return;
+  const path = continuityProbeGrantPath(configDir, operationId);
+  if (existsSync(path)) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw continuityFailure("route_probe", "private_grant", "Lifecycle grant is not a private regular file.");
+    const grant = JSON.parse(readFileSync(path, "utf8"));
+    if (grant.operation_id !== operationId) throw continuityFailure("route_probe", "grant_binding", "Lifecycle grant belongs to a different operation.");
+    if (Date.parse(grant.expires_at) > Date.now() + 15 * 60 * 1000) return;
+  }
+  writeContinuityAtomic(path, { operation_id: operationId, token: randomBytes(32).toString("base64url"),
+    expires_at: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString() });
+}
+
+export function removeContinuityProbeGrant(configDir, operationId) {
+  rmSync(continuityProbeGrantPath(configDir, operationId), { force: true });
+}
+
+export function verifyContinuityProbeGrant(configDir, operationId, token) {
+  try {
+    const receipt = readContinuity(continuityReceiptPath(configDir, operationId), operationId);
+    if (["CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state)) return false;
+    const expected = Buffer.from(readGrant(configDir, operationId).token);
+    const actual = Buffer.from(typeof token === "string" ? token : "");
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  } catch { return false; }
+}
+
+export async function fetchContinuityObservation({ configDir, operationId, origin, timeoutMs = 10_000 }) {
+  const url = new URL(origin);
+  if (url.origin !== origin || url.username || url.password ||
+      !(url.protocol === "https:" || (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) {
+    throw continuityFailure("route_probe", "bounded_origin", "Lifecycle observation requires the retained HTTPS or loopback origin.");
+  }
+  const nonce = randomUUID();
+  url.pathname = CONTINUITY_PROBE_ENDPOINT;
+  url.searchParams.set("operation_id", operationId);
+  url.searchParams.set("nonce", nonce);
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${readGrant(configDir, operationId).token}`, Accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs), redirect: "error", cache: "no-store",
+  });
+  if (!response.ok) {
+    const failure = await response.json().catch(() => null);
+    if (failure?.operation_id === operationId && failure.request_nonce === nonce &&
+        typeof failure.lifecycle_diagnostic?.stage === "string" && typeof failure.lifecycle_diagnostic?.check === "string") {
+      throw continuityFailure(failure.lifecycle_diagnostic.stage, failure.lifecycle_diagnostic.check,
+        String(failure.error || "Bound lifecycle observation failed."));
+    }
+    throw continuityFailure("route_probe", "http_status", `Lifecycle observation returned HTTP ${response.status}.`);
+  }
+  const observed = await response.json();
+  if (observed.operation_id !== operationId || observed.request_nonce !== nonce) {
+    throw continuityFailure("route_probe", "response_binding", "Lifecycle observation is stale or belongs to a different operation.");
+  }
+  return {
+    ...observed,
+    route: { origin, device_id: observed.host.device_id, operation_id: operationId,
+      authenticated: true, authentication: "operation_read_only_grant", http_status: response.status },
+  };
+}

package/host-service/lifecycle-continuity-projection.mjs

@@ -0,0 +1,22 @@
+// UI state is a projection of durable facts, never HTTP/consumed inference.
+export function projectContinuityOperation(operation, receipt) {
+  if (!receipt || receipt.operation_id !== operation.operation_id) return operation;
+  const restartOnly = receipt.transaction_kind === "restart_only";
+  const common = { ...operation, continuity_state: receipt.state,
+    restart_attempted: receipt.restart_attempted === true,
+    ...(receipt.first_failure ? { root_failure: { ...receipt.first_failure,
+      safe_message: receipt.first_failure.message, observed_at: receipt.first_failure.at } } : {}),
+  };
+  if (!["CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state)) return common;
+  const recovered = receipt.state === "ROLLED_BACK_HEALTHY";
+  return { ...common, status: restartOnly ? "restart_complete" : recovered ? "rolled_back" : "update_complete",
+    running: false, runner_pid: null, runner_lease_expires_at: null, lifecycle_owner_pid: null,
+    phase: recovered ? "Prior Host, every Session, history and route qualified; recovery evidence retained"
+      : "Host, every Session, history and route qualified; cleanup complete",
+    final_observed_version: recovered ? receipt.source.version : receipt.target.version,
+    operation_cleanup_completed: !recovered, rollback_completed: recovered && !restartOnly,
+    service_status: "healthy", session_restore_status: "qualified_without_replay",
+    restart_restore_status: receipt.recovery_qualification?.sessions?.restore_required === false ? "not_required" : "consumed",
+    next_safe_action: null, recovery_required_at: null, recovery_reason: null, recovery_boundary: null,
+  };
+}

package/host-service/lifecycle-continuity-runner.mjs

@@ -0,0 +1,88 @@
+import {
+  CONTINUITY_STATES, advanceContinuity, continuityFailure, readContinuity, qualifyContinuityHost,
+  qualifyContinuitySessions, qualifyContinuityTunnel,
+} from "./lifecycle-continuity.mjs";
+import { fetchContinuityObservation } from "./lifecycle-continuity-probe.mjs";
+
+/** Shared qualification used by the existing runner and the one-time adapter.
+ * Observations are live authenticated reads; the retained baseline is never
+ * replaced by a new observation after a restart or a failed qualification.
+ */
+export async function qualifyLifecycleContinuity({
+  path, operationId, configDir, healthUrl, version, definitionDigest,
+  rollback = false, requireRestore = true, restartId = null,
+  timeoutMs = 180_000, onStage = () => {}, observe = fetchContinuityObservation,
+}) {
+  const receipt = readContinuity(path, operationId);
+  const baseline = receipt.baseline;
+  const expectedOrigin = new URL(baseline.host.managed_endpoint || baseline.host.direct_host_url).origin;
+  const loopbackOrigin = new URL(healthUrl).origin;
+  const result = {};
+  const advance = (stage, proof) => {
+    if (rollback) return;
+    const current = readContinuity(path, operationId);
+    if (CONTINUITY_STATES.indexOf(current.state) < CONTINUITY_STATES.indexOf(stage)) {
+      advanceContinuity(path, operationId, stage, proof);
+    }
+  };
+  const waitFor = async (stage, callback) => {
+    await onStage(stage);
+    const deadline = Date.now() + timeoutMs;
+    let failure;
+    do {
+      try { return await callback(); } catch (error) {
+        failure = error;
+        // Identity, lost history, explicit failed/skipped restores and changed
+        // resume IDs cannot be repaired by waiting. Provider boot and route
+        // readiness may be transient.
+        const transient = new Set([
+          "p233_runtime_not_ready", "p233_http_status", "p233_authenticated_path",
+          "p233_restart_not_consumed", "p233_user_path_pending",
+        ]).has(error.code) || ["TypeError", "TimeoutError", "AbortError"].includes(error.name);
+        if (!transient) throw error;
+        if (Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, Math.min(1000, deadline - Date.now())));
+      }
+    } while (Date.now() < deadline);
+    throw failure;
+  };
+  const local = () => observe({ configDir, operationId, origin: loopbackOrigin });
+  const checkHost = (observation) => {
+    const proof = qualifyContinuityHost(baseline.host, observation.host, {
+      version, runtimeIdentityDigest: receipt.source.runtime_identity_digest,
+      expectNewPid: requireRestore, definitionDigest,
+    });
+    if (result.host && proof.pid !== result.host.pid) throw continuityFailure("host_qualification", "qualification_pid_changed", "Host PID changed during qualification; retain recovery assets.");
+    return proof;
+  };
+  const checkSessions = (observation) => {
+    if (requireRestore && (observation.restart_state !== "consumed" || observation.restart_id !== restartId)) {
+      throw continuityFailure("session_qualification", "restart_not_consumed", "Waiting for the exact fresh Session restore receipt.");
+    }
+    return qualifyContinuitySessions(baseline.sessions, observation.sessions,
+      observation.restore_result?.session_restore, { requireRestore });
+  };
+  result.host = await waitFor("HOST_QUALIFIED", async () => checkHost(await local()));
+  advance("HOST_QUALIFIED", result.host);
+  result.sessions = await waitFor("SESSIONS_QUALIFIED", async () => {
+    const observation = await local();
+    checkHost(observation);
+    return checkSessions(observation);
+  });
+  advance("SESSIONS_QUALIFIED", result.sessions);
+  result.tunnel = await waitFor("TUNNEL_QUALIFIED", async () => {
+    const observation = await observe({ configDir, operationId, origin: expectedOrigin });
+    // A provider can exit while the user signs back in. Commit only a fresh
+    // observation that still proves the same Host and complete Session roster.
+    checkHost(observation);
+    checkSessions(observation);
+    // The scoped route probe proves transport and Host identity; a real
+    // dashboard-authenticated request on that origin proves the normal user
+    // path. Neither observation substitutes for the other.
+    if (observation.authenticated_user_path?.pid !== observation.host.pid) {
+      throw continuityFailure("tunnel_qualification", "user_path_pending", "Sign in through the existing Host URL to finish authenticated route verification.");
+    }
+    return qualifyContinuityTunnel({ origin: expectedOrigin, device_id: baseline.host.device_id, operation_id: operationId }, observation.route);
+  });
+  advance("TUNNEL_QUALIFIED", result.tunnel);
+  return result;
+}