@or3/cloud 0.1.15 → 0.1.34

package/dist/cli.mjs

@@ -2,12 +2,12 @@
 
 // src/cli.ts
 import { createHash, randomBytes } from "node:crypto";
-import { execFile as execFileCallback } from "node:child_process";
+import { execFile as execFileCallback, spawn } from "node:child_process";
 import { createServer } from "node:net";
 import { lookup } from "node:dns/promises";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { existsSync } from "node:fs";
+import { createReadStream, createWriteStream, existsSync } from "node:fs";
 import {
   chmod,
   copyFile,
@@ -17,22 +17,31 @@ import {
   rename,
   rm,
   stat,
+  statfs,
   writeFile
 } from "node:fs/promises";
+import { Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { promisify } from "node:util";
-import { dirname, basename, isAbsolute, join, resolve } from "node:path";
+import { dirname, basename, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createGunzip } from "node:zlib";
 var execFile = promisify(execFileCallback);
-var PACKAGE_VERSION = "0.1.15";
+var PACKAGE_VERSION = "0.1.34";
 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 DEFAULT_PORT = 3000;
 var DEEP_HEALTH_TIMEOUT_MS = 180000;
+var BACKUP_RETENTION_KEEP = 5;
+var PURGE_REQUIRES_BACKUP_WITHIN_MS = 24 * 60 * 60 * 1000;
+var FREE_SPACE_HEADROOM_BYTES = 64 * 1024 * 1024;
+var BACKUP_ID_PATTERN = /^backup-[0-9A-Za-z-]+$/;
 var SECRET_KEYS = [
   "OR3_BASIC_AUTH_JWT_SECRET",
   "OR3_BASIC_AUTH_REFRESH_SECRET",
   "OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD",
+  "OR3_AUTH_INVITE_TOKEN_SECRET",
   "OR3_STORAGE_FS_TOKEN_SECRET",
   "OR3_ADMIN_JWT_SECRET",
   "OR3_ADMIN_PASSWORD"
@@ -49,6 +58,8 @@ var ALLOWED_ENV_KEYS = new Set([
   "SSR_AUTH_ENABLED",
   "AUTH_PROVIDER",
   "OR3_AUTH_PROVIDER",
+  "OR3_AUTH_REGISTRATION_MODE",
+  "OR3_AUTH_AUTO_PROVISION",
   "OR3_GUEST_ACCESS_ENABLED",
   "OR3_BASIC_AUTH_JWT_SECRET",
   "OR3_BASIC_AUTH_REFRESH_SECRET",
@@ -93,6 +104,17 @@ function randomSecret() {
 function randomPassword() {
   return `A${randomBytes(20).toString("base64url")}a1`;
 }
+function serializeInitialCredentials(input2) {
+  return [
+    "# OR3 first-run credentials — move to a password manager, then delete this file.",
+    `OR3_BASIC_AUTH_BOOTSTRAP_EMAIL=${serializeCredentialValue(input2.bootstrapEmail)}`,
+    `OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD=${serializeCredentialValue(input2.bootstrapPassword)}`,
+    `OR3_ADMIN_USERNAME=${serializeCredentialValue(input2.adminUsername)}`,
+    `OR3_ADMIN_PASSWORD=${serializeCredentialValue(input2.adminPassword)}`,
+    ""
+  ].join(`
+`);
+}
 function validatePassword(password) {
   if (password.length < 12 || !/[A-Z]/.test(password) || !/[a-z]/.test(password) || !/[0-9]/.test(password)) {
     throw new Error("The administrator password must be at least 12 characters and contain uppercase, lowercase, and numeric characters.");
@@ -135,12 +157,19 @@ function parseFlags(argv) {
 var COMMAND_FLAGS = {
   init: ["local", "public", "domain", "admin-email", "admin-password", "admin-password-file", "port"],
   update: ["to"],
-  backup: [],
+  backup: ["keep", "force", "yes"],
   restore: ["yes"],
   rollback: ["yes"],
   doctor: [],
   recover: [],
-  adopt: ["from"]
+  adopt: ["from"],
+  credentials: ["yes", "owner-password", "admin-password"],
+  status: [],
+  logs: ["tail"],
+  start: [],
+  stop: [],
+  restart: [],
+  remove: ["purge-data", "yes"]
 };
 function assertCommandFlags(command, flags) {
   const allowed = new Set(["help", ...COMMAND_FLAGS[command] ?? []]);
@@ -214,14 +243,22 @@ async function run(command, args, cwd) {
       encoding: "utf8",
       env: process.env
     });
-    return { ok: true, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+    return {
+      ok: true,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      command: printable,
+      exitCode: 0
+    };
   } catch (error) {
     const failure = error;
+    const stdout = failure.stdout ?? "";
     return {
       ok: false,
+      stdout,
       command: printable,
       exitCode: typeof failure.code === "number" ? failure.code : null,
-      stderr: redact(failure.stderr ?? failure.stdout ?? String(error))
+      stderr: redact(failure.stderr || stdout || String(error))
     };
   }
 }
@@ -256,6 +293,24 @@ async function fileExists(path) {
 async function readText(path) {
   return readFile(path, "utf8");
 }
+function requiredArchiveSpace(requiredBytes) {
+  return requiredBytes + Math.max(Math.ceil(requiredBytes / 2), FREE_SPACE_HEADROOM_BYTES);
+}
+function assertEnoughFreeSpace(freeBytes, requiredBytes, label) {
+  const needed = requiredArchiveSpace(requiredBytes);
+  if (freeBytes < needed) {
+    throw new Error(`${label} needs at least ${needed} bytes of free space (${requiredBytes} required plus reserve headroom) but only ${freeBytes} bytes are available. Free disk space or move backups off-host before retrying.`);
+  }
+}
+async function assertFreeSpaceForArchive(targetPath, requiredBytes, label) {
+  let stats;
+  try {
+    stats = await statfs(dirname(targetPath));
+  } catch (error) {
+    throw new Error(`Could not check free disk space for ${dirname(targetPath)}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  assertEnoughFreeSpace(Number(stats.bavail) * Number(stats.bsize), requiredBytes, label);
+}
 function parseEnv(text) {
   const values = {};
   for (const line of text.split(/\r?\n/)) {
@@ -281,6 +336,11 @@ function serializeEnvValue(value) {
   }
   return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
 }
+function serializeCredentialValue(value) {
+  if (/^[A-Za-z0-9._:@%+=/-]+$/.test(value))
+    return value;
+  return serializeEnvValue(value);
+}
 function serializeEnv(values) {
   return `${Object.entries(values).filter(([, value]) => value !== undefined).map(([key, value]) => `${key}=${serializeEnvValue(value)}`).join(`
 `)}
@@ -292,7 +352,8 @@ function deploymentPaths(directory) {
     env: join(directory, ".env"),
     state: join(cloud, "state.json"),
     operations: join(cloud, "operations"),
-    backups: join(cloud, "backups")
+    backups: join(cloud, "backups"),
+    exports: join(cloud, "exports")
   };
 }
 async function readState(directory) {
@@ -337,11 +398,38 @@ function diagnostics(directory, mode) {
   const files = `-f ${quote(join(directory, "compose.yaml"))}${mode === "public" ? ` -f ${quote(join(directory, "compose.public.yaml"))}` : ""}`;
   return `cd ${quote(directory)} && docker compose --env-file ${quote(join(directory, ".env"))} ${files} ps && docker compose --env-file ${quote(join(directory, ".env"))} ${files} logs --tail=200`;
 }
+async function captureComposeDiagnostics(directory, mode, secrets) {
+  const sections = [];
+  for (const [label, command] of [
+    ["compose ps", ["ps", "-a"]],
+    ["compose logs", ["logs", "--tail=200"]]
+  ]) {
+    const result = await run("docker", composeArgs(directory, mode, [...command]), directory);
+    const detail = [result.stdout, result.stderr].filter(Boolean).join(`
+`).trim();
+    sections.push(`${label}:
+${detail || "(no output)"}`);
+  }
+  const containers = await run("docker", composeArgs(directory, mode, ["ps", "-aq"]), directory);
+  for (const container of containers.stdout.split(/\s+/).filter(Boolean)) {
+    const state = await run("docker", ["inspect", "--format", "{{json .State}}", container], directory);
+    const detail = [state.stdout, state.stderr].filter(Boolean).join(`
+`).trim();
+    sections.push(`container ${container} state:
+${detail || "(no output)"}`);
+  }
+  return redact(sections.join(`
+
+`), secrets);
+}
 async function compose(directory, mode, command, secrets = []) {
   const result = await run("docker", composeArgs(directory, mode, command), directory);
   if (!result.ok) {
-    throw new Error(`${result.command}
+    const captured = await captureComposeDiagnostics(directory, mode, secrets).catch((error) => redact(`Diagnostics capture failed: ${error instanceof Error ? error.message : String(error)}`, secrets));
+    throw new Error(`${redact(result.command, secrets)}
 ${redact(result.stderr, secrets)}
+Captured Docker diagnostics:
+${captured}
 Diagnostics: ${diagnostics(directory, mode)}`);
   }
   return result.stdout;
@@ -402,11 +490,13 @@ async function assertSafeComposeBinding(directory, mode, env) {
   }
 }
 var HEALTH_SCRIPT = "fetch('http://127.0.0.1:3000/api/health?deep=true').then(async response=>{const body=await response.json().catch(()=>({}));if(!response.ok||body.status!=='ok')process.exit(1)}).catch(()=>process.exit(1))";
+var MAINTENANCE_SCRIPT = "fetch('http://127.0.0.1:3000/api/health?deep=true').then(async response=>{const body=await response.json().catch(()=>({}));const m=body?.providers?.sync?.details?.maintenance;if(m)console.log(JSON.stringify(m))}).catch(()=>{})";
+var CONTAINER_NODE = "/nodejs/bin/node";
 async function waitForDeepHealthWithArgs(composeCommand, directory, secrets = []) {
   const deadline = Date.now() + DEEP_HEALTH_TIMEOUT_MS;
   let lastError = "health check did not complete";
   while (Date.now() < deadline) {
-    const result = await run("docker", [...composeCommand, "exec", "-T", "or3", "node", "-e", HEALTH_SCRIPT], directory);
+    const result = await run("docker", [...composeCommand, "exec", "-T", "or3", CONTAINER_NODE, "-e", HEALTH_SCRIPT], directory);
     if (result.ok)
       return;
     lastError = redact(result.stderr, secrets);
@@ -430,7 +520,10 @@ async function waitForDeepHealth(directory, mode, secrets = []) {
   try {
     await waitForDeepHealthWithArgs(composeArgs(directory, mode), directory, secrets);
   } catch (error) {
+    const captured = await captureComposeDiagnostics(directory, mode, secrets).catch((captureError) => redact(`Diagnostics capture failed: ${captureError instanceof Error ? captureError.message : String(captureError)}`, secrets));
     throw new Error(`${error instanceof Error ? error.message : String(error)}
+Captured Docker diagnostics:
+${captured}
 Diagnostics: ${diagnostics(directory, mode)}`);
   }
 }
@@ -487,6 +580,50 @@ ${result.stderr}`);
     throw new Error(`Could not resolve a digest for ${image}.`);
   return idResult.stdout.trim();
 }
+function supportedImageArchitectures(manifest) {
+  if (manifest && Array.isArray(manifest.manifests)) {
+    const architectures = manifest.manifests.map((entry) => entry.platform?.architecture).filter((value) => typeof value === "string");
+    if (architectures.length > 0)
+      return [...new Set(architectures)];
+  }
+  if (manifest && typeof manifest.architecture === "string")
+    return [manifest.architecture];
+  throw new Error("The OR3 image manifest has no recognizable architecture list. Refusing to continue without confirming the image supports this machine.");
+}
+function assertSupportedArchitecture(manifest, hostArch) {
+  const supported = supportedImageArchitectures(manifest);
+  if (!supported.includes(hostArch)) {
+    throw new Error(`OR3 does not publish a ${hostArch} image for this version yet. Supported architectures: ${supported.join(", ") || "none detected"}. Install on a supported machine or wait for the next release.`);
+  }
+}
+function hostArchitecture() {
+  if (process.arch === "arm64")
+    return "arm64";
+  if (process.arch === "x64")
+    return "amd64";
+  throw new Error(`OR3 supports only linux/amd64 and linux/arm64 hosts; this machine reports ${process.arch}. Install on a supported machine.`);
+}
+async function assertSupportedHostArchitecture(image) {
+  const hostArch = hostArchitecture();
+  if (process.env.OR3_CLOUD_SKIP_PULL === "true") {
+    const local = await run("docker", ["image", "inspect", "--format", "{{.Architecture}}", image]);
+    if (local.ok && local.stdout.trim()) {
+      assertSupportedArchitecture({ architecture: local.stdout.trim() }, hostArch);
+      return;
+    }
+  }
+  const result = await run("docker", ["manifest", "inspect", image]);
+  if (!result.ok) {
+    throw new Error(`Could not inspect the OR3 image manifest for ${image}. ${result.stderr.trim()}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(result.stdout.trim());
+  } catch {
+    throw new Error(`The OR3 image manifest for ${image} could not be parsed. Refusing to continue without confirming the image supports this machine.`);
+  }
+  assertSupportedArchitecture(manifest, hostArch);
+}
 function composeProjectNames(directory) {
   const base = sanitizeName(basename(directory));
   return {
@@ -511,7 +648,11 @@ function buildEnv(input2) {
     SSR_AUTH_ENABLED: "true",
     AUTH_PROVIDER: "basic-auth",
     OR3_AUTH_PROVIDER: "basic-auth",
+    OR3_AUTH_REGISTRATION_MODE: "invite_only",
+    OR3_AUTH_AUTO_PROVISION: "false",
     OR3_GUEST_ACCESS_ENABLED: "false",
+    OR3_PLUGIN_ZIP_INSTALL_ENABLED: "false",
+    OR3_ADMIN_ALLOW_REBUILD: "false",
     OR3_BASIC_AUTH_JWT_SECRET: secrets.OR3_BASIC_AUTH_JWT_SECRET ?? randomSecret(),
     OR3_BASIC_AUTH_REFRESH_SECRET: secrets.OR3_BASIC_AUTH_REFRESH_SECRET ?? randomSecret(),
     OR3_BASIC_AUTH_ACCESS_TTL_SECONDS: "900",
@@ -519,6 +660,7 @@ function buildEnv(input2) {
     OR3_BASIC_AUTH_DB_PATH: "/data/auth.sqlite",
     OR3_BASIC_AUTH_BOOTSTRAP_EMAIL: input2.email,
     OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD: input2.password,
+    OR3_AUTH_INVITE_TOKEN_SECRET: secrets.OR3_AUTH_INVITE_TOKEN_SECRET ?? randomSecret(),
     OR3_SYNC_ENABLED: "true",
     OR3_CLOUD_SYNC_ENABLED: "true",
     OR3_SYNC_PROVIDER: "sqlite",
@@ -638,6 +780,111 @@ async function startProject(directory, mode, env) {
 function backupDirectory(directory, backupId) {
   return join(deploymentPaths(directory).backups, backupId);
 }
+async function dataVolumeSize(directory, mode, env) {
+  const parseDuOutput = (stdout) => {
+    const match = stdout.trim().match(/^(\d+)/);
+    if (!match)
+      throw new Error(`Could not parse the data volume size from "du" output.`);
+    return Number(match[1]);
+  };
+  const exec = await run("docker", [...composeArgs(directory, mode, ["exec", "-T", "or3", "sh", "-c", "du -sb /data 2>/dev/null"])], directory);
+  if (exec.ok)
+    return parseDuOutput(exec.stdout);
+  const fallback = await run("docker", [...composeArgs(directory, mode, ["run", "--rm", "--no-deps", "--entrypoint", "sh", "or3", "-c", "du -sb /data 2>/dev/null"])], directory);
+  if (fallback.ok)
+    return parseDuOutput(fallback.stdout);
+  throw new Error(`Could not measure the data volume size for the free-space preflight. Start the deployment and retry. ${redact(`${exec.stderr} ${fallback.stderr}`)}`);
+}
+function assertRemovableArtifactName(name) {
+  if (!BACKUP_ID_PATTERN.test(name)) {
+    throw new Error(`Refusing to remove a backup artifact named "${name}". Only paths matching an OR3-generated backup ID may be removed.`);
+  }
+  return name;
+}
+async function removeNamedBackupArtifact(directory, backupId) {
+  assertRemovableArtifactName(backupId);
+  const target = backupDirectory(directory, backupId);
+  if (dirname(target) !== deploymentPaths(directory).backups) {
+    throw new Error(`Refusing to remove a path outside the backups directory: ${target}.`);
+  }
+  await rm(target, { recursive: true, force: true });
+  await rm(join(deploymentPaths(directory).exports, `${backupId}.json`), { force: true });
+}
+async function readBackupManifestMetadata(backupPath) {
+  try {
+    const manifest = JSON.parse(await readText(join(backupPath, "manifest.json")));
+    if (manifest.schemaVersion !== 1 || !manifest.backupId || !manifest.createdAt)
+      return null;
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+async function enumerateBackups(directory) {
+  const backupsRoot = deploymentPaths(directory).backups;
+  let entries = [];
+  try {
+    entries = await readdir(backupsRoot);
+  } catch {
+    return [];
+  }
+  const result = [];
+  for (const entry of entries) {
+    const path = join(backupsRoot, entry);
+    const manifest = await readBackupManifestMetadata(path);
+    if (!manifest)
+      continue;
+    let bytes = 0;
+    try {
+      for (const file of ["data.tgz", "config.env", "manifest.json"]) {
+        bytes += (await stat(join(path, file))).size;
+      }
+    } catch {
+      bytes = 0;
+    }
+    result.push({
+      backupId: manifest.backupId,
+      createdAt: manifest.createdAt,
+      appVersion: manifest.appVersion,
+      path,
+      bytes,
+      dataSha256: manifest.dataSha256
+    });
+  }
+  result.sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
+  return result;
+}
+function selectPruneTargets(backups, keep, protectedIds, force = false) {
+  if (!Number.isInteger(keep) || keep < 1)
+    throw new Error("Backup retention must be an integer of at least 1.");
+  const sorted = [...backups].sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
+  const deletable = force ? sorted : sorted.filter((backup) => !protectedIds.has(backup.backupId));
+  return deletable.slice(keep).map((backup) => backup.backupId);
+}
+function parseKeep(flags) {
+  const value = stringFlag(flags, "keep") ?? String(BACKUP_RETENTION_KEEP);
+  const keep = Number(value);
+  if (!Number.isInteger(keep) || keep < 1)
+    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);
+  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) {
+    await removeNamedBackupArtifact(directory, backupId);
+    console.log(`Deleted backup ${backupId} at ${backupDirectory(directory, backupId)}`);
+  }
+  return targets.length;
+}
 function assertDeploymentIdentity(state, env) {
   const expected = {
     OR3_COMPOSE_PROJECT: state.composeProject,
@@ -655,6 +902,26 @@ function assertDeploymentIdentity(state, env) {
     }
   }
 }
+function assertDeploymentDirectoryIdentity(directory, state) {
+  const resolved = resolve(directory);
+  const names = composeProjectNames(resolved);
+  const mismatches = [];
+  if (state.composeProject !== names.project) {
+    mismatches.push(`compose project "${state.composeProject}" (this directory resolves to "${names.project}")`);
+  }
+  if (state.volumeName !== names.volume) {
+    mismatches.push(`volume "${state.volumeName}" (this directory resolves to "${names.volume}")`);
+  }
+  if (state.mode === "public") {
+    if (state.caddyDataVolume !== names.caddyData)
+      mismatches.push(`Caddy data volume "${state.caddyDataVolume}"`);
+    if (state.caddyConfigVolume !== names.caddyConfig)
+      mismatches.push(`Caddy config volume "${state.caddyConfigVolume}"`);
+  }
+  if (mismatches.length) {
+    throw new Error(`Managed state does not match the deployment directory identity: ${mismatches.join("; ")}. Refusing to operate on an unrelated project. Run doctor for diagnostics.`);
+  }
+}
 function assertBackupMatchesDeployment(manifest, backupEnv, state, env) {
   if (manifest.mode !== state.mode || manifest.appVersion === undefined || manifest.image === undefined) {
     throw new Error(`Backup ${manifest.backupId} does not match the managed deployment mode.`);
@@ -696,69 +963,128 @@ function assertBackupMatchesDeployment(manifest, backupEnv, state, env) {
 }
 async function sha256File(path) {
   const digest = createHash("sha256");
-  digest.update(await readFile(path));
+  await new Promise((resolvePromise, reject) => {
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => digest.update(chunk));
+    stream.once("error", reject);
+    stream.once("end", resolvePromise);
+  });
   return digest.digest("hex");
 }
+async function streamCommandToFile(command, args, destination, cwd, secrets = []) {
+  if (await fileExists(destination)) {
+    throw new Error(`Refusing to overwrite existing archive ${destination}.`);
+  }
+  await mkdir(dirname(destination), { recursive: true, mode: 448 });
+  const temporary = `${destination}.${randomBytes(8).toString("hex")}.partial`;
+  const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    stderr = `${stderr}${chunk}`.slice(-64 * 1024);
+  });
+  const exit = new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("close", resolvePromise);
+  });
+  try {
+    const [exitCode] = await Promise.all([
+      exit,
+      pipeline(child.stdout, createWriteStream(temporary, { flags: "wx", mode: 384 }))
+    ]);
+    if (exitCode !== 0) {
+      throw new Error(`${command} ${args.join(" ")} exited with ${exitCode}. ${redact(stderr, secrets)}`.trim());
+    }
+    await chmod(temporary, 384);
+    await rename(temporary, destination);
+  } catch (error) {
+    if (!child.killed)
+      child.kill("SIGTERM");
+    await rm(temporary, { force: true }).catch(() => {
+      return;
+    });
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${detail}${stderr && !detail.includes(stderr) ? `
+${redact(stderr, secrets)}` : ""}`);
+  }
+}
+async function streamFileToCommand(command, args, source, cwd, secrets = []) {
+  const child = spawn(command, args, { cwd, stdio: ["pipe", "ignore", "pipe"] });
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    stderr = `${stderr}${chunk}`.slice(-64 * 1024);
+  });
+  const exit = new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("close", resolvePromise);
+  });
+  try {
+    const [exitCode] = await Promise.all([
+      exit,
+      pipeline(createReadStream(source), child.stdin)
+    ]);
+    if (exitCode !== 0) {
+      throw new Error(`${command} ${args.join(" ")} exited with ${exitCode}. ${redact(stderr, secrets)}`.trim());
+    }
+  } catch (error) {
+    if (!child.killed)
+      child.kill("SIGTERM");
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${detail}${stderr && !detail.includes(stderr) ? `
+${redact(stderr, secrets)}` : ""}`);
+  }
+}
+async function gzipUncompressedBytes(path) {
+  let bytes = 0;
+  const counter = new Writable({
+    write(chunk, _encoding, callback) {
+      bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
+      callback();
+    }
+  });
+  await pipeline(createReadStream(path), createGunzip(), counter);
+  return bytes;
+}
 async function volumeArchive(directory, mode, env, backupDir) {
-  const mount = `${backupDir}:/backup`;
-  await compose(directory, mode, [
+  await streamCommandToFile("docker", composeArgs(directory, mode, [
     "run",
     "--rm",
     "--no-deps",
-    "--user",
-    "0:0",
-    "-v",
-    mount,
     "--entrypoint",
     "sh",
     "or3",
     "-c",
-    "umask 077 && tar czf /backup/data.tgz -C /data . && tar tzf /backup/data.tgz >/dev/null"
-  ], secretValues(env));
+    "tar czf - -C /data ."
+  ]), join(backupDir, "data.tgz"), directory, secretValues(env));
 }
 async function archiveExternalVolume(image, volume, backupDir) {
-  const result = await run("docker", [
-    "run",
-    "--rm",
-    "--user",
-    "0:0",
-    "-v",
-    `${volume}:/source:ro`,
-    "-v",
-    `${backupDir}:/backup`,
-    image,
-    "sh",
-    "-c",
-    "umask 077 && tar czf /backup/data.tgz -C /source . && tar tzf /backup/data.tgz >/dev/null"
-  ]);
-  if (!result.ok)
-    throw new Error(`${result.command}
-${result.stderr}`);
+  await streamCommandToFile("docker", ["run", "--rm", "--user", "0:0", "-v", `${volume}:/source:ro`, image, "sh", "-c", "tar czf - -C /source ."], join(backupDir, "data.tgz"));
 }
-async function restoreAdoptionBackup(directory, mode, env, backupPath) {
-  await compose(directory, mode, [
+async function restoreVolumeArchive(directory, mode, env, backupPath) {
+  await streamFileToCommand("docker", composeArgs(directory, mode, [
     "run",
     "--rm",
+    "-T",
     "--no-deps",
-    "--user",
-    "0:0",
-    "-v",
-    `${backupPath}:/backup:ro`,
     "--entrypoint",
     "sh",
     "or3",
     "-c",
-    "find /data -mindepth 1 -delete && tar xzf /backup/data.tgz -C /data"
-  ], secretValues(env));
+    "find /data -mindepth 1 -delete && tar xzf - -C /data"
+  ]), join(backupPath, "data.tgz"), directory, secretValues(env));
 }
 async function createBackup(directory, state, env) {
   await requireImageDigest(state.image, state.imageDigest, "Current deployment");
   const backupId = id("backup");
   const backupDir = backupDirectory(directory, backupId);
-  await mkdir(backupDir, { recursive: true, mode: 448 });
-  await chmod(backupDir, 448);
+  const volumeSize = await dataVolumeSize(directory, state.mode, env);
+  await assertFreeSpaceForArchive(backupDir, volumeSize, "Backup");
+  let manifestWritten = false;
   let stopAttempted = false;
   try {
+    await mkdir(backupDir, { recursive: true, mode: 448 });
+    await chmod(backupDir, 448);
     stopAttempted = true;
     await stopProject(directory, state.mode);
     await volumeArchive(directory, state.mode, env, backupDir);
@@ -771,6 +1097,7 @@ async function createBackup(directory, state, env) {
       image: state.image,
       imageDigest: state.imageDigest,
       dataSha256: await sha256File(join(backupDir, "data.tgz")),
+      dataBytes: volumeSize,
       configSha256: await sha256File(join(backupDir, "config.env")),
       mode: state.mode,
       domain: state.domain,
@@ -782,7 +1109,21 @@ async function createBackup(directory, state, env) {
     };
     await writeSecure(join(backupDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `);
+    manifestWritten = true;
+    try {
+      await pruneBackups(directory, state, BACKUP_RETENTION_KEEP, false);
+    } catch (error) {
+      console.log(`Warning: automatic backup retention could not run: ${error instanceof Error ? error.message : String(error)}`);
+    }
     return { backupId, backupDir, manifest };
+  } catch (error) {
+    if (!manifestWritten) {
+      await removeNamedBackupArtifact(directory, backupId).catch(() => {
+        return;
+      });
+      throw new Error(`${error instanceof Error ? error.message : String(error)} The partial backup artifact at ${backupDir} was removed.`);
+    }
+    throw error;
   } finally {
     if (stopAttempted) {
       try {
@@ -795,7 +1136,7 @@ async function createBackup(directory, state, env) {
 }
 async function readManifest(backupPath) {
   const manifest = JSON.parse(await readText(join(backupPath, "manifest.json")));
-  if (manifest.schemaVersion !== 1 || !manifest.backupId || !isVersion(manifest.appVersion) || !manifest.image || !/^sha256:[0-9a-f]{64}$/i.test(manifest.imageDigest)) {
+  if (manifest.schemaVersion !== 1 || !manifest.backupId || !isVersion(manifest.appVersion) || !manifest.image || !/^sha256:[0-9a-f]{64}$/i.test(manifest.imageDigest) || manifest.dataBytes !== undefined && (!Number.isSafeInteger(manifest.dataBytes) || manifest.dataBytes < 0)) {
     throw new Error(`Invalid backup manifest at ${backupPath}.`);
   }
   const actual = await sha256File(join(backupPath, "data.tgz"));
@@ -808,6 +1149,28 @@ async function readManifest(backupPath) {
   }
   return manifest;
 }
+async function dataVolumeFreeBytes(directory, mode, env) {
+  const parse = (stdout) => {
+    const blocks = Number(stdout.trim());
+    if (!Number.isSafeInteger(blocks) || blocks < 0)
+      throw new Error("Could not parse free blocks from the data volume.");
+    return blocks * 1024;
+  };
+  const script = "df -Pk /data | awk 'NR == 2 { print $4 }'";
+  const exec = await run("docker", [...composeArgs(directory, mode, ["exec", "-T", "or3", "sh", "-c", script])], directory);
+  if (exec.ok)
+    return parse(exec.stdout);
+  const fallback = await run("docker", [...composeArgs(directory, mode, ["run", "--rm", "--no-deps", "--entrypoint", "sh", "or3", "-c", script])], directory);
+  if (fallback.ok)
+    return parse(fallback.stdout);
+  throw new Error(`Could not measure free space in the Docker data volume. ${redact(`${exec.stderr} ${fallback.stderr}`, secretValues(env))}`);
+}
+async function assertRestoreFreeSpace(directory, state, env, manifest, backupPath) {
+  const archiveBytes = await gzipUncompressedBytes(join(backupPath, "data.tgz"));
+  const requiredBytes = Math.max(manifest.dataBytes ?? 0, archiveBytes);
+  const freeBytes = await dataVolumeFreeBytes(directory, state.mode, env);
+  assertEnoughFreeSpace(freeBytes, requiredBytes, "Restore");
+}
 async function restoreBackupData(directory, state, env, backupPath) {
   const manifest = await readManifest(backupPath);
   const backupEnv = parseEnv(await readText(join(backupPath, "config.env")));
@@ -817,26 +1180,14 @@ async function restoreBackupData(directory, state, env, backupPath) {
   assertBackupMatchesDeployment(manifest, backupEnv, state, env);
   if (manifest.imageDigest)
     await requireImageDigest(manifest.image, manifest.imageDigest, `Backup ${manifest.backupId}`);
+  await assertRestoreFreeSpace(directory, state, env, manifest, backupPath);
   let started = false;
   let stopAttempted = false;
   try {
     stopAttempted = true;
     await stopProject(directory, state.mode);
     await copySecure(join(backupPath, "config.env"), deploymentPaths(directory).env);
-    await compose(directory, state.mode, [
-      "run",
-      "--rm",
-      "--no-deps",
-      "--user",
-      "0:0",
-      "-v",
-      `${backupPath}:/backup:ro`,
-      "--entrypoint",
-      "sh",
-      "or3",
-      "-c",
-      "find /data -mindepth 1 -delete && tar xzf /backup/data.tgz -C /data"
-    ], secretValues(backupEnv));
+    await restoreVolumeArchive(directory, state.mode, backupEnv, backupPath);
     const restoredEnv = parseEnv(await readText(deploymentPaths(directory).env));
     await startProject(directory, state.mode, restoredEnv);
     started = true;
@@ -878,19 +1229,29 @@ 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
+  npx @or3/cloud backup [list|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 <p> --admin-password <p>]
   npx @or3/cloud doctor
   npx @or3/cloud recover
   npx @or3/cloud adopt --from <v1-directory> [directory]
+  npx @or3/cloud status
+  npx @or3/cloud logs [--tail <n>] [service]
+  npx @or3/cloud start | stop | restart
+  npx @or3/cloud remove [--purge-data --yes]
 
 Options:
   --admin-email <email>          Administrator email for first login
-  --admin-password <password>    Explicit password (prefer --admin-password-file)
+  --admin-password <password>    Explicit password (prefer --admin-password-file); for credentials reset, the new admin password
   --admin-password-file <path>   Read the bootstrap password without shell history
+  --owner-password <password>    New owner (basic auth) password for credentials reset
   --port <port>                  Local OR3 port (default: 3000)
-  --yes                          Confirm a destructive restore or rollback
+  --keep <n>                     Backups to retain when pruning (default: 5)
+  --force                        Prune backups even when referenced by the rollback point
+  --tail <n>                     Log lines to show (default: 200)
+  --purge-data                   Remove data volumes and managed files (with remove)
+  --yes                          Confirm a destructive restore, rollback, credentials reset, or purge
   --help                         Show this help
   --version                      Show the Cloud package version
 
@@ -938,6 +1299,7 @@ async function initCommand(positionals, flags) {
   const version = PACKAGE_VERSION;
   const image = imageFor(version);
   await pullImage(image);
+  await assertSupportedHostArchitecture(image);
   await mkdir(directory, { recursive: true, mode: 448 });
   await chmod(directory, 448);
   await mkdir(deploymentPaths(directory).operations, { recursive: true, mode: 448 });
@@ -945,9 +1307,12 @@ async function initCommand(positionals, flags) {
   await copyAssets(directory, mode);
   const env = buildEnv({ mode, version, directory, email, password, domain, port });
   await writeSecure(deploymentPaths(directory).env, serializeEnv(env));
-  await writeSecure(join(directory, ".or3-initial-credentials"), `email=${email}
-password=${password}
-`);
+  await writeSecure(join(directory, ".or3-initial-credentials"), serializeInitialCredentials({
+    bootstrapEmail: email,
+    bootstrapPassword: password,
+    adminUsername: email,
+    adminPassword: password
+  }));
   const digest = await imageDigest(image);
   const state = stateFromEnv(directory, env, mode, "init", digest);
   await markPending(directory, state, {
@@ -999,6 +1364,16 @@ async function recoverCommand(directory) {
     return;
   }
   try {
+    if (pending.operation === "credentials-reset") {
+      const nextEnv = pending.credentialReset?.nextEnv;
+      if (!nextEnv)
+        throw new Error("The incomplete credential reset has no protected recovery data. Restore a backup rather than guessing credentials.");
+      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;
+    }
     if (pending.operation === "restore" || pending.operation === "rollback") {
       if (!pending.backupId)
         throw new Error(`The incomplete ${pending.operation} has no recorded backup ID.`);
@@ -1079,7 +1454,7 @@ async function recoverCommand(directory) {
         throw new Error(`Source backup ${sourceManifest.backupId} does not match the managed adoption target.`);
       }
       await stopProject(loaded.directory, loaded.state.mode);
-      await restoreAdoptionBackup(loaded.directory, loaded.state.mode, loaded.env, sourceBackupPath);
+      await restoreVolumeArchive(loaded.directory, loaded.state.mode, loaded.env, sourceBackupPath);
     }
     await pullAndRequireImage(loaded.state.image, loaded.state.imageDigest, "Current deployment");
     await startProject(loaded.directory, loaded.state.mode, loaded.env);
@@ -1090,7 +1465,8 @@ async function recoverCommand(directory) {
     await commitRecoveredState(loaded.directory, loaded.state, recovered);
     console.log(`Recovered the incomplete ${pending.operation} operation. OR3 ${recovered.appVersion} is deeply healthy.`);
   } catch (error) {
-    loaded.state.lastError = redact(error instanceof Error ? error.message : String(error), secretValues(loaded.env));
+    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);
     if (pending.operation === "adopt" && pending.sourceDirectory) {
       try {
         await compose(loaded.directory, loaded.state.mode, ["down"]).catch(() => {
@@ -1115,7 +1491,7 @@ function assertNoPending(state) {
     throw new Error(`An incomplete ${state.incompleteOperation.operation} is recorded. Run "npx @or3/cloud recover" before starting another operation.`);
   }
 }
-async function backupCommand(directory) {
+async function backupCreateCommand(directory) {
   await ensureDocker();
   const loaded = await loadManaged(directory);
   assertNoPending(loaded.state);
@@ -1137,6 +1513,109 @@ async function backupCommand(directory) {
     throw error;
   }
 }
+async function backupListCommand(directory) {
+  const loaded = await loadManaged(directory);
+  const backups = await enumerateBackups(loaded.directory);
+  if (backups.length === 0) {
+    console.log(`No backups exist yet for ${loaded.directory}. Run "npx @or3/cloud backup" to create one.`);
+    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)}`);
+  }
+  console.log(`
+Backups contain credentials and secrets; keep them owner-only and export off-host.`);
+}
+async function backupPruneCommand(directory, flags) {
+  const loaded = await loadManaged(directory);
+  assertNoPending(loaded.state);
+  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}).`);
+}
+async function backupExportCommand(directory, backupId, destination) {
+  const backupPath = await resolveBackup(directory, backupId);
+  const manifest = await readManifest(backupPath);
+  const dest = resolve(destination);
+  const source = resolve(backupPath);
+  if (source === dest || dest.startsWith(`${source}${sep}`)) {
+    throw new Error("Choose a destination directory different from the backup itself.");
+  }
+  if (await fileExists(dest))
+    throw new Error(`Destination ${dest} already exists. Choose a new empty destination so an export can never merge with unrelated files.`);
+  await mkdir(dirname(dest), { recursive: true, mode: 448 });
+  await mkdir(dest, { mode: 448 });
+  try {
+    await chmod(dest, 448);
+    for (const file of ["data.tgz", "config.env", "manifest.json"]) {
+      await copySecure(join(backupPath, file), join(dest, file));
+    }
+    const dataSha = await sha256File(join(dest, "data.tgz"));
+    if (dataSha !== manifest.dataSha256) {
+      throw new Error(`Exported data.tgz checksum mismatch for ${manifest.backupId}. Expected ${manifest.dataSha256}, got ${dataSha}.`);
+    }
+    if (manifest.configSha256) {
+      const configSha = await sha256File(join(dest, "config.env"));
+      if (configSha !== manifest.configSha256) {
+        throw new Error(`Exported config.env checksum mismatch for ${manifest.backupId}.`);
+      }
+    }
+    const destinationDevice = (await stat(dest)).dev;
+    await mkdir(deploymentPaths(directory).exports, { recursive: true, mode: 448 });
+    const receipt = {
+      schemaVersion: 1,
+      backupId: manifest.backupId,
+      exportedAt: now(),
+      destination: dest,
+      destinationDevice,
+      dataSha256: manifest.dataSha256,
+      configSha256: manifest.configSha256
+    };
+    await writeSecure(join(deploymentPaths(directory).exports, `${manifest.backupId}.json`), `${JSON.stringify(receipt, null, 2)}
+`);
+    const bytes = (await stat(join(dest, "data.tgz"))).size + (await stat(join(dest, "config.env"))).size + (await stat(join(dest, "manifest.json"))).size;
+    console.log(`Exported backup ${manifest.backupId} (${bytes} bytes) to ${dest}`);
+    console.log("The exported copy contains credentials and secrets. It is owner-only (0600); keep it off-host.");
+    if ((await stat(backupPath)).dev === destinationDevice) {
+      console.log("This export is on the same filesystem as the deployment and cannot authorize `remove --purge-data`. Copy it to a mounted backup disk or another host, then export again there.");
+    } else {
+      console.log("Verified export recorded. It can authorize `remove --purge-data --yes` while this backup remains fresh.");
+    }
+  } catch (error) {
+    await rm(dest, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function backupCommand(directory, positionals, flags) {
+  const subcommand = positionals[0];
+  if (!subcommand)
+    return await backupCreateCommand(directory);
+  if (subcommand === "list") {
+    if (positionals.length > 1)
+      throw new Error("backup list accepts no arguments.");
+    return await backupListCommand(directory);
+  }
+  if (subcommand === "prune") {
+    if (positionals.length > 1)
+      throw new Error("backup prune accepts no arguments.");
+    return await backupPruneCommand(directory, flags);
+  }
+  if (subcommand === "export") {
+    const backupId = positionals[1];
+    const destination = positionals[2];
+    if (!backupId || !destination)
+      throw new Error("backup export requires a backup ID and a destination directory.");
+    if (positionals.length > 3)
+      throw new Error("backup export accepts a backup ID and a destination directory only.");
+    return await backupExportCommand(directory, backupId, destination);
+  }
+  throw new Error(`Unknown backup subcommand "${subcommand}". Use list, prune, export, or no subcommand to create a backup.`);
+}
 async function updateCommand(directory, flags) {
   await ensureDocker();
   const loaded = await loadManaged(directory);
@@ -1145,11 +1624,12 @@ async function updateCommand(directory, flags) {
   await waitForDeepHealth(loaded.directory, state.mode, secretValues(env));
   const targetVersion = stringFlag(flags, "to")?.trim() ?? PACKAGE_VERSION;
   if (!isVersion(targetVersion))
-    throw new Error("--to must be a complete semantic version such as 0.1.15.");
+    throw new Error(`--to must be a complete semantic version such as ${PACKAGE_VERSION}.`);
   if (targetVersion === state.appVersion)
     throw new Error(`The deployment is already on OR3 ${targetVersion}.`);
   const targetImage = imageFor(targetVersion);
   const targetDigest = await pullImage(targetImage);
+  await assertSupportedHostArchitecture(targetImage);
   const oldEnv = { ...env };
   const pending = {
     id: id("update"),
@@ -1228,6 +1708,8 @@ async function restoreCommand(directory, flags, positionals) {
   assertBackupMatchesDeployment(manifest, backupEnv, loaded.state, loaded.env);
   if (manifest.imageDigest)
     await pullAndRequireImage(manifest.image, manifest.imageDigest, `Backup ${manifest.backupId}`);
+  await assertSupportedHostArchitecture(manifest.image);
+  await assertRestoreFreeSpace(loaded.directory, loaded.state, loaded.env, manifest, backupPath);
   const pending = {
     id: id("restore"),
     operation: "restore",
@@ -1274,6 +1756,8 @@ async function rollbackCommand(directory, flags) {
   }
   assertBackupMatchesDeployment(manifest, backupEnv, loaded.state, loaded.env);
   await pullAndRequireImage(point.image, point.imageDigest, "Rollback");
+  await assertSupportedHostArchitecture(point.image);
+  await assertRestoreFreeSpace(loaded.directory, loaded.state, loaded.env, manifest, backupPath);
   const pending = {
     id: id("rollback"),
     operation: "rollback",
@@ -1540,6 +2024,7 @@ async function adoptCommand(positionals, flags) {
     throw new Error(`V1 OR3_IMAGE ${sourceEnv.OR3_IMAGE} does not match the published image for ${release.or3Version}.`);
   }
   await pullImage(image);
+  await assertSupportedHostArchitecture(image);
   const sourceVolume = await readSourceVolume(sourceDirectory);
   const email = sourceEnv.OR3_BASIC_AUTH_BOOTSTRAP_EMAIL;
   const password = sourceEnv.OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD;
@@ -1586,9 +2071,12 @@ async function adoptCommand(positionals, flags) {
       throw new Error(`Docker volume ${volume} already exists. Choose a new adoption target directory.`);
   }
   await writeSecure(deploymentPaths(targetDirectory).env, serializeEnv(targetEnv));
-  await writeSecure(join(targetDirectory, ".or3-initial-credentials"), `email=${email}
-password=${password}
-`);
+  await writeSecure(join(targetDirectory, ".or3-initial-credentials"), serializeInitialCredentials({
+    bootstrapEmail: email,
+    bootstrapPassword: password,
+    adminUsername: email,
+    adminPassword: password
+  }));
   const digest = await imageDigest(image);
   const state = stateFromEnv(targetDirectory, targetEnv, mode, "adopt", digest);
   await markPending(targetDirectory, state, {
@@ -1638,7 +2126,7 @@ password=${password}
     await writeSecure(join(sourceBackupDir, "manifest.json"), `${JSON.stringify(sourceManifest, null, 2)}
 `);
     await updatePending(targetDirectory, state, { backupId: sourceBackupId });
-    await compose(targetDirectory, mode, ["run", "--rm", "--no-deps", "--user", "0:0", "-v", `${sourceVolume}:/source:ro`, "--entrypoint", "sh", "or3", "-c", "mkdir -p /data && cp -a /source/. /data/"], secretValues(targetEnv));
+    await restoreVolumeArchive(targetDirectory, mode, targetEnv, sourceBackupDir);
     await startProject(targetDirectory, mode, targetEnv);
     await clearPending(targetDirectory, state);
     console.log(`Adopted ${sourceDirectory} into ${targetDirectory} at OR3 ${release.or3Version}.`);
@@ -1662,6 +2150,448 @@ password=${password}
 ${sourceRecoveryError ? "The original V1 deployment needs manual recovery. " : "The original V1 deployment was restarted and deeply healthy. "}Managed files remain at ${targetDirectory}.${sourceBackupDir ? ` Source backup: ${sourceBackupDir}.` : ""}`);
   }
 }
+async function resolveResetPasswords(flags) {
+  const ownerPassword = stringFlag(flags, "owner-password");
+  const adminPassword = stringFlag(flags, "admin-password");
+  if (ownerPassword !== undefined || adminPassword !== undefined) {
+    if (ownerPassword === undefined || adminPassword === undefined) {
+      throw new Error("Use both --owner-password and --admin-password together so a reset never applies one credential without the other.");
+    }
+    validatePassword(ownerPassword);
+    validatePassword(adminPassword);
+    return { ownerPassword, adminPassword };
+  }
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error("--owner-password and --admin-password are required in a non-interactive session. Credentials are never generated automatically.");
+  }
+  const prompt = readline.createInterface({ input, output });
+  try {
+    const owner = (await prompt.question("New owner (basic auth) password: ")).trim();
+    validatePassword(owner);
+    const admin = (await prompt.question("New admin password: ")).trim();
+    validatePassword(admin);
+    return { ownerPassword: owner, adminPassword: admin };
+  } finally {
+    prompt.close();
+  }
+}
+function buildCredentialsResetScript(input2) {
+  const authDbPath = input2.authDbPath ?? "/data/auth.sqlite";
+  const adminCredentialsPath = input2.adminCredentialsPath ?? "/data/admin/admin-credentials.json";
+  return `const fs = require('fs');
+const path = require('path');
+const candidates = [process.cwd(), '/app'];
+const resolveModule = (name) => {
+  for (const root of candidates) {
+    const resolved = path.join(root, '.output/server/node_modules', name);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  return null;
+};
+let Database;
+try {
+  const betterSqlite3Path = resolveModule('better-sqlite3');
+  if (!betterSqlite3Path) throw new Error('better-sqlite3 directory not found');
+  Database = require(betterSqlite3Path);
+} catch (error) {
+  console.error('OR3 credentials reset failed: better-sqlite3 is not available in this image, so the auth database could not be updated. Nothing was changed. Update the OR3 image to a release that bundles it, then retry.');
+  process.exit(1);
+}
+let bcrypt;
+try {
+  // bcryptjs 2.x ships a broken "exports" map (require -> missing umd/index.js),
+  // so it must be loaded by explicit absolute path, like the server bundle does.
+  const bcryptPath = resolveModule('bcryptjs/index.js');
+  if (!bcryptPath) throw new Error('bcryptjs directory not found');
+  bcrypt = require(bcryptPath);
+} catch (error) {
+  console.error('OR3 credentials reset failed: bcryptjs is not available in this image, so new password hashes could not be computed. Nothing was changed. Update the OR3 image to a release that bundles it, then retry.');
+  process.exit(1);
+}
+const ownerEmail = process.env.OR3_RESET_OWNER_EMAIL;
+const ownerPassword = process.env.OR3_RESET_OWNER_PASSWORD;
+const adminUsername = process.env.OR3_RESET_ADMIN_USERNAME;
+const adminPassword = process.env.OR3_RESET_ADMIN_PASSWORD;
+if (!ownerEmail || !ownerPassword || !adminUsername || !adminPassword) {
+  console.error('OR3 credentials reset failed: required environment values were not supplied to the reset script. Nothing was changed.');
+  process.exit(1);
+}
+const ownerHash = bcrypt.hashSync(ownerPassword, 12);
+const adminHash = bcrypt.hashSync(adminPassword, 12);
+const now = Date.now();
+const db = new Database(${JSON.stringify(authDbPath)});
+db.pragma('busy_timeout = 10000');
+const account = db.prepare('SELECT id FROM basic_auth_accounts WHERE email = ?').get(ownerEmail);
+if (!account) {
+  console.error('OR3 credentials reset failed: no Basic Auth account matches OR3_BASIC_AUTH_BOOTSTRAP_EMAIL. Nothing was changed.');
+  process.exit(1);
+}
+const adminCredentialsPath = ${JSON.stringify(adminCredentialsPath)};
+const previousCredentials = (() => {
+  try { return fs.readFileSync(adminCredentialsPath, 'utf8'); } catch { return null; }
+})();
+let credentials;
+try {
+  credentials = previousCredentials ? JSON.parse(previousCredentials) : { created_at: new Date().toISOString() };
+} catch (error) {
+  console.error('OR3 credentials reset failed: the admin credentials file is corrupt. Nothing was changed.');
+  process.exit(1);
+}
+credentials.username = adminUsername;
+credentials.password_hash_bcrypt = adminHash;
+credentials.updated_at = new Date().toISOString();
+try {
+  fs.writeFileSync(adminCredentialsPath, JSON.stringify(credentials, null, 2) + '\\n', { mode: 0o600 });
+} catch (error) {
+  console.error('OR3 credentials reset failed: could not update the admin credentials file at ' + adminCredentialsPath + '. Nothing was changed. ' + (error && error.message ? error.message : String(error)));
+  process.exit(1);
+}
+try {
+  db.transaction(() => {
+    db.prepare('UPDATE basic_auth_accounts SET password_hash = ?, token_version = token_version + 1, updated_at = ? WHERE id = ?').run(ownerHash, now, account.id);
+    db.prepare('UPDATE basic_auth_sessions SET revoked_at = COALESCE(revoked_at, ?), rotation_grace_until = NULL, rotation_grace_refresh_token = NULL WHERE account_id = ?').run(now, account.id);
+  })();
+} catch (error) {
+  if (previousCredentials !== null) {
+    try { fs.writeFileSync(adminCredentialsPath, previousCredentials, { mode: 0o600 }); } catch {}
+  } else {
+    try { fs.rmSync(adminCredentialsPath, { force: true }); } catch {}
+  }
+  console.error('OR3 credentials reset failed: the authentication database rejected the update. Any partial change was rolled back. ' + (error && error.message ? error.message : String(error)));
+  process.exit(1);
+}
+db.close();
+console.log('credentials-reset: owner hash, sessions, and admin credentials updated.');
+`;
+}
+function credentialResetValues(env) {
+  const ownerEmail = env.OR3_BASIC_AUTH_BOOTSTRAP_EMAIL;
+  const ownerPassword = env.OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD;
+  const adminUsername = env.OR3_ADMIN_USERNAME;
+  const adminPassword = env.OR3_ADMIN_PASSWORD;
+  if (!ownerEmail || !ownerPassword || !adminUsername || !adminPassword) {
+    throw new Error("Credential recovery data is incomplete. Run doctor and restore a backup rather than guessing credentials.");
+  }
+  return { ownerEmail, ownerPassword, adminUsername, adminPassword };
+}
+var CREDENTIALS_VERIFY_SCRIPT = `
+const request = async (path, body) => {
+  const response = await fetch('http://127.0.0.1:3000' + path, {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30000),
+  });
+  if (!response.ok) throw new Error(path + ' returned HTTP ' + response.status);
+};
+Promise.all([
+  request('/api/basic-auth/sign-in', { email: process.env.OR3_RESET_OWNER_EMAIL, password: process.env.OR3_RESET_OWNER_PASSWORD }),
+  request('/api/admin/auth/login', { username: process.env.OR3_RESET_ADMIN_USERNAME, password: process.env.OR3_RESET_ADMIN_PASSWORD }),
+]).catch((error) => { console.error('Credential verification failed: ' + error.message); process.exit(1); });
+`;
+async function runCredentialsResetScript(directory, mode, values) {
+  const script = buildCredentialsResetScript(values);
+  const result = await run("docker", [
+    ...composeArgs(directory, mode, [
+      "exec",
+      "-T",
+      "-e",
+      `OR3_RESET_OWNER_EMAIL=${values.ownerEmail}`,
+      "-e",
+      `OR3_RESET_OWNER_PASSWORD=${values.ownerPassword}`,
+      "-e",
+      `OR3_RESET_ADMIN_USERNAME=${values.adminUsername}`,
+      "-e",
+      `OR3_RESET_ADMIN_PASSWORD=${values.adminPassword}`,
+      "or3",
+      CONTAINER_NODE,
+      "-e",
+      script
+    ])
+  ], directory);
+  if (!result.ok)
+    throw new Error(`${result.command}
+${redact(result.stderr, [values.ownerPassword, values.adminPassword])}`);
+}
+async function verifyCredentialsInsideContainer(directory, mode, values) {
+  const result = await run("docker", [
+    ...composeArgs(directory, mode, [
+      "exec",
+      "-T",
+      "-e",
+      `OR3_RESET_OWNER_EMAIL=${values.ownerEmail}`,
+      "-e",
+      `OR3_RESET_OWNER_PASSWORD=${values.ownerPassword}`,
+      "-e",
+      `OR3_RESET_ADMIN_USERNAME=${values.adminUsername}`,
+      "-e",
+      `OR3_RESET_ADMIN_PASSWORD=${values.adminPassword}`,
+      "or3",
+      CONTAINER_NODE,
+      "-e",
+      CREDENTIALS_VERIFY_SCRIPT
+    ])
+  ], directory);
+  if (!result.ok)
+    throw new Error(`Credential verification inside the OR3 container failed. ${redact(result.stderr, [values.ownerPassword, values.adminPassword])}`);
+}
+async function applyCredentialReset(directory, state, nextEnv) {
+  const values = credentialResetValues(nextEnv);
+  const running = await run("docker", [...composeArgs(directory, state.mode, ["ps", "-q", "or3"])], directory);
+  if (!running.ok || !running.stdout.trim()) {
+    await writeSecure(deploymentPaths(directory).env, serializeEnv(nextEnv));
+    await startProject(directory, state.mode, nextEnv);
+  }
+  await runCredentialsResetScript(directory, state.mode, values);
+  await writeSecure(deploymentPaths(directory).env, serializeEnv(nextEnv));
+  const initialCredentials = join(directory, ".or3-initial-credentials");
+  if (await fileExists(initialCredentials)) {
+    await writeSecure(initialCredentials, serializeInitialCredentials({
+      bootstrapEmail: values.ownerEmail,
+      bootstrapPassword: values.ownerPassword,
+      adminUsername: values.adminUsername,
+      adminPassword: values.adminPassword
+    }));
+  }
+  await stopProject(directory, state.mode);
+  await startProject(directory, state.mode, nextEnv);
+  await verifyCredentialsInsideContainer(directory, state.mode, values);
+}
+async function credentialsResetCommand(directory, flags) {
+  if (!boolFlag(flags, "yes"))
+    throw new Error("Credentials reset changes the owner password, revokes all app sessions, and changes the admin password. Re-run with --yes after confirming the impact.");
+  await ensureDocker();
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, loaded.state);
+  assertNoPending(loaded.state);
+  const ownerEmail = loaded.env.OR3_BASIC_AUTH_BOOTSTRAP_EMAIL;
+  const adminUsername = loaded.env.OR3_ADMIN_USERNAME;
+  if (!ownerEmail)
+    throw new Error("OR3_BASIC_AUTH_BOOTSTRAP_EMAIL is missing from .env, so the owner account cannot be reset.");
+  if (!adminUsername)
+    throw new Error("OR3_ADMIN_USERNAME is missing from .env, so the admin password cannot be reset.");
+  const { ownerPassword, adminPassword } = await resolveResetPasswords(flags);
+  const nextEnv = {
+    ...loaded.env,
+    OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD: ownerPassword,
+    OR3_ADMIN_PASSWORD: adminPassword,
+    OR3_ADMIN_JWT_SECRET: randomSecret()
+  };
+  const pending = {
+    id: id("credentials-reset"),
+    operation: "credentials-reset",
+    startedAt: now(),
+    message: "Resetting owner and admin credentials",
+    credentialReset: { nextEnv }
+  };
+  await markPending(loaded.directory, loaded.state, pending);
+  try {
+    await applyCredentialReset(loaded.directory, loaded.state, nextEnv);
+    await clearPending(loaded.directory, loaded.state);
+    console.log("Owner and admin credentials are now separate. The old owner password and all app sessions were revoked.");
+    console.log("Admin session cookies were invalidated by rotating OR3_ADMIN_JWT_SECRET. New passwords were written only to protected files; sign in again with them.");
+  } catch (error) {
+    loaded.state.lastError = redact(error instanceof Error ? error.message : String(error), secretValues(nextEnv));
+    await writeState(loaded.directory, loaded.state);
+    throw new Error(`${loaded.state.lastError}
+Credential reset is recoverable: run "npx @or3/cloud recover" to replay the intended protected operation.`);
+  }
+}
+async function credentialsCommand(directory, positionals, flags) {
+  const subcommand = positionals[0];
+  if (subcommand !== "reset") {
+    throw new Error(`Unknown credentials subcommand "${subcommand ?? ""}". Use "npx @or3/cloud credentials reset --yes".`);
+  }
+  if (positionals.length > 1)
+    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());
+  } else {
+    console.log(`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);
+}
+async function printMaintenanceSummary(directory, mode) {
+  const result = await run("docker", [...composeArgs(directory, mode, ["exec", "-T", "or3", CONTAINER_NODE, "-e", MAINTENANCE_SCRIPT])], directory);
+  if (!result.ok || !result.stdout.trim())
+    return;
+  try {
+    const maintenance = JSON.parse(result.stdout.trim());
+    if (!maintenance.enabled)
+      return;
+    const state = maintenance.state ?? "idle";
+    const line = `Sync history maintenance: ${state}${maintenance.lastRun ? ` (last run ${maintenance.lastRun})` : ""}${maintenance.backlog !== undefined ? `, backlog ${maintenance.backlog}` : ""}`;
+    if (state === "failed") {
+      console.log(`⚠ ${line}${maintenance.lastError ? `: ${maintenance.lastError}` : ""}`);
+    } else {
+      console.log(`  ${line}`);
+    }
+  } catch {}
+}
+async function logsCommand(directory, flags, positionals) {
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, loaded.state);
+  if (positionals.length > 1)
+    throw new Error("logs accepts at most one service name.");
+  const tailValue = stringFlag(flags, "tail") ?? "200";
+  const tail = Number(tailValue);
+  if (!Number.isInteger(tail) || tail < 1)
+    throw new Error("--tail must be a positive integer.");
+  const service = positionals[0];
+  const args = composeArgs(directory, loaded.state.mode, [
+    "logs",
+    "--no-color",
+    "--tail",
+    String(tail),
+    ...service ? [service] : []
+  ]);
+  const result = await run("docker", [...args], directory);
+  if (!result.ok)
+    throw new Error(`${result.command}
+${result.stderr}`);
+  const secrets = secretValues(loaded.env);
+  process.stdout.write(redact(result.stdout, secrets));
+  if (result.stderr)
+    process.stderr.write(redact(result.stderr, secrets));
+}
+async function startCommand(directory) {
+  await ensureDocker();
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, 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}.`);
+}
+async function stopCommand(directory) {
+  await ensureDocker();
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, loaded.state);
+  await stopProject(directory, loaded.state.mode);
+  console.log("OR3 stopped. The data volume, backups, and managed state are retained.");
+}
+async function restartCommand(directory) {
+  await ensureDocker();
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, 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.");
+}
+function purgeVolumesFromState(state) {
+  const volumes = [state.volumeName];
+  if (state.mode === "public") {
+    if (state.caddyDataVolume)
+      volumes.push(state.caddyDataVolume);
+    if (state.caddyConfigVolume)
+      volumes.push(state.caddyConfigVolume);
+  }
+  return volumes;
+}
+function assertPurgeBackupFreshness(backups, nowMs) {
+  const cutoff = nowMs - PURGE_REQUIRES_BACKUP_WITHIN_MS;
+  if (!backups.some((backup) => new Date(backup.createdAt).getTime() >= cutoff)) {
+    throw new Error('No backup newer than 24 hours exists for this deployment. Run "npx @or3/cloud backup" and "npx @or3/cloud backup export <backup-id> <destination-dir>" before destroying local data.');
+  }
+}
+async function readBackupExportReceipt(directory, backupId) {
+  try {
+    const receipt = JSON.parse(await readText(join(deploymentPaths(directory).exports, `${backupId}.json`)));
+    if (receipt.schemaVersion !== 1 || receipt.backupId !== backupId || typeof receipt.destination !== "string" || !isAbsolute(receipt.destination) || typeof receipt.destinationDevice !== "number" || !receipt.dataSha256)
+      return;
+    return receipt;
+  } catch {
+    return;
+  }
+}
+async function assertPurgeHasVerifiedExport(directory, backups, nowMs) {
+  assertPurgeBackupFreshness(backups, nowMs);
+  const cutoff = nowMs - PURGE_REQUIRES_BACKUP_WITHIN_MS;
+  for (const backup of backups) {
+    if (new Date(backup.createdAt).getTime() < cutoff)
+      continue;
+    const receipt = await readBackupExportReceipt(directory, backup.backupId);
+    if (!receipt || !await fileExists(receipt.destination))
+      continue;
+    try {
+      const exported = await readManifest(receipt.destination);
+      const sourceDevice = (await stat(backup.path)).dev;
+      const destinationDevice = (await stat(receipt.destination)).dev;
+      if (sourceDevice !== destinationDevice && receipt.destinationDevice === destinationDevice && exported.backupId === backup.backupId && exported.dataSha256 === receipt.dataSha256 && exported.dataSha256 === backup.dataSha256 && exported.configSha256 === receipt.configSha256)
+        return receipt;
+    } catch {}
+  }
+  throw new Error("No fresh checksum-verified backup export on another filesystem is available. Run `npx @or3/cloud backup export <backup-id> <new-directory-on-a-mounted-backup-disk>` before purging local data.");
+}
+async function removeCommand(directory, flags) {
+  if (boolFlag(flags, "purge-data") && !boolFlag(flags, "yes")) {
+    throw new Error("--purge-data deletes the data volume, every backup, and the managed files. Re-run with --purge-data --yes after confirming the data-loss boundary.");
+  }
+  await ensureDocker();
+  const loaded = await loadManaged(directory);
+  assertDeploymentDirectoryIdentity(directory, loaded.state);
+  assertNoPending(loaded.state);
+  const { state } = loaded;
+  if (!boolFlag(flags, "purge-data")) {
+    await compose(directory, state.mode, ["down"]);
+    console.log(`Removed runtime containers and network. Data volume, backups, configuration, and managed state are retained at ${directory}. Re-run \`npx @or3/cloud start\` to restore service.`);
+    return;
+  }
+  const exportReceipt = await assertPurgeHasVerifiedExport(directory, await enumerateBackups(directory), Date.now());
+  const volumes = purgeVolumesFromState(state);
+  const managedFiles = [".env", ".or3-cloud", "compose.yaml", ...state.mode === "public" ? ["compose.public.yaml", "Caddyfile"] : [], ".or3-initial-credentials"];
+  console.log("Removing exactly these targets:");
+  for (const volume of volumes)
+    console.log(`  docker volume ${volume}`);
+  for (const file of managedFiles)
+    console.log(`  ${join(directory, file)}`);
+  await compose(directory, state.mode, ["down"]);
+  for (const volume of volumes) {
+    const result = await run("docker", ["volume", "rm", volume], directory);
+    if (!result.ok)
+      throw new Error(`${result.command}
+${result.stderr}`);
+  }
+  for (const file of managedFiles) {
+    await rm(join(directory, file), { recursive: true, force: true });
+  }
+  console.log(`Purged: data volumes, backups, .env, managed state, and compose files were deleted. The verified export at ${exportReceipt.destination} is the remaining copy.`);
+}
+async function probeDeepHealth(directory, mode) {
+  const result = await run("docker", [...composeArgs(directory, mode, ["exec", "-T", "or3", CONTAINER_NODE, "-e", HEALTH_SCRIPT])], directory);
+  if (result.ok)
+    return "ok";
+  const ps = await run("docker", [...composeArgs(directory, mode, ["ps", "-q", "or3"])], directory);
+  if (ps.ok && ps.stdout.trim())
+    return "degraded";
+  return "unreachable";
+}
 async function main(argv = process.argv.slice(2)) {
   const [command = "help", ...rest] = argv;
   if (command === "--help" || command === "help")
@@ -1678,17 +2608,31 @@ async function main(argv = process.argv.slice(2)) {
     if (command === "update")
       return await updateCommand(process.cwd(), parsed.flags);
     if (command === "backup")
-      return await backupCommand(process.cwd());
+      return await backupCommand(process.cwd(), parsed.positionals, parsed.flags);
     if (command === "restore")
       return await restoreCommand(process.cwd(), parsed.flags, parsed.positionals);
     if (command === "rollback")
       return await rollbackCommand(process.cwd(), parsed.flags);
+    if (command === "credentials")
+      return await credentialsCommand(process.cwd(), parsed.positionals, parsed.flags);
     if (command === "doctor")
       return await doctorCommand(process.cwd());
     if (command === "recover")
       return await recoverCommand(process.cwd());
     if (command === "adopt")
       return await adoptCommand(parsed.positionals, parsed.flags);
+    if (command === "status")
+      return await statusCommand(process.cwd());
+    if (command === "logs")
+      return await logsCommand(process.cwd(), parsed.flags, parsed.positionals);
+    if (command === "start")
+      return await startCommand(process.cwd());
+    if (command === "stop")
+      return await stopCommand(process.cwd());
+    if (command === "restart")
+      return await restartCommand(process.cwd());
+    if (command === "remove")
+      return await removeCommand(process.cwd(), parsed.flags);
     throw new Error(`Unknown command "${command}". Run npx @or3/cloud --help.`);
   } catch (error) {
     console.error(`
@@ -1701,16 +2645,27 @@ if (invokedAsCli || process.argv[1] && resolve(process.argv[1]) === resolve(file
   await main();
 }
 export {
+  validatePassword,
+  supportedImageArchitectures,
   stateFromEnv,
+  serializeInitialCredentials,
   serializeEnv,
+  selectPruneTargets,
+  requiredArchiveSpace,
   redact,
+  purgeVolumesFromState,
   parseFlags,
   parseEnv,
   isVersion,
   checkResolvedLoopbackBinding,
   buildEnv,
+  buildCredentialsResetScript,
   assertSupportedSourceCompose,
   assertSupportedSource,
+  assertSupportedArchitecture,
+  assertRemovableArtifactName,
+  assertPurgeBackupFreshness,
+  assertEnoughFreeSpace,
   assertCommandFlags,
   assertBackupMatchesDeployment,
   PACKAGE_VERSION,