run-spaceapp 1.0.2 → 1.0.31

package/src/cli.mjs

@@ -1,7 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { createReadStream, createWriteStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { createInterface } from "node:readline";
+import { once } from "node:events";
+import { PromptController } from "./prompt-controller.mjs";
 import {
   copyFile,
   mkdir,
@@ -24,6 +26,7 @@ import {
   initializeInstallation,
   inspectSystemResources,
   installResourceChecks,
+  profileRuntimeSettings,
   loadConfig,
   planConfigRepairs,
   prepareInstallation,
@@ -40,6 +43,7 @@ import {
   writeRuntimeFiles,
   writeSetupToken
 } from "./index.mjs";
+import { inspectStoragePlan, storageChecks } from "./storage.mjs";
 import {
   ensureDockerAvailable,
   prepareDockerCliPath,
@@ -59,6 +63,7 @@ import {
 const APPLICATION_READY_WAIT_MINUTES = 10;
 const APPLICATION_READY_WAIT_MS = APPLICATION_READY_WAIT_MINUTES * 60 * 1_000;
 const APPLICATION_READY_POLL_MS = 2_000;
+const APPLICATION_READY_ATTEMPT_TIMEOUT_MS = 5_000;
 const APPLICATION_READY_MAX_ATTEMPTS = APPLICATION_READY_WAIT_MS / APPLICATION_READY_POLL_MS;
 const APPLICATION_READY_PROGRESS_ATTEMPTS = 30_000 / APPLICATION_READY_POLL_MS;
 const APPLICATION_READY_LOG_INTERVAL_SECONDS = 120;
@@ -114,37 +119,44 @@ export async function withHeadlessDockerConfig(platform, spec, run) {
   }
 }
 
+function approvedAutomation(stdin) {
+  const controller = stdin?._spaceappPromptController;
+  return controller?.nonInteractive === true && controller.answers.confirm === true;
+}
+
 function interactiveAvailable(stdin) {
   return Boolean(stdin?.isTTY && typeof stdin?.setRawMode === "function");
 }
 
-async function promptYesNo(stdin, stdout, question, { defaultYes = false } = {}) {
+async function promptYesNo(stdin, stdout, question, { defaultYes = false, answerKey = null } = {}) {
   for (;;) {
-    const answer = (await readSecret(stdin, stdout, `${question} [${defaultYes ? "Y/n" : "y/N"}] `, { mask: false })).trim().toLowerCase();
+    const answer = (await readSecret(stdin, stdout, `${question} [${defaultYes ? "Y/n" : "y/N"}] `, { mask: false, answerKey, defaultValue: defaultYes ? "y" : "n" })).trim().toLowerCase();
     if (answer === "") {
       return defaultYes;
     }
-    if (answer === "y" || answer === "yes") {
+    if (answer === "y" || answer === "yes" || answer === "true") {
       return true;
     }
-    if (answer === "n" || answer === "no") {
+    if (answer === "n" || answer === "no" || answer === "false") {
       return false;
     }
     stdout.write("Please answer y or n.\n");
   }
 }
 
-async function promptChoice(stdin, stdout, question, options, { defaultIndex = 0 } = {}) {
+async function promptChoice(stdin, stdout, question, options, { defaultIndex = 0, answerKey = null } = {}) {
   stdout.write(`${question}\n`);
   options.forEach((option, index) => {
     stdout.write(`  [${index + 1}] ${option.label}\n`);
   });
   for (;;) {
-    const answer = (await readSecret(stdin, stdout, `Select 1-${options.length} [${defaultIndex + 1}]: `, { mask: false })).trim();
+    const answer = (await readSecret(stdin, stdout, `Select 1-${options.length} [${defaultIndex + 1}]: `, { mask: false, answerKey, defaultValue: String(defaultIndex + 1) })).trim();
     if (answer === "") {
       return options[defaultIndex].value;
     }
-    const index = Number.parseInt(answer, 10);
+    const byValue = options.find((option) => option.value === answer);
+    if (byValue) return byValue.value;
+    const index = /^\d+$/.test(answer) ? Number(answer) : NaN;
     if (Number.isInteger(index) && index >= 1 && index <= options.length) {
       return options[index - 1].value;
     }
@@ -157,7 +169,7 @@ async function finalConfirmation(stdin, stdout, lines) {
   for (const line of lines) {
     stdout.write(`  - ${line}\n`);
   }
-  const approved = await promptYesNo(stdin, stdout, "Apply this plan?", { defaultYes: false });
+  const approved = await promptYesNo(stdin, stdout, "Apply this plan?", { defaultYes: false, answerKey: "confirm" });
   if (!approved) {
     stdout.write("Cancelled. No changes were made.\n");
   }
@@ -265,9 +277,73 @@ export async function run(argv, {
   runtimeVersion = RUNTIME_VERSION,
   hostRootRuntimeCompatible = HOST_ROOT_RUNTIME_COMPATIBLE
 } = {}) {
-  const [command = "help", ...args] = argv;
+  const globalFlags = {
+    localImages: false,
+    json: false,
+    plan: false,
+    nonInteractive: false,
+    logFile: null,
+    answersFile: null
+  };
+  const filteredArgv = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--local-images") {
+      globalFlags.localImages = true;
+    } else if (arg === "--json") {
+      globalFlags.json = true;
+    } else if (arg === "--plan") {
+      globalFlags.plan = true;
+    } else if (arg === "--non-interactive") {
+      globalFlags.nonInteractive = true;
+    } else if (arg === "--log-file" && i + 1 < argv.length) {
+      globalFlags.logFile = argv[++i];
+    } else if (arg.startsWith("--log-file=")) {
+      globalFlags.logFile = arg.slice("--log-file=".length);
+    } else if (arg === "--answers" && i + 1 < argv.length) {
+      globalFlags.answersFile = argv[++i];
+    } else if (arg.startsWith("--answers=")) {
+      globalFlags.answersFile = arg.slice("--answers=".length);
+    } else {
+      filteredArgv.push(arg);
+    }
+  }
+
+  const promptController = new PromptController({
+    stdin,
+    stdout,
+    stderr,
+    logFile: globalFlags.logFile,
+    nonInteractive: globalFlags.nonInteractive,
+    answersFile: globalFlags.answersFile,
+    planMode: globalFlags.plan,
+    jsonMode: globalFlags.json
+  });
+  if (stdin) {
+    stdin._spaceappPromptController = promptController;
+  }
+
+  const [command = "help", ...args] = filteredArgv;
   const root = resolveSpaceAppHome({ env, platform });
 
+  if (["help", "--help", "-h"].includes(command) || args.includes("--help") || args.includes("-h")) {
+    stdout.write(helpText());
+    return 0;
+  }
+  if (globalFlags.localImages) {
+    const originalExecute = execute;
+    execute = async (spec, io) => {
+      if (spec.command === "docker" && spec.args?.includes("compose")) {
+        if (spec.args.at(-1) === "pull") {
+          stdout.write("Local images only: skipping registry downloads; missing images will fail startup.\n");
+          return 0;
+        }
+        const index = spec.args.indexOf("up");
+        if (index !== -1) spec = {...spec, args: [...spec.args.slice(0,index+1), "--pull", "never", ...spec.args.slice(index+1)]};
+      }
+      return originalExecute(spec, io);
+    };
+  }
   if (command !== "install") {
     await prepareDockerPath({ platform, env });
   }
@@ -279,6 +355,10 @@ export async function run(argv, {
     stdout.write(`${launcherVersion}\n`);
     return 0;
   }
+  if (globalFlags.plan) {
+    stdout.write(`[PLAN] Preview execution for "${command}" at ${root} (no changes applied).\n`);
+    return 0;
+  }
   if (command === "install") {
     return installCommand(args, {
       root,
@@ -321,6 +401,14 @@ export async function run(argv, {
     return 0;
   }
 
+  if (command === "doctor" && !args.includes("--fix")) {
+    assertNoArgs(args, "doctor");
+    return doctor({ root, platform, stdout, stderr, execute, stdin, inspectResources });
+  }
+  if (command === "repair" || command === "doctor" && args.includes("--fix")) {
+    if (args.some((arg) => !["--dry-run", "--fix"].includes(arg))) throw new Error("Usage: repair [--dry-run] or doctor --fix");
+    return repairRuntime({ root, config: null, platform, stdin, stdout, stderr, execute, request, sleep, ensureDocker, env, arch, inspectResources, dryRun: args.includes("--dry-run") });
+  }
   const config = await loadConfig(root);
   if (commandNeedsRuntimeFiles(command, args)) {
     await writeRuntimeFiles(root, config);
@@ -349,6 +437,26 @@ export async function run(argv, {
     assertNoArgs(args, "doctor");
     return doctor({ root, platform, stdout, stderr, execute, stdin, inspectResources });
   }
+  if (command === "support-bundle") {
+    let outPath = null;
+    const outIdx = args.indexOf("--out");
+    if (outIdx !== -1 && args[outIdx + 1]) {
+      outPath = args[outIdx + 1];
+    }
+    return supportBundleCommand({ root, config, platform, arch, stdout, stderr, execute: runtimeExecute, request, outPath });
+  }
+  if (command === "repair") {
+    const dryRun = args.includes("--dry-run");
+    return repairRuntime({ root, config, platform, stdin, stdout, stderr, execute: runtimeExecute, request, sleep, dryRun });
+  }
+  if (command === "reinstall") {
+    const keepData = !args.includes("--purge-data");
+    return reinstallCommand({ root, config, platform, stdin, stdout, stderr, execute: runtimeExecute, request, sleep, keepData });
+  }
+  if (command === "factory-reset") {
+    assertNoArgs(args, "factory-reset");
+    return factoryResetCommand({ root, config, platform, stdin, stdout, stderr, execute: runtimeExecute, runtimeVersion, persistSetupToken });
+  }
   if (command === "workspace") {
     return workspaceCommand(args, { root, config, stdout });
   }
@@ -370,7 +478,10 @@ export async function run(argv, {
       stdin,
       stdout,
       stderr,
-      execute: runtimeExecute
+      execute: runtimeExecute,
+      request,
+      sleep,
+      inspectResources, ensureDocker, env, arch
     });
   }
   if (command === "rollback") {
@@ -518,7 +629,7 @@ async function installCommand(args, {
     stdout,
     stderr,
     execute,
-    inspectResources
+    inspectResources, request, sleep, ensureDocker, env, arch
   });
   if (wizard.exit !== undefined) {
     return wizard.exit;
@@ -545,7 +656,8 @@ async function installCommand(args, {
   }
   await prepareDockerPath({ platform, env });
   const resources = await inspectResources(root);
-  const profile = resolveInstallProfile(requestedProfile, resources.totalMemoryBytes);
+  let profile = requestedProfile === "auto" && existingConfig
+    ? existingConfig.profile : resolveInstallProfile(requestedProfile, resources);
   if (accessMode === "host-root") {
     stderr.write(
       "WARNING: host-root access lets SpaceApp CLI sessions read and modify the entire Linux host through /host, including credentials and system files.\n"
@@ -578,7 +690,8 @@ async function installCommand(args, {
     `Selected profile: ${profile} (${formatGibibytes(resources.totalMemoryBytes)} GiB system memory detected).\n`
   );
   stdout.write(`SpaceApp installation root: ${root}\n`);
-  if (installResourceChecks(resources).some((check) => !check.ok)) {
+  const operation = existingConfig ? (existingConfig.version === runtimeVersion ? "repair" : "upgrade") : "fresh";
+  if (installResourceChecks(resources, profile, { operation }).some((check) => !check.ok)) {
     const doctorCode = await doctor({
       root,
       platform,
@@ -587,7 +700,8 @@ async function installCommand(args, {
       execute,
       stdin,
       inspectResources,
-      resources
+      resources,
+      profile, operation
     });
     stderr.write(
       `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
@@ -603,7 +717,7 @@ async function installCommand(args, {
     stdout,
     stderr,
     execute,
-    installArgs: { root, requestedProfile, requestedAccessMode, noOpen }
+    installArgs: { root, requestedProfile, requestedAccessMode, noOpen, autoConfirm: true }
   });
   if (prerequisiteResult.reexecuted) {
     return prerequisiteResult.code;
@@ -615,6 +729,16 @@ async function installCommand(args, {
     return prerequisiteResult.code;
   }
 
+  let storagePlan = await inspectStoragePlan({ root, config: result.config, existingConfig, resources, execute, operation });
+  if (requestedProfile === "auto" && !existingConfig) {
+    const engineProfile = resolveInstallProfile("auto", storagePlan.resources);
+    if (engineProfile !== profile) {
+      profile = engineProfile;
+      result.config = { ...result.config, profile };
+      stdout.write(`Docker resources select profile: ${profile}.\n`);
+      storagePlan = await inspectStoragePlan({ root, config: result.config, resources: storagePlan.resources, execute, operation });
+    }
+  }
   const doctorCode = await doctor({
     root,
     platform,
@@ -624,7 +748,8 @@ async function installCommand(args, {
     stdin,
     inspectResources,
     resources,
-    dockerReady: true
+    profile,
+    dockerReady: true, operation, storagePlan
   });
   if (doctorCode !== 0) {
     stderr.write(
@@ -634,6 +759,7 @@ async function installCommand(args, {
   }
   const stagedStateRoot = await mkdtemp(join(tmpdir(), "run-spaceapp-install-"));
   let runtimeMutationAttempted = false;
+  let upgradeCheckpoint = null;
   const failAfterRuntimeMutation = async (code) => {
     if (runtimeMutationAttempted) {
       await reportInstallDiagnostics({
@@ -646,7 +772,10 @@ async function installCommand(args, {
         stderr,
         execute
       });
-      await restoreRuntimeAfterFailedInstall({
+      if (upgradeCheckpoint) {
+        await retainFailedUpgrade(root, upgradeCheckpoint,
+          {...result.config,accessMode:existingConfig.accessMode}, {stdin,stdout,stderr,execute});
+      } else await restoreRuntimeAfterFailedInstall({
         root,
         stagedStateRoot,
         existingConfig,
@@ -682,7 +811,18 @@ async function installCommand(args, {
       )
     );
     if (pullCode !== 0) return pullCode;
+    if (await verifyStorage({ root, config: result.config, existingConfig, operation,
+      inspectResources, execute, stdout, stderr }) !== 0) return 1;
+    if(existingConfig && existingConfig.version !== result.config.version) {
+      upgradeCheckpoint = await createQuiescedCheckpoint(root, existingConfig, {stdin,stdout,stderr,execute,platform});
+    }
     runtimeMutationAttempted = true;
+    if (existingConfig && !profileRuntimeSettings(existingConfig.profile).temporalEnabled &&
+        profileRuntimeSettings(profile).temporalEnabled) {
+      const temporalCode = await executeWithDockerDiagnostics(execute,
+        stagedComposeCommand("enableTemporal"), { stdin, stdout, stderr }, { platform, stderr });
+      if (temporalCode !== 0) return await failAfterRuntimeMutation(temporalCode);
+    }
     const upCode = await executeWithDockerDiagnostics(
       execute,
       stagedComposeCommand("up"),
@@ -699,6 +839,7 @@ async function installCommand(args, {
       url,
       request,
       sleep,
+      attemptTimeoutMs: Number(env.SPACEAPP_READY_ATTEMPT_TIMEOUT_MS) || APPLICATION_READY_ATTEMPT_TIMEOUT_MS,
       onProgress: async ({ elapsedSeconds }) => {
         stdout.write(
           `Still waiting for SpaceApp services (${elapsedSeconds} seconds elapsed; ` +
@@ -783,23 +924,9 @@ async function installCommand(args, {
       }
     }
 
-    if (profile === "light") {
-      const removeBrowserCode = await executeWithDockerDiagnostics(
-        execute,
-        composeCommand("removeBrowser", root, {
-          profile: "standard",
-          stateRoot: stagedStateRoot
-        }),
-        { stdin, stdout, stderr },
-        { platform, stderr }
-      );
-      if (removeBrowserCode !== 0) {
-        stderr.write(
-          "SpaceApp is ready, but the managed browser container could not be removed for the light profile.\n"
-        );
-        return await failAfterRuntimeMutation(removeBrowserCode);
-      }
-    }
+    const cleanupCode = await removeInactiveProfileServices({root, config: result.config,
+      stateRoot: stagedStateRoot, execute, stdin, stdout, stderr});
+    if (cleanupCode !== 0) return await failAfterRuntimeMutation(cleanupCode);
 
     if (setupToken) {
       try {
@@ -811,9 +938,12 @@ async function installCommand(args, {
         );
         return await failAfterRuntimeMutation(1);
       }
+
+
     }
 
     await commitInstallation(root, result.config);
+    if(upgradeCheckpoint) await markCheckpointVerified(upgradeCheckpoint);
     runtimeMutationAttempted = false;
     try {
       await reportFirstInstallPing({
@@ -840,7 +970,8 @@ async function installCommand(args, {
       stdout.write(`If it expires, run: ${UNIVERSAL_COMMAND} owner rotate-setup-token\n`);
     }
     stdout.write(
-      `Next: add CLI credentials with "${UNIVERSAL_COMMAND} credentials set <provider>".\n`
+      "Next: open the Getting Started room and use OpenCode. A working free model is selected on first launch.\n" +
+      `Optional providers: "${UNIVERSAL_COMMAND} credentials set <provider>".\n`
     );
     if (noOpen) return 0;
     const openCode = await openBrowser(url, platform, execute, { stdin, stdout, stderr });
@@ -856,6 +987,22 @@ async function installCommand(args, {
   }
 }
 
+async function removeInactiveProfileServices({root, config, stateRoot = root, execute, stdin, stdout, stderr}) {
+  const settings = profileRuntimeSettings(config.profile);
+  for (const [enabled, action, profile] of [
+    [settings.browserEnabled, "removeBrowser", "standard"],
+    [settings.temporalEnabled, "removeTemporal", "medium"]
+  ]) {
+    if (enabled) continue;
+    const code = await execute(composeCommand(action, root, {profile, stateRoot}), {stdin, stdout, stderr});
+    if (code !== 0) {
+      stderr.write("Inactive service cleanup failed. Data volumes were preserved. Run doctor --fix.\n");
+      return code;
+    }
+  }
+  return 0;
+}
+
 async function planInteractiveSetup({
   args,
   root,
@@ -865,7 +1012,8 @@ async function planInteractiveSetup({
   stdout,
   stderr,
   execute,
-  inspectResources
+  inspectResources,
+  request, sleep, ensureDocker, env, arch
 }) {
   const parsed = parseInstallArgs(args);
   const rawExisting = await readRawConfig(root);
@@ -874,7 +1022,7 @@ async function planInteractiveSetup({
   const interactive = interactiveAvailable(stdin);
   const continuation = await readRunOnceContinuation(root, { platform, runtimeVersion });
 
-  if (!interactive && !continuation) {
+  if (!interactive && !continuation && !approvedAutomation(stdin)) {
     stderr.write(
       "SpaceApp setup changes require an interactive terminal (TTY). " +
       "Re-run from a terminal, or continue an approved Windows RunOnce plan.\n"
@@ -884,7 +1032,8 @@ async function planInteractiveSetup({
 
   const resources = await inspectResources(root);
   const resolveProfileChoice = (choice) => {
-    const resolved = resolveInstallProfile(choice, resources.totalMemoryBytes);
+    const resolved = choice === "auto" && rawExisting?.profile
+      ? rawExisting.profile : resolveInstallProfile(choice, resources);
     return { resolved, display: choice === "auto" ? `auto (${resolved})` : resolved };
   };
 
@@ -904,16 +1053,19 @@ async function planInteractiveSetup({
 
   if (path === "fresh") {
     const profileChoice = await promptChoice(stdin, stdout, "Which installation profile?", [
-      { label: `auto (light profile on this system; ${formatGibibytes(resources.totalMemoryBytes)} GiB detected)`, value: "auto" },
-      { label: "light (smaller footprint)", value: "light" },
-      { label: "standard (full features, incl. managed browser)", value: "standard" }
-    ], { defaultIndex: ["auto", "light", "standard"].indexOf(parsed.requestedProfile) });
+      { label: `auto (${resolveProfileChoice("auto").resolved}; ${resources.cpuCount} CPUs, ${formatGibibytes(resources.totalMemoryBytes)} GiB RAM, ${formatGibibytes(resources.freeDiskBytes)} GiB free)`, value: "auto" },
+      { label: "small (SpaceApp + OpenCode; no background workflows or managed browser)", value: "small" },
+      { label: "medium (background workflows and integration workers)", value: "medium" },
+      { label: "large (workflows + managed browser; larger resource limits)", value: "large" },
+      { label: "light (legacy compatibility)", value: "light" },
+      { label: "standard (legacy compatibility)", value: "standard" }
+    ], { defaultIndex: Math.max(0, ["auto", "small", "medium", "large", "light", "standard"].indexOf(parsed.requestedProfile)), answerKey: "profile" });
     const accessChoice = await promptChoice(stdin, stdout, "Which access mode?", [
       { label: "isolated (recommended; no host access)", value: "isolated" },
       { label: "host-root (Linux only; CLI sessions can read and modify the whole host)", value: "host-root" }
-    ], { defaultIndex: parsed.requestedAccessMode === "host-root" ? 1 : 0 });
-    const companionsChoice = await promptYesNo(stdin, stdout, "Enable companion integrations (Claude Code, browser companions)?", { defaultYes: parsed.companionsEnabled });
-    const telemetryChoice = await promptYesNo(stdin, stdout, "Enable anonymous usage telemetry?", { defaultYes: false });
+    ], { defaultIndex: parsed.requestedAccessMode === "host-root" ? 1 : 0, answerKey: "access" });
+    const companionsChoice = await promptYesNo(stdin, stdout, "Enable companion integrations (Claude Code, browser companions)?", { defaultYes: parsed.companionsEnabled, answerKey: "companions" });
+    const telemetryChoice = await promptYesNo(stdin, stdout, "Enable anonymous usage telemetry?", { defaultYes: false, answerKey: "telemetry" });
     let dockerChoice = true;
     if (platform === "win32") {
       const dockerProbe = await detectDockerAvailable({ execute });
@@ -921,7 +1073,7 @@ async function planInteractiveSetup({
         dockerChoice = await promptYesNo(stdin, stdout, "Docker Engine was not detected. Include automatic Docker installation?", { defaultYes: true });
       }
     }
-    const openBrowserChoice = await promptYesNo(stdin, stdout, "Open the web application when installation completes?", { defaultYes: !parsed.noOpen });
+    const openBrowserChoice = await promptYesNo(stdin, stdout, "Open the web application when installation completes?", { defaultYes: !parsed.noOpen, answerKey: "open" });
 
     const { resolved } = resolveProfileChoice(profileChoice);
     const approved = await finalConfirmation(stdin, stdout, [
@@ -961,7 +1113,7 @@ async function planInteractiveSetup({
       { label: "Run doctor diagnostics (read-only)", value: "doctor" },
       { label: "Repair the runtime (recreate containers from the current configuration)", value: "repair" },
       { label: "Cancel", value: "cancel" }
-    ]);
+    ], {defaultIndex:1, answerKey:"action"});
     if (choice === "cancel") {
       stdout.write("Cancelled. No changes were made.\n");
       return { exit: 0 };
@@ -971,7 +1123,9 @@ async function planInteractiveSetup({
     }
     await applyApprovedConfigRepairs(root, rawExisting);
     const config = await loadExistingInstallation(root);
-    return { exit: await repairRuntime({ root, config, platform, stdin, stdout, stderr, execute }) };
+    const code = await repairRuntime({ root, config, platform, stdin, stdout, stderr, execute, request, sleep, ensureDocker, env, arch, inspectResources });
+    if(code === 0 && !parsed.noOpen) await openBrowser(`http://${config.bindHost}:${config.port}`, platform, execute, {stdin,stdout,stderr});
+    return {exit:code};
   }
 
   if (path === "downgrade") {
@@ -1006,7 +1160,7 @@ async function planInteractiveSetup({
     ...repairLines,
     path === "preserve-recreate"
       ? "Runtime: preserve/recreate (containers are recreated without touching data volumes)."
-      : "Runtime: standard staged upgrade; previous runtime is restored automatically on failure.",
+      : "Runtime: staged upgrade with a verified checkpoint; a failure after cutover preserves current data for recovery with doctor --fix.",
     "Preserved: data, workspaces, credentials, secrets, and persistent Docker volumes."
   ]);
   if (!approved) {
@@ -1083,7 +1237,26 @@ async function offerUnattendedContinuation(root, runtimeVersion, stdin, stdout,
   }
 }
 
-async function repairRuntime({ root, config, platform, stdin, stdout, stderr, execute }) {
+async function repairRuntime({ root, config, platform, stdin, stdout, stderr, execute, request, sleep, dryRun = false, ensureDocker = ensureDockerAvailable, env = process.env, arch = process.arch, inspectResources = inspectSystemResources }) {
+  const raw = await readRawConfig(root);
+  const plan = planConfigRepairs(raw);
+  if (dryRun) {
+    stdout.write(`Config repairs planned: ${JSON.stringify(plan)}\n`);
+    return 0;
+  }
+  if (!raw) throw new Error(`No installation found. Run "${UNIVERSAL_COMMAND} install" first.`);
+  const repaired = applyConfigRepairs(raw);
+  if (!await requireChangeApproval(stdin, stdout, stderr, [
+    "Repair configuration and recreate the current runtime without deleting data.",
+    ...plan.actions.map((action) => action.detail)
+  ])) return 1;
+  const prerequisites = await ensureDocker({platform, arch, env, stdin, stdout, stderr, execute, sleep: sleep || wait,
+    installArgs: {root,requestedProfile:repaired.profile,requestedAccessMode:repaired.accessMode,noOpen:true,autoConfirm:true}});
+  if(prerequisites.reexecuted || prerequisites.code !== 0) return prerequisites.code;
+  config = repaired;
+  if (await verifyStorage({ root, config, existingConfig: config, operation: "repair", inspectResources, execute, stdout, stderr }) !== 0) return 1;
+  await saveConfig(root, config);
+  await writeRuntimeFiles(root, config);
   const pullCode = await withHeadlessDockerConfig(
     platform,
     composeCommand("pull", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
@@ -1093,6 +1266,7 @@ async function repairRuntime({ root, config, platform, stdin, stdout, stderr, ex
     writeWindowsCredentialHint(platform, stderr);
     return pullCode;
   }
+  if (await verifyStorage({ root, config, existingConfig: config, operation: "repair", inspectResources, execute, stdout, stderr }) !== 0) return 1;
   const upCode = await execute(
     composeCommand("repair", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
     { stdin, stdout, stderr }
@@ -1100,6 +1274,23 @@ async function repairRuntime({ root, config, platform, stdin, stdout, stderr, ex
   if (upCode !== 0) {
     return upCode;
   }
+  if (typeof request === "function") {
+    const url = `http://${config.bindHost}:${config.port}`;
+    const ready = await waitForReadiness({
+      url,
+      request,
+      sleep: sleep || wait,
+      onProgress: async ({ elapsedSeconds }) => {
+        stdout.write(`Waiting for SpaceApp readiness after repair (${elapsedSeconds}s)...\n`);
+      }
+    });
+    if (!ready) {
+      stderr.write("SpaceApp runtime repair completed, but readiness check timed out.\n");
+      return 1;
+    }
+  }
+  const cleanupCode = await removeInactiveProfileServices({root, config, execute, stdin, stdout, stderr});
+  if (cleanupCode !== 0) return cleanupCode;
   stdout.write(`SpaceApp ${config.version} runtime repaired.\n`);
   return 0;
 }
@@ -1113,7 +1304,10 @@ async function performUpdate({
   stdout,
   stderr,
   execute,
-  preserveRecreate
+  preserveRecreate,
+  request,
+  sleep,
+  inspectResources = inspectSystemResources
 }) {
   const updated = targetVersion === config.version
     ? config
@@ -1122,27 +1316,22 @@ async function performUpdate({
       version: targetVersion,
       previousVersion: config.version
     };
-  const checkpoint = await createCheckpoint(root, config, { stdin, stdout, stderr, execute, platform });
+  const stagedRoot = await mkdtemp(join(tmpdir(), "spaceapp-update-"));
+  let checkpoint = null;
   try {
-    await writeRuntimeFiles(root, updated);
-    if (preserveRecreate) {
-      const downCode = await execute(
-        composeCommand("down", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
-        { stdin, stdout, stderr }
-      );
-      if (downCode !== 0) {
-        throw new Error(`Preserve/recreate stop failed with Docker exit ${downCode}.`);
-      }
-    }
+    await writeRuntimeFiles(stagedRoot, updated);
+    const stagedCommand = (action) => composeCommand(action, root, {...updated, stateRoot: stagedRoot});
     const pullCode = await withHeadlessDockerConfig(
-      platform,
-      composeCommand("pull", root, { profile: updated.profile, companionsEnabled: updated.companionsEnabled }),
+      platform, stagedCommand("pull"),
       (pullSpec) => execute(pullSpec, { stdin, stdout, stderr })
     );
     if (pullCode !== 0) {
       writeWindowsCredentialHint(platform, stderr);
       throw new Error(`Image pull failed with Docker exit ${pullCode}.`);
     }
+    if (await verifyStorage({ root, config: updated, existingConfig: config, operation: "upgrade", inspectResources, execute, stdout, stderr }) !== 0) return 1;
+    checkpoint = await createQuiescedCheckpoint(root, config, {stdin, stdout, stderr, execute, platform});
+    await writeRuntimeFiles(root, updated);
     const upCode = await execute(
       composeCommand("up", root, { profile: updated.profile, companionsEnabled: updated.companionsEnabled }),
       { stdin, stdout, stderr }
@@ -1150,27 +1339,38 @@ async function performUpdate({
     if (upCode !== 0) {
       throw new Error(`Runtime start failed with Docker exit ${upCode}.`);
     }
+    if (typeof request === "function") {
+      const url = `http://${updated.bindHost}:${updated.port}`;
+      const ready = await waitForReadiness({
+        url,
+        request,
+        sleep: sleep || wait,
+        onProgress: async ({ elapsedSeconds }) => {
+          stdout.write(`Waiting for SpaceApp readiness after update (${elapsedSeconds}s)...\n`);
+        }
+      });
+      if (!ready) {
+        throw new Error("Updated runtime started, but readiness check timed out.");
+      }
+    }
     await saveConfig(root, updated);
     await markCheckpointVerified(checkpoint);
     stdout.write(`Updated to SpaceApp ${targetVersion}.\n`);
     return 0;
   } catch (error) {
     stderr.write(`SpaceApp update failed: ${error?.message || String(error)}\n`);
-    const restored = await restoreCheckpoint(root, checkpoint, { stdin, stdout, stderr, execute, config });
-    if (!restored) {
-      stderr.write(
-        `Automatic restore failed. The checkpoint remains available at ${checkpoint.path} for manual recovery.\n`
-      );
-    }
+    if(checkpoint) await retainFailedUpgrade(root, checkpoint, updated, {stdin,stdout,stderr,execute});
     return 1;
+  } finally {
+    await rm(stagedRoot, {recursive: true, force: true});
   }
 }
 
-const CHECKPOINT_ID_PATTERN = /^spaceapp-checkpoint-\d{8}T\d{6}Z$/;
+const CHECKPOINT_ID_PATTERN = /^spaceapp-checkpoint-\d{8}T\d{6}Z(?:-[a-f0-9]{8})?$/;
 const CHECKPOINT_KEEP_COUNT = 2;
 
 function checkpointId() {
-  return `spaceapp-checkpoint-${new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}`;
+  return `spaceapp-checkpoint-${new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}-${randomBytes(4).toString("hex")}`;
 }
 
 async function manifestEntry(path, logicalPath) {
@@ -1207,6 +1407,19 @@ async function collectFiles(directory, logicalDirectory) {
   return files;
 }
 
+async function createQuiescedCheckpoint(root, config, io) {
+  io.stdout.write("Pausing SpaceApp writers before the database checkpoint...\n");
+  try {
+    const code = await io.execute(composeCommand("stopForRestore", root, config), io);
+    if (code !== 0) throw new Error(`Could not pause SpaceApp writers (exit ${code}).`);
+    return await createCheckpoint(root, config, io);
+  } catch (error) {
+    const resumed = await io.execute(composeCommand("up", root, config), io).catch(() => 1);
+    if (resumed !== 0) io.stderr.write("RECOVERY_REQUIRED: could not resume the unchanged runtime. Run doctor --fix.\n");
+    throw error;
+  }
+}
+
 async function createCheckpoint(root, config, { stdin, stdout, stderr, execute, platform }) {
   const id = checkpointId();
   const path = join(root, "checkpoints", id);
@@ -1234,18 +1447,22 @@ async function createCheckpoint(root, config, { stdin, stdout, stderr, execute,
   }
   stdout.write("Creating checkpoint (configuration, secrets, and database dump)...\n");
   const dumpPath = join(path, "postgres.dump");
-  const dumpCode = await execute(
-    composeCommand("checkpointDump", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
-    { stdin: null, stdout: createWriteStream(dumpPath), stderr }
-  );
-  if (dumpCode !== 0) {
-    await rm(path, { recursive: true, force: true });
-    throw new Error(`Checkpoint database dump failed with Docker exit ${dumpCode}. No changes were made.`);
-  }
+  const dumpStream=createWriteStream(dumpPath,{mode:0o600});
+  await once(dumpStream,"open");
+  let dumpCode;
   try {
-    await stat(dumpPath);
-  } catch {
-    await writeFile(dumpPath, "");
+    dumpCode = await execute(
+      composeCommand("checkpointDump", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
+      { stdin: null, stdout: dumpStream, stderr }
+    );
+  } finally {
+    dumpStream.end();
+    await once(dumpStream,"close");
+  }
+  const dumpSize=(await stat(dumpPath)).size;
+  if (dumpCode !== 0 || dumpSize === 0) {
+    await rm(path, { recursive: true, force: true });
+    throw new Error(`Checkpoint database dump failed or was empty (exit ${dumpCode}). The upgrade was not applied.`);
   }
   manifest.files.push(await manifestEntry(dumpPath, "postgres.dump"));
   await writeFile(join(path, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
@@ -1266,6 +1483,21 @@ async function verifyCheckpoint(checkpoint) {
   return true;
 }
 
+async function retainFailedUpgrade(root, checkpoint, attemptedConfig, io) {
+  // A partially started runtime may already have accepted owner writes. Never
+  // replace its database automatically with an older snapshot.
+  const stopCode = await io.execute(composeCommand("stopForRestore", root, attemptedConfig),
+    {stdin:null,stdout:io.stdout,stderr:io.stderr}).catch(()=>1);
+  await commitInstallation(root, attemptedConfig);
+  const recovery = {status:"RECOVERY_REQUIRED",failedAt:new Date().toISOString(),
+    previousVersion:checkpoint.manifest.version,attemptedVersion:attemptedConfig.version,
+    checkpointPath:checkpoint.path,databasePreserved:true,writersStopped:stopCode===0};
+  await writeFile(join(checkpoint.path,"recovery.json"),`${JSON.stringify(recovery,null,2)}\n`,{mode:0o600});
+  io.stderr.write(`RECOVERY_REQUIRED: the current database and volumes were retained. Checkpoint: ${checkpoint.path}\n`);
+  if(stopCode!==0)io.stderr.write("Could not stop all application writers. No database restore was attempted.\n");
+  io.stderr.write(`Run "${UNIVERSAL_COMMAND} doctor --fix" to repair the attempted version. Restoring older data requires an explicit recovery decision.\n`);
+}
+
 async function markCheckpointVerified(checkpoint) {
   await writeFile(
     join(checkpoint.path, "verified.json"),
@@ -1281,49 +1513,17 @@ async function pruneCheckpoints(currentPath) {
     .filter((entry) => entry.isDirectory() && CHECKPOINT_ID_PATTERN.test(entry.name))
     .map((entry) => join(parent, entry.name))
     .sort();
-  while (entries.length > CHECKPOINT_KEEP_COUNT) {
-    await rm(entries.shift(), { recursive: true, force: true });
-  }
-}
-
-async function restoreCheckpoint(root, checkpoint, { stdin, stdout, stderr, execute, config }) {
-  if (!checkpoint) {
-    stderr.write("No checkpoint was available for restore.\n");
-    return false;
-  }
-  const verified = await verifyCheckpoint(checkpoint);
-  if (!verified) {
-    stderr.write(`Checkpoint ${checkpoint.id} failed verification; it remains at ${checkpoint.path} for manual recovery.\n`);
-    return false;
-  }
-  stdout.write(`Restoring checkpoint ${checkpoint.id}...\n`);
-  await execute(
-    composeCommand("down", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
-    { stdin: null, stdout: null, stderr: null }
-  ).catch(() => {});
-  const fileNames = ["config.json", "runtime.env", "compose.yml", "compose.workspaces.yml", "compose.host-access.yml"];
-  for (const fileName of fileNames) {
-    await copyFile(join(checkpoint.path, fileName), join(root, fileName));
+  const verified = [];
+  for (const entry of entries) {
+    if (await stat(join(entry, "verified.json")).catch(() => null)) verified.push(entry);
   }
-  const restored = await loadConfig(root);
-  const dumpPath = join(checkpoint.path, "postgres.dump");
-  const dbCode = await execute(
-    composeCommand("checkpointRestore", root, { profile: restored.profile, companionsEnabled: restored.companionsEnabled }),
-    { stdin: createReadStream(dumpPath), stdout, stderr }
-  );
-  if (dbCode !== 0) {
-    stderr.write(`Checkpoint database restore failed with Docker exit ${dbCode}. Checkpoint remains at ${checkpoint.path}.\n`);
-    return false;
+  while (verified.length > CHECKPOINT_KEEP_COUNT) {
+    await rm(verified.shift(), { recursive: true, force: true });
   }
-  const upCode = await execute(
-    composeCommand("up", root, { profile: restored.profile, companionsEnabled: restored.companionsEnabled }),
-    { stdin, stdout, stderr }
-  );
-  return upCode === 0;
 }
 
 async function requireChangeApproval(stdin, stdout, stderr, lines) {
-  if (!interactiveAvailable(stdin)) {
+  if (!interactiveAvailable(stdin) && !approvedAutomation(stdin)) {
     stderr.write("This change requires an interactive terminal (TTY). No changes were made.\n");
     return false;
   }
@@ -1394,18 +1594,9 @@ async function restoreRuntimeAfterFailedInstall({
         })
       );
       if (restoreCode === 0) {
-        if (existingConfig.profile === "light") {
-          const cleanupCode = await runtimeExecute(
-            composeCommand("removeBrowser", root, {
-              profile: "standard"
-            })
-          );
-          if (cleanupCode !== 0) {
-            stderr.write(
-              "The previous SpaceApp runtime was restored, but an inactive browser container may remain.\n"
-            );
-          }
-        }
+        const cleanupCode = await removeInactiveProfileServices({root, config: existingConfig,
+          execute: runtimeExecute, stdin, stdout, stderr});
+        if (cleanupCode !== 0) stderr.write("The previous runtime was restored, but inactive service cleanup failed. Run doctor --fix.\n");
         stderr.write("The previous SpaceApp runtime and access mode were restored.\n");
         return;
       }
@@ -1467,18 +1658,18 @@ function parseInstallArgs(args) {
       continue;
     }
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
     );
   }
   if (
-    !["auto", "light", "standard"].includes(requestedProfile) ||
+    !["auto", "small", "medium", "large", "light", "standard"].includes(requestedProfile) ||
     (
       requestedAccessMode !== undefined &&
       !["isolated", "host-root"].includes(requestedAccessMode)
     )
   ) {
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
     );
   }
   return { requestedProfile, requestedAccessMode, noOpen, companionsEnabled };
@@ -1573,11 +1764,14 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
 }
 
 async function providerCommand(args, { root, config, stdin, stdout, stderr, execute }) {
-  if (args.length !== 2 || args[0] !== "install" || args[1] !== "claude") {
-    throw new Error(`Usage: ${UNIVERSAL_COMMAND} provider install claude`);
-  }
-  stdout.write("Installing Claude Code from Anthropic into this installation's private provider volume.\n");
-  return execute(composeCommand("installClaude", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
+  if (args.length !== 2 || args[0] !== "install") {
+    throw new Error(`Usage: ${UNIVERSAL_COMMAND} provider install <provider>`);
+  }
+  const provider=args[1];
+  stdout.write(`Installing optional provider ${provider} into this installation's private provider volume.\n`);
+  // Keep the existing Claude path compatible with older runtime images.
+  const action=provider === "claude" ? "installClaude" : "installProvider";
+  return execute(composeCommand(action, root, { profile: config.profile, companionsEnabled: config.companionsEnabled, provider }), { stdin, stdout, stderr });
 }
 
 async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute }) {
@@ -1612,7 +1806,179 @@ async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute
   });
 }
 
-async function updateCommand(args, { root, config, version, platform, stdin, stdout, stderr, execute }) {
+async function reinstallCommand({
+  root,
+  config,
+  platform,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  request,
+  sleep
+}) {
+  const approved = await requireChangeApproval(stdin, stdout, stderr, [
+    `Clean setup SpaceApp at ${root}`,
+    "This recreates managed files, templates, and runtime containers.",
+    "Your database, persistent data, and credentials will be preserved."
+  ]);
+  if (!approved) {
+    return 0;
+  }
+  const downCode = await execute(
+    composeCommand("down", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
+    { stdin, stdout, stderr }
+  );
+  if (downCode !== 0) {
+    stderr.write(`Clean setup warning: container stop returned exit ${downCode}.\n`);
+  }
+  await writeRuntimeFiles(root, config);
+  const upCode = await execute(
+    composeCommand("up", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
+    { stdin, stdout, stderr }
+  );
+  if (upCode !== 0) {
+    stderr.write(`Clean setup failed during container startup (exit ${upCode}).\n`);
+    return upCode;
+  }
+  if (typeof request === "function") {
+    const url = `http://${config.bindHost}:${config.port}`;
+    const ready = await waitForReadiness({
+      url,
+      request,
+      sleep: sleep || wait,
+      onProgress: async ({ elapsedSeconds }) => {
+        stdout.write(`Waiting for SpaceApp readiness after clean setup (${elapsedSeconds}s)...\n`);
+      }
+    });
+    if (!ready) {
+      stderr.write("Clean setup completed container start, but readiness check timed out.\n");
+      return 1;
+    }
+  }
+  stdout.write("SpaceApp clean setup completed successfully. All data and settings preserved.\n");
+  return 0;
+}
+
+async function supportBundleCommand({
+  root,
+  config,
+  platform,
+  arch,
+  stdout,
+  stderr,
+  execute,
+  request,
+  outPath
+}) {
+  const bundle = {
+    schemaVersion: "1.0.0",
+    collectedAt: new Date().toISOString(),
+    system: {
+      platform,
+      arch,
+      nodeVersion: process.version,
+      release: typeof process.release === "object" ? process.release.name : "unknown"
+    },
+    launcher: {
+      version: PACKAGE_VERSION,
+      runtimeVersion: RUNTIME_VERSION
+    },
+    installation: {
+      root,
+      config: config
+        ? {
+            version: config.version,
+            profile: config.profile,
+            accessMode: config.accessMode,
+            companionsEnabled: config.companionsEnabled,
+            bindHost: config.bindHost,
+            port: config.port,
+            previousVersion: config.previousVersion ?? null
+          }
+        : null
+    },
+    services: {},
+    health: {}
+  };
+
+  if (config) {
+    const url = `http://${config.bindHost}:${config.port}`;
+    if (typeof request === "function") {
+      try {
+        const res = await request(`${url}/readyz`, { method: "GET", signal: AbortSignal.timeout(3000) });
+        bundle.health.readyz = { status: res.status, ok: res.ok };
+      } catch (e) {
+        bundle.health.readyz = { error: e.message };
+      }
+    }
+  }
+
+  const destination = outPath || join(
+    root,
+    `support-bundle-${new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}.json`
+  );
+  await writeFile(destination, JSON.stringify(bundle, null, 2), { mode: 0o600 });
+  stdout.write(`SpaceApp support bundle generated: ${destination}\n`);
+  return 0;
+}
+
+async function factoryResetCommand({
+  root,
+  config,
+  platform,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  runtimeVersion,
+  persistSetupToken
+}) {
+  stdout.write("\nWARNING: Factory reset will PERMANENTLY ERASE all local database records, persistent volumes, and configuration.\n");
+  stdout.write("External workspaces outside the installation root are preserved.\n\n");
+
+  try {
+    stdout.write("Creating safety backup before factory reset...\n");
+    await execute(
+      composeCommand("backup", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
+      { stdin, stdout, stderr }
+    );
+  } catch (err) {
+    stdout.write(`Safety backup notice: ${err.message}. Continuing with reset confirmation.\n`);
+  }
+
+  const confirm = await readSecret(
+    stdin,
+    stdout,
+    "Type FACTORY-RESET to remove all data and reset SpaceApp: ",
+    { mask: false }
+  );
+  if (confirm.trim() !== "FACTORY-RESET") {
+    stdout.write("Factory reset cancelled. No data was erased.\n");
+    return 0;
+  }
+
+  await execute(
+    composeCommand("purge", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
+    { stdin, stdout, stderr }
+  );
+
+  try {
+    await rm(join(root, "config.json"), { force: true });
+    await rm(join(root, "runtime.env"), { force: true });
+    await rm(join(root, "compose.yml"), { force: true });
+  } catch {}
+
+  const result = await initializeInstallation(root, { version: runtimeVersion });
+  stdout.write(`SpaceApp factory reset complete. Clean installation initialized at ${root}\n`);
+  if (result.setupToken) {
+    stdout.write(`One-time setup token: ${result.setupToken}\n`);
+    stdout.write("Store it temporarily; it expires after first owner setup.\n");
+  }
+  return 0;
+}
+
+async function updateCommand(args, { root, config, version, platform, stdin, stdout, stderr, execute, request, sleep, inspectResources = inspectSystemResources, ensureDocker = ensureDockerAvailable, env = process.env, arch = process.arch }) {
   if (args.length > 1) {
     throw new Error(`Usage: ${UNIVERSAL_COMMAND} update [version]`);
   }
@@ -1620,7 +1986,7 @@ async function updateCommand(args, { root, config, version, platform, stdin, std
   const path = upgradePath(config.version, targetVersion);
   const interactive = interactiveAvailable(stdin);
   const continuation = await readRunOnceContinuation(root, { platform, runtimeVersion: targetVersion });
-  if (!interactive && !continuation) {
+  if (!interactive && !continuation && !approvedAutomation(stdin)) {
     stderr.write(
       "SpaceApp update changes require an interactive terminal (TTY). " +
       "Re-run from a terminal, or continue an approved Windows RunOnce plan.\n"
@@ -1646,7 +2012,7 @@ async function updateCommand(args, { root, config, version, platform, stdin, std
         return doctor({ root, platform, stdout, stderr, execute, stdin, inspectResources: inspectSystemResources });
       }
     }
-    return repairRuntime({ root, config, platform, stdin, stdout, stderr, execute });
+    return repairRuntime({ root, config, platform, stdin, stdout, stderr, execute, request, sleep, inspectResources, ensureDocker, env, arch });
   }
   if (path === "downgrade") {
     if (!continuation) {
@@ -1675,16 +2041,23 @@ async function updateCommand(args, { root, config, version, platform, stdin, std
   if (!continuation) {
     const approved = await finalConfirmation(stdin, stdout, [
       `Runtime image version: ${config.version} -> ${targetVersion}`,
-      "Checkpoint: configuration, secrets, and a database dump are saved before the change and restored automatically on failure.",
+      "Checkpoint: configuration, secrets, and a verified database dump are saved before the change; current data is preserved if cutover fails.",
       "Downtime: containers restart during the cutover.",
       SPACEAPP_UPGRADE_POLICY.rollbackCapable
-        ? "Rollback: the previous runtime is restored automatically on failure; the previous version stays recorded for manual rollback."
+        ? "Recovery: use doctor --fix after a failed cutover; the previous version and verified checkpoint remain available for explicit rollback."
         : "Rollback: not supported for this target version."
     ]);
     if (!approved) {
       return 0;
     }
   }
+  const prerequisites = await ensureDocker({ platform, arch, env, stdin, stdout, stderr, execute,
+    installArgs: { root, requestedProfile: config.profile, noOpen: true, autoConfirm: true } });
+  if (prerequisites.reexecuted || prerequisites.code !== 0) return prerequisites.code;
+  const resources = await inspectResources(root);
+  const storagePlan = await inspectStoragePlan({ root, config: { ...config, version: targetVersion }, existingConfig: config, resources, execute, operation: "upgrade" });
+  if (await doctor({ root, platform, stdout, stderr, execute, stdin, inspectResources, resources,
+    profile: config.profile, dockerReady: true, operation: "upgrade", storagePlan }) !== 0) return 1;
   return performUpdate({
     root,
     config,
@@ -1694,10 +2067,25 @@ async function updateCommand(args, { root, config, version, platform, stdin, std
     stdout,
     stderr,
     execute,
+    request,
+    sleep,
+    inspectResources,
     preserveRecreate: path === "preserve-recreate"
   });
 }
 
+async function verifyStorage({ root, config, existingConfig, operation, inspectResources, execute, stdout, stderr }) {
+  const resources = await inspectResources(root);
+  const plan = await inspectStoragePlan({ root, config, existingConfig, operation, resources, execute });
+  const checks = storageChecks(plan, resources);
+  for (const check of checks) (check.ok ? stdout : stderr).write(`${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}\n`);
+  if (checks.some((check) => !check.ok)) {
+    stderr.write("Insufficient additional storage. Existing data and runtime have not been replaced; free space and retry.\n");
+    return 1;
+  }
+  return 0;
+}
+
 async function doctor({
   root,
   platform,
@@ -1707,13 +2095,33 @@ async function doctor({
   stdin,
   inspectResources,
   resources,
+  profile,
+  operation,
+  storagePlan,
   dockerReady = false
 }) {
+  const configuration = profile ? { ok: true, detail: "Prepared installation configuration" } : await loadConfig(root).then(() => ({ ok: true, detail: root })).catch((error) => ({ ok: false, detail: `${error.message}. Run install for a new setup, or doctor --fix for an existing setup.` }));
   const detectedResources = resources ?? await inspectResources(root);
+  let resolvedProfile = profile;
+  if (!resolvedProfile) {
+    const existingConfig = await loadConfig(root).catch(() => null);
+    if (existingConfig?.profile) {
+      resolvedProfile = existingConfig.profile;
+    } else if (detectedResources?.totalMemoryBytes) {
+      resolvedProfile = resolveInstallProfile("auto", detectedResources);
+    } else {
+      resolvedProfile = "light";
+    }
+  }
+  operation ??= await loadConfig(root).then(() => "maintenance").catch(() => "fresh");
+  const resourceChecks = installResourceChecks(storagePlan?.resources ?? detectedResources, resolvedProfile, {
+    operation, ...(storagePlan ? { requiredDiskBytes: storagePlan.requiredDiskBytes } : {})
+  });
   const checks = [
     { name: "Node.js", ok: Number(process.versions.node.split(".")[0]) >= 20, detail: process.version },
-    { name: "Configuration", ok: true, detail: root },
-    ...installResourceChecks(detectedResources)
+    { name: "Configuration", ...configuration },
+    ...resourceChecks.filter((check) => !storagePlan || check.name !== "Free disk"),
+    ...(storagePlan ? storageChecks(storagePlan, detectedResources) : [])
   ];
   const dockerResults = [];
   for (const probe of [
@@ -1770,7 +2178,8 @@ async function waitForApplicationReady({
   request,
   sleep,
   onProgress,
-  maxAttempts = APPLICATION_READY_MAX_ATTEMPTS
+  maxAttempts = APPLICATION_READY_MAX_ATTEMPTS,
+  attemptTimeoutMs = APPLICATION_READY_ATTEMPT_TIMEOUT_MS
 }) {
   if (typeof request !== "function") {
     throw new Error("SpaceApp readiness requires a Fetch-compatible request function.");
@@ -1779,12 +2188,19 @@ async function waitForApplicationReady({
   const timeout = setTimeout(() => controller.abort(), APPLICATION_READY_WAIT_MS);
   try {
     for (let attempt = 0; attempt <= maxAttempts; attempt += 1) {
+      const attemptController = new AbortController();
+      const attemptTimeout = setTimeout(
+        () => attemptController.abort(),
+        attemptTimeoutMs
+      );
+      const onOverallAbort = () => attemptController.abort();
+      controller.signal.addEventListener("abort", onOverallAbort, { once: true });
       try {
         const response = await request(`${url}/readyz`, {
           method: "GET",
           headers: { accept: "application/json" },
           redirect: "error",
-          signal: controller.signal
+          signal: attemptController.signal
         });
         if (response?.ok) {
           const payload = await response.json();
@@ -1796,6 +2212,9 @@ async function waitForApplicationReady({
         if (controller.signal.aborted) {
           return false;
         }
+      } finally {
+        clearTimeout(attemptTimeout);
+        controller.signal.removeEventListener("abort", onOverallAbort);
       }
       if (attempt < maxAttempts && !controller.signal.aborted) {
         await sleep(APPLICATION_READY_POLL_MS);
@@ -1816,6 +2235,8 @@ async function waitForApplicationReady({
   }
 }
 
+const waitForReadiness = waitForApplicationReady;
+
 async function requestSetupStatus({ url, request }) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), SETUP_STATUS_TIMEOUT_MS);
@@ -1859,131 +2280,9 @@ async function executeWithDockerDiagnostics(execute, spec, io, { platform, stder
   return code;
 }
 
-export async function readSecret(stdin, stdout, prompt, { mask = true } = {}) {
-  stdout.write(prompt);
-  if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
-    // Non-TTY stdin (e.g. piped input on Windows through npx.cmd). Read only
-    // up to the first newline so an interactive console that reports non-TTY
-    // stdin still works: previously this drained the stream to EOF, so typing
-    // "y" + Enter looked frozen and a second keystroke produced "y\ny" and
-    // "Please answer y or n." loops. When the stream ends before a newline
-    // (fully piped answers), everything read is returned as-is so "y\nn\n"
-    // piped input still yields successive valid answers. Event listeners are
-    // used instead of the Readable async iterator because an abandoned
-    // iterator can destroy the stream, breaking the next prompt.
-    const value = await new Promise((resolve) => {
-      let answer = "";
-      const finish = (result) => {
-        cleanup();
-        resolve(result);
-      };
-      // Paused-mode reads: consume exactly one line from the buffer, leaving
-      // the rest (and the stream itself) intact for the next prompt.
-      const onReadable = () => {
-        let chunk;
-        while ((chunk = stdin.read()) !== null) {
-          for (const character of String(chunk)) {
-            if (character === "\r" || character === "\n") {
-              finish(answer);
-              return;
-            }
-            answer += character;
-          }
-        }
-      };
-      const onEnd = () => finish(answer);
-      const onClose = () => finish(answer);
-      const cleanup = () => {
-        stdin.off("readable", onReadable);
-        stdin.off("end", onEnd);
-        stdin.off("close", onClose);
-      };
-      if (typeof stdin.read === "function" && typeof stdin.on === "function") {
-        stdin.on("readable", onReadable);
-        stdin.once("end", onEnd);
-        stdin.once("close", onClose);
-        onReadable();
-      } else {
-        // Fallback for exotic streams without readable-mode support.
-        const iterator = stdin[Symbol.asyncIterator]();
-        (async () => {
-          for (;;) {
-            const step = await iterator.next();
-            if (step.done) {
-              finish(answer);
-              return;
-            }
-            for (const character of String(step.value)) {
-              if (character === "\r" || character === "\n") {
-                finish(answer);
-                return;
-              }
-              answer += character;
-            }
-          }
-        })().catch(() => finish(answer));
-      }
-    });
-    stdout.write("\n");
-    return value;
-  }
-  if (process.platform === "win32") {
-    // Windows consoles (PowerShell 7 / ConPTY) do not reliably forward
-    // raw-mode keystrokes to native children: a "y" + Enter can be frozen,
-    // split across chunks, or doubled ("yy" -> "Please answer y or n.").
-    // Read cooked console lines without setRawMode instead; the console
-    // itself provides line editing and echo.
-    const rl = createInterface({ input: stdin, terminal: false, crlfDelay: Infinity });
-    const cooked = await new Promise((resolve) => {
-      let got = null;
-      rl.on("line", (line) => {
-        got = line;
-        rl.close();
-      });
-      rl.on("close", () => resolve(got ?? ""));
-    });
-    stdout.write("\n");
-    return cooked;
-  }
-  stdin.setRawMode(true);
-  stdin.resume();
-  stdin.setEncoding("utf8");
-  let value = "";
-  try {
-    // Drive the iterator manually instead of breaking a for-await loop:
-    // breaking a for-await early calls the Readable async iterator's return(),
-    // which DESTROYS the stream, so any later prompt would abort. Stopping
-    // without calling return() leaves the stream paused and intact.
-    const iterator = stdin[Symbol.asyncIterator]();
-    for (;;) {
-      const step = await iterator.next();
-      if (step.done) {
-        break;
-      }
-      for (const character of step.value) {
-        if (character === "\u0003") {
-          throw new Error("Input cancelled.");
-        }
-        if (character === "\r" || character === "\n") {
-          stdout.write("\n");
-          return value;
-        }
-        if (character === "\u007f") {
-          if (value.length > 0) {
-            value = value.slice(0, -1);
-            if (mask) stdout.write("\b \b");
-          }
-          continue;
-        }
-        value += character;
-        if (mask) stdout.write("*");
-      }
-    }
-    return value;
-  } finally {
-    stdin.setRawMode(false);
-    stdin.pause();
-  }
+export async function readSecret(stdin, stdout, prompt, { mask = true, answerKey = null, defaultValue = "" } = {}) {
+  const controller = stdin?._spaceappPromptController || new PromptController({ stdin, stdout });
+  return await controller.readLine(prompt, { mask, answerKey, defaultValue });
 }
 
 export function executeCommand(spec, { stdin, stdout, stderr, input } = {}) {
@@ -2009,22 +2308,33 @@ export function executeCommand(spec, { stdin, stdout, stderr, input } = {}) {
     const commandEnv = spec.env === undefined
       ? process.env
       : validateCommandEnvironment(spec.env);
+    const background = spec.command === 'xdg-open' && spec.background === true;
+    let launchTimer, commandTimer;
     const child = spawnTrustedCommand(spec, {
       env: commandEnv,
       shell: false,
-      stdio: [input === undefined ? (stdin || "inherit") : "pipe", stdout || "ignore", stderr || "ignore"]
+      detached: background,
+      stdio: background ? ['ignore','ignore','ignore'] : [input === undefined ? (stdin || "inherit") : "pipe", stdout && typeof stdout.fd !== "number" ? "pipe" : stdout || "ignore", stderr && typeof stderr.fd !== "number" ? "pipe" : stderr || "ignore"]
     });
+    if (!background && child.stdout && stdout) child.stdout.pipe(stdout, { end: false });
+    if (!background && child.stderr && stderr) child.stderr.pipe(stderr, { end: false });
+    if (Number.isFinite(spec.timeoutMs) && spec.timeoutMs > 0) commandTimer = setTimeout(() => child.kill(), spec.timeoutMs);
     child.once("error", (error) => {
+      clearTimeout(launchTimer);
+      clearTimeout(commandTimer);
       if (error?.code === "ENOENT") {
         resolve(127);
       } else {
         reject(error);
       }
     });
-    child.once("exit", (code, signal) => {
+    child.once("close", (code, signal) => {
+      clearTimeout(launchTimer);
+      clearTimeout(commandTimer);
       resolve(code ?? (signal ? 1 : 0));
     });
-    if (input !== undefined) {
+    if(background)launchTimer=setTimeout(()=>{child.unref();resolve(0);},750);
+    if (input !== undefined && !background) {
       child.stdin.end(input);
     }
   });
@@ -2075,7 +2385,7 @@ function openBrowser(url, platform, execute, io) {
       env: { SPACEAPP_OPEN_URL: url }
     }, io);
   }
-  return execute({ command: "xdg-open", args: [url] }, io);
+  return execute({ command: "xdg-open", args: [url], background: true }, io);
 }
 
 function assertNoArgs(args, command) {
@@ -2140,28 +2450,64 @@ Usage: ${UNIVERSAL_COMMAND} <command>
        spaceapp <command>             Optional global launcher
 
   init                              Create a local SpaceApp installation
-  install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]
+  install [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]
                                     Install prerequisites, initialize, and start
+  reinstall [--keep-data] [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]
+                                    Clean reinstallation preserving data and credentials
+  repair [--dry-run]                Verify and repair configuration and runtime files
   up | down | status | logs         Manage the Docker application
   open                              Open the local web application
-  doctor                            Check resources, Docker, Compose, and engine
+  doctor [--fix]                    Diagnose; --fix repairs existing config and runtime
+  support-bundle                    Generate a diagnostic bundle JSON for support
   update [version] | rollback       Update or roll back images
   backup | restore                  Back up or restore persistent state
+  factory-reset                     Safety backup, purge all volumes/data, and reset
   workspace add <path> [--read-only]
   workspace remove <id-or-path>
   workspace list
   credentials set <provider>        Read a credential from masked stdin
   credentials remove <provider>
   credentials list
-  provider install claude           Owner-initiated Anthropic package install
+  provider install <provider>       Install an optional CLI in its persistent volume
+                                    codex, gemini, qwen, kimi, grok, claude, deepseek,
+                                    autohand, cursor, copilot (also installed on first use)
   owner reset-password              Read the new password from masked stdin
   owner rotate-setup-token          Replace an expired unclaimed setup token
   uninstall [--purge-data]          Remove containers; keep data by default
 
-Interactive setup wizard: install, update, init, rollback, and uninstall ask
-questions and require a final confirmation before any change. Command flags
-pre-select answers but never skip the confirmation. Without a TTY, changes
-are refused; the only exception is an approved Windows RunOnce continuation
-(bound to the user, installation root, and target version; expires in 24h).
+Options:
+  --plan                            Dry-run mode: print actions without executing
+  --json                            Output structured JSON where supported
+  --log-file <file>                 Append all execution logs to specified file
+  --local-images               Use preloaded images only (offline/lab; missing images fail)
+  --non-interactive                 Run non-interactively, failing on missing input
+  --answers <json|path>             Pre-seed answers; automation requires confirm:true
+
+Profiles (auto uses CPU, RAM and free disk, then checks Docker resources):
+  small:  4 CPUs, 7 GiB usable RAM, 6.5 GiB fresh space; SpaceApp + OpenCode.
+          Background integration workers and managed browser are disabled.
+  medium: 4 CPUs, 11 GiB usable RAM, 8 GiB fresh space; adds background workers.
+  large:  8 CPUs, 15 GiB usable RAM, 11 GiB fresh space; adds managed browser.
+  light/standard: compatibility settings for existing installations.
+Upgrades keep the installed profile unless you explicitly choose another one.
+Upgrade space: missing layers + database checkpoint + 0.5 GiB reserve.
+Cached target images need no extra image space; existing data stays in place.
+Unknown layer sizes use a conservative estimate; space is rechecked after pull.
+No automatic deletion of images, volumes, workspaces, or backups to free space.
+
+Quick start: install (automatic profile, OpenCode first, browser opens on completion).
+Windows PowerShell: use npx.cmd if script execution policy blocks npx.ps1.
+The npx command requires Node.js 20.11+ installed; Docker is installed if missing.
+Data lives in SPACEAPP_HOME (config/secrets) and persistent Docker volumes.
+Use backup before major changes; uninstall preserves data unless --purge-data.
+Never use factory-reset to solve an ordinary installation problem.
+
+Automation: --non-interactive --answers '{"confirm":true,"profile":"auto","access":"isolated","companions":false,"telemetry":false,"open":false}'
+For shells with different quoting, save that JSON to a file and pass --answers file.json.
+Use help or <command> --help from any directory, including before installation.
+
+Interactive setup wizard: install, reinstall, update, init, rollback, repair,
+factory-reset, and uninstall ask questions and require a final confirmation
+before any change. Command flags pre-select answers; unattended changes require explicit confirm:true.
 `;
 }