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

package/host-service/lifecycle-compat-preload.mjs

@@ -0,0 +1,89 @@
+// Host-only observation; lifecycle children receive only the exact renderer
+// bridge. Provider children receive neither NODE_OPTIONS nor this observer.
+import { channel } from 'node:diagnostics_channel';
+import { registerHooks, syncBuiltinESMExports } from 'node:module';
+import childProcess from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readCompatibility, assertCompatibilityProcess } from './lifecycle-compatibility.mjs';
+import { readContinuity } from './lifecycle-continuity.mjs';
+import { ensureContinuityProbeGrant, fetchContinuityObservation, removeContinuityProbeGrant } from './lifecycle-continuity-probe.mjs';
+import { readContinuityUserPath, recordContinuityUserPath } from './lifecycle-user-path.mjs';
+
+export function installResponseObserver(bound, dependencies = {}) {
+  const d = bound.descriptor;
+  const observe = dependencies.observe || fetchContinuityObservation;
+  const responseChannel = dependencies.channel || channel('http.server.response.finish');
+  let active = true, inFlight = false;
+  const unsubscribe = () => { active = false; responseChannel.unsubscribe(onResponse); };
+  async function onResponse({ request }) {
+    if (!active || inFlight || !request || /^\/(health|admin\/lifecycle-qualification)(?:\?|$)/.test(request.url || '')) return;
+    inFlight = true;
+    try {
+      readCompatibility(bound.path); // Changed descriptor/dependencies never authorize evidence.
+      const receipt = readContinuity(d.receipt_path, d.operation_id);
+      const expected = readContinuityUserPath(d.receipt_path, receipt);
+      if (!['COMMITTED','CLEANED','ROLLED_BACK_HEALTHY'].includes(receipt.state) || !receipt.snapshot_replay_retired_at) return;
+      if (expected?.status === 'verified') { removeContinuityProbeGrant(d.config_dir, d.observation_id); unsubscribe(); return; }
+      if (expected?.status !== 'pending' || expected.pid !== process.pid || expected.origin !== d.origin) return;
+      ensureContinuityProbeGrant(d.config_dir, d.observation_id);
+      const observation = await observe({ configDir: d.config_dir, operationId: d.observation_id, origin: d.origin, timeoutMs: 5000 });
+      const proof = observation.authenticated_user_path;
+      const observedOrigin = new URL(observation.host.managed_endpoint || observation.host.direct_host_url || `http://127.0.0.1:${observation.host.port}`).origin;
+      if (observedOrigin !== d.origin || observation.host.version !== receipt.source.version ||
+          observation.host.pid !== process.pid || observation.host.config_dir !== d.config_dir ||
+          observation.host.package_root !== d.package_root || observation.host.runtime_identity_digest !== d.runtime_identity_digest ||
+          observation.host.service_definition_sha256 !== d.definition_sha256 || observation.route.origin !== d.origin ||
+          observation.route.operation_id !== d.observation_id || !proof || proof.pid !== process.pid) return;
+      // The old Host selects its configured route Map entry; no Dashboard auth
+      // is performed by this request. This function only writes the sidecar.
+      if (recordContinuityUserPath(d.receipt_path, d.operation_id, { ...proof, origin: d.origin })) {
+        removeContinuityProbeGrant(d.config_dir, d.observation_id);
+        unsubscribe();
+      }
+    } catch { /* One failed event stays pending. No retry timer or mutation. */ }
+    finally { inFlight = false; }
+  }
+  responseChannel.subscribe(onResponse);
+  return { unsubscribe, state: () => ({ active, inFlight }) };
+}
+
+export function installLifecycleChildBridge(bound) {
+  const d = bound.descriptor;
+  const allowed = new Set(['preflight_oysterun_restart.sh', 'oysterun_update_restart_runner.mjs', 'install_oysterun_update.mjs']
+    .map(name => join(d.package_root, 'tool_scripts', name)));
+  for (const key of ['spawn', 'spawnSync']) {
+    const original = childProcess[key];
+    childProcess[key] = function(command, args, options) {
+      if (Array.isArray(args) && allowed.has(args[0]) && options?.cwd === d.package_root &&
+          options.env?.OYSTERUN_CONFIG_DIR === d.config_dir &&
+          (command === '/bin/bash' || command === d.node_realpath)) {
+        readCompatibility(bound.path);
+        options = { ...options, env: { ...options.env, NODE_OPTIONS: d.preload } };
+      }
+      return original.call(this, command, args, options);
+    };
+  }
+  syncBuiltinESMExports();
+}
+
+if (process.env.NODE_OPTIONS?.includes(import.meta.url)) {
+  const bound = readCompatibility(join(dirname(fileURLToPath(import.meta.url)), 'descriptor.json'));
+  const d = bound.descriptor;
+  const bridges = new Map(['service-definition-migration.mjs', 'lifecycle-continuity-projection.mjs'].map(name =>
+    [pathToFileURL(join(d.package_root, 'host-service', name)).href, pathToFileURL(join(bound.root, name)).href]));
+  registerHooks({ resolve(specifier, context, nextResolve) {
+    const result = nextResolve(specifier, context);
+    const bridged = bridges.get(result.url.split('?')[0]);
+    if (bridged) return { ...result, url: bridged, shortCircuit: true };
+    return result;
+  } });
+  if (resolve(process.argv[1] || '') === join(d.package_root, 'host-service/server.mjs')) {
+    assertCompatibilityProcess(bound);
+    delete process.env.NODE_OPTIONS;
+    // fork inherits execArgv as well as env. The observer must never propagate.
+    process.execArgv = process.execArgv.filter(arg => !arg.includes('lifecycle-compat-preload.mjs'));
+    installLifecycleChildBridge(bound);
+    installResponseObserver(bound);
+  }
+}

package/host-service/lifecycle-compatibility.mjs

@@ -0,0 +1,164 @@
+// Receipt-bound executable dependency for a restored pre-P267 Host. The pointer
+// selects an immutable descriptor; it is never an active mutation operation.
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, mkdirSync, writeFileSync, rmSync, symlinkSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve, relative } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readContinuity, continuityReceiptPath, prepareContinuity, writeContinuityAtomic, writeContinuityBytesAtomic } from './lifecycle-continuity.mjs';
+import { createContinuityProbeGrant } from './lifecycle-continuity-probe.mjs';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => { throw new Error(`p267_compatibility: ${message}`); };
+export const compatibilityPointer = config => join(resolve(config), 'lifecycle-compatibility.json');
+const names = ['lifecycle-compatibility.mjs', 'lifecycle-compat-preload.mjs', 'lifecycle-compat-cli.mjs',
+  'service-definition-migration.mjs', 'lifecycle-continuity.mjs', 'lifecycle-continuity-probe.mjs',
+  'lifecycle-user-path.mjs', 'lifecycle-continuity-projection.mjs', 'restart-restore-state.mjs', 'npm-update-policy.mjs', 'lifecycle-diagnostics.mjs'];
+function bytes(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail('dependency must be a regular file');
+  return readFileSync(path);
+}
+export function readCompatibility(path, seen = new Set()) {
+  if (seen.has(path)) fail('cyclic predecessor');
+  seen.add(path);
+  const descriptor = JSON.parse(bytes(path));
+  const d = descriptor;
+  if (d.schema !== 'oysterun.lifecycle_compatibility.v1' ||
+      path !== join(resolve(d.config_dir), 'lifecycle-compat', d.operation_id, 'descriptor.json') ||
+      d.receipt_path !== continuityReceiptPath(d.config_dir, d.operation_id)) fail('descriptor geometry');
+  const receipt = readContinuity(d.receipt_path, d.operation_id);
+  if (receipt.compatibility?.descriptor_path !== path || receipt.compatibility.sha256 !== hash(bytes(path)) ||
+      receipt.source.service_definition_sha256 !== d.source_definition_sha256 ||
+      receipt.baseline.host.package_root !== d.package_root || receipt.baseline.host.config_dir !== d.config_dir ||
+      receipt.baseline.host.stack !== d.stack || receipt.source.runtime_identity_digest !== d.runtime_identity_digest)
+    fail('descriptor receipt binding');
+  if (lstatSync(dirname(path)).isSymbolicLink()) fail('dependency directory symlink');
+  const inventory = Object.keys(d.files).sort().join();
+  const currentInventory = [...names, 'compatible-definition.json'].sort().join();
+  const rendererOnlyInventory = [...names.filter(name => name !== 'lifecycle-continuity-projection.mjs'), 'compatible-definition.json'].sort().join();
+  // A preceding receipt may retain the renderer-only closure. Its exact bytes
+  // remain bound; a new descriptor always retains the complete current closure.
+  if (inventory !== currentInventory && inventory !== rendererOnlyInventory) fail('dependency inventory');
+  for (const [name, digest] of Object.entries(d.files)) if (hash(bytes(join(dirname(path), name))) !== digest) fail(`changed dependency ${name}`);
+  if (d.predecessor) {
+    const prior = readCompatibility(d.predecessor.descriptor_path, seen);
+    if (hash(bytes(prior.path)) !== d.predecessor.sha256 || prior.descriptor.config_dir !== d.config_dir ||
+        prior.descriptor.definition_sha256 !== d.source_definition_sha256) fail('predecessor binding');
+  }
+  const definition = JSON.parse(bytes(join(dirname(path), 'compatible-definition.json')));
+  if (hash(definition.bytes) !== d.definition_sha256 || definition.sha256 !== d.definition_sha256) fail('definition identity');
+  return { descriptor: d, receipt, definition, path, root: dirname(path) };
+}
+export function readInstalledCompatibility(configDir) {
+  const pointer = compatibilityPointer(configDir);
+  if (!existsSync(pointer)) return null;
+  const selected = JSON.parse(bytes(pointer));
+  const bound = readCompatibility(selected.descriptor_path);
+  if (bound.descriptor.config_dir !== resolve(configDir) || hash(bytes(bound.path)) !== selected.sha256) fail('installed pointer binding');
+  return bound;
+}
+export function compatibilityRender(base, bundle) {
+  const bound = readInstalledCompatibility(bundle.host.config_dir);
+  if (!bound || bundle.artifact.package_root !== bound.descriptor.package_root ||
+      bundle.artifact.integrity_sha256 !== bound.descriptor.manifest_sha256) return base;
+  if (base.sha256 !== bound.descriptor.source_render_sha256 ||
+      bundle.runtime.toolchain_identity_digest !== bound.descriptor.runtime_identity_digest ||
+      bundle.host.stack_name !== bound.descriptor.stack) fail('canonical source render changed');
+  return bound.definition;
+}
+export function prepareCompatibility({ path, operationId, render }) {
+  let receipt = readContinuity(path, operationId);
+  if (receipt.compatibility) return readCompatibility(receipt.compatibility.descriptor_path);
+  if (['COMMITTED','CLEANED','ROLLED_BACK_HEALTHY'].includes(receipt.state)) fail('cannot add authority after closeout');
+  if (!receipt.resources || !receipt.source.definition_snapshot_digest) return null;
+  const source = existsSync(receipt.resources.previous_package_root) ? receipt.resources.previous_package_root : receipt.resources.active_package_root;
+  if (existsSync(join(source, 'host-service/lifecycle-user-path.mjs'))) return null;
+  const snapshot = JSON.parse(bytes(receipt.resources.service_definition_snapshot_path));
+  if (!snapshot.existed) return null; // No installed service dependency to extend.
+  const bundle = JSON.parse(bytes(receipt.resources.source_service_render_bundle_path));
+  const original = render(bundle, { compatibility: false });
+  const installed = readInstalledCompatibility(receipt.baseline.host.config_dir);
+  if ((original.sha256 !== snapshot.sha256 && installed?.definition.sha256 !== snapshot.sha256) ||
+      snapshot.sha256 !== receipt.source.service_definition_sha256) fail('source render/snapshot differs');
+  const config = receipt.baseline.host.config_dir;
+  const root = join(config, 'lifecycle-compat', operationId);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const files = {};
+  for (const name of names) {
+    const data = bytes(join(dirname(fileURLToPath(import.meta.url)), name));
+    writeFileSync(join(root, name), data, { mode: name === 'lifecycle-compat-cli.mjs' ? 0o700 : 0o600 });
+    files[name] = hash(data);
+  }
+  const preload = `--import=${pathToFileURL(join(root, 'lifecycle-compat-preload.mjs')).href}`;
+  if (bundle.version_owned.environment.NODE_OPTIONS) fail('source already has Node loader options');
+  const definition = render({ ...bundle, version_owned: { ...bundle.version_owned,
+    environment: { ...bundle.version_owned.environment, NODE_OPTIONS: preload } } }, { compatibility: false });
+  const defBytes = JSON.stringify(definition);
+  writeFileSync(join(root, 'compatible-definition.json'), defBytes, { mode: 0o600 });
+  files['compatible-definition.json'] = hash(defBytes);
+  const observationId = `p267-observation-${operationId}`;
+  const observationPath = continuityReceiptPath(config, observationId);
+  if (!existsSync(observationPath)) prepareContinuity({ path: observationPath, operationId: observationId, source: receipt.source, target: receipt.source,
+    baseline: { ...receipt.baseline, sessions: [] }, authority: { purpose: 'supplementary_read_only_observation', parent_operation_id: operationId } });
+  if (!existsSync(`${observationPath}.probe`)) createContinuityProbeGrant(config, observationId);
+  const d = { schema: 'oysterun.lifecycle_compatibility.v1', operation_id: operationId,
+    receipt_path: path, config_dir: config, package_root: receipt.baseline.host.package_root,
+    stack: receipt.baseline.host.stack, port: receipt.baseline.host.port,
+    source_definition_sha256: snapshot.sha256, source_render_sha256: original.sha256, definition_path: snapshot.definition_path,
+    definition_sha256: definition.sha256, manifest_sha256: hash(bytes(join(source, 'package.json'))),
+    runtime_identity_digest: receipt.source.runtime_identity_digest, node_realpath: bundle.runtime.node_realpath,
+    origin: new URL(receipt.baseline.host.managed_endpoint || receipt.baseline.host.direct_host_url || `http://127.0.0.1:${receipt.baseline.host.port}`).origin,
+    observation_id: observationId, observation_path: observationPath, preload, files,
+    predecessor: installed?.definition.sha256 === snapshot.sha256
+      ? { descriptor_path: installed.path, sha256: hash(bytes(installed.path)) } : null };
+  const descriptorPath = join(root, 'descriptor.json');
+  writeContinuityAtomic(descriptorPath, d);
+  receipt = { ...receipt, compatibility: { descriptor_path: descriptorPath, sha256: hash(bytes(descriptorPath)) } };
+  writeContinuityAtomic(path, receipt);
+  return readCompatibility(descriptorPath);
+}
+export function installCompatibility(bound) {
+  // Caller already validated the source/target pair before restoring source.
+  const { descriptor: d, definition } = readCompatibility(bound.path);
+  if (hash(bytes(d.definition_path)) !== d.source_definition_sha256) fail('install requires exact restored source definition');
+  writeContinuityBytesAtomic(d.definition_path, definition.bytes, { mode: 0o644 });
+  writeContinuityAtomic(compatibilityPointer(d.config_dir), { descriptor_path: bound.path, sha256: hash(bytes(bound.path)) });
+  const cli = join(resolve(d.package_root, '../../..'), 'bin/oysterun');
+  rmSync(cli, { force: true });
+  symlinkSync(relative(dirname(cli), join(bound.root, 'lifecycle-compat-cli.mjs')), cli);
+}
+export function compatibilityEnvironment(configDir, environment) {
+  if (!configDir) return environment;
+  const bound = readInstalledCompatibility(configDir);
+  if (!bound) return environment;
+  if (hash(bytes(bound.descriptor.definition_path)) !== bound.descriptor.definition_sha256) return environment;
+  return { ...environment, NODE_OPTIONS: bound.descriptor.preload };
+}
+export function assertCompatibilityProcess(bound) {
+  const d = bound.descriptor;
+  if (realpathSync(process.execPath) !== d.node_realpath || resolve(process.env.OYSTERUN_CONFIG_DIR || '') !== d.config_dir ||
+      hash(bytes(join(d.package_root, 'package.json'))) !== d.manifest_sha256 ||
+      hash(bytes(d.definition_path)) !== d.definition_sha256) fail('running Host identity');
+}
+
+export function retireUnusedCompatibility(configDir, { isAlive = pid => {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+} } = {}) {
+  const bound = readInstalledCompatibility(configDir);
+  if (!bound) return false;
+  const d = bound.descriptor;
+  if (hash(bytes(d.definition_path)) === d.definition_sha256) return false;
+  const chain = [bound];
+  while (chain.at(-1).descriptor.predecessor) chain.push(readCompatibility(chain.at(-1).descriptor.predecessor.descriptor_path));
+  // File replacement alone is not proof that launchd's loaded dependency died.
+  for (const entry of chain) {
+    const priorPid = entry.receipt.user_path_verification?.pid;
+    if (!Number.isInteger(priorPid) || isAlive(priorPid)) return false;
+  }
+  rmSync(compatibilityPointer(configDir));
+  for (const entry of chain) {
+    rmSync(`${entry.descriptor.observation_path}.probe`, { force: true });
+    rmSync(entry.descriptor.observation_path, { force: true });
+    rmSync(entry.root, { recursive: true });
+  }
+  return true;
+}

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

@@ -0,0 +1,222 @@
+import {
+  chmodSync, 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";
+
+import { readCompatibility, installCompatibility, retireUnusedCompatibility } from "./lifecycle-compatibility.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.`);
+  }
+  const definitionBindings = [
+    r.service_definition_path,
+    r.service_definition_authority_path,
+    r.service_definition_snapshot_path,
+  ];
+  const absentDefinitionBindings = definitionBindings.every((value) => value === null);
+  const partialDefinitionBindings = definitionBindings.some((value) => value === null) &&
+    !absentDefinitionBindings;
+  const absentDefinitionGeometry = receipt.baseline.host.service_definition_sha256 === "absent" &&
+    receipt.source.service_definition_sha256 === "absent" &&
+    receipt.target.service_definition_sha256 === "absent";
+  if (partialDefinitionBindings || (absentDefinitionBindings && !absentDefinitionGeometry)) {
+    fail("definition_binding", "Recovery definition/authority differs from the retained Host binding.");
+  }
+  if (!absentDefinitionBindings) {
+    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, absent_service_definition_bindings: absentDefinitionBindings };
+}
+
+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 });
+}
+
+function preserveCopiedPackageModes(source, target) {
+  const sourceStat = lstatSync(source);
+  const targetStat = lstatSync(target);
+  if (sourceStat.isSymbolicLink()) {
+    if (!targetStat.isSymbolicLink()) fail("restore_copy_kind", "Prepared rollback package changed a symlink boundary.");
+    return;
+  }
+  if (sourceStat.isDirectory() !== targetStat.isDirectory() ||
+      sourceStat.isFile() !== targetStat.isFile()) {
+    fail("restore_copy_kind", "Prepared rollback package changed a file boundary.");
+  }
+  chmodSync(target, sourceStat.mode & 0o777);
+  if (sourceStat.isDirectory()) {
+    for (const name of readdirSync(source)) {
+      preserveCopiedPackageModes(join(source, name), join(target, name));
+    }
+  }
+}
+
+// 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.
+  let snapshot = null;
+  let rendered = null;
+  if (!r.absent_service_definition_bindings) {
+    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 compatible = receipt.compatibility ? readCompatibility(receipt.compatibility.descriptor_path) : null;
+    const liveDigest = existsSync(r.service_definition_path) ? continuityDigest(readFileSync(r.service_definition_path)) : null;
+    rendered = { sha256: compatible && liveDigest === compatible.descriptor.definition_sha256
+      ? compatible.descriptor.definition_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 (key === "service_authority" && r.absent_service_definition_bindings) {
+      if (binding && (
+        binding.path !== null ||
+        binding.saved_path !== r.saved_service_definition_authority_path ||
+        binding.existed !== false ||
+        binding.mode !== null ||
+        binding.sha256 !== null
+      )) fail("definition_binding", "Absent service-definition geometry retained an unexpected authority file binding.");
+      continue;
+    }
+    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 });
+      // Node's recursive copy applies the process umask to directories on
+      // Linux. Restore the receipt-bound mode bits before hashing the copy;
+      // never relax the package digest to accommodate that platform detail.
+      preserveCopiedPackageModes(r.previous_package_root, prepared);
+    }
+    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);
+  if (!r.absent_service_definition_bindings) {
+    restoreServiceDefinitionSnapshot({ definitionPath: r.service_definition_path, snapshot, rendered });
+  }
+  for (const binding of bindings) restoreRetainedFile(binding);
+  if (receipt.compatibility) installCompatibility(readCompatibility(receipt.compatibility.descriptor_path));
+  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);
+  retireUnusedCompatibility(configDir);
+  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,29 @@
+import { readContinuityUserPath } from "./lifecycle-user-path.mjs";
+// 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 userPath = readContinuityUserPath(operation.continuity_path, receipt);
+  const routeMessage = userPath?.status === "pending"
+    ? " Ordinary login verification is pending; Sessions are available."
+    : " Authenticated login path verified.";
+  const common = { ...operation, continuity_state: receipt.state,
+    user_path_verification: userPath,
+    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: (restartOnly ? "Host restart complete; Host and Sessions are healthy."
+      : recovered ? "Update failed; prior Host and Sessions are restored and usable."
+      : "Host and Sessions are healthy; automatic update checks and cleanup complete.") + routeMessage,
+    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,
+  };
+}