@or3/cloud 0.1.67 → 0.1.68

package/dist/cli.mjs

@@ -31,10 +31,10 @@ import { fileURLToPath } from "node:url";
 import { createGunzip } from "node:zlib";
 var execFile = promisify(execFileCallback);
 var PACKAGE_ROOT = resolve(fileURLToPath(new URL("../", import.meta.url)));
-var PACKAGE_VERSION = "0.1.67";
+var PACKAGE_VERSION = "0.1.68";
 var IMAGE_REPOSITORY = "ghcr.io/saluana/or3-chat";
 var ASSET_ROOT = resolve(fileURLToPath(new URL("../assets/", import.meta.url)));
-var STATE_SCHEMA_VERSION = 1;
+var LEGACY_STATE_SCHEMA_VERSION = 1;
 var DEFAULT_PORT = 3000;
 var DEEP_HEALTH_TIMEOUT_MS = 180000;
 var COMMAND_TIMEOUT_MS = 180000;
@@ -70,6 +70,21 @@ var DEPLOYMENT_ENV_KEYS = [
   "OR3_PUBLIC_DOMAIN"
 ];
 var DEPLOYMENT_ID_ENV_KEY = "OR3_DEPLOYMENT_ID";
+function emitOperationResult(outcome) {
+  console.log(JSON.stringify({ schemaVersion: 1, kind: "or3-operation-result", outcome }, null, 2));
+}
+var STATE_SCHEMA_COMPATIBILITY = {
+  1: { readers: ["bridge", "schema-2"], writer: "migrating", mutable: false },
+  2: { readers: ["bridge", "schema-2"], writer: "schema-2", mutable: true }
+};
+var MAX_SUPPORTED_STATE_SCHEMA = 2;
+var READER_SUPPORTED_STATE_SCHEMAS = [1, 2];
+function assertKnownStateSchema(schemaVersion) {
+  if (schemaVersion !== 1 && schemaVersion !== 2) {
+    throw new Error(`Unsupported managed state schema ${String(schemaVersion)}. This CLI reads schemas 1 and 2. Run a compatible exact-version @or3/cloud CLI for this deployment instead of editing managed state.`);
+  }
+}
+var lifecycleFaults = {};
 var PROCESS_ENV_PASSTHROUGH = [
   "PATH",
   "HOME",
@@ -201,22 +216,25 @@ function parseFlags(argv) {
 }
 var COMMAND_FLAGS = {
   init: ["local", "public", "domain", "admin-email", "admin-password", "admin-password-file", "port"],
-  update: ["to"],
-  backup: ["keep", "force", "yes"],
+  update: ["to", "dry-run", "json"],
+  backup: ["keep", "force", "yes", "json"],
   restore: ["yes"],
   rollback: ["yes"],
   doctor: [],
-  verify: ["public", "verification-email", "verification-password-file"],
-  recover: [],
+  verify: ["public", "verification-email", "verification-password-file", "read-only", "json"],
+  recover: ["dry-run", "finish", "restore", "yes", "json"],
   adopt: ["from"],
   credentials: ["yes", "owner-password", "owner-password-file", "admin-password", "admin-password-file"],
-  status: [],
+  status: ["json"],
   logs: ["tail"],
   start: [],
   stop: [],
   restart: [],
   remove: ["purge-data", "yes"]
 };
+function verifyIsReadOnly(flags) {
+  return flags["read-only"] === true;
+}
 function assertCommandFlags(command, flags) {
   const allowed = new Set(["help", ...COMMAND_FLAGS[command] ?? []]);
   const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
@@ -262,6 +280,15 @@ function requireStringFlag(flags, key) {
 function isVersion(value) {
   return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 }
+function compareReleaseVersions(left, right) {
+  const leftParts = left.split("-", 1)[0].split(".").map(Number);
+  const rightParts = right.split("-", 1)[0].split(".").map(Number);
+  for (let index = 0;index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index])
+      return leftParts[index] > rightParts[index] ? 1 : -1;
+  }
+  return 0;
+}
 function imageFor(version) {
   if (!isVersion(version))
     throw new Error(`Invalid release version "${version}".`);
@@ -329,6 +356,7 @@ function commandEnvironment(command, args, cwd, supplied) {
 }
 async function run(command, args, cwd, environment) {
   const printable = `${command} ${args.map(quote).join(" ")}`;
+  await lifecycleFaults.beforeCommand?.(command, args);
   try {
     const result = await execFile(command, args, {
       cwd,
@@ -478,6 +506,7 @@ function deploymentPaths(directory) {
     operations: join(cloud, "operations"),
     backups: join(cloud, "backups"),
     exports: join(cloud, "exports"),
+    lastOperation: join(cloud, "last-operation.json"),
     lease: join(cloud, "operation-lease"),
     backupAuthKey: join(cloud, "backup-auth.key"),
     operatorIpc: join(cloud, "operator-ipc")
@@ -530,14 +559,17 @@ async function assertBackupAuthentication(directory, backupPath, manifestContent
 async function readState(directory) {
   const paths = deploymentPaths(directory);
   const parsed = JSON.parse(await readText(paths.state));
-  if (parsed.schemaVersion !== STATE_SCHEMA_VERSION || !parsed.appVersion || !parsed.image || !parsed.composeProject) {
+  assertKnownStateSchema(parsed.schemaVersion);
+  if (!parsed.appVersion || !parsed.image || !parsed.composeProject || !parsed.mode) {
     throw new Error(`Invalid managed state at ${paths.state}. Run "npx @or3/cloud doctor" for diagnostics.`);
   }
   return parsed;
 }
 async function writeState(directory, state) {
+  await lifecycleFaults.beforeStateWrite?.();
   await writeSecure(deploymentPaths(directory).state, `${JSON.stringify(state, null, 2)}
 `);
+  await lifecycleFaults.afterStateWrite?.();
 }
 async function readDirectoryEmpty(directory) {
   try {
@@ -883,8 +915,10 @@ function containerNodeCommand(script) {
   return ["sh", "-c", CONTAINER_NODE_SHELL, "or3-node", script];
 }
 async function waitForDeepHealthWithArgs(composeCommand, directory, secrets = []) {
-  const deadline = Date.now() + DEEP_HEALTH_TIMEOUT_MS;
+  const startedAt = Date.now();
+  const deadline = startedAt + DEEP_HEALTH_TIMEOUT_MS;
   let lastError = "health check did not complete";
+  let lastProgressAt = startedAt;
   while (Date.now() < deadline) {
     const result = await run("docker", [
       ...composeCommand,
@@ -896,6 +930,10 @@ async function waitForDeepHealthWithArgs(composeCommand, directory, secrets = []
     if (result.ok)
       return;
     lastError = redact(result.stderr, secrets);
+    if (Date.now() - lastProgressAt >= 15000) {
+      console.error(`Waiting for OR3 deep health (${Math.round((Date.now() - startedAt) / 1000)}s elapsed)…`);
+      lastProgressAt = Date.now();
+    }
     await new Promise((resolvePromise) => setTimeout(resolvePromise, 1000));
   }
   throw new Error(`OR3 deep health did not pass within ${DEEP_HEALTH_TIMEOUT_MS / 1000} seconds. Last error: ${lastError}`);
@@ -1112,6 +1150,26 @@ function packagedSourceRevision(version) {
   }
   return revision;
 }
+function packagedOr3CloudMetadata() {
+  try {
+    const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return manifest.or3Cloud ?? {};
+  } catch {
+    return {};
+  }
+}
+function writeStateSchema() {
+  const value = packagedOr3CloudMetadata().stateSchema;
+  if (value === undefined)
+    return LEGACY_STATE_SCHEMA_VERSION;
+  if (value === 1 || value === 2)
+    return value;
+  throw new Error("This @or3/cloud package declares an unsupported managed state schema. Refusing to write managed state.");
+}
+function packagedMinimumSourceVersion() {
+  const value = packagedOr3CloudMetadata().dashboardUpdateMinimumSourceVersion;
+  return typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value) ? value : undefined;
+}
 function expectedImageDigest(version) {
   const packaged = packagedImageDigest(version);
   const supplied = process.env.OR3_EXPECTED_IMAGE_DIGEST?.trim();
@@ -1438,10 +1496,11 @@ function dashboardOperatorHandoffArgs(directory, env, jobId) {
     project
   ];
 }
-async function scheduleDashboardOperatorHandoff(directory, env) {
-  const jobId = process.env.OR3_DASHBOARD_UPDATE_JOB_ID?.trim();
+async function scheduleDashboardOperatorHandoff(directory, env, jobIdOverride) {
+  const jobId = jobIdOverride ?? process.env.OR3_DASHBOARD_UPDATE_JOB_ID?.trim();
   if (!jobId || env.OR3_DASHBOARD_UPDATES_ENABLED !== "true")
     return;
+  await lifecycleFaults.beforeHandoff?.();
   const scheduled = await run("docker", dashboardOperatorHandoffArgs(directory, env, jobId), directory);
   if (!scheduled.ok || !/^[0-9a-f]{12,64}$/i.test(scheduled.stdout.trim())) {
     throw new Error(`Could not schedule the dashboard operator handoff. ${scheduled.stderr.trim()}`);
@@ -1642,6 +1701,15 @@ async function copyAssets(directory, mode) {
   }
   await installManagedAssets(directory, assets);
 }
+async function installedManagedAssetChecksums(directory, mode) {
+  const checksums = {};
+  for (const name of managedAssetNames(mode)) {
+    if (!await fileExists(join(directory, name)))
+      continue;
+    checksums[name] = await sha256File(join(directory, name));
+  }
+  return checksums;
+}
 async function snapshotManagedAssets(directory, mode, backupDir) {
   const assetDir = join(backupDir, "managed-assets");
   await mkdir(assetDir, { recursive: true, mode: 448 });
@@ -1731,14 +1799,61 @@ async function updatePending(directory, state, patch) {
 async function removeOperationRecord(directory, operationId) {
   if (!operationId)
     return;
+  await lifecycleFaults.beforeMirrorDelete?.();
   await rm(join(deploymentPaths(directory).operations, `${operationId}.json`), { force: true });
 }
-async function clearPending(directory, state) {
+async function removeOperationRecordSafely(directory, operationId) {
+  try {
+    await removeOperationRecord(directory, operationId);
+  } catch (error) {
+    console.warn(`Could not remove the redundant operation mirror ${operationId ?? "(none)"}: ${redact(error instanceof Error ? error.message : String(error))}`);
+  }
+}
+async function commitTerminalState(directory, state, receipt) {
   const operationId = state.incompleteOperation?.id;
   delete state.incompleteOperation;
+  if (receipt)
+    state.lastReceipt = receipt;
   state.updatedAt = now();
-  await removeOperationRecord(directory, operationId);
   await writeState(directory, state);
+  if (receipt) {
+    try {
+      await exportTerminalReceipt(directory, receipt);
+    } catch (error) {
+      console.warn(`Could not export the latest operation receipt: ${redact(error instanceof Error ? error.message : String(error))}`);
+    }
+  }
+  return { committed: true, operationId };
+}
+async function exportTerminalReceipt(directory, receipt) {
+  const payload = `${JSON.stringify(receipt, null, 2)}
+`;
+  await writeSecure(deploymentPaths(directory).lastOperation, payload);
+}
+async function persistReceiptWarnings(directory, state, warnings) {
+  if (warnings.length === 0 || !state.lastReceipt)
+    return;
+  const existing = state.lastReceipt.warnings;
+  const additions = warnings.filter((warning) => !existing.some((current) => current.code === warning.code && current.message === warning.message));
+  if (additions.length === 0)
+    return;
+  const merged = { ...state.lastReceipt, warnings: [...existing, ...additions] };
+  try {
+    if (state.incompleteOperation)
+      return;
+    state.lastReceipt = merged;
+    state.updatedAt = now();
+    await writeState(directory, state);
+    await exportTerminalReceipt(directory, merged).catch((error) => {
+      console.warn(`Could not re-export the operation receipt: ${redact(error instanceof Error ? error.message : String(error))}`);
+    });
+  } catch (error) {
+    console.warn(`Could not persist maintenance warnings to the receipt: ${redact(error instanceof Error ? error.message : String(error))}`);
+  }
+}
+async function clearPending(directory, state, receipt) {
+  const { operationId } = await commitTerminalState(directory, state, receipt);
+  await removeOperationRecordSafely(directory, operationId);
 }
 async function stopProject(directory, mode) {
   await compose(directory, mode, ["stop", "or3"]);
@@ -1807,6 +1922,7 @@ function assertRemovableArtifactName(name) {
   return name;
 }
 async function removeNamedBackupArtifact(directory, backupId) {
+  await lifecycleFaults.beforeArtifactDelete?.();
   assertRemovableArtifactName(backupId);
   const target = backupDirectory(directory, backupId);
   if (dirname(target) !== deploymentPaths(directory).backups) {
@@ -1816,6 +1932,7 @@ async function removeNamedBackupArtifact(directory, backupId) {
   await rm(join(deploymentPaths(directory).exports, `${backupId}.json`), { force: true });
 }
 async function removeEnumeratedBackupArtifact(directory, backup) {
+  await lifecycleFaults.beforeArtifactDelete?.();
   const backupsRoot = resolve(deploymentPaths(directory).backups);
   const target = resolve(backup.path);
   if (dirname(target) !== backupsRoot || basename(target) !== backup.backupId || !BACKUP_ID_PATTERN.test(backup.backupId)) {
@@ -1824,55 +1941,159 @@ async function removeEnumeratedBackupArtifact(directory, backup) {
   await rm(target, { recursive: true, force: true });
   await rm(join(deploymentPaths(directory).exports, `${backup.backupId}.json`), { force: true });
 }
-async function enumerateBackups(directory) {
-  const backupsRoot = deploymentPaths(directory).backups;
-  let entries = [];
+function classifyBackupError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/authentication failed|no valid deployment authentication tag|invalid authentication tag/i.test(message)) {
+    return { code: "backup-authentication-failed", message };
+  }
+  if (/checksum mismatch/i.test(message))
+    return { code: "backup-checksum-mismatch", message };
+  if (/invalid managed asset inventory|managed asset checksum mismatch/i.test(message)) {
+    return { code: "backup-assets-invalid", message };
+  }
+  if (/Invalid backup manifest/i.test(message))
+    return { code: "backup-manifest-invalid", message };
+  if (error?.code === "ENOENT")
+    return { code: "backup-entry-incomplete", message };
+  return { code: "backup-entry-invalid", message };
+}
+async function inspectBackupEntry(backupsRoot, entry, directory) {
+  const path = join(backupsRoot, entry);
+  let info;
   try {
-    entries = await readdir(backupsRoot);
+    info = await lstat(path);
   } catch (error) {
-    if (error.code === "ENOENT")
-      return [];
-    throw new Error(`Could not enumerate managed backups at ${backupsRoot}: ${error instanceof Error ? error.message : String(error)}`);
+    return { kind: "unreadable", entryName: entry, ...classifyBackupError(error) };
   }
-  const result = [];
-  for (const entry of entries) {
-    if (/^adopt-source-[0-9A-Za-z-]+$/.test(entry) && (await lstat(join(backupsRoot, entry))).isDirectory()) {
-      continue;
-    }
-    if (!BACKUP_ID_PATTERN.test(entry)) {
-      throw new Error(`Backup store contains an unexpected artifact ${join(backupsRoot, entry)}. Refusing to use it for retention; inspect or remove it explicitly.`);
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    return {
+      kind: "invalid",
+      entryName: entry,
+      code: "backup-entry-not-directory",
+      message: `Backup store entry ${entry} is not a regular directory; symlinks and non-directories are never trusted.`
+    };
+  }
+  if (/^adopt-source-[0-9A-Za-z-]+$/.test(entry)) {
+    return {
+      kind: "legacy-adoption",
+      entryName: entry,
+      code: "backup-legacy-adoption",
+      message: `Preserved legacy adoption source ${entry}; it is not an authenticated managed backup.`
+    };
+  }
+  if (!BACKUP_ID_PATTERN.test(entry)) {
+    return {
+      kind: "invalid",
+      entryName: entry,
+      code: "backup-entry-unexpected",
+      message: `Backup store contains an unexpected artifact ${path}; inspect or remove it explicitly.`
+    };
+  }
+  try {
+    await lstat(join(path, "manifest.auth"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {
+        kind: "legacy-unsigned",
+        entryName: entry,
+        code: "backup-unsigned",
+        message: `Preserved unauthenticated backup ${entry} (no manifest.auth); never trusted for restore.`
+      };
     }
-    const path = join(backupsRoot, entry);
-    try {
-      await lstat(join(path, "manifest.auth"));
-    } catch (error) {
-      if (error.code !== "ENOENT")
-        throw error;
-      console.warn(`Preserving unauthenticated backup ${entry}: no manifest.auth; excluded from managed backup listing and retention.`);
-      continue;
+    return { kind: "unreadable", entryName: entry, ...classifyBackupError(error) };
+  }
+  try {
+    const raw = JSON.parse(await readText(join(path, "manifest.json")));
+    if (typeof raw.schemaVersion === "number" && raw.schemaVersion > 1) {
+      return {
+        kind: "unsupported",
+        entryName: entry,
+        code: "backup-format-unsupported",
+        message: `Backup ${entry} uses manifest schema ${raw.schemaVersion}; preserved for a newer reader.`
+      };
     }
+  } catch (error) {
+    return { kind: "invalid", entryName: entry, ...classifyBackupError(error) };
+  }
+  try {
     const manifest = await readManifest(path, directory);
     if (manifest.backupId !== entry) {
-      throw new Error(`Backup directory ${path} does not match manifest ID ${manifest.backupId}. Refusing to use it for retention.`);
+      return {
+        kind: "invalid",
+        entryName: entry,
+        code: "backup-id-mismatch",
+        message: `Backup directory ${path} does not match manifest ID ${manifest.backupId}.`
+      };
     }
     if (!Number.isFinite(Date.parse(manifest.createdAt))) {
-      throw new Error(`Backup ${manifest.backupId} has an invalid creation time.`);
+      return {
+        kind: "invalid",
+        entryName: entry,
+        code: "backup-created-at-invalid",
+        message: `Backup ${manifest.backupId} has an invalid creation time.`
+      };
     }
     let bytes = 0;
     for (const file of ["data.tgz", "config.env", "manifest.json", "manifest.auth"]) {
-      bytes += (await stat(join(path, file))).size;
+      bytes += (await lstat(join(path, file))).size;
     }
-    result.push({
-      backupId: manifest.backupId,
-      createdAt: manifest.createdAt,
-      appVersion: manifest.appVersion,
-      path,
-      bytes,
-      dataSha256: manifest.dataSha256
-    });
+    return {
+      kind: "verified",
+      backup: {
+        backupId: manifest.backupId,
+        createdAt: manifest.createdAt,
+        appVersion: manifest.appVersion,
+        path,
+        bytes,
+        dataSha256: manifest.dataSha256
+      }
+    };
+  } catch (error) {
+    return { kind: "invalid", entryName: entry, ...classifyBackupError(error) };
   }
-  result.sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
-  return result;
+}
+var BACKUP_ENTRY_SEVERITY = {
+  verified: 0,
+  "legacy-unsigned": 1,
+  "legacy-adoption": 2,
+  unsupported: 3,
+  invalid: 4,
+  unreadable: 5
+};
+async function inventoryBackups(directory) {
+  const backupsRoot = deploymentPaths(directory).backups;
+  let names;
+  try {
+    names = await readdir(backupsRoot);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { entries: [], storeErrors: [] };
+    return {
+      entries: [],
+      storeErrors: [{
+        code: "backup-store-unreadable",
+        severity: "blocker",
+        resource: backupsRoot,
+        message: `Could not enumerate managed backups at ${backupsRoot}: ${error instanceof Error ? error.message : String(error)}`
+      }]
+    };
+  }
+  const entries = [];
+  for (const name of [...names].sort())
+    entries.push(await inspectBackupEntry(backupsRoot, name, directory));
+  entries.sort((a, b) => {
+    const severity = BACKUP_ENTRY_SEVERITY[a.kind] - BACKUP_ENTRY_SEVERITY[b.kind];
+    if (severity !== 0)
+      return severity;
+    const aName = a.kind === "verified" ? a.backup.backupId : a.entryName;
+    const bName = b.kind === "verified" ? b.backup.backupId : b.entryName;
+    return aName < bName ? -1 : aName > bName ? 1 : 0;
+  });
+  return { entries, storeErrors: [] };
+}
+async function enumerateBackups(directory) {
+  const inventory = await inventoryBackups(directory);
+  return inventory.entries.filter((entry) => entry.kind === "verified").map((entry) => entry.backup).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
 }
 function selectPruneTargets(backups, keep, protectedIds, force = false) {
   if (!Number.isInteger(keep) || keep < 1)
@@ -1881,6 +2102,40 @@ function selectPruneTargets(backups, keep, protectedIds, force = false) {
   const deletable = force ? sorted : sorted.filter((backup) => !protectedIds.has(backup.backupId));
   return deletable.slice(keep).map((backup) => backup.backupId);
 }
+function planRetention(entries, keep, protectedIds, options = {}) {
+  if (!Number.isInteger(keep) || keep < 1)
+    throw new Error("Backup retention must be an integer of at least 1.");
+  const automatic = options.automatic ?? true;
+  const warnings = [];
+  const preserve = [];
+  let canPrune = true;
+  for (const entry of entries) {
+    if (entry.kind === "verified")
+      continue;
+    preserve.push({ entryName: entry.entryName, reason: entry.message });
+    if (entry.kind === "legacy-unsigned" || entry.kind === "legacy-adoption")
+      continue;
+    warnings.push({
+      code: entry.code,
+      severity: entry.kind === "unreadable" ? "blocker" : "warning",
+      resource: entry.entryName,
+      message: entry.message
+    });
+    if (automatic)
+      canPrune = false;
+  }
+  const verified = entries.filter((entry) => entry.kind === "verified").map((entry) => entry.backup).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
+  const removable = verified.filter((backup) => !protectedIds.has(backup.backupId));
+  const remove = removable.slice(keep).map((backup) => backup.backupId);
+  const removeSet = new Set(remove);
+  return {
+    keep: verified.filter((backup) => !removeSet.has(backup.backupId)).map((backup) => backup.backupId),
+    remove,
+    preserve,
+    warnings,
+    canPrune
+  };
+}
 function parseKeep(flags) {
   const value = stringFlag(flags, "keep") ?? String(BACKUP_RETENTION_KEEP);
   const keep = Number(value);
@@ -1888,25 +2143,53 @@ function parseKeep(flags) {
     throw new Error("--keep must be an integer of at least 1.");
   return keep;
 }
-async function pruneBackups(directory, state, keep, force) {
-  const backups = await enumerateBackups(directory);
+function retentionProtectedIds(state) {
   const protectedIds = new Set;
   if (state.rollback?.backupId)
     protectedIds.add(state.rollback.backupId);
-  if (state.incompleteOperation?.backupId)
-    protectedIds.add(state.incompleteOperation.backupId);
-  const targets = selectPruneTargets(backups, keep, protectedIds, force);
-  if (force && targets.length > 0) {
-    console.log(`--force --yes will permanently delete: ${targets.join(", ")}`);
-  }
-  for (const backupId of targets) {
-    const backup = backups.find((entry) => entry.backupId === backupId);
+  const pending = state.incompleteOperation;
+  if (pending?.backupId)
+    protectedIds.add(pending.backupId);
+  if (pending?.previousBackupId)
+    protectedIds.add(pending.previousBackupId);
+  return protectedIds;
+}
+async function pruneBackups(directory, state, keep, force, options = {}) {
+  const automatic = options.automatic ?? !force;
+  const log = options.log ?? ((message) => console.log(message));
+  const warn = options.warn ?? ((message) => console.warn(message));
+  const inventory = await inventoryBackups(directory);
+  if (inventory.storeErrors.length > 0) {
+    if (automatic)
+      return { removed: 0, deferred: inventory.storeErrors };
+    throw new Error(inventory.storeErrors.map((diagnostic) => diagnostic.message).join(" "));
+  }
+  const plan = planRetention(inventory.entries, keep, retentionProtectedIds(state), { automatic });
+  if (!plan.canPrune && !force) {
+    warn("Automatic backup pruning was deferred because the store contains entries that need inspection.");
+    for (const warning of plan.warnings)
+      warn(`  ${warning.code}: ${warning.message}`);
+    return { removed: 0, deferred: plan.warnings };
+  }
+  const verified = new Map(inventory.entries.filter((entry) => entry.kind === "verified").map((entry) => [entry.backup.backupId, entry.backup]));
+  if (force && plan.remove.length > 0) {
+    log(`--force --yes will permanently delete: ${plan.remove.join(", ")}`);
+  }
+  let removed = 0;
+  for (const backupId of plan.remove) {
+    const backup = verified.get(backupId);
     if (!backup)
       throw new Error(`Retention selected backup ${backupId}, but its verified path disappeared before deletion.`);
-    await removeEnumeratedBackupArtifact(directory, backup);
-    console.log(`Deleted backup ${backupId} at ${backup.path}`);
+    const revalidated = await inspectBackupEntry(deploymentPaths(directory).backups, backupId, directory);
+    const current = revalidated.kind === "verified" ? revalidated.backup : undefined;
+    if (!current || current.path !== backup.path || current.dataSha256 !== backup.dataSha256) {
+      throw new Error(`Backup ${backupId} changed while pruning was in progress. Aborting retention before deletion.`);
+    }
+    await removeEnumeratedBackupArtifact(directory, current);
+    log(`Deleted backup ${backupId} at ${current.path}`);
+    removed += 1;
   }
-  return targets.length;
+  return { removed, deferred: plan.warnings };
 }
 function assertDeploymentIdentity(state, env) {
   const expected = {
@@ -2314,6 +2597,7 @@ async function createBackup(directory, state, env, options = {}) {
   }
 }
 async function readManifest(backupPath, authenticatedForDirectory) {
+  await lifecycleFaults.beforeArchiveRead?.();
   const manifestContents = await readText(join(backupPath, "manifest.json"));
   if (authenticatedForDirectory)
     await assertBackupAuthentication(authenticatedForDirectory, backupPath, manifestContents);
@@ -2418,7 +2702,7 @@ async function restoreBackupData(directory, state, env, backupPath, options = {}
 }
 function stateFromEnv(directory, env, mode, operation, digest) {
   return {
-    schemaVersion: 1,
+    schemaVersion: writeStateSchema(),
     mode,
     composeProject: env.OR3_COMPOSE_PROJECT,
     volumeName: env.OR3_VOLUME_NAME,
@@ -2441,16 +2725,16 @@ function help() {
 Usage:
   npx @or3/cloud init [directory] --local
   npx @or3/cloud init [directory] --public --domain <hostname>
-  npx @or3/cloud update [--to <exact-version>]
-  npx @or3/cloud backup [list|prune [--keep <n>]|export <backup-id> <destination-dir>]
+  npx @or3/cloud update [--to <exact-version>] [--dry-run] [--json]
+  npx @or3/cloud backup [list [--json]|prune [--keep <n>]|export <backup-id> <destination-dir>]
   npx @or3/cloud restore <backup-id-or-path> --yes
   npx @or3/cloud rollback --yes
   npx @or3/cloud credentials reset --yes [--owner-password-file <path> --admin-password-file <path>]
   npx @or3/cloud doctor
-  npx @or3/cloud verify [--public] [--verification-email <email> --verification-password-file <path>]
-  npx @or3/cloud recover
+  npx @or3/cloud verify [--read-only] [--public] [--verification-email <email> --verification-password-file <path>]
+  npx @or3/cloud recover [--dry-run | --finish | --restore --yes]
   npx @or3/cloud adopt --from <v1-directory> [directory]
-  npx @or3/cloud status
+  npx @or3/cloud status [--json]
   npx @or3/cloud logs [--tail <n>] [service]
   npx @or3/cloud start | stop | restart
   npx @or3/cloud remove [--purge-data --yes]
@@ -2468,6 +2752,11 @@ Options:
   --force                        Prune backups even when referenced by the rollback point
   --tail <n>                     Log lines to show (default: 200)
   --public                       Require verification through the public HTTPS origin
+  --read-only                    Verify without the lease, login, storage, or database writes
+  --dry-run                      Preview an update or recovery without changing anything
+  --finish                       Commit a proven completed replacement without restoring data
+  --restore                      Explicitly restore the recorded snapshot (requires --yes)
+  --json                         Emit one machine-readable result object on stdout
   --purge-data                   Remove data volumes and managed files (with remove)
   --yes                          Confirm a destructive restore, rollback, credentials reset, or purge
   --help                         Show this help
@@ -2557,7 +2846,8 @@ ${existing.stderr}`)) {
     await clearPending(directory, state);
     console.log(`
 OR3 Cloud ${version} is running at ${mode === "public" ? `https://${domain}` : `http://127.0.0.1:${port}`}`);
-    console.log(`Credentials were written to ${join(directory, ".or3-initial-credentials")} (mode 0600). Save them, then remove that file.`);
+    console.log(`Credentials were written to ${join(directory, ".or3-initial-credentials")} (mode 0600). Move them to protected storage (a password manager), then remove that file.`);
+    console.log('The bootstrap owner signs in to the app; the admin account manages the deployment. Rotate either later with "npx @or3/cloud credentials reset --yes".');
     console.log(`
 Check: cd ${quote(directory)} && npx @or3/cloud doctor`);
     if (operator)
@@ -2572,22 +2862,179 @@ Check: cd ${quote(directory)} && npx @or3/cloud doctor`);
 The new deployment files were preserved at ${directory}.`);
   }
 }
-async function loadManaged(directory = process.cwd()) {
+function assertStateSchemaWritable(state) {
+  const writer = writeStateSchema();
+  if (state.schemaVersion > writer) {
+    throw new Error(`This CLI reads managed state schema ${state.schemaVersion} but is qualified to write schema ${writer}. Run the compatible exact-version @or3/cloud CLI for this deployment; do not edit or hand-migrate managed state.`);
+  }
+}
+async function loadManaged(directory = process.cwd(), options = {}) {
   const resolved = resolve(directory);
   const state = await readState(resolved);
+  if (options.writable !== false)
+    assertStateSchemaWritable(state);
   const env = parseEnv(await readText(deploymentPaths(resolved).env));
   assertDeploymentIdentity(state, env);
   assertDeploymentDirectoryIdentity(resolved, state);
   return { directory: resolved, state, env };
 }
+async function observeDeployment(directory, options = {}) {
+  const resolved = resolve(directory);
+  const observedAt = now();
+  let state = null;
+  let stateError = null;
+  try {
+    state = await readState(resolved);
+  } catch (error) {
+    stateError = redact(error instanceof Error ? error.message : String(error));
+  }
+  let env = null;
+  let envError = null;
+  try {
+    env = parseEnv(await readText(deploymentPaths(resolved).env));
+  } catch (error) {
+    envError = redact(error instanceof Error ? error.message : String(error));
+  }
+  const leasePath = deploymentPaths(resolved).lease;
+  let lease = { status: "none" };
+  if (await fileExists(leasePath)) {
+    const owner = await readLeaseOwner(leasePath);
+    if (!owner)
+      lease = { status: "unreadable" };
+    else if (cliLeaseOwnerIsGone(owner) || dashboardLeaseOwnerIsStale(owner))
+      lease = { status: "stale", owner };
+    else
+      lease = { status: "active", owner };
+  }
+  let backups = null;
+  const backupErrors = [];
+  try {
+    backups = await inventoryBackups(resolved);
+    backupErrors.push(...backups.storeErrors);
+  } catch (error) {
+    backupErrors.push({ code: "backup-store-unreadable", severity: "blocker", message: redact(error instanceof Error ? error.message : String(error)) });
+  }
+  const checkDocker = options.checkDocker ?? true;
+  const checkImage = options.checkImage ?? true;
+  let docker = false;
+  let recordedImageDigest = state?.imageDigest ?? null;
+  let actualImageDigest = null;
+  let identityMatches = null;
+  if (checkDocker) {
+    try {
+      await ensureDocker();
+      docker = true;
+    } catch {
+      docker = false;
+    }
+  }
+  if (checkImage && docker && state?.image) {
+    try {
+      actualImageDigest = await runningContainerImageDigest(resolved, state.mode, state.image);
+      identityMatches = actualImageDigest === state.imageDigest;
+    } catch {
+      actualImageDigest = null;
+      identityMatches = null;
+    }
+  }
+  const partial = Boolean(stateError || envError || backupErrors.length > 0 || checkDocker && !docker);
+  return {
+    directory: resolved,
+    observedAt,
+    state,
+    stateError,
+    env,
+    envError,
+    lease,
+    docker,
+    recordedImageDigest,
+    actualImageDigest,
+    identityMatches,
+    backups,
+    backupErrors,
+    changing: lease.status === "active",
+    partial
+  };
+}
+async function runningContainerImageDigest(directory, mode, fallbackImage) {
+  let containerId = "";
+  try {
+    const ps = await run("docker", composeArgs(directory, mode, ["ps", "-q", "or3"]), directory);
+    containerId = ps.ok ? ps.stdout.trim() : "";
+  } catch {
+    containerId = "";
+  }
+  if (!containerId)
+    return await imageDigest(fallbackImage);
+  const image = await run("docker", ["inspect", "--format", "{{.Image}}", containerId], directory);
+  const imageId = image.ok ? image.stdout.trim() : "";
+  if (!imageId)
+    throw new Error("Could not inspect the running OR3 container image.");
+  const digests = await run("docker", ["image", "inspect", "--format", "{{json .RepoDigests}}", imageId], directory);
+  if (!digests.ok)
+    throw new Error("Could not inspect repository digests for the running OR3 container.");
+  let values;
+  try {
+    values = JSON.parse(digests.stdout.trim());
+  } catch {
+    throw new Error("The running OR3 container has no readable repository digests.");
+  }
+  const match = values.map((value) => value.match(/@(sha256:[0-9a-f]{64})$/i)?.[1]).find((value) => Boolean(value));
+  if (!match)
+    throw new Error("The running OR3 container image is not digest-qualified.");
+  return match;
+}
+function publicStateProjection(state) {
+  const pending = state.incompleteOperation;
+  return {
+    schemaVersion: state.schemaVersion,
+    mode: state.mode,
+    appVersion: state.appVersion,
+    image: state.image,
+    imageDigest: state.imageDigest,
+    domain: state.domain ?? null,
+    port: state.port,
+    deploymentId: state.deploymentId ?? null,
+    lastSuccessfulOperation: state.lastSuccessfulOperation,
+    updatedAt: state.updatedAt,
+    rollback: state.rollback ? { appVersion: state.rollback.appVersion, imageDigest: state.rollback.imageDigest, backupId: state.rollback.backupId, createdAt: state.rollback.createdAt } : null,
+    incompleteOperation: pending ? {
+      id: pending.id,
+      operation: pending.operation,
+      phase: pending.phase ?? null,
+      origin: pending.origin ?? null,
+      dashboardJobId: pending.dashboardJobId ?? null,
+      targetVersion: pending.targetVersion ?? null,
+      targetImageDigest: pending.targetImageDigest ?? null
+    } : null,
+    lastReceipt: state.lastReceipt ?? null,
+    lastError: state.lastError ? redact(state.lastError) : null
+  };
+}
+function observationFindings(observation) {
+  const findings = [];
+  if (observation.stateError)
+    findings.push({ code: "state-unreadable", severity: "blocker", resource: deploymentPaths(observation.directory).state, message: observation.stateError });
+  if (observation.envError)
+    findings.push({ code: "env-unreadable", severity: "blocker", resource: deploymentPaths(observation.directory).env, message: observation.envError });
+  if (observation.lease.status === "active") {
+    findings.push({ code: "operation-in-progress", severity: "info", message: `A ${observation.lease.owner.origin} operation (${observation.lease.owner.command}) is active; this observation is not authoritative.` });
+  }
+  if (observation.lease.status === "unreadable")
+    findings.push({ code: "lease-unreadable", severity: "warning", message: "The deployment lease owner record is unreadable; run doctor before any mutation." });
+  if (observation.identityMatches === false) {
+    findings.push({ code: "image-digest-mismatch", severity: "blocker", resource: observation.state?.image, message: `Recorded digest ${observation.recordedImageDigest} does not match the local image ${observation.actualImageDigest}.` });
+  }
+  return findings;
+}
 function operationToStateOperation(operation, fallback) {
   if (operation === "init" || operation === "update" || operation === "adopt")
     return operation;
   return fallback;
 }
 async function commitRecoveredState(directory, previous, next) {
-  await removeOperationRecord(directory, previous.incompleteOperation?.id);
   await writeState(directory, next);
+  await removeOperationRecordSafely(directory, previous.incompleteOperation?.id);
 }
 async function commitPreMutationRecovery(directory, state, message) {
   const restoredEnv = parseEnv(await readText(deploymentPaths(directory).env));
@@ -2597,14 +3044,293 @@ async function commitPreMutationRecovery(directory, state, message) {
   await commitRecoveredState(directory, state, recovered);
   return recovered;
 }
-async function recoverCommand(directory) {
+function decideRecoveryAction(state) {
+  const pending = state.incompleteOperation;
+  if (!pending) {
+    const handoff = state.lastReceipt?.operatorHandoff;
+    if (handoff === "pending" || handoff === "needs-attention") {
+      return { action: "reconcile-handoff", detail: `The application is complete but the dashboard operator handoff is ${handoff}. Reconcile only the recorded handoff.` };
+    }
+    return { action: "none", detail: "No incomplete operation is recorded." };
+  }
+  if (pending.operation === "update" && pending.phase === "target-ready" && pending.evidence) {
+    return { action: "finish", detail: "A completed replacement carries durable target-ready evidence and can be committed without restoring data." };
+  }
+  if (pending.phase === "prepared" || pending.phase === "snapshot-created") {
+    return { action: "resume", detail: `The ${pending.operation} had not replaced data; resume the known-good source.` };
+  }
+  if (pending.operation === "update" || pending.operation === "restore" || pending.operation === "rollback") {
+    const snapshotId = pending.operation === "update" ? pending.backupId : pending.previousBackupId ?? pending.backupId;
+    return {
+      action: "require-explicit-restore",
+      detail: `The ${pending.operation} may have changed data and has no completion proof. Health alone cannot authorize adoption.`,
+      snapshotId
+    };
+  }
+  return { action: "resume", detail: `Resume the ${pending.operation} using its durable evidence.` };
+}
+function assertRecoverFlags(flags) {
+  const dryRun = boolFlag(flags, "dry-run");
+  const finish = boolFlag(flags, "finish");
+  const restore = boolFlag(flags, "restore");
+  if (finish && restore)
+    throw new Error("Use either --finish or --restore, not both.");
+  if (dryRun && (finish || restore))
+    throw new Error("--dry-run cannot be combined with --finish or --restore.");
+  if (restore && !boolFlag(flags, "yes")) {
+    throw new Error("recover --restore replaces live data. Review `npx @or3/cloud recover --dry-run` first, then re-run with `recover --restore --yes`.");
+  }
+}
+async function reconcileOperatorHandoff(directory, state, report = console.log) {
+  const env = parseEnv(await readText(deploymentPaths(directory).env));
+  if (env.OR3_DASHBOARD_UPDATES_ENABLED !== "true") {
+    const detail2 = "Dashboard updates are disabled in this deployment; no operator handoff needs reconciliation.";
+    report(detail2);
+    return detail2;
+  }
+  const receipt = state.lastReceipt;
+  const jobId = receipt?.dashboardJobId ?? process.env.OR3_DASHBOARD_UPDATE_JOB_ID?.trim();
+  if (!jobId) {
+    throw new Error("The completed update recorded no dashboard job for its operator handoff. Re-run the host CLI update, or disable dashboard updates until the operator is restored.");
+  }
+  await scheduleDashboardOperatorHandoff(directory, env, jobId);
+  if (receipt) {
+    receipt.operatorHandoff = "pending";
+    await writeState(directory, state);
+    await exportTerminalReceipt(directory, receipt).catch(() => {
+      return;
+    });
+  }
+  const detail = `Rescheduled the dashboard operator handoff for job ${jobId.slice(0, 8)}. The successor operator marks it verified once it is running.`;
+  report(detail);
+  return detail;
+}
+async function collectTargetReadyChecks(directory, mode, env) {
+  const checks = [];
+  let containerId;
+  const container = await run("docker", composeArgs(directory, mode, ["ps", "-q", "or3"]), directory);
+  containerId = container.ok ? container.stdout.trim() || undefined : undefined;
+  checks.push(containerId ? { code: "container-binding", status: "passed", detail: `Observed target container ${containerId}.` } : { code: "container-binding", status: "failed", detail: "Could not resolve the running target container." });
+  const databaseCheck = await run("docker", [
+    ...composeArgs(directory, mode, ["exec", "-T", "or3", ...containerNodeCommand(VERIFY_DATABASES_SCRIPT)])
+  ], directory);
+  let databasesOk = false;
+  if (databaseCheck.ok) {
+    try {
+      const databases = JSON.parse(databaseCheck.stdout.trim());
+      databasesOk = databases.length === 2 && databases.every((entry) => entry.quickCheck === "ok" && entry.tables >= 1);
+    } catch {
+      databasesOk = false;
+    }
+  }
+  checks.push(databasesOk ? { code: "database-integrity", status: "passed", detail: "auth.sqlite and sync.sqlite quick_check passed with managed ownership." } : { code: "database-integrity", status: "failed", detail: `SQLite integrity or ownership verification failed. ${redact(databaseCheck.stderr.trim(), secretValues(env))}` });
+  const baseUrl = new URL(mode === "public" ? `https://${env.OR3_PUBLIC_DOMAIN}` : `http://127.0.0.1:${env.OR3_PORT}`);
+  try {
+    validateVerificationHealth(await verificationJson(baseUrl, "/api/health?deep=true"));
+    checks.push({ code: "public-health", status: "passed", detail: `${baseUrl.origin} deep health reports the managed profile.` });
+  } catch (error) {
+    checks.push({ code: "public-health", status: "failed", detail: redact(error instanceof Error ? error.message : String(error)) });
+  }
+  return { containerId, checks };
+}
+async function finishTargetReadyUpdate(directory, state, env, report = console.log) {
+  const pending = state.incompleteOperation;
+  if (!pending?.evidence || !pending.targetVersion || !pending.targetImage) {
+    throw new Error("recover --finish requires a recorded target-ready milestone; none is present.");
+  }
+  const targetEnv = parseEnv(await readText(deploymentPaths(directory).env));
+  if (targetEnv.OR3_VERSION !== pending.targetVersion || targetEnv.OR3_IMAGE !== pending.targetImage) {
+    throw new Error("The live .env no longer matches the recorded target-ready identities; refusing to finish.");
+  }
+  const expectedTargetDigest = pending.targetImageDigest ?? await imageDigest(targetEnv.OR3_IMAGE);
+  await pullAndRequireImage(targetEnv.OR3_IMAGE, expectedTargetDigest, "Target deployment");
+  await assertRunningAppImage(directory, state.mode, targetEnv.OR3_IMAGE);
+  const actualDigest = await imageDigest(targetEnv.OR3_IMAGE);
+  if (actualDigest !== pending.evidence.imageDigest) {
+    throw new Error(`The running target image ${actualDigest} does not match the recorded target-ready proof ${pending.evidence.imageDigest}.`);
+  }
+  const configurationSha256 = await sha256File(deploymentPaths(directory).env);
+  if (configurationSha256 !== pending.evidence.configurationSha256) {
+    throw new Error("The managed configuration changed after the target-ready milestone; refusing to finish. Inspect the change, or run `recover --restore --yes` to return to the recorded snapshot.");
+  }
+  const assets = await installedManagedAssetChecksums(directory, state.mode);
+  for (const [name, expected] of Object.entries(pending.evidence.managedAssetSha256)) {
+    if (assets[name] !== expected) {
+      throw new Error(`Managed asset ${name} changed after the target-ready milestone; refusing to finish.`);
+    }
+  }
+  const expectedDeploymentId = targetEnv.OR3_DEPLOYMENT_ID ?? pending.targetDeploymentId;
+  if (pending.evidence.deploymentId && expectedDeploymentId && pending.evidence.deploymentId !== expectedDeploymentId) {
+    throw new Error("The recorded target-ready deployment identity no longer matches the live deployment.");
+  }
+  await recordedBackupPath(directory, pending);
+  for (const required of ["container-binding", "database-integrity", "public-health"]) {
+    const recorded = pending.evidence.checks.find((check) => check.code === required);
+    if (!recorded || recorded.status !== "passed") {
+      throw new Error(`The recorded target-ready proof is missing ${required}; refusing to finish. Run "npx @or3/cloud recover --restore --yes" to return to the recorded snapshot.`);
+    }
+  }
+  await waitForDeepHealth(directory, state.mode, secretValues(targetEnv));
+  const revalidated = await collectTargetReadyChecks(directory, state.mode, targetEnv);
+  if (!revalidated.containerId || revalidated.containerId !== pending.evidence.containerId) {
+    throw new Error("The running target container no longer matches the recorded target-ready proof; refusing to finish.");
+  }
+  const failedChecks = revalidated.checks.filter((check) => check.status !== "passed");
+  if (failedChecks.length > 0) {
+    throw new Error(`Target verification failed at finish (${failedChecks.map((check) => check.code).join(", ")}); refusing to finish.`);
+  }
+  const sourceVersion = state.appVersion;
+  const sourceImage = state.image;
+  const sourceDigest = state.imageDigest;
+  const digest = actualDigest;
+  const recordedDashboardJobId = pending.dashboardJobId ?? (process.env.OR3_DASHBOARD_UPDATE_JOB_ID?.trim() || undefined);
+  const receipt = {
+    schemaVersion: 1,
+    operationId: pending.id,
+    dashboardJobId: recordedDashboardJobId,
+    cliVersion: PACKAGE_VERSION,
+    source: { appVersion: sourceVersion, image: sourceImage, imageDigest: sourceDigest, sourceRevision: packagedSourceRevision(sourceVersion), operatorImageDigest: expectedOperatorImageDigest(sourceVersion) },
+    target: { appVersion: pending.targetVersion, image: pending.targetImage, imageDigest: digest, sourceRevision: packagedSourceRevision(pending.targetVersion), operatorImageDigest: expectedOperatorImageDigest(pending.targetVersion) },
+    observed: { appVersion: pending.targetVersion, image: pending.targetImage, imageDigest: digest },
+    completedAt: now(),
+    rollbackBackupId: pending.backupId ?? "",
+    checks: revalidated.checks,
+    warnings: [],
+    phaseDurationsMs: {},
+    operatorHandoff: "not-required"
+  };
+  const next = stateFromEnv(directory, targetEnv, state.mode, "update", digest);
+  next.rollback = {
+    appVersion: sourceVersion,
+    image: sourceImage,
+    imageDigest: sourceDigest,
+    backupId: pending.backupId ?? "",
+    createdAt: now()
+  };
+  next.lastError = undefined;
+  if (targetEnv.OR3_DASHBOARD_UPDATES_ENABLED === "true" && recordedDashboardJobId) {
+    try {
+      await scheduleDashboardOperatorHandoff(directory, targetEnv, recordedDashboardJobId);
+      receipt.operatorHandoff = "pending";
+    } catch (error) {
+      receipt.operatorHandoff = "needs-attention";
+      receipt.warnings.push({ code: "operator-handoff-schedule-failed", severity: "warning", message: redact(error instanceof Error ? error.message : String(error), secretValues(targetEnv)) });
+    }
+  }
+  const commit = await commitTerminalState(directory, next, receipt);
+  await removeOperationRecordSafely(directory, commit.operationId);
+  const maintenance = [];
+  const prune = await pruneBackups(directory, next, BACKUP_RETENTION_KEEP, false, {
+    automatic: true,
+    log: (message) => report(message),
+    warn: (message) => report(message)
+  }).catch((error) => {
+    maintenance.push({ code: "retention-failed", severity: "warning", message: redact(error instanceof Error ? error.message : String(error), secretValues(targetEnv)) });
+    return { removed: 0, deferred: [] };
+  });
+  maintenance.push(...prune.deferred);
+  await persistReceiptWarnings(directory, next, maintenance);
+  const detail = `Finished the recorded update as OR3 ${pending.targetVersion}. Post-replacement writes were preserved.`;
+  report(detail);
+  for (const warning of [...receipt.warnings, ...maintenance])
+    report(`  ⚠ ${warning.code}: ${warning.message}`);
+  return detail;
+}
+async function recoverCommand(directory, flags = {}) {
+  assertRecoverFlags(flags);
+  const explicitRestore = boolFlag(flags, "restore");
+  const finishRequested = boolFlag(flags, "finish");
+  const dryRun = boolFlag(flags, "dry-run");
+  if (dryRun) {
+    const observation = await observeDeployment(directory, { checkDocker: true, checkImage: true });
+    const state = observation.state;
+    const decision = state ? decideRecoveryAction(state) : { action: "none", detail: "Managed state is unreadable; only diagnosis is available." };
+    const pending = state?.incompleteOperation;
+    const payload = {
+      schemaVersion: 1,
+      kind: "or3-recover-preview",
+      observedAt: observation.observedAt,
+      directory: observation.directory,
+      partial: observation.partial,
+      inProgress: observation.changing,
+      source: state ? { appVersion: state.appVersion, image: state.image, imageDigest: state.imageDigest } : null,
+      target: pending?.targetVersion ? { appVersion: pending.targetVersion, image: pending.targetImage ?? null, imageDigest: pending.targetImageDigest ?? null } : null,
+      phase: pending?.phase ?? null,
+      operation: pending?.operation ?? null,
+      decision,
+      dataLoss: decision.action === "require-explicit-restore",
+      findings: observationFindings(observation)
+    };
+    if (boolFlag(flags, "json"))
+      console.log(JSON.stringify(payload, null, 2));
+    else {
+      console.log(`OR3 recovery preview for ${observation.directory}`);
+      console.log(`  source: ${payload.source ? `OR3 ${payload.source.appVersion} (${payload.source.imageDigest})` : "unknown"}`);
+      console.log(`  target: ${payload.target ? `OR3 ${payload.target.appVersion}` : "none"}`);
+      console.log(`  operation: ${payload.operation ?? "none"}${payload.phase ? ` (${payload.phase})` : ""}`);
+      console.log(`  action: ${decision.action} — ${decision.detail}`);
+      if (payload.dataLoss)
+        console.log("  data loss: yes — restoring the recorded snapshot discards writes made after it.");
+      for (const finding of payload.findings)
+        console.log(`  [${finding.severity}] ${finding.code}: ${finding.message}`);
+      console.log(`
+Preview only: nothing was changed.`);
+    }
+    return;
+  }
+  const asJson = boolFlag(flags, "json");
+  const report = (...args) => {
+    if (asJson)
+      console.error(...args);
+    else
+      console.log(...args);
+  };
   await ensureDocker();
+  try {
+    const outcome = await runRecovery(directory, { explicitRestore, finishRequested, report });
+    if (asJson)
+      emitOperationResult(outcome);
+  } catch (error) {
+    if (!asJson)
+      throw error;
+    const message = redact(error instanceof Error ? error.message : String(error));
+    console.error(`OR3 Cloud failed: ${message}`);
+    emitOperationResult({ kind: "blocked", findings: [{ code: "recovery-failed", severity: "blocker", message, nextCommand: "npx @or3/cloud recover --dry-run" }] });
+    process.exitCode = 1;
+  }
+}
+async function runRecovery(directory, context) {
+  const { explicitRestore, finishRequested, report } = context;
   const loaded = await loadManaged(directory);
   const pending = loaded.state.incompleteOperation;
+  const decision = decideRecoveryAction(loaded.state);
+  if (decision.action === "reconcile-handoff") {
+    if (explicitRestore)
+      throw new Error("This deployment completed its application update; only the dashboard operator handoff needs reconciliation. Run `npx @or3/cloud recover --finish` without --restore.");
+    const detail = await reconcileOperatorHandoff(loaded.directory, loaded.state, report);
+    return { kind: "recovered", operation: "update", detail };
+  }
   if (!pending) {
-    console.log("No incomplete OR3 Cloud operation is recorded.");
-    return;
+    if (finishRequested) {
+      if (loaded.state.lastReceipt) {
+        const detail2 = `No incomplete operation is recorded; the last ${loaded.state.lastReceipt.operationId} completion remains authoritative. Nothing to finish.`;
+        report(detail2);
+        return { kind: "no-op", detail: detail2 };
+      }
+      throw new Error("recover --finish requires an incomplete operation, but none is recorded.");
+    }
+    const detail = "No incomplete OR3 Cloud operation is recorded.";
+    report(detail);
+    return { kind: "no-op", detail };
+  }
+  if (finishRequested) {
+    if (decision.action !== "finish") {
+      throw new Error(`recover --finish is not admissible: ${decision.detail} Run "npx @or3/cloud recover --dry-run" to inspect the supported actions.`);
+    }
+    const detail = await finishTargetReadyUpdate(loaded.directory, loaded.state, loaded.env, report);
+    return { kind: "recovered", operation: "update", detail };
   }
+  const requiresExplicitRestore = decision.action === "require-explicit-restore";
   try {
     if (pending.phase === "prepared") {
       if (pending.operation === "backup" || pending.operation === "update" || pending.operation === "adopt") {
@@ -2621,24 +3347,30 @@ async function recoverCommand(directory) {
       await applyCredentialReset(loaded.directory, loaded.state, nextEnv);
       loaded.state.lastError = undefined;
       await clearPending(loaded.directory, loaded.state);
-      console.log("Recovered the incomplete credential reset. Owner and admin credentials were verified inside the OR3 container.");
-      return;
+      const detail2 = "Recovered the incomplete credential reset. Owner and admin credentials were verified inside the OR3 container.";
+      report(detail2);
+      return { kind: "recovered", operation: "credentials-reset", detail: detail2 };
     }
     if (pending.operation === "restore" || pending.operation === "rollback") {
       if (pending.phase === "prepared" || pending.phase === "snapshot-created") {
         await startProject(loaded.directory, loaded.state.mode, loaded.env);
         loaded.state.lastError = undefined;
         await clearPending(loaded.directory, loaded.state);
-        console.log(`Recovered the incomplete ${pending.operation} before data replacement. OR3 ${loaded.state.appVersion} is deeply healthy.`);
-        return;
+        const detail3 = `Recovered the incomplete ${pending.operation} before data replacement. OR3 ${loaded.state.appVersion} is deeply healthy.`;
+        report(detail3);
+        return { kind: "recovered", operation: pending.operation, detail: detail3 };
+      }
+      if (requiresExplicitRestore && !explicitRestore) {
+        throw new Error(`The incomplete ${pending.operation} may have replaced data and has no completion proof. Nothing was changed. Review "npx @or3/cloud recover --dry-run", then restore deliberately with "npx @or3/cloud recover --restore --yes" (this discards writes made after the recorded snapshot).`);
       }
       if (!pending.previousBackupPath && !pending.previousBackupId) {
         throw new Error(`The incomplete ${pending.operation} has no verified pre-mutation snapshot. Refusing to replay a target that may have been partially restored; inspect the deployment and restore an authenticated backup explicitly.`);
       }
       const previous = await restorePreMutationSnapshot(loaded.directory, loaded.state, loaded.env);
       const recovered2 = await commitPreMutationRecovery(loaded.directory, loaded.state, `Interrupted ${pending.operation} was rolled back to pre-mutation snapshot ${previous.manifest.backupId}.`);
-      console.log(`Recovered the incomplete ${pending.operation} by restoring pre-mutation snapshot ${previous.manifest.backupId}. OR3 ${recovered2.appVersion} is deeply healthy.`);
-      return;
+      const detail2 = `Recovered the incomplete ${pending.operation} by restoring pre-mutation snapshot ${previous.manifest.backupId}. OR3 ${recovered2.appVersion} is deeply healthy.`;
+      report(detail2);
+      return { kind: "recovered", operation: pending.operation, detail: detail2 };
     }
     if (pending.operation === "update") {
       if (pending.phase === "prepared" || pending.phase === "snapshot-created") {
@@ -2648,16 +3380,25 @@ async function recoverCommand(directory) {
         recovered3.rollback = loaded.state.rollback;
         recovered3.lastError = undefined;
         await commitRecoveredState(loaded.directory, loaded.state, recovered3);
-        console.log(`Recovered the incomplete update before the replacement was applied. OR3 ${recovered3.appVersion} is deeply healthy.`);
-        return;
+        const detail3 = `Recovered the incomplete update before the replacement was applied. OR3 ${recovered3.appVersion} is deeply healthy.`;
+        report(detail3);
+        return { kind: "recovered", operation: "update", detail: detail3 };
+      }
+      if (decision.action === "finish" && !explicitRestore) {
+        const detail3 = await finishTargetReadyUpdate(loaded.directory, loaded.state, loaded.env, report);
+        return { kind: "recovered", operation: "update", detail: detail3 };
+      }
+      if (requiresExplicitRestore && !explicitRestore) {
+        throw new Error(`The incomplete update may have replaced data and has no completion proof. Nothing was changed. Review "npx @or3/cloud recover --dry-run", then restore deliberately with "npx @or3/cloud recover --restore --yes" (this discards writes made after the recorded pre-update snapshot).`);
       }
       if (!pending.backupPath && !pending.backupId) {
         throw new Error("The incomplete update has no verified pre-update snapshot. Refusing to guess which image or data should be live.");
       }
       const previous = await restorePreMutationSnapshot(loaded.directory, loaded.state, loaded.env);
       const recovered2 = await commitPreMutationRecovery(loaded.directory, loaded.state, `Interrupted update was rolled back to pre-update snapshot ${previous.manifest.backupId}.`);
-      console.log(`Recovered the incomplete update by restoring pre-update snapshot ${previous.manifest.backupId}. OR3 ${recovered2.appVersion} is deeply healthy.`);
-      return;
+      const detail2 = `Recovered the incomplete update by restoring pre-update snapshot ${previous.manifest.backupId}. OR3 ${recovered2.appVersion} is deeply healthy.`;
+      report(detail2);
+      return { kind: "recovered", operation: "update", detail: detail2 };
     }
     if (pending.operation === "adopt") {
       if (!pending.backupId)
@@ -2673,8 +3414,9 @@ async function recoverCommand(directory) {
     if (pending.operation === "backup" && pending.initialAppRunning === false) {
       loaded.state.lastError = undefined;
       await clearPending(loaded.directory, loaded.state);
-      console.log("Recovered the incomplete backup operation and preserved the intentionally stopped OR3 service.");
-      return;
+      const detail2 = "Recovered the incomplete backup operation and preserved the intentionally stopped OR3 service.";
+      report(detail2);
+      return { kind: "recovered", operation: "backup", detail: detail2 };
     }
     await pullAndRequireImage(loaded.state.image, loaded.state.imageDigest, "Current deployment");
     await startProject(loaded.directory, loaded.state.mode, loaded.env);
@@ -2691,7 +3433,9 @@ async function recoverCommand(directory) {
     recovered.rollback = loaded.state.rollback;
     recovered.lastError = undefined;
     await commitRecoveredState(loaded.directory, loaded.state, recovered);
-    console.log(`Recovered the incomplete ${pending.operation} operation. OR3 ${recovered.appVersion} is deeply healthy.`);
+    const detail = `Recovered the incomplete ${pending.operation} operation. OR3 ${recovered.appVersion} is deeply healthy.`;
+    report(detail);
+    return { kind: "recovered", operation: pending.operation, detail };
   } catch (error) {
     const recoverySecrets = pending.operation === "credentials-reset" ? secretValues(pending.credentialReset?.nextEnv ?? loaded.env) : secretValues(loaded.env);
     loaded.state.lastError = redact(error instanceof Error ? error.message : String(error), recoverySecrets);
@@ -2721,6 +3465,12 @@ function assertNoPending(state) {
     throw new Error(`An incomplete ${state.incompleteOperation.operation} is recorded. Run "npx @or3/cloud recover" before starting another operation.`);
   }
 }
+function assertPhaseAllowsCommand(command, state) {
+  const pending = state.incompleteOperation;
+  if (!pending || command === "stop")
+    return;
+  throw new Error(`An incomplete ${pending.operation}${pending.phase ? ` (${pending.phase})` : ""} is recorded. Refusing to ${command} an ambiguous deployment. Run "npx @or3/cloud recover --dry-run" to inspect the supported actions, then "npx @or3/cloud recover --finish" or "npx @or3/cloud recover --restore --yes".`);
+}
 async function backupCreateCommand(directory) {
   await ensureDocker();
   const loaded = await loadManaged(directory);
@@ -2741,26 +3491,66 @@ async function backupCreateCommand(directory) {
   try {
     const result = await createBackup(loaded.directory, loaded.state, loaded.env, { backupId, initiallyRunning: initialAppRunning });
     await clearPending(loaded.directory, loaded.state);
-    await pruneBackups(loaded.directory, loaded.state, BACKUP_RETENTION_KEEP, false);
+    const prune = await pruneBackups(loaded.directory, loaded.state, BACKUP_RETENTION_KEEP, false, { automatic: true });
     console.log(`Backup ${result.backupId} created at ${result.backupDir}`);
     console.log(`SHA-256: ${result.manifest.dataSha256}`);
+    if (prune.deferred.length > 0) {
+      console.warn(`Maintenance warning: ${prune.deferred.length} backup entr${prune.deferred.length === 1 ? "y" : "ies"} need inspection; all backups were preserved. Run "npx @or3/cloud backup list" for details.`);
+    }
   } catch (error) {
     loaded.state.lastError = redact(error instanceof Error ? error.message : String(error), secretValues(loaded.env));
     await writeState(loaded.directory, loaded.state);
     throw error;
   }
 }
-async function backupListCommand(directory) {
-  const loaded = await loadManaged(directory);
-  const backups = await enumerateBackups(loaded.directory);
-  if (backups.length === 0) {
-    console.log(`No authenticated backups are available for ${loaded.directory}. Run "npx @or3/cloud backup" to create one.`);
+async function backupListCommand(directory, flags = {}) {
+  const loaded = await loadManaged(directory, { writable: false });
+  const inventory = await inventoryBackups(loaded.directory);
+  const verified = inventory.entries.filter((entry) => entry.kind === "verified").map((entry) => entry.backup);
+  const findings = inventory.entries.filter((entry) => entry.kind !== "verified");
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      directory: loaded.directory,
+      backups: verified.map((backup) => ({
+        backupId: backup.backupId,
+        createdAt: backup.createdAt,
+        appVersion: backup.appVersion,
+        bytes: backup.bytes,
+        dataSha256: backup.dataSha256,
+        trust: "verified"
+      })),
+      findings: findings.map((entry) => ({ entryName: entry.entryName, kind: entry.kind, code: entry.code, message: entry.message })),
+      storeErrors: inventory.storeErrors
+    }, null, 2));
     return;
   }
-  console.log(`OR3 Cloud backups for ${loaded.directory} (${backups.length}):`);
-  console.log("backupId                      createdAt                      version  bytes     checksum");
-  for (const backup of backups) {
-    console.log(`${backup.backupId.padEnd(30)} ${backup.createdAt.padEnd(30)} ${backup.appVersion.padEnd(8)} ${String(backup.bytes).padStart(9)}  ${backup.dataSha256.slice(0, 12)}`);
+  if (verified.length === 0 && findings.length === 0) {
+    console.log(`No backups are available for ${loaded.directory}. Run "npx @or3/cloud backup" to create one.`);
+    return;
+  }
+  if (verified.length === 0) {
+    console.log(`No authenticated backups are available for ${loaded.directory}.`);
+  } else {
+    console.log(`OR3 Cloud backups for ${loaded.directory} (${verified.length} verified):`);
+    console.log("backupId                      createdAt                      version  bytes     trust     checksum");
+    for (const backup of verified) {
+      console.log(`${backup.backupId.padEnd(30)} ${backup.createdAt.padEnd(30)} ${backup.appVersion.padEnd(8)} ${String(backup.bytes).padStart(9)}  ${"verified".padEnd(9)} ${backup.dataSha256.slice(0, 12)}`);
+    }
+  }
+  if (findings.length > 0) {
+    console.log(`
+Preserved history (${findings.length}; never trusted for restore):`);
+    for (const entry of findings) {
+      console.log(`  ${entry.entryName.padEnd(30)} ${entry.kind.padEnd(16)} ${entry.code}`);
+      console.log(`    ${entry.message}`);
+    }
+    console.log(`
+To obtain a trusted restore point, create a new backup of the current healthy deployment: npx @or3/cloud backup`);
+  }
+  for (const diagnostic of inventory.storeErrors) {
+    console.log(`
+Store error (${diagnostic.severity}): ${diagnostic.message}`);
   }
   console.log(`
 Backups contain credentials and secrets; keep them owner-only and export off-host.`);
@@ -2771,9 +3561,18 @@ async function backupPruneCommand(directory, flags) {
   const keep = parseKeep(flags);
   const force = boolFlag(flags, "force");
   if (force && !boolFlag(flags, "yes"))
-    throw new Error("--force may delete the only rollback or recovery backup. Re-run with --force --yes after confirming the exact backups shown by `backup list`.");
-  const deleted = await pruneBackups(loaded.directory, loaded.state, keep, force);
-  console.log(deleted > 0 ? `Pruned ${deleted} backup(s); keeping the newest ${keep}.` : `Nothing to prune: keeping all backups (newest ${keep}).`);
+    throw new Error("--force may delete backups beyond the retention count. Re-run with --force --yes after confirming the exact backups shown by `backup list`.");
+  const result = await pruneBackups(loaded.directory, loaded.state, keep, force, { automatic: !force });
+  if (!force && result.deferred.length > 0 && result.removed === 0) {
+    throw new Error(`Backup pruning is blocked because the store contains entries that need inspection:
+${result.deferred.map((diagnostic) => `  ${diagnostic.code}: ${diagnostic.message}`).join(`
+`)}
+No backups were deleted. Run "npx @or3/cloud backup list" to inspect them, or re-run with --force --yes to prune only verified backups while preserving protected recovery sources.`);
+  }
+  console.log(result.removed > 0 ? `Pruned ${result.removed} backup(s); keeping the newest ${keep}.` : `Nothing to prune: keeping all backups (newest ${keep}).`);
+  if (result.deferred.length > 0) {
+    console.warn(`Preserved ${result.deferred.length} suspect or legacy entr${result.deferred.length === 1 ? "y" : "ies"} without deletion.`);
+  }
 }
 async function backupExportCommand(directory, backupId, destination) {
   const backupPath = await resolveBackup(directory, backupId);
@@ -2854,8 +3653,10 @@ async function backupCommand(directory, positionals, flags) {
   if (subcommand === "list") {
     if (positionals.length > 1)
       throw new Error("backup list accepts no arguments.");
-    return await backupListCommand(directory);
+    return await backupListCommand(directory, flags);
   }
+  if (boolFlag(flags, "json"))
+    throw new Error("--json is supported only by `backup list`.");
   if (subcommand === "prune") {
     if (positionals.length > 1)
       throw new Error("backup prune accepts no arguments.");
@@ -2872,7 +3673,184 @@ async function backupCommand(directory, positionals, flags) {
   }
   throw new Error(`Unknown backup subcommand "${subcommand}". Use list, prune, export, or no subcommand to create a backup.`);
 }
+function stateFingerprint(state) {
+  return createHash("sha256").update(JSON.stringify({
+    schema: state.schemaVersion,
+    appVersion: state.appVersion,
+    image: state.image,
+    imageDigest: state.imageDigest,
+    pending: state.incompleteOperation?.id ?? null
+  })).digest("hex").slice(0, 16);
+}
+async function assessUpdate(directory, targetVersion, options = {}) {
+  const checkDocker = options.checkDocker ?? false;
+  const observation = await observeDeployment(directory, { checkDocker, checkImage: false });
+  const state = observation.state;
+  const checks = [];
+  const findings = [...observationFindings(observation)];
+  const targetImage = imageFor(targetVersion);
+  if (!state) {
+    findings.push({ code: "state-unreadable", severity: "blocker", message: "Managed state must be readable to preview an update." });
+  } else if (state.incompleteOperation) {
+    findings.push({
+      code: "operation-incomplete",
+      severity: "blocker",
+      message: `An incomplete ${state.incompleteOperation.operation} is recorded. Run "npx @or3/cloud recover" before updating.`,
+      nextCommand: "npx @or3/cloud recover"
+    });
+  }
+  if (observation.changing && !options.underLease) {
+    findings.push({ code: "operation-in-progress", severity: "blocker", message: "A mutation lease is active; preview is non-executable until it settles." });
+  }
+  let noOp = false;
+  if (state && targetVersion === state.appVersion && !state.incompleteOperation) {
+    noOp = true;
+    checks.push({ code: "already-installed", status: "passed", detail: `OR3 ${targetVersion} is already the installed release; execution is a no-op.` });
+  } else {
+    checks.push({ code: "target-version", status: "passed", detail: `Target OR3 ${targetVersion} (${targetImage}).` });
+  }
+  try {
+    const stats = await statfs(deploymentPaths(directory).backups);
+    const freeBytes = Number(stats.bavail) * Number(stats.bsize);
+    checks.push({ code: "backup-filesystem-space", status: "passed", detail: `${freeBytes} bytes available on the backup filesystem.` });
+  } catch (error) {
+    checks.push({ code: "backup-filesystem-space", status: "unknown", detail: redact(error instanceof Error ? error.message : String(error)) });
+  }
+  checks.push({ code: "data-volume-space", status: "deferred", detail: "The live data-volume requirement is validated after the snapshot, before downtime." });
+  if (checkDocker) {
+    if (observation.docker) {
+      try {
+        const architecture = await dockerDaemonArchitecture();
+        checks.push({ code: "docker-availability", status: "passed", detail: `Docker daemon is reachable (${architecture}).` });
+      } catch (error) {
+        checks.push({ code: "docker-availability", status: "failed", detail: redact(error instanceof Error ? error.message : String(error)) });
+      }
+    } else {
+      checks.push({ code: "docker-availability", status: "unknown", detail: "The Docker daemon is not reachable from this host; it is revalidated at execution time." });
+    }
+  } else {
+    checks.push({ code: "docker-availability", status: "deferred", detail: "Docker availability and daemon architecture are revalidated at execution time." });
+  }
+  checks.push({ code: "image-pull", status: "deferred", detail: "The target image pull and architecture/provenance checks run at execution time." });
+  checks.push({ code: "fresh-snapshot", status: "deferred", detail: "A fresh authenticated snapshot is created at execution time." });
+  const plan = planRetention(observation.backups?.entries ?? [], BACKUP_RETENTION_KEEP, state ? retentionProtectedIds(state) : new Set, { automatic: true });
+  checks.push({
+    code: "retention",
+    status: plan.canPrune ? "passed" : "deferred",
+    detail: plan.canPrune ? `Would keep ${plan.keep.length} verified backup(s) and prune ${plan.remove.length}.` : `${plan.warnings.length} entry(ies) need inspection; automatic pruning is deferred and all backups are preserved.`
+  });
+  for (const warning of plan.warnings)
+    findings.push(warning);
+  if (options.inspectAssets !== false) {
+    const changed = [];
+    for (const name of managedAssetNames(state?.mode ?? "local")) {
+      let desired;
+      try {
+        desired = await readFile(join(ASSET_ROOT, name));
+      } catch (error) {
+        findings.push({
+          code: "managed-asset-unreadable",
+          severity: "blocker",
+          resource: name,
+          message: `Required generated asset ${name} could not be read from this CLI: ${redact(error instanceof Error ? error.message : String(error))}`
+        });
+        continue;
+      }
+      try {
+        const installedPath = join(directory, name);
+        if (!await fileExists(installedPath)) {
+          changed.push(`${name} (add)`);
+          continue;
+        }
+        const installed = await readFile(installedPath);
+        if (!installed.equals(desired))
+          changed.push(`${name} (update)`);
+      } catch (error) {
+        findings.push({
+          code: "managed-asset-unreadable",
+          severity: "blocker",
+          resource: name,
+          message: `Installed generated asset ${name} could not be read from ${directory}: ${redact(error instanceof Error ? error.message : String(error))}`
+        });
+      }
+    }
+    checks.push(changed.length ? { code: "managed-assets", status: "passed", detail: `Generated assets change: ${changed.join(", ")}.` } : { code: "managed-assets", status: "passed", detail: "Generated assets are unchanged." });
+  }
+  try {
+    assertKnownStateSchema(state?.schemaVersion);
+    checks.push({ code: "state-schema", status: "passed", detail: `Managed state schema ${String(state?.schemaVersion)} is supported.` });
+  } catch (error) {
+    findings.push({ code: "state-schema-unsupported", severity: "blocker", message: error instanceof Error ? error.message : String(error) });
+  }
+  const blockers = findings.filter((finding) => finding.severity === "blocker");
+  blockers.sort((a, b) => a.code < b.code ? -1 : a.code > b.code ? 1 : 0);
+  return {
+    schemaVersion: 1,
+    observedAt: observation.observedAt,
+    source: state ? { appVersion: state.appVersion, image: state.image, imageDigest: state.imageDigest } : null,
+    target: { appVersion: targetVersion, image: targetImage, imageDigest: expectedImageDigest(targetVersion) ?? "unknown" },
+    checks,
+    findings: [...blockers, ...findings.filter((finding) => finding.severity !== "blocker")],
+    retention: plan,
+    stateFingerprint: state ? stateFingerprint(state) : "unavailable"
+  };
+}
+async function updatePreviewCommand(directory, flags) {
+  const targetVersion = stringFlag(flags, "to")?.trim() ?? PACKAGE_VERSION;
+  if (!isVersion(targetVersion))
+    throw new Error(`--to must be a complete semantic version such as ${PACKAGE_VERSION}.`);
+  if (targetVersion !== PACKAGE_VERSION) {
+    throw new Error(`This CLI contains deployment assets for OR3 ${PACKAGE_VERSION}. Preview the matching CLI with \`npx --yes @or3/cloud@${targetVersion} update --to ${targetVersion} --dry-run\`.`);
+  }
+  const assessment = await assessUpdate(directory, targetVersion, { checkDocker: true });
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({ ...assessment, kind: "or3-update-preview" }, null, 2));
+  } else {
+    console.log(`OR3 update preview for ${directory}`);
+    console.log(`  source: ${assessment.source ? `OR3 ${assessment.source.appVersion} (${assessment.source.imageDigest})` : "unknown"}`);
+    console.log(`  target: OR3 ${assessment.target.appVersion} (${assessment.target.imageDigest})`);
+    console.log(`  state fingerprint: ${assessment.stateFingerprint}`);
+    console.log();
+    for (const check of assessment.checks)
+      console.log(`  [${check.status}] ${check.code}: ${check.detail}`);
+    console.log();
+    for (const finding of assessment.findings)
+      console.log(`  [${finding.severity}] ${finding.code}: ${finding.message}`);
+    if (assessment.retention.preserve.length) {
+      console.log(`
+  Preserved backups:`);
+      for (const entry of assessment.retention.preserve)
+        console.log(`    ${entry.entryName}: ${entry.reason}`);
+    }
+    console.log(`
+Dry run only: no state, assets, lease, images, services, snapshots, or backups were changed.`);
+  }
+  if (assessment.findings.some((finding) => finding.severity === "blocker"))
+    process.exitCode = 1;
+}
 async function updateCommand(directory, flags) {
+  const asJson = boolFlag(flags, "json");
+  try {
+    return await runUpdateCommand(directory, flags, asJson);
+  } catch (error) {
+    if (!asJson)
+      throw error;
+    const message = redact(error instanceof Error ? error.message : String(error));
+    console.error(`OR3 Cloud failed: ${message}`);
+    emitOperationResult({
+      kind: "blocked",
+      findings: [{ code: "update-failed", severity: "blocker", message, nextCommand: "npx @or3/cloud recover --dry-run" }]
+    });
+    process.exitCode = 1;
+  }
+}
+async function runUpdateCommand(directory, flags, asJson) {
+  const progress = (...args) => {
+    if (asJson)
+      console.error(...args);
+    else
+      console.log(...args);
+  };
   await ensureDocker();
   const loaded = await loadManaged(directory);
   const { state, env } = loaded;
@@ -2884,8 +3862,18 @@ async function updateCommand(directory, flags) {
   if (targetVersion !== PACKAGE_VERSION) {
     throw new Error(`This CLI contains deployment assets for OR3 ${PACKAGE_VERSION}. Run \`npx --yes @or3/cloud@${targetVersion} update --to ${targetVersion}\` so the image and generated assets match.`);
   }
-  if (targetVersion === state.appVersion)
-    throw new Error(`The deployment is already on OR3 ${targetVersion}.`);
+  if (targetVersion === state.appVersion) {
+    if (asJson)
+      emitOperationResult({ kind: "no-op", detail: `OR3 ${targetVersion} is already installed.`, currentVersion: state.appVersion, targetVersion });
+    else
+      progress(`OR3 ${targetVersion} is already installed. Nothing to do.`);
+    return;
+  }
+  const preflight = await assessUpdate(loaded.directory, targetVersion, { underLease: true, checkDocker: true });
+  const preflightBlockers = preflight.findings.filter((finding) => finding.severity === "blocker");
+  if (preflightBlockers.length > 0) {
+    throw new Error(`Update to ${targetVersion} is blocked by preflight: ${preflightBlockers.map((finding) => `${finding.code} (${finding.message})`).join(" ")}`);
+  }
   const targetImageTag = imageFor(targetVersion);
   const targetDigest = await pullImage(targetImageTag, expectedImageDigest(targetVersion));
   await assertSupportedHostArchitecture(targetImageTag);
@@ -2908,16 +3896,32 @@ async function updateCommand(directory, flags) {
     phase: "prepared"
   };
   await markPending(loaded.directory, state, pending);
+  const startedAtMs = Date.now();
   try {
+    const operator = await prepareVerifiedDashboardOperator(loaded.directory, targetVersion);
     const backup = await createBackup(loaded.directory, state, env, { restartAfter: false, backupId });
+    const writeSchema = writeStateSchema();
+    if (writeSchema >= 2) {
+      const minimumSource = packagedMinimumSourceVersion();
+      if (minimumSource && compareReleaseVersions(state.appVersion, minimumSource) < 0) {
+        throw new Error(`OR3 ${targetVersion} writes managed state schema 2, which requires the compatibility bridge (source ${minimumSource} or newer). Run the host CLI bridge update first, then retry this schema-2 release.`);
+      }
+      state.schemaVersion = writeSchema;
+    }
     await updatePending(loaded.directory, state, {
       backupId: backup.backupId,
       backupPath: backup.backupDir,
       backupDataSha256: backup.manifest.dataSha256,
       backupConfigSha256: backup.manifest.configSha256,
-      phase: "snapshot-created"
+      phase: "snapshot-created",
+      verifiedSnapshot: {
+        backupId: backup.backupId,
+        path: backup.backupDir,
+        dataSha256: backup.manifest.dataSha256,
+        configSha256: backup.manifest.configSha256 ?? "",
+        createdAt: backup.manifest.createdAt
+      }
     });
-    const operator = await prepareVerifiedDashboardOperator(loaded.directory, targetVersion);
     if (env.OR3_DASHBOARD_UPDATES_ENABLED === "true" && !operator && !process.env.OR3_DASHBOARD_UPDATE_JOB_ID) {
       await removeDashboardOperator(loaded.directory, state.mode);
     }
@@ -2953,7 +3957,6 @@ async function updateCommand(directory, flags) {
       if (migrateLegacyVolume || recreateDataVolume) {
         await restoreVolumeArchive(loaded.directory, state.mode, nextEnv, backup.backupDir);
       }
-      await startProject(loaded.directory, state.mode, nextEnv);
     } catch (error) {
       await updatePending(loaded.directory, state, { phase: "restoring-previous" });
       try {
@@ -2971,11 +3974,88 @@ async function updateCommand(directory, flags) {
       const recovered = await commitPreMutationRecovery(loaded.directory, state, `Update to ${targetVersion} failed and was restored: ${redact(error instanceof Error ? error.message : String(error), secretValues(oldEnv))}`);
       throw new Error(recovered.lastError);
     }
+    await updatePending(loaded.directory, state, { phase: "starting-target" });
+    try {
+      await startProject(loaded.directory, state.mode, nextEnv);
+    } catch (error) {
+      throw new Error(`Update to ${targetVersion} started the target but it did not pass verification: ${redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv))}. Writes may have been accepted, so the deployment was NOT restored automatically. Run "npx @or3/cloud recover --dry-run", then "npx @or3/cloud recover --finish" if the target is proven, or "npx @or3/cloud recover --restore --yes" to return to the pre-update snapshot.`);
+    }
     const digest = await requireImageDigest(targetImage, targetDigest, `OR3 ${targetVersion}`);
+    const targetChecks = await collectTargetReadyChecks(loaded.directory, state.mode, nextEnv);
+    const failedTargetChecks = targetChecks.checks.filter((check) => check.status !== "passed");
+    if (!targetChecks.containerId || failedTargetChecks.length > 0) {
+      throw new Error(`Update to ${targetVersion} did not pass the required target checks (${failedTargetChecks.map((check) => check.code).join(", ") || "container-binding"}). Writes may have been accepted, so the deployment was NOT restored automatically. Run "npx @or3/cloud recover --dry-run", then "npx @or3/cloud recover --restore --yes" to return to the pre-update snapshot.`);
+    }
+    const targetReadyEvidence = {
+      checkedAt: now(),
+      deploymentId: targetDeploymentId,
+      deploymentRoot: resolve(loaded.directory),
+      containerId: targetChecks.containerId,
+      imageDigest: digest,
+      configurationSha256: await sha256File(deploymentPaths(loaded.directory).env),
+      managedAssetSha256: await installedManagedAssetChecksums(loaded.directory, state.mode),
+      dataReplacementCompleted: true,
+      checks: [
+        { code: "image-digest", status: "passed", detail: `${targetImage}@${digest}` },
+        { code: "deep-health", status: "passed", detail: "OR3 deep health and running-image identity verified" },
+        ...targetChecks.checks
+      ]
+    };
+    if (writeSchema >= 2) {
+      await updatePending(loaded.directory, state, { phase: "target-ready", evidence: targetReadyEvidence });
+    }
+    const warnings = [];
+    const hadDashboardJob = Boolean(process.env.OR3_DASHBOARD_UPDATE_JOB_ID);
+    let operatorHandoff = "not-required";
+    if (nextEnv.OR3_DASHBOARD_UPDATES_ENABLED === "true" && hadDashboardJob) {
+      try {
+        await scheduleDashboardOperatorHandoff(loaded.directory, nextEnv);
+        operatorHandoff = "pending";
+      } catch (error) {
+        operatorHandoff = "needs-attention";
+        warnings.push({
+          code: "operator-handoff-schedule-failed",
+          severity: "warning",
+          resource: pending.id,
+          message: `The application is upgraded, but the dashboard operator handoff could not be scheduled: ${redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv))}. Run "npx @or3/cloud recover --finish" on the host.`,
+          nextCommand: "npx @or3/cloud recover --finish"
+        });
+      }
+    }
+    const sourceVersion = state.appVersion;
+    const sourceImage = state.image;
+    const sourceDigest = state.imageDigest;
+    const receipt = {
+      schemaVersion: 1,
+      operationId: pending.id,
+      dashboardJobId: process.env.OR3_DASHBOARD_UPDATE_JOB_ID?.trim() || undefined,
+      cliVersion: PACKAGE_VERSION,
+      source: {
+        appVersion: sourceVersion,
+        image: sourceImage,
+        imageDigest: sourceDigest,
+        sourceRevision: packagedSourceRevision(sourceVersion),
+        operatorImageDigest: expectedOperatorImageDigest(sourceVersion)
+      },
+      target: {
+        appVersion: targetVersion,
+        image: targetImage,
+        imageDigest: digest,
+        sourceRevision: packagedSourceRevision(targetVersion),
+        operatorImageDigest: expectedOperatorImageDigest(targetVersion)
+      },
+      observed: { appVersion: targetVersion, image: targetImage, imageDigest: digest },
+      completedAt: now(),
+      rollbackBackupId: backup.backupId,
+      checks: targetReadyEvidence.checks,
+      warnings,
+      phaseDurationsMs: { "replace-and-verify": Date.now() - startedAtMs },
+      operatorHandoff
+    };
     state.rollback = {
-      appVersion: state.appVersion,
-      image: state.image,
-      imageDigest: state.imageDigest,
+      appVersion: sourceVersion,
+      image: sourceImage,
+      imageDigest: sourceDigest,
       backupId: backup.backupId,
       createdAt: now()
     };
@@ -2986,11 +4066,39 @@ async function updateCommand(directory, flags) {
     state.deploymentRoot = resolve(loaded.directory);
     state.lastSuccessfulOperation = "update";
     state.lastError = undefined;
-    await pruneBackups(loaded.directory, state, BACKUP_RETENTION_KEEP, false);
-    await scheduleDashboardOperatorHandoff(loaded.directory, nextEnv);
-    await clearPending(loaded.directory, state);
-    console.log(`OR3 updated to ${targetVersion}. Image digest: ${digest}`);
-    console.log(`Rollback point: ${backup.backupId}. Keep it until login, chat, and file checks pass.`);
+    let commit;
+    try {
+      commit = await commitTerminalState(loaded.directory, state, receipt);
+    } catch (error) {
+      throw new Error(`OR3 ${targetVersion} replaced the running release, but the terminal state write could not be confirmed. Recovery evidence was preserved; re-run status/doctor and "npx @or3/cloud recover" to resolve the durable outcome before any further mutation. ${redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv))}`);
+    }
+    try {
+      await removeOperationRecord(loaded.directory, commit.operationId);
+    } catch (error) {
+      warnings.push({ code: "operation-mirror-delete-failed", severity: "warning", resource: commit.operationId, message: redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv)) });
+    }
+    const prune = await pruneBackups(loaded.directory, state, BACKUP_RETENTION_KEEP, false, { automatic: true, log: progress, warn: progress }).catch((error) => {
+      warnings.push({ code: "retention-failed", severity: "warning", message: redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv)) });
+      return { removed: 0, deferred: [] };
+    });
+    for (const diagnostic of prune.deferred)
+      warnings.push(diagnostic);
+    progress(`OR3 updated to ${targetVersion}. Image digest: ${digest}`);
+    progress(`Rollback point: ${backup.backupId}. Keep it until login, chat, and file checks pass.`);
+    progress("Not checked: live OpenRouter authorization (complete it in the browser).");
+    if (warnings.length > 0) {
+      warnings.forEach((warning) => console.warn(`⚠ ${warning.code}: ${warning.message}`));
+    }
+    await persistReceiptWarnings(loaded.directory, state, warnings);
+    if (asJson) {
+      const outcome = warnings.length > 0 ? { kind: "completed-with-warnings", receipt, warnings } : { kind: "completed", receipt };
+      emitOperationResult(outcome);
+    } else if (warnings.length > 0) {
+      console.log(`Update complete with ${warnings.length} maintenance warning(s).`);
+      console.log("Next: npx @or3/cloud backup list");
+    } else {
+      console.log("Update complete. No maintenance warnings.");
+    }
   } catch (error) {
     if (state.incompleteOperation) {
       state.lastError = redact(error instanceof Error ? error.message : String(error), secretValues(env));
@@ -3110,8 +4218,8 @@ async function restoreCommand(directory, flags, positionals) {
     const digest = await imageDigest(restoredEnv.OR3_IMAGE);
     const nextState = stateFromEnv(loaded.directory, restoredEnv, loaded.state.mode, "restore", digest);
     nextState.lastError = undefined;
-    await removeOperationRecord(loaded.directory, pending.id);
     await writeState(loaded.directory, nextState);
+    await removeOperationRecordSafely(loaded.directory, pending.id);
     console.log(`Restored ${manifest.backupId}. Verify sign-in, a conversation, and a previously uploaded file.`);
   } catch (error) {
     const original = redact(error instanceof Error ? error.message : String(error), secretValues(loaded.env));
@@ -3201,8 +4309,8 @@ async function rollbackCommand(directory, flags) {
     const restoredEnv = parseEnv(await readText(deploymentPaths(loaded.directory).env));
     const nextState = stateFromEnv(loaded.directory, restoredEnv, loaded.state.mode, "restore", await imageDigest(restoredEnv.OR3_IMAGE));
     nextState.rollback = undefined;
-    await removeOperationRecord(loaded.directory, pending.id);
     await writeState(loaded.directory, nextState);
+    await removeOperationRecordSafely(loaded.directory, pending.id);
     console.log(`Rolled back to OR3 ${nextState.appVersion}. Verify sign-in, chat, and file access.`);
   } catch (error) {
     const original = redact(error instanceof Error ? error.message : String(error), secretValues(loaded.env));
@@ -3739,6 +4847,53 @@ ${redact(serious.slice(-20).join(`
   console.log("✓ Recent bounded logs contain no fatal, panic, unhandled, or OOM events");
   console.log("OR3 production verification passed.");
 }
+async function verifyReadOnlyCommand(directory, flags) {
+  const observation = await observeDeployment(directory, { checkDocker: true, checkImage: true });
+  const state = observation.state;
+  if (!state) {
+    throw new Error(`Read-only verification needs readable managed state.${observation.stateError ? ` ${observation.stateError}` : ""} Run "npx @or3/cloud doctor" for diagnostics.`);
+  }
+  if (boolFlag(flags, "public") && state.mode !== "public")
+    throw new Error("--public requires a managed public deployment.");
+  const checks = [];
+  const findings = observationFindings(observation);
+  checks.push(observation.identityMatches === true ? { code: "image-digest", status: "passed", detail: `Recorded digest matches the local image (${state.imageDigest}).` } : observation.identityMatches === false ? { code: "image-digest", status: "failed", detail: `Recorded ${observation.recordedImageDigest} does not match local ${observation.actualImageDigest}.` } : { code: "image-digest", status: "unknown", detail: "The managed image could not be inspected safely." });
+  const baseUrl = new URL(state.mode === "public" ? `https://${state.domain}` : `http://127.0.0.1:${state.port}`);
+  try {
+    const root = await verificationFetch(baseUrl);
+    checks.push(root.status === 200 ? { code: "http-root", status: "passed", detail: `${baseUrl.origin} returned HTTP 200 without redirects.` } : { code: "http-root", status: "failed", detail: `${baseUrl.origin} returned HTTP ${root.status}.` });
+  } catch (error) {
+    checks.push({ code: "http-root", status: "failed", detail: redact(error instanceof Error ? error.message : String(error)) });
+  }
+  try {
+    validateVerificationHealth(await verificationJson(baseUrl, "/api/health?deep=true"));
+    checks.push({ code: "deep-health", status: "passed", detail: "Deep health reports the managed Basic Auth + SQLite + filesystem profile." });
+  } catch (error) {
+    checks.push({ code: "deep-health", status: "failed", detail: redact(error instanceof Error ? error.message : String(error)) });
+  }
+  checks.push({ code: "auth-and-storage-journey", status: "deferred", detail: "Sign-in, sync, and storage probes are excluded from read-only verification." });
+  checks.push({ code: "sqlite-integrity", status: "deferred", detail: "SQLite inspection is deferred because a safe read-only mechanism is unavailable." });
+  checks.push({ code: "bounded-logs", status: "deferred", detail: "Log scanning is deliberately skipped by read-only verification; run full verify for it." });
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      kind: "or3-verify-read-only",
+      observedAt: observation.observedAt,
+      directory: observation.directory,
+      readOnly: true,
+      checks,
+      findings
+    }, null, 2));
+  } else {
+    for (const check of checks)
+      console.log(`  [${check.status}] ${check.code}: ${check.detail}`);
+    for (const finding of findings)
+      console.log(`  [${finding.severity}] ${finding.code}: ${finding.message}`);
+  }
+  if (checks.some((check) => check.status === "failed")) {
+    process.exitCode = 1;
+  }
+}
 async function readSourceVolume(sourceDirectory) {
   const composeResult = await run("docker", [
     "compose",
@@ -4353,37 +5508,79 @@ async function credentialsCommand(directory, positionals, flags) {
     throw new Error("credentials reset accepts no arguments.");
   return await credentialsResetCommand(directory, flags);
 }
-async function statusCommand(directory) {
-  const loaded = await loadManaged(directory);
-  assertDeploymentDirectoryIdentity(directory, loaded.state);
-  const { state } = loaded;
-  console.log(`OR3 Cloud deployment: ${loaded.directory}`);
-  console.log(`  mode: ${state.mode}`);
-  console.log(`  version: ${state.appVersion}`);
-  if (state.domain)
-    console.log(`  domain: ${state.domain}`);
-  console.log(`  port: ${state.port}`);
-  console.log(`  image digest: ${state.imageDigest}`);
-  console.log(`  last successful operation: ${state.lastSuccessfulOperation} (${state.updatedAt})`);
-  if (state.incompleteOperation)
-    console.log(`  incomplete operation: ${state.incompleteOperation.operation} (${state.incompleteOperation.id})`);
-  if (state.lastError)
-    console.log(`  last error: ${state.lastError}`);
-  console.log();
-  const ps = await run("docker", [...composeArgs(directory, state.mode, ["ps"])], directory);
-  if (ps.ok) {
-    console.log(ps.stdout.trim());
+async function statusCommand(directory, flags = {}) {
+  const observation = await observeDeployment(directory, { checkDocker: true, checkImage: true });
+  const findings = observationFindings(observation);
+  const state = observation.state;
+  if (boolFlag(flags, "json")) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      kind: "or3-deployment-status",
+      observedAt: observation.observedAt,
+      partial: observation.partial,
+      inProgress: observation.changing,
+      directory: observation.directory,
+      state: state ? publicStateProjection(state) : null,
+      stateError: observation.stateError,
+      envError: observation.envError,
+      lease: observation.lease.status,
+      docker: observation.docker,
+      recordedImageDigest: observation.recordedImageDigest,
+      actualImageDigest: observation.actualImageDigest,
+      identityMatches: observation.identityMatches,
+      lastReceipt: state?.lastReceipt ?? null,
+      backups: observation.backups,
+      findings
+    }, null, 2));
+    return;
+  }
+  console.log(`OR3 Cloud deployment: ${observation.directory}`);
+  if (observation.changing)
+    console.log("  status: in progress (a mutation lease is active; this observation is not authoritative)");
+  if (!state) {
+    console.log(`  state: unreadable${observation.stateError ? ` — ${observation.stateError}` : ""}`);
   } else {
-    console.log(`Could not list containers: ${ps.stderr}`);
+    console.log(`  mode: ${state.mode}`);
+    console.log(`  version: ${state.appVersion}`);
+    if (state.domain)
+      console.log(`  domain: ${state.domain}`);
+    console.log(`  port: ${state.port}`);
+    console.log(`  image digest: ${state.imageDigest}`);
+    console.log(`  last successful operation: ${state.lastSuccessfulOperation} (${state.updatedAt})`);
+    if (state.incompleteOperation)
+      console.log(`  incomplete operation: ${state.incompleteOperation.operation} (${state.incompleteOperation.id})`);
+    if (state.lastError)
+      console.log(`  last error: ${state.lastError}`);
+  }
+  if (observation.envError)
+    console.log(`  environment: unreadable — ${observation.envError}`);
+  if (observation.identityMatches === false)
+    console.log(`  image: MISMATCH (recorded ${observation.recordedImageDigest}, local ${observation.actualImageDigest})`);
+  else if (observation.identityMatches === true)
+    console.log("  image: digest matches managed state");
+  console.log();
+  if (state && observation.docker && observation.env) {
+    try {
+      const ps = await run("docker", [...composeArgs(directory, state.mode, ["ps"])], directory);
+      console.log(ps.ok ? ps.stdout.trim() : `Could not list containers: ${ps.stderr}`);
+      const health = await probeDeepHealth(directory, state.mode);
+      if (health === "ok")
+        console.log("Deep health: OK");
+      else if (health === "degraded")
+        console.log("Deep health: DEGRADED (the container is running but /api/health?deep=true is failing).");
+      else
+        console.log("Deep health: unreachable (the or3 container is not running).");
+      await printMaintenanceSummary(directory, state.mode);
+    } catch (error) {
+      console.log(`Container and health checks were skipped: ${redact(error instanceof Error ? error.message : String(error))}`);
+    }
+  } else if (state && !observation.docker) {
+    console.log("Docker is unavailable; container and health checks were skipped.");
+  } else if (state && !observation.env) {
+    console.log("The managed environment is unreadable; container and health checks were skipped.");
   }
-  const health = await probeDeepHealth(directory, state.mode);
-  if (health === "ok")
-    console.log("Deep health: OK");
-  else if (health === "degraded")
-    console.log("Deep health: DEGRADED (the container is running but /api/health?deep=true is failing).");
-  else
-    console.log("Deep health: unreachable (the or3 container is not running).");
-  await printMaintenanceSummary(directory, state.mode);
+  for (const finding of findings)
+    console.log(`  [${finding.severity}] ${finding.code}: ${finding.message}`);
 }
 async function printMaintenanceSummary(directory, mode) {
   const result = await run("docker", [...composeArgs(directory, mode, ["exec", "-T", "or3", ...containerNodeCommand(MAINTENANCE_SCRIPT)])], directory);
@@ -4403,7 +5600,7 @@ async function printMaintenanceSummary(directory, mode) {
   } catch {}
 }
 async function logsCommand(directory, flags, positionals) {
-  const loaded = await loadManaged(directory);
+  const loaded = await loadManaged(directory, { writable: false });
   assertDeploymentDirectoryIdentity(directory, loaded.state);
   if (positionals.length > 1)
     throw new Error("logs accepts at most one service name.");
@@ -4432,6 +5629,7 @@ async function startCommand(directory) {
   await ensureDocker();
   const loaded = await loadManaged(directory);
   assertDeploymentDirectoryIdentity(directory, loaded.state);
+  assertPhaseAllowsCommand("start", loaded.state);
   await startProject(directory, loaded.state.mode, loaded.env);
   const url = loaded.state.mode === "public" ? `https://${loaded.state.domain}` : `http://127.0.0.1:${loaded.state.port}`;
   console.log(`OR3 started and is deeply healthy at ${url}.`);
@@ -4447,6 +5645,7 @@ async function restartCommand(directory) {
   await ensureDocker();
   const loaded = await loadManaged(directory);
   assertDeploymentDirectoryIdentity(directory, loaded.state);
+  assertPhaseAllowsCommand("restart", loaded.state);
   await compose(directory, loaded.state.mode, ["restart", "or3"]);
   await waitForDeepHealth(directory, loaded.state.mode, secretValues(loaded.env));
   console.log("OR3 restarted and is deeply healthy.");
@@ -4588,8 +5787,11 @@ async function main(argv = process.argv.slice(2)) {
     const dispatch = async () => {
       if (command === "init")
         return await initCommand(parsed.positionals, parsed.flags);
-      if (command === "update")
+      if (command === "update") {
+        if (boolFlag(parsed.flags, "dry-run"))
+          return await updatePreviewCommand(process.cwd(), parsed.flags);
         return await updateCommand(process.cwd(), parsed.flags);
+      }
       if (command === "backup")
         return await backupCommand(process.cwd(), parsed.positionals, parsed.flags);
       if (command === "restore")
@@ -4600,14 +5802,17 @@ async function main(argv = process.argv.slice(2)) {
         return await credentialsCommand(process.cwd(), parsed.positionals, parsed.flags);
       if (command === "doctor")
         return await doctorCommand(process.cwd());
-      if (command === "verify")
+      if (command === "verify") {
+        if (verifyIsReadOnly(parsed.flags))
+          return await verifyReadOnlyCommand(process.cwd(), parsed.flags);
         return await verifyCommand(process.cwd(), parsed.flags, parsed.positionals);
+      }
       if (command === "recover")
-        return await recoverCommand(process.cwd());
+        return await recoverCommand(process.cwd(), parsed.flags);
       if (command === "adopt")
         return await adoptCommand(parsed.positionals, parsed.flags);
       if (command === "status")
-        return await statusCommand(process.cwd());
+        return await statusCommand(process.cwd(), parsed.flags);
       if (command === "logs")
         return await logsCommand(process.cwd(), parsed.flags, parsed.positionals);
       if (command === "start")
@@ -4620,7 +5825,8 @@ async function main(argv = process.argv.slice(2)) {
         return await removeCommand(process.cwd(), parsed.flags);
       throw new Error(`Unknown command "${command}". Run npx @or3/cloud --help.`);
     };
-    if (MUTATING_COMMANDS.has(command)) {
+    const readOnlyInvocation = command === "verify" && verifyIsReadOnly(parsed.flags) || command === "update" && boolFlag(parsed.flags, "dry-run") || command === "recover" && boolFlag(parsed.flags, "dry-run") || command === "backup" && parsed.positionals[0] === "list";
+    if (!readOnlyInvocation && MUTATING_COMMANDS.has(command)) {
       return await withDeploymentLease(mutationDirectory(command, parsed.positionals, parsed.flags), command, dispatch);
     }
     return await dispatch();
@@ -4635,12 +5841,15 @@ if (invokedAsCli || process.argv[1] && resolve(process.argv[1]) === resolve(file
   await main();
 }
 export {
+  writeStateSchema,
   withoutProvisioningCredentials,
+  verifyIsReadOnly,
   validateVerificationHealth,
   validatePassword,
   updateRequiresVolumeRecreation,
   supportedImageArchitectures,
   stateFromEnv,
+  stateFingerprint,
   snapshotManagedAssets,
   serializeInitialCredentials,
   serializeEnv,
@@ -4652,28 +5861,45 @@ export {
   redact,
   recordedBackupPath,
   purgeVolumesFromState,
+  publicStateProjection,
+  planRetention,
   parseFlags,
   parseEnv,
+  packagedMinimumSourceVersion,
+  observeDeployment,
+  observationFindings,
   managedAssetNames,
+  lifecycleFaults,
   isVersion,
+  inventoryBackups,
+  installedManagedAssetChecksums,
   enumerateBackups,
+  decideRecoveryAction,
   dashboardOperatorHandoffArgs,
   copyAssets,
+  compareReleaseVersions,
   checkResolvedLoopbackBinding,
   buildEnv,
   buildCredentialsResetScript,
+  assessUpdate,
   assertVerificationGrant,
   assertSupportedSourceCompose,
   assertSupportedSource,
   assertSupportedArchitecture,
+  assertStateSchemaWritable,
   assertRemovableArtifactName,
   assertPurgeBackupFreshness,
+  assertPhaseAllowsCommand,
+  assertKnownStateSchema,
   assertImageReleaseLabels,
   assertEnoughFreeSpace,
   assertDashboardOperatorMounts,
   assertCommandPositionals,
   assertCommandFlags,
   assertBackupMatchesDeployment,
+  STATE_SCHEMA_COMPATIBILITY,
+  READER_SUPPORTED_STATE_SCHEMAS,
   PACKAGE_VERSION,
+  MAX_SUPPORTED_STATE_SCHEMA,
   IMAGE_REPOSITORY
 };