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

package/host-service/lifecycle-continuity.mjs

@@ -0,0 +1,493 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync,
+  readFileSync, renameSync, writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { compareOysterunSemver } from "./npm-update-policy.mjs";
+import { fileURLToPath } from "node:url";
+import { sanitizeLifecycleDiagnostic } from "./lifecycle-diagnostics.mjs";
+import { retireHostRestartRestoreState } from "./restart-restore-state.mjs";
+import { channel } from "node:diagnostics_channel";
+
+// One operation-owned record shared by normal updates and the bounded legacy
+// adapter. Lower-case lifecycle/UI statuses remain projections of this record.
+export const CONTINUITY_STATES = Object.freeze([
+  "PREPARED", "PACKAGE_SWITCHED", "SERVICE_RESTARTED", "HOST_QUALIFIED",
+  "SESSIONS_QUALIFIED", "TUNNEL_QUALIFIED", "COMMITTED", "CLEANED",
+]);
+export const CONTINUITY_SCHEMA = "oysterun.lifecycle_continuity.v1";
+export const RECOVERY_IDENTITY_SCHEMA = "oysterun.recovery_identity.v1";
+const durableBoundaryChannel = channel("oysterun.lifecycle.continuity.durable");
+function publishDurableBoundary(path, receipt) {
+  durableBoundaryChannel.publish({ path, operation_id: receipt.operation_id, state: receipt.state });
+  return receipt;
+}
+
+export function continuityFailure(stage, check, message) {
+  const error = new Error(message);
+  error.code = `p233_${check}`;
+  error.lifecycle_diagnostic = { stage, check, code: error.code, result: "failed" };
+  return error;
+}
+
+function requireValue(condition, stage, check, message) {
+  if (!condition) throw continuityFailure(stage, check, message);
+}
+
+const identityFields = ["session_id", "provider", "provider_resume_id", "provider_thread_id",
+  "agent_id", "agent_folder", "matrix_binding_host_session_id", "matrix_room_id", "resume_identity_kind"];
+const baselineHostFields = new Set(["version", "pid", "port", "stack", "package_root", "process_cwd",
+  "node_version", "runtime_identity_digest", "device_id", "config_dir", "host_folder",
+  "browser_root", "connection_mode", "managed_endpoint", "direct_host_url", "service_definition_sha256",
+  "service_definition_path"]);
+const baselineSessionFields = new Set([...identityFields, "adapter_resume_identity_kind", "adapter_registered",
+  "alive", "ready", "history_anchors", "observation_error"]);
+const requiredIdentityFields = ["session_id", "provider", "agent_id", "agent_folder",
+  "matrix_binding_host_session_id", "matrix_room_id"];
+const realProviders = new Set(["codex", "claude", "xai"]);
+const bounded = (value) => typeof value === "string" && value.length <= 2048 && value.trim() === value && value.length > 0 ? value : null;
+
+// Only these fields can affect recovery identity. The adapter's declared mode
+// is captured by the Host, never inferred from the provider name or a Session ID.
+export function canonicalizeContinuityIdentity(row) {
+  const identity = Object.fromEntries(identityFields.map((key) => [key, bounded(row?.[key])]));
+  identity.schema = RECOVERY_IDENTITY_SCHEMA;
+  const adapterKind = bounded(row?.adapter_resume_identity_kind);
+  const missing = requiredIdentityFields.find((key) => !identity[key]);
+  if (missing) return { identity, error: `session_${missing}` };
+  if (identity.matrix_binding_host_session_id !== identity.session_id) return { identity, error: "session_matrix_binding_host_session_id" };
+  const fixture = adapterKind === "host_session" && row?.adapter_registered === true &&
+    !realProviders.has(identity.provider);
+  if (identity.resume_identity_kind === "host_session") {
+    if (!fixture || identity.provider_resume_id ||
+      (identity.provider_thread_id && identity.provider_thread_id !== identity.session_id))
+      return { identity, error: "session_resume_identity_kind" };
+  } else if (identity.resume_identity_kind === "provider_metadata" || identity.resume_identity_kind === null) {
+    if (!realProviders.has(identity.provider) || adapterKind !== "provider_metadata" ||
+      row?.adapter_registered !== true || !identity.provider_resume_id ||
+      !identity.provider_thread_id || identity.provider_resume_id === identity.session_id ||
+      identity.provider_thread_id === identity.session_id)
+      return { identity, error: "session_provider_resume_id" };
+    // The sole legacy representation exception is an absent source mode with
+    // provider-owned identity already present. Both observations use this mode.
+    identity.resume_identity_kind = "provider_metadata";
+  } else return { identity, error: "session_resume_identity_kind" };
+  return { identity, error: null };
+}
+
+export function hasCompleteContinuityResumeIdentity(row) {
+  return canonicalizeContinuityIdentity(row).error === null;
+}
+
+function boundedIdentityObservation(rows) {
+  return Array.isArray(rows) ? rows.slice(0, 256).map((row) => ({
+    ...Object.fromEntries(identityFields.map((key) => [key, bounded(row?.[key])])),
+    adapter_resume_identity_kind: bounded(row?.adapter_resume_identity_kind),
+    adapter_registered: row?.adapter_registered === true,
+    alive: row?.alive === true, ready: row?.ready === true,
+    history_anchors: Array.isArray(row?.history_anchors) ? row.history_anchors.slice(0, 8).map((anchor) => ({
+      event_id: bounded(anchor?.event_id), sha256: /^[a-f0-9]{64}$/i.test(anchor?.sha256 || "") ? anchor.sha256 : null,
+    })) : null,
+  })) : null;
+}
+
+function boundedBaseline(baseline) {
+  const host = Object.fromEntries(Object.entries(baseline.host).filter(([key]) => baselineHostFields.has(key))
+    .map(([key, value]) => [key, ["pid", "port"].includes(key)
+      ? (Number.isSafeInteger(value) && value > 0 ? value : null) : bounded(value)]));
+  const sessions = baseline.sessions.slice(0, 256).map((row) => Object.fromEntries(
+    Object.entries(row).filter(([key]) => baselineSessionFields.has(key)).map(([key, value]) => [key,
+      key === "history_anchors" ? (Array.isArray(value) ? value.slice(0, 8).map((anchor) => ({
+        event_id: bounded(anchor?.event_id), sha256: bounded(anchor?.sha256),
+      })) : null) : ["alive", "ready", "adapter_registered"].includes(key)
+        ? value === true : bounded(value)])));
+  return { host, sessions, captured_at: bounded(baseline.captured_at) };
+}
+
+export function compareContinuityIdentities(expected, observed, { path = null, operationId = null, stage = "session_qualification" } = {}) {
+  const source = boundedIdentityObservation(expected), target = boundedIdentityObservation(observed);
+  const normalizedSource = source?.map(canonicalizeContinuityIdentity) || [];
+  const normalizedTarget = target?.map(canonicalizeContinuityIdentity) || [];
+  let check = !source || !target ? "roster_missing" :
+    source.length !== expected.length || target.length !== observed.length ? "roster_limit" : null;
+  if (!check && new Set(target.map((row) => row.session_id)).size !== target.length) check = "duplicate_runtime";
+  if (!check && source.length !== target.length) check = "roster_changed";
+  for (let index = 0; !check && index < source.length; index++) {
+    const before = normalizedSource[index];
+    const afterIndex = target.findIndex((row) => row.session_id === source[index].session_id);
+    if (afterIndex < 0) { check = "session_missing"; break; }
+    const after = normalizedTarget[afterIndex];
+    if (before.error || after.error) { check = before.error || after.error; break; }
+    for (const key of identityFields) {
+      if (before.identity[key] !== after.identity[key]) { check = `session_${key}`; break; }
+    }
+  }
+  const evidence = { schema: RECOVERY_IDENTITY_SCHEMA, stage, source, target,
+    normalized_source: normalizedSource.map((row) => row.identity),
+    normalized_target: normalizedTarget.map((row) => row.identity),
+    verdict: { passed: !check, check } };
+  persistContinuityIdentityEvidence(evidence, { path, operationId });
+  if (check) throw continuityFailure(stage, check, `Continuity identity failed ${check}.`);
+  return evidence;
+}
+
+function persistContinuityIdentityEvidence(evidence, { path = null, operationId = null } = {}) {
+  if (path) {
+    const receipt = readContinuity(path, operationId);
+    receipt.identity_comparisons ||= [];
+    receipt.identity_comparisons.push(evidence);
+    // Keep retries bounded while preserving the first terminal failure ahead
+    // of a transient pending observation. A pending subset must never evict
+    // the raw/normalized evidence that caused the actual rollback.
+    if (receipt.identity_comparisons.length > 12) {
+      const firstFailure = receipt.identity_comparisons.find((row) =>
+        row.verdict.passed === false && row.verdict.pending !== true);
+      const firstPending = receipt.identity_comparisons.find((row) => row.verdict.pending === true);
+      const retainedPriority = firstFailure || firstPending;
+      const tail = receipt.identity_comparisons.slice(-12);
+      receipt.identity_comparisons = retainedPriority && !tail.includes(retainedPriority)
+        ? [retainedPriority, ...tail.slice(-11)] : tail;
+    }
+    writeContinuityAtomic(path, receipt);
+  }
+}
+
+// A restart receipt can be complete before every restored provider runtime is
+// observable in the live roster. Preserve the full bounded observation before
+// waiting, while a separate exact-subset qualification validates every runtime
+// that is already visible. This pending verdict is not a continuity PASS.
+export function recordContinuityRosterPending(expected, observed,
+  { path = null, operationId = null, stage = "session_qualification" } = {}) {
+  const source = boundedIdentityObservation(expected), target = boundedIdentityObservation(observed);
+  const normalizedSource = source?.map(canonicalizeContinuityIdentity) || [];
+  const normalizedTarget = target?.map(canonicalizeContinuityIdentity) || [];
+  const evidence = { schema: RECOVERY_IDENTITY_SCHEMA, stage, source, target,
+    normalized_source: normalizedSource.map((row) => row.identity),
+    normalized_target: normalizedTarget.map((row) => row.identity),
+    verdict: { passed: false, pending: true, check: "roster_changed" } };
+  persistContinuityIdentityEvidence(evidence, { path, operationId });
+  return evidence;
+}
+
+export function continuityDigest(value) {
+  return createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value)
+    ? value : JSON.stringify(value)).digest("hex");
+}
+
+export function writeContinuityBytesAtomic(path, bytes, { mode = 0o600 } = {}) {
+  requireValue(isAbsolute(path), "receipt", "absolute_path", "Continuity receipt requires an absolute path.");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  if (existsSync(path)) {
+    const stat = lstatSync(path);
+    requireValue(stat.isFile() && !stat.isSymbolicLink(), "receipt", "regular_file", "Continuity receipt must be a regular file.");
+  }
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, "wx", mode);
+  try {
+    writeFileSync(fd, bytes);
+    fsyncSync(fd);
+  } finally { closeSync(fd); }
+  renameSync(temporary, path);
+  const directory = openSync(dirname(path), "r");
+  try { fsyncSync(directory); } finally { closeSync(directory); }
+  return path;
+}
+
+export function writeContinuityAtomic(path, value) {
+  writeContinuityBytesAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+  return value;
+}
+
+export function continuityReceiptPath(configDir, operationId) {
+  requireValue(/^[a-zA-Z0-9-]+$/.test(operationId || ""), "receipt", "operation_id", "Invalid lifecycle operation identity.");
+  return join(resolve(configDir), "operation_logs", `continuity-${operationId}.json`);
+}
+
+export function readContinuity(path, operationId) {
+  const stat = lstatSync(path);
+  requireValue(stat.isFile() && !stat.isSymbolicLink(), "receipt", "regular_file", "Continuity receipt must be a regular file.");
+  const receipt = JSON.parse(readFileSync(path, "utf8"));
+  requireValue(receipt.schema === CONTINUITY_SCHEMA && receipt.operation_id === operationId,
+    "receipt", "operation_binding", "Continuity receipt belongs to a different operation.");
+  requireValue(Array.isArray(receipt.transitions) && receipt.transitions.length > 0,
+    "receipt", "transition_history", "Continuity transition history is missing.");
+  requireValue(receipt.baseline_digest === continuityDigest(receipt.baseline),
+    "receipt", "baseline_identity", "Retained continuity baseline changed.");
+  let previous = null;
+  for (const [index, transition] of receipt.transitions.entries()) {
+    const next = CONTINUITY_STATES[CONTINUITY_STATES.indexOf(previous) + 1];
+    const recovery = ["RECOVERY_REQUIRED", "ROLLED_BACK_HEALTHY"].includes(transition.state);
+    requireValue(transition.sequence === index + 1 && Number.isFinite(Date.parse(transition.at)) &&
+      (index === 0 ? transition.state === "PREPARED" :
+        recovery ? !["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(previous) :
+          CONTINUITY_STATES.includes(previous) && transition.state === next),
+    "receipt", "transition_history", "Continuity transition history is inconsistent.");
+    previous = transition.state;
+    if (transition.state.endsWith("_QUALIFIED")) requireValue(transition.evidence?.passed === true &&
+      receipt.qualifications?.[transition.state]?.passed === true, "receipt", "qualification_evidence", "Durable qualification has no positive evidence.");
+  }
+  requireValue(previous === receipt.state, "receipt", "transition_history", "Continuity state differs from its durable history.");
+  if (receipt.state === "ROLLED_BACK_HEALTHY") requireValue(["host", "sessions", "tunnel"].every((key) =>
+    receipt.recovery_qualification?.[key]?.passed === true), "receipt", "rollback_evidence", "Healthy rollback requires the full prior-state qualification.");
+  return receipt;
+}
+
+// The final live Sessions are captured by the running coordinator immediately before
+// its handoff gate closes. Installation may take minutes; the initial live Sessions
+// must never silently stand in for this fresh capture.
+export function assertFreshContinuitySnapshot(baseline, restartId, restartState, evidence = {}) {
+  requireValue(restartId && Array.isArray(baseline?.sessions), "preparation", "fresh_roster_identity", "Fresh live Session identity is missing.");
+  const ids = baseline.sessions.map((row) => row.session_id);
+  const saved = restartState?.runtime_snapshot?.sessions?.filter((row) => row.alive_before_restart || row.ready_before_restart);
+  requireValue(restartState?.state === "prepared" && restartState.restart_id === restartId && Array.isArray(saved),
+    "preparation", "fresh_snapshot_roster", "Fresh live Sessions differ from the exact prepared Session snapshot; stop before handoff.");
+  compareContinuityIdentities(saved.map((row) => ({ ...row,
+    provider_thread_id: row.provider_thread_id || row.provider_resume_id || null })),
+  baseline.sessions, { ...evidence, stage: "preparation" });
+  requireValue(new Set(ids).size === ids.length && baseline.sessions.every((row) => row.session_id &&
+    hasCompleteContinuityResumeIdentity(row) && !row.observation_error && Array.isArray(row.history_anchors)),
+  "preparation", "fresh_roster_complete", "Fresh Session resume/history identities are incomplete.");
+}
+
+export function bindFreshContinuityBaseline(path, operationId, baseline, restartId, restartState) {
+  const receipt = readContinuity(path, operationId);
+  requireValue((["PREPARED", "PACKAGE_SWITCHED"].includes(receipt.state) ||
+      (receipt.state === "RECOVERY_REQUIRED" && !receipt.restart_id)) && !receipt.restart_attempted,
+    "preparation", "fresh_roster_boundary", "The fresh live Sessions cannot change after restart begins.");
+  requireValue(baseline?.host?.pid === receipt.baseline.host.pid,
+    "preparation", "fresh_roster_identity", "Fresh live Sessions must come from the retained running Host.");
+  assertFreshContinuitySnapshot(baseline, restartId, restartState, { path, operationId });
+  requireValue(baseline.sessions.length <= 256, "preparation", "roster_limit", "Too many live Sessions for bounded continuity evidence.");
+  receipt.initial_baseline_digest ||= receipt.baseline_digest;
+  receipt.baseline = boundedBaseline(baseline);
+  receipt.baseline_digest = continuityDigest(receipt.baseline);
+  receipt.restart_id = restartId;
+  return writeContinuityAtomic(path, receipt);
+}
+
+// Stable releases that predate the explicit route-mode field still expose the
+// selected mode on their loopback health response. The target runner may bind
+// that value exactly once, while the original PID is still the sole listener
+// and before any restart attempt. This does not reinterpret a receipt after
+// handoff and cannot change a receipt that already declared its mode.
+export function bindLegacyContinuityConnectionMode(path, operationId, connectionMode, proof) {
+  const receipt = readContinuity(path, operationId);
+  requireValue(!Object.hasOwn(receipt.baseline.host, "connection_mode"),
+    "preparation", "connection_mode_already_bound", "Lifecycle route mode is already retained.");
+  requireValue(receipt.state === "PACKAGE_SWITCHED" && receipt.restart_attempted === false,
+    "preparation", "connection_mode_binding_boundary", "Legacy route mode must bind before the first restart attempt.");
+  requireValue(["cloud", "direct"].includes(connectionMode),
+    "preparation", "connection_mode_invalid", "Legacy Host route mode is invalid.");
+  requireValue(proof?.pid === receipt.baseline.host.pid &&
+    proof?.device_id === receipt.baseline.host.device_id && proof?.sole_listener === true,
+  "preparation", "connection_mode_live_identity", "Legacy route mode does not belong to the retained live Host.");
+  receipt.initial_baseline_digest ||= receipt.baseline_digest;
+  receipt.baseline.host.connection_mode = connectionMode;
+  receipt.baseline_digest = continuityDigest(receipt.baseline);
+  receipt.legacy_connection_mode_binding = {
+    connection_mode: connectionMode,
+    pid: proof.pid,
+    device_id: proof.device_id,
+    sole_listener: true,
+    observed_at: bounded(proof.observed_at),
+  };
+  return writeContinuityAtomic(path, receipt);
+}
+
+export function prepareContinuity({ path, operationId, source, target, baseline, operationRoot = null, transactionKind = "update", authority = {} }) {
+  requireValue(!existsSync(path), "receipt", "already_prepared", "Continuity operation is already prepared; recover that operation.");
+  requireValue(source?.version && target?.version && source?.runtime_identity_digest &&
+    source.runtime_identity_digest === target.runtime_identity_digest,
+  "preparation", "source_target_identity", "Source and target runtime identities must be complete and equal.");
+  requireValue(baseline?.host && Array.isArray(baseline.sessions) && baseline.captured_at,
+    "preparation", "fresh_live_sessions", "A fresh Host and dynamic Session baseline is required.");
+  requireValue(baseline.sessions.length <= 256, "preparation", "roster_limit", "Too many live Sessions for bounded continuity evidence.");
+  const ids = baseline.sessions.map((row) => row.session_id);
+  requireValue(ids.every(Boolean) && new Set(ids).size === ids.length,
+    "preparation", "unique_roster", "The fresh live Sessions have missing or duplicate identities.");
+  const retainedBaseline = boundedBaseline(baseline);
+  return publishDurableBoundary(path, writeContinuityAtomic(path, {
+    ...authority, schema: CONTINUITY_SCHEMA, operation_id: operationId, transaction_kind: transactionKind,
+    source, target, baseline: retainedBaseline, baseline_digest: continuityDigest(retainedBaseline), operation_root: operationRoot,
+    state: "PREPARED", restart_attempted: false, first_failure: null, qualifications: {},
+    transitions: [{ sequence: 1, state: "PREPARED", at: new Date().toISOString() }],
+  }));
+}
+
+export function advanceContinuity(path, operationId, state, evidence = {}) {
+  const receipt = readContinuity(path, operationId);
+  if (receipt.state === state) return receipt;
+  const currentIndex = CONTINUITY_STATES.indexOf(receipt.state);
+  const expected = currentIndex >= 0 ? CONTINUITY_STATES[currentIndex + 1] : null;
+  requireValue(expected === state, "receipt", "transition_order",
+    `Cannot advance lifecycle from ${receipt.state} to ${state}.`);
+  if (state === "COMMITTED") {
+    for (const required of ["HOST_QUALIFIED", "SESSIONS_QUALIFIED", "TUNNEL_QUALIFIED"]) {
+      requireValue(receipt.qualifications[required]?.passed === true,
+        "commit", "qualification_required", `${required} must pass before commit.`);
+    }
+  }
+  if (state.endsWith("_QUALIFIED")) {
+    requireValue(evidence.passed === true, "qualification", "positive_proof_required", `${state} requires positive proof.`);
+    receipt.qualifications[state] = evidence;
+  }
+  if (state === "COMMITTED") {
+    retireHostRestartRestoreState({ configDir: receipt.baseline.host.config_dir, restartId: receipt.restart_id });
+    receipt.snapshot_replay_retired_at = new Date().toISOString();
+    receipt.user_path_verification = continuityUserPathExpectation(
+      evidence.final_qualification?.tunnel || receipt.qualifications.TUNNEL_QUALIFIED
+    );
+  }
+  receipt.state = state;
+  receipt.transitions.push({ sequence: receipt.transitions.length + 1, state, at: new Date().toISOString(), evidence });
+  return publishDurableBoundary(path, writeContinuityAtomic(path, receipt));
+}
+
+export function recordContinuityRestartAttempt(path, operationId) {
+  const receipt = readContinuity(path, operationId);
+  requireValue(!["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state),
+    "restart", "terminal_operation", "A terminal operation cannot restart again.");
+  receipt.restart_attempted = true;
+  receipt.restart_attempted_at ||= new Date().toISOString();
+  return writeContinuityAtomic(path, receipt);
+}
+
+
+function continuityUserPathExpectation(tunnel) {
+  const verified = Boolean(tunnel?.host?.pid && tunnel.authenticated_user_path?.pid === tunnel.host.pid);
+  return { status: verified ? "verified" : "pending", origin: tunnel?.origin || null,
+    pid: tunnel?.host?.pid || null,
+    observed_at: verified ? tunnel.authenticated_user_path.observed_at || null : null };
+}
+
+export function recordContinuityRecovery(path, operationId, error, qualification = null) {
+  const receipt = readContinuity(path, operationId);
+  if (receipt.state === "ROLLED_BACK_HEALTHY") return receipt;
+  requireValue(!["COMMITTED", "CLEANED"].includes(receipt.state), "recovery", "already_committed", "A committed operation cannot roll back.");
+  const diagnostic = error?.lifecycle_diagnostic;
+  receipt.first_failure ||= {
+    stage: diagnostic?.stage || "recovery", check: diagnostic?.check || "transaction_failed",
+    code: error?.code || "p233_transaction_failed", message: sanitizeLifecycleDiagnostic(error?.message || String(error)),
+    restart_attempted: receipt.restart_attempted,
+    at: new Date().toISOString(),
+  };
+  const qualified = qualification?.host?.passed === true && qualification?.sessions?.passed === true && qualification?.tunnel?.passed === true;
+  if (qualified) {
+    retireHostRestartRestoreState({ configDir: receipt.baseline.host.config_dir, restartId: receipt.restart_id });
+    receipt.snapshot_replay_retired_at = new Date().toISOString();
+    receipt.user_path_verification = continuityUserPathExpectation(qualification.tunnel);
+  }
+  receipt.state = qualified ? "ROLLED_BACK_HEALTHY" : "RECOVERY_REQUIRED";
+  receipt.recovery_qualification = qualification;
+  receipt.transitions.push({ sequence: receipt.transitions.length + 1, state: receipt.state, at: new Date().toISOString() });
+  return writeContinuityAtomic(path, receipt);
+}
+
+export function assertContinuityFinalizable(path, operationId) {
+  const receipt = readContinuity(path, operationId);
+  requireValue(["COMMITTED", "CLEANED"].includes(receipt.state), "cleanup", "commit_required",
+    "Rollback resources are retained until the lifecycle receipt is COMMITTED.");
+  return receipt;
+}
+
+export function assertConfirmedUpdateTarget({ currentVersion, targetVersion, expectedCurrentVersion, expectedTargetVersion, source }) {
+  if (source !== "terminal") {
+    requireValue(expectedCurrentVersion === currentVersion && expectedTargetVersion === targetVersion,
+      "confirmation", "stale_target", "The confirmed update changed. Check for updates and confirm the exact version again.");
+  }
+  const comparison = compareOysterunSemver(targetVersion, currentVersion);
+  requireValue(comparison === 1, "confirmation", comparison === -1 ? "downgrade_rejected" : "no_newer_version",
+    "No newer Oysterun version is available. Reinstall and downgrade are not update operations.");
+  return { current_version: currentVersion, target_version: targetVersion };
+}
+
+export function qualifyContinuityHost(baseline, observed, { version, runtimeIdentityDigest, expectNewPid = true, definitionDigest }) {
+  requireValue(observed && observed.version === version, "host_qualification", "package_version", "Running Host version differs from the transaction target.");
+  requireValue(observed.runtime_identity_digest === runtimeIdentityDigest && /^v?22\./.test(observed.node_version),
+    "host_qualification", "node_identity", "Running Host Node 22 identity differs from the retained runtime.");
+  for (const key of ["device_id", "config_dir", "browser_root", "host_folder", "port", "stack", "managed_endpoint", "direct_host_url"]) {
+    requireValue(Object.hasOwn(baseline, key) && baseline[key] === observed[key],
+      "host_qualification", `host_${key}`, `Retained Host ${key} changed.`);
+  }
+  if (Object.hasOwn(baseline, "connection_mode")) {
+    requireValue(baseline.connection_mode === observed.connection_mode,
+      "host_qualification", "host_connection_mode", "Retained Host connection_mode changed.");
+  }
+  requireValue(Number.isInteger(observed.pid) && observed.pid > 0 && (!expectNewPid || observed.pid !== baseline.pid),
+    "host_qualification", "replacement_pid", "Expected one new Host process identity.");
+  if (baseline.package_root) {
+    requireValue(observed.package_root === baseline.package_root && observed.process_cwd === join(baseline.package_root, "host-service"),
+    "host_qualification", "running_package_path", "Running Host cwd/package does not match the retained active root.");
+  }
+  requireValue(observed.service_definition_sha256 === definitionDigest,
+    "host_qualification", "service_definition", "Service definition differs from the receipt-bound target.");
+  return { passed: true, pid: observed.pid, port: observed.port, version, runtime_identity_digest: runtimeIdentityDigest, service_definition_sha256: definitionDigest };
+}
+
+export function qualifyContinuitySessions(expected, observed, restoreResult, { requireRestore = true, path = null, operationId = null } = {}) {
+  compareContinuityIdentities(expected, observed, { path, operationId });
+  requireValue(Array.isArray(expected) && Array.isArray(observed), "session_qualification", "roster_missing", "Session qualification requires both exact live Sessions.");
+  if (requireRestore) {
+    qualifyContinuityRestoreResult(expected, restoreResult);
+  }
+  const observedIds = observed.map((row) => row.session_id);
+  requireValue(new Set(observedIds).size === observedIds.length, "session_qualification", "duplicate_runtime", "Duplicate live Session identity.");
+  requireValue(observed.length === expected.length, "session_qualification", "roster_changed", "Current live Sessions differ from the freshly retained live Sessions.");
+  for (const before of expected) {
+    const after = observed.find((row) => row.session_id === before.session_id);
+    requireValue(after, "session_qualification", "session_missing", `Session ${before.session_id} is missing.`);
+    requireValue(!after.observation_error, "session_qualification", after.observation_error || "session_observation",
+      `Session ${before.session_id} runtime/history observation failed.`);
+    requireValue(after.alive === true && after.ready === true && hasCompleteContinuityResumeIdentity(before),
+      "session_qualification", "runtime_not_ready", `Session ${before.session_id} has no ready resumed provider runtime.`);
+    if (requireRestore) {
+      const restored = restoreResult.restored.find((row) => row.session_id === before.session_id);
+      requireValue(restored?.restored_as_runtime === true && restored.prompt_replay === false,
+        "session_qualification", "runtime_restore_unproven", `Session ${before.session_id} was not restored without prompt replay.`);
+    }
+    requireValue(Array.isArray(before.history_anchors) && Array.isArray(after.history_anchors),
+      "session_qualification", "history_missing", `Session ${before.session_id} history proof is missing.`);
+    for (const anchor of before.history_anchors) {
+      requireValue(after.history_anchors.some((row) => row.event_id === anchor.event_id && row.sha256 === anchor.sha256),
+        "session_qualification", "history_anchor_changed", `Session ${before.session_id} lost or changed a committed history anchor.`);
+    }
+  }
+  return { passed: true, expected_count: expected.length, session_ids: expected.map((row) => row.session_id), prompt_replay: false, restore_required: requireRestore };
+}
+
+export function qualifyContinuityRestoreResult(expected, restoreResult) {
+  requireValue(Array.isArray(expected), "session_qualification", "roster_missing",
+    "Session restore qualification requires the exact source Sessions.");
+  requireValue(restoreResult && Array.isArray(restoreResult.restored) &&
+    Array.isArray(restoreResult.failed) && Array.isArray(restoreResult.skipped),
+  "session_qualification", "restore_result_missing", "Consumed state has no complete Session restore result.");
+  const expectedIds = new Set(expected.map((row) => row.session_id));
+  const unresolvedSkipped = restoreResult.skipped.filter((row) =>
+    expectedIds.has(row.session_id) || row.reason !== "not_live_or_ready_before_restart");
+  requireValue(restoreResult.failed.length === 0 && unresolvedSkipped.length === 0,
+    "session_qualification", "restore_incomplete", "Session restore contains unresolved failed or skipped Sessions.");
+  for (const before of expected) {
+    const restored = restoreResult.restored.find((row) => row.session_id === before.session_id);
+    requireValue(restored?.restored_as_runtime === true && restored.prompt_replay === false,
+      "session_qualification", "runtime_restore_unproven", `Session ${before.session_id} was not restored without prompt replay.`);
+  }
+  return { passed: true, expected_count: expected.length };
+}
+
+export function qualifyContinuityTunnel(expected, observed) {
+  requireValue(expected?.origin && observed?.origin === expected.origin && observed.device_id === expected.device_id,
+    "tunnel_qualification", "route_identity", "Existing authenticated Host route identity changed.");
+  requireValue(observed.authenticated === true && observed.http_status === 200 && observed.operation_id === expected.operation_id,
+    "tunnel_qualification", "authenticated_path", "The existing authenticated user route has not qualified for this operation.");
+  return { passed: true, ...observed };
+}
+
+// Internal single-restart marker. This is not a new public Oysterun command.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [action, path, operationId, ...extra] = process.argv.slice(2);
+  if (action !== "mark-restart" || !path || !operationId || extra.length) {
+    throw new Error("Usage: lifecycle-continuity.mjs mark-restart <absolute-receipt> <operation-id>");
+  }
+  recordContinuityRestartAttempt(path, operationId);
+}

package/host-service/lifecycle-service-render-bundle.mjs

@@ -0,0 +1,120 @@
+// P226 render-bundle construction, extracted without changing its invariants.
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { buildNodeNpmChildEnvironment } from "./node-npm-runtime-identity.mjs";
+import { sanitizeLifecycleDiagnostic } from "./lifecycle-diagnostics.mjs";
+
+export function getServiceDefinitionIdentity({ stackName, configDir: inputConfigDir, homeDir = homedir() }) {
+  const production = stackName === "production";
+  const configDir = resolve(inputConfigDir);
+  const stackRoot = production ? configDir : dirname(configDir);
+  const logDir = production ? join(configDir, "logs") : join(stackRoot, "logs");
+  const serviceLabel = production ? "com.oysterun.host" : `com.oysterun.host.${stackName}`;
+  const stackKind = ["production", "staging", "test1", "test2", "test3", "test4"].includes(stackName)
+    ? "preset"
+    : "custom";
+  return {
+    production,
+    configDir,
+    stackRoot,
+    logDir,
+    hostLog: join(logDir, stackKind === "custom" ? `oysterun-host-${stackName}.log` : "oysterun-host.log"),
+    serviceLabel,
+    stackKind,
+    definitionPath: join(homeDir, "Library", "LaunchAgents", `${serviceLabel}.plist`),
+  };
+}
+
+function resolveFrozenProviderLaunchPath({ toolchain, packageRoot, configPath, environment }) {
+  const result = spawnSync(
+    toolchain.node_path,
+    [
+      join(packageRoot, "host-service", "provider-command-detection.mjs"),
+      "--print-launch-path",
+      "--config-path",
+      configPath,
+      "--node-bin",
+      toolchain.node_path,
+    ],
+    {
+      cwd: packageRoot,
+      env: buildNodeNpmChildEnvironment(toolchain, environment),
+      encoding: "utf8",
+      stdio: "pipe",
+    }
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`target provider resolution failed: ${sanitizeLifecycleDiagnostic(result.stderr || result.stdout)}`);
+  }
+  const pathEntries = String(result.stdout || "").trim().split(":").filter(Boolean);
+  if (pathEntries.length === 0) throw new Error("target provider resolution returned an empty PATH");
+  return pathEntries;
+}
+
+export function buildServiceRenderBundle({
+  toolchain,
+  stackName,
+  registry,
+  packageRoot, packageVersion, configDir, configPath, port,
+  environment = process.env, homeDir = homedir(),
+}) {
+  const identity = getServiceDefinitionIdentity({ stackName, configDir, homeDir });
+  const manifestRaw = readFileSync(join(packageRoot, "package.json"), "utf8");
+  const manifest = JSON.parse(manifestRaw);
+  const versionOwned = manifest.oysterun_service_definition || {};
+  return {
+    schema_version: 1,
+    artifact: {
+      package_root: resolve(packageRoot),
+      package_realpath: realpathSync(packageRoot),
+      package_version: packageVersion,
+      integrity_sha256: createHash("sha256").update(manifestRaw).digest("hex"),
+    },
+    host: {
+      launch_domain: `gui/${process.getuid?.() ?? 0}`,
+      user: environment.USER || "unknown",
+      stack_name: stackName,
+      port,
+      config_dir: identity.configDir,
+      stack_root: identity.stackRoot,
+      log_dir: identity.logDir,
+      host_log: identity.hostLog,
+      service_label: identity.serviceLabel,
+      stack_kind: identity.stackKind,
+      production: identity.production,
+    },
+    runtime: {
+      node_path: toolchain.node_path,
+      node_realpath: toolchain.node_realpath,
+      node_version: toolchain.node_version,
+      node_abi: toolchain.node_abi,
+      npm_cli_path: toolchain.npm_cli_path,
+      npm_cli_realpath: toolchain.npm_cli_realpath,
+      npm_version: toolchain.npm_version,
+      platform: toolchain.platform,
+      architecture: toolchain.architecture,
+      toolchain_identity_digest: toolchain.toolchain_identity_digest,
+    },
+    update: {
+      registry_authority: registry.source,
+      registry_url: registry.override_active ? registry.url : null,
+      state_path: environment.OYSTERUN_UPDATE_REGISTRY_STATE_PATH || null,
+    },
+    provider_resolution: {
+      path_entries: resolveFrozenProviderLaunchPath({ toolchain, packageRoot, configPath, environment }),
+      environment: {},
+    },
+    version_owned: {
+      environment: versionOwned.environment || {},
+      top_level: versionOwned.top_level || {},
+      run_at_load: versionOwned.run_at_load ?? true,
+      keep_alive: versionOwned.keep_alive ?? true,
+      throttle_interval: versionOwned.throttle_interval ?? 10,
+    },
+  };
+}
+

package/host-service/lifecycle-user-path.mjs

@@ -0,0 +1,34 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { readContinuity, writeContinuityAtomic } from "./lifecycle-continuity.mjs";
+
+// Ordinary Dashboard authentication supplements a completed transaction. Keep
+// this evidence separate so it cannot race a runner's receipt/projection write,
+// reacquire mutation authority, or compare today's roster with an old snapshot.
+export function readContinuityUserPath(path, receipt) {
+  const expected = receipt.user_path_verification;
+  if (!expected || expected.status === "verified") return expected || null;
+  const evidencePath = `${path}.user-path`;
+  try {
+    if (!existsSync(evidencePath)) return expected;
+    const stat = lstatSync(evidencePath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) return expected;
+    const proof = JSON.parse(readFileSync(evidencePath, "utf8"));
+    if (proof.operation_id === receipt.operation_id && proof.baseline_digest === receipt.baseline_digest &&
+        proof.origin === expected.origin && proof.pid === expected.pid &&
+        proof.status === "verified" && Number.isFinite(Date.parse(proof.observed_at))) return proof;
+  } catch { /* Missing supplementary evidence does not reopen a transaction. */ }
+  return expected;
+}
+
+export function recordContinuityUserPath(path, operationId, { origin, pid, observed_at }) {
+  const receipt = readContinuity(path, operationId);
+  const expected = readContinuityUserPath(path, receipt);
+  if (!["COMMITTED", "CLEANED", "ROLLED_BACK_HEALTHY"].includes(receipt.state) ||
+      !receipt.snapshot_replay_retired_at || expected?.status !== "pending" ||
+      expected.origin !== origin || expected.pid !== pid || !Number.isFinite(Date.parse(observed_at))) return false;
+  writeContinuityAtomic(`${path}.user-path`, {
+    operation_id: operationId, baseline_digest: receipt.baseline_digest,
+    status: "verified", origin, pid, observed_at,
+  });
+  return true;
+}