Make backup and restore reliable, and keep NFS out of them (0.64.0)

A review of the backup path found several ways a backup was not one, and a
restore could destroy data it did not contain.

Data loss:
- Restore with overwrite rmtree'd the whole stack directory, including
  folders the backup had left out (over 2 GiB, deselected, an NFS share
  mounted inside). It now clears only what the backup holds, keeps the
  excluded paths (recorded in the manifest) and never crosses into another
  filesystem.
- The stack was only stopped when named volumes were selected, so data
  folders inside the stack directory were archived while in use. Any
  selected data now stops it.
- Retention matched by prefix: pruning "app" deleted "app-db"'s backups.
  It now matches backup-<id>-(full|config)-<date>.tar.gz exactly.
- A restore under a new name wrote into the original's volumes when they
  had an explicit name, and into its folders outside the stack directory.
  Both are skipped now; a volume owned by another stack or mounted by a
  running container is never overwritten.
- A truncated archive was only noticed after the old stack was gone. The
  whole archive is verified first, and the stack directory is unpacked
  next to the old one and swapped in.

Remote storage:
- Bind folders on a mounted share (fstab/autofs), bind-type volumes
  pointing at one and shares mounted inside the stack folder are detected
  by filesystem type and not selected; a folder du cannot measure in 20s
  is no longer selected by default either.

Reliability:
- After a backup exactly the containers that ran are started again with
  compose start (falling back to the Docker API), instead of up -d, which
  started services stopped on purpose and applied undeployed edits. A
  stack that cannot be stopped is not backed up.
- Backup and restore hold the stack lock; a scheduled backup that finds
  the stack busy retries after 10 minutes. Restore stops the stack while
  replacing its data and brings it back up.
- external: true volumes are backed up; anonymous ones are listed, not
  selected. Restored volumes get their original driver and options.
- A backup with uncaptured data or a stack that did not restart is
  reported as incomplete: in the dialog, and for schedules as a warning
  with a notification and without rotating older backups out.
- Archive writing and restore run off the event loop; downloads delete
  their temp file; helper containers use the long-timeout client; S3
  listing is paginated; a file changing mid-read no longer corrupts the
  archive.

Manifest format 3 records compose_binds/excluded and volume
driver/options/external; format 1/2 backups still restore.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stackpilot-frontend",
   "private": true,
-  "version": "0.63.0",
+  "version": "0.64.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/src/api/backups.ts

@@ -18,6 +18,8 @@ export interface BackupBind {
   covered_by_compose: boolean;
   via: "compose" | "archive";
   system: boolean;
+  /** Network filesystem the folder sits on (nfs, cifs, …); never archived. */
+  remote?: string | null;
   include_default: boolean;
   selected: boolean;
   reason: string | null;
@@ -29,6 +31,8 @@ export interface BackupVolume {
   driver: string;
   remote: boolean;
   remote_type: string | null;
+  /** Used by the stack but not created by compose for it (external: true). */
+  external?: boolean;
   include_default: boolean;
   selected: boolean;
   reason: string | null;
@@ -49,6 +53,14 @@ export interface BackupReport {
   volumes: { name: string; bytes: number | null; error: string | null }[];
   skipped: { kind: string; source?: string; name?: string; reason: string | null }[];
   path_mismatch: { host: string; container: string } | null;
+  /** Services stopped for a consistent snapshot (and started again). */
+  stopped?: string[];
+  /** Data that should have been captured and was not. */
+  errors?: string[];
+  /** Files that changed or could not be read while archiving. */
+  warnings?: string[];
+  /** Set when the stack could not be started again after the backup. */
+  restart_error?: string | null;
 }
 
 export interface RestoreResult {
@@ -57,6 +69,9 @@ export interface RestoreResult {
   volumes_restored: number;
   binds_restored?: number;
   skipped?: { kind: string; source?: string; name?: string; reason: string | null }[];
+  /** What went wrong during this restore (not what the backup left out). */
+  problems?: string[];
+  restarted?: boolean;
 }
 
 export interface BackupOptions {

frontend/src/components/stacks/BackupRestore.tsx

@@ -150,6 +150,25 @@ export function BackupButton({ stackId }: { stackId: string }) {
     const skipped = report.skipped.filter((s) => s.reason !== "not requested").length;
     return `Backup: ${parts.join(" · ")}${skipped ? ` — ${skipped} skipped` : ""}`;
   };
+  // A backup that is missing data, or left the stack down, is not a success.
+  const announce = (tid: string | number, text: string, report?: BackupReport | null) => {
+    const problems = [
+      ...(report?.errors ?? []).map((e) => `Not captured: ${e}`),
+      ...(report?.restart_error ? [`Stack did not start again: ${report.restart_error}`] : []),
+    ];
+    if (problems.length) {
+      toast.error(`${text} — incomplete`, { id: tid, description: problems.join("\n") });
+    } else if (report?.warnings?.length) {
+      toast.warning(text, {
+        id: tid,
+        description: `${report.warnings.length} file(s) changed while being read: ${report.warnings
+          .slice(0, 3)
+          .join("; ")}`,
+      });
+    } else {
+      toast.success(text, { id: tid });
+    }
+  };
 
   const run = async () => {
     setBusy(true);
@@ -166,7 +185,7 @@ export function BackupButton({ stackId }: { stackId: string }) {
       };
       if (target === "download") {
         const report = await backupsApi.download(stackId, opts);
-        toast.success(describe(report), { id: tid });
+        announce(tid, describe(report), report);
       } else {
         const body = {
           destination_id: Number(target),
@@ -177,7 +196,7 @@ export function BackupButton({ stackId }: { stackId: string }) {
           volumes: opts.volumes,
         };
         const res = await backupsApi.push(stackId, body);
-        toast.success(`Pushed to ${res.destination}`, { id: tid });
+        announce(tid, `Pushed to ${res.destination} — ${describe(res.report)}`, res.report);
       }
       setOpen(false);
     } catch (e) {
@@ -246,6 +265,7 @@ export function BackupButton({ stackId }: { stackId: string }) {
                     detail={`named volume (${v.driver})`}
                     badges={[
                       ...(v.remote ? [{ text: v.remote_type || "remote", tone: "warn" as const }] : []),
+                      ...(v.external ? [{ text: "external" }] : []),
                       ...(v.reason && !v.remote ? [{ text: v.reason, tone: "warn" as const }] : []),
                     ]}
                   />
@@ -257,8 +277,9 @@ export function BackupButton({ stackId }: { stackId: string }) {
                 )}
               </div>
               <p className="mt-1 text-[11px] text-slate-500">
-                Remote storage (NFS/CIFS) is unchecked by default — it lives on your NAS and would be
-                overwritten on restore.
+                Remote storage (NFS/CIFS volumes, and folders on a mounted share) is never selected by
+                default — it lives on your NAS. The stack is stopped while its data is read and
+                started again afterwards.
               </p>
             </div>
 
@@ -354,7 +375,12 @@ export function RestoreButton() {
       }
       const bits = [`${res.volumes_restored} volume(s)`];
       if (res.binds_restored) bits.push(`${res.binds_restored} folder(s)`);
-      toast.success(`Restored '${res.stack_id}' — ${bits.join(", ")}`, { id: tid });
+      const text = `Restored '${res.stack_id}' — ${bits.join(", ")}`;
+      if (res.problems?.length) {
+        toast.warning(text, { id: tid, description: res.problems.slice(0, 5).join("\n") });
+      } else {
+        toast.success(text, { id: tid });
+      }
       qc.invalidateQueries({ queryKey: ["stacks"] });
       setOpen(false);
       setFile(null);
@@ -464,7 +490,7 @@ export function RestoreButton() {
               checked={overwrite}
               onChange={setOverwrite}
               label="Overwrite if a stack with this id already exists"
-              hint="Replaces the existing stack files and volume contents."
+              hint="Stops the stack, puts back the files, folders and volumes in the backup and starts it again. Folders the backup left out are kept."
             />
           </div>
           <div className="mt-4 flex justify-end gap-2">