parrot-blackbox 2.0.4 → 2.0.6

package/README.md

@@ -86,6 +86,20 @@ rclone cat cloud → [decrypt] → zstd decompress → btrfs receive → Timeshi
 - Applies incrementals automatically
 - Reconstructs the exact filesystem byte-for-byte
 
+> **Timeshift layout on BTRFS:** Timeshift (BTRFS mode) stores every snapshot
+> as a *directory* `<snapshots>/<name>/` that contains a read-only `@`
+> subvolume. parrot-blackbox automatically resolves that inner `@` before
+> running `btrfs send` (so uploads never hit the "not a subvolume" error), and
+> on restore it receives each stream back into `<name>/@` plus the `info.json`
+> control file — so `timeshift --restore --snapshot <id>` recognizes the
+> restored backup immediately. If a snapshot is not a subvolume at all
+> (Timeshift rsync mode), the tool falls back to the legacy file-copy method.
+>
+> **No phantom backups:** a failed `btrfs send` (for example a wrong path) used
+> to leave a few-byte "stream" and manifest in the cloud that could corrupt the
+> incremental chain. Only real streams (≥ 1 MiB) are now recorded, and any
+> interrupted upload is removed from the cloud automatically.
+
 ### Why BTRFS send/receive is better
 
 | Old way (v1.x) | New way (v2.0) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parrot-blackbox",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Crash-proof, multi-cloud backup & recovery automation for Parrot OS. Daily/weekly off-disk backups with automatic catch-up, smart storage across many MEGA + Google Drive accounts, Timeshift snapshot backups and one-command restore.",
   "type": "module",
   "main": "src/cli.js",

package/src/backup/btrfs-send.js

@@ -18,7 +18,16 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { execa, execaSync } from 'execa';
 import { hasCommandSync } from '../core/store.js';
-import { sudoExec, sudoExecSync } from '../util/sudo.js';
+import { sudoExec, sudoExecSync, sudoNonInteractive } from '../util/sudo.js';
+
+/**
+ * Minimum size (bytes) a stored BTRFS stream must have to be considered a
+ * real backup. Failed sends still splice a few dozen bytes through the pipe
+ * before exiting 1, and those phantom streams must never be used as an
+ * incremental parent or offered for restore. A real system snapshot stream
+ * is orders of magnitude larger than 1 MiB, so this threshold is safe.
+ */
+export const MIN_VALID_STREAM_BYTES = 1024 * 1024;
 
 /**
  * Check if BTRFS tools are available on the system.
@@ -27,6 +36,18 @@ export function hasBtrfs() {
   return hasCommandSync('btrfs');
 }
 
+/**
+ * Validate a schema-2 snapshot manifest: does it describe a real BTRFS stream
+ * big enough to be an actual backup (not a failed few-byte send)?
+ * @param {object} manifest
+ * @returns {boolean}
+ */
+export function isValidBtrfsStreamManifest(manifest) {
+  if (!manifest || manifest.schema !== 2) return false;
+  const entry = (manifest.entries || []).find((e) => e.rel === 'btrfs.stream');
+  return Boolean(entry && entry.size >= MIN_VALID_STREAM_BYTES && Array.isArray(entry.loc) && entry.loc.length > 0);
+}
+
 /**
  * Check if a given path is on a BTRFS filesystem.
  * @param {string} dirPath - Path to check (e.g., '/' for root filesystem)
@@ -60,13 +81,17 @@ export async function getBtrfsDevice(mountPoint = '/') {
 
 /**
  * Check if a path is actually a BTRFS subvolume (not just a directory on BTRFS).
- * @param {string} path
+ * @param {string} subvolPath
+ * @param {object} opts - {privileged: 'interactive'|'noninteractive'}
  * @returns {Promise<boolean>}
  */
-export async function isSubvolume(path) {
+export async function isSubvolume(subvolPath, { privileged = 'noninteractive' } = {}) {
+  if (!subvolPath || !fs.existsSync(subvolPath)) return false;
   try {
-    // Need sudo to check subvolume info
-    const res = await execa('sudo', ['-n', 'btrfs', 'subvolume', 'show', path], { reject: false });
+    const args = ['btrfs', 'subvolume', 'show', subvolPath];
+    const res = process.env.PBB_SUDO_DIRECT === '1'
+      ? await execa('btrfs', ['subvolume', 'show', subvolPath], { reject: false })
+      : await sudoNonInteractive(args);
     return res.exitCode === 0;
   } catch {
     return false;
@@ -98,28 +123,64 @@ export async function setSubvolumeReadOnly(subvolPath, readOnly = true, { privil
 /**
  * Check if a subvolume is read-only.
  * @param {string} subvolPath
+ * @param {object} opts - {privileged: 'interactive'|'noninteractive'}
  * @returns {Promise<boolean>}
  */
-export async function isSubvolumeReadOnly(subvolPath) {
+export async function isSubvolumeReadOnly(subvolPath, { privileged = 'noninteractive' } = {}) {
   try {
-    const res = await execa('btrfs', ['property', 'get', '-ts', subvolPath, 'ro'], { reject: false });
-    if (res.exitCode !== 0) return false;
-    return res.stdout.includes('ro=true');
+    if (process.env.PBB_SUDO_DIRECT === '1') {
+      const res = await execa('btrfs', ['property', 'get', '-ts', subvolPath, 'ro'], { reject: false });
+      return res.exitCode === 0 && res.stdout.includes('ro=true');
+    }
+    const res = await sudoNonInteractive(['btrfs', 'property', 'get', '-ts', subvolPath, 'ro']);
+    return res.exitCode === 0 && res.stdout.includes('ro=true');
   } catch {
     return false;
   }
 }
 
+/**
+ * Resolve the actual BTRFS subvolume inside a Timeshift snapshot directory.
+ *
+ * Timeshift (BTRFS mode) stores every snapshot as:
+ *   <snapshots>/<name>/@          <- read-only snapshot subvolume of "@"
+ *   <snapshots>/<name>/info.json  <- control file
+ *
+ * Running `btrfs send` on the *container directory* fails with
+ * "failed to get flags for subvolume ... Invalid argument" — the directory is
+ * NOT a subvolume, only the inner "@" is. Some older/exotic layouts put the
+ * snapshot content directly in a subvolume at the container path itself, so
+ * both shapes are resolved here.
+ *
+ * @param {string} snapDir - Snapshot directory (container) already on disk
+ * @param {object} opts - {privileged}
+ * @returns {Promise<string|null>} - The subvolume path to send, or null when
+ *   the snapshot is not backed by a subvolume at all (e.g. Timeshift rsync mode).
+ */
+export async function findSnapshotSubvolume(snapDir, { privileged = 'noninteractive' } = {}) {
+  if (!snapDir || !fs.existsSync(snapDir)) return null;
+  if (await isSubvolume(snapDir, { privileged })) return snapDir;
+  const nested = path.join(snapDir, '@');
+  if (fs.existsSync(nested) && (await isSubvolume(nested, { privileged }))) return nested;
+  return null;
+}
+
 /**
  * Find the most recent successfully uploaded snapshot that can serve as a parent.
  * Looks for manifest files in the local manifests directory.
+ *
+ * A manifest is only trusted when it describes a REAL BTRFS stream: the send
+ * must have completed and uploaded a stream at least MIN_VALID_STREAM_BYTES
+ * in size. Failed sends (e.g. "not a subvolume") leave behind byte-sized
+ * phantom manifests that would otherwise corrupt the incremental chain.
+ *
  * @param {string} manifestsDir - Path to the manifests directory
  * @param {Array<{name:string}>} localSnapshots - List of local snapshots from timeshift
  * @returns {string|null} - The snapshot name to use as parent, or null for full send
  */
 export function findLastUploadedSnapshot(manifestsDir, localSnapshots) {
   if (!fs.existsSync(manifestsDir)) return null;
-  
+
   const manifestFiles = fs.readdirSync(manifestsDir)
     .filter(f => f.startsWith('snapshots-') && f.endsWith('.json'))
     .map(f => {
@@ -129,14 +190,19 @@ export function findLastUploadedSnapshot(manifestsDir, localSnapshots) {
     // Sort by name (which is timestamp-based) descending
     .sort((a, b) => b.name.localeCompare(a.name));
 
-  // Find the most recent manifest whose snapshot still exists locally
-  for (const { name } of manifestFiles) {
+  // Find the most recent valid manifest whose snapshot still exists locally
+  for (const { name, file } of manifestFiles) {
     const existsLocally = localSnapshots.some(s => s.name === name);
-    if (existsLocally) {
-      return name;
+    if (!existsLocally) continue;
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(manifestsDir, file), 'utf8'));
+      if (!isValidBtrfsStreamManifest(manifest)) continue;
+    } catch {
+      continue;
     }
+    return name;
   }
-  
+
   return null;
 }
 
@@ -172,9 +238,9 @@ export async function createSendStream(subvolPath, { parent = null, privileged =
 
   // Spawn via sudo, return the stdout stream and the child process so callers
   // can detect errors (btrfs send exits non-zero when the path is not a subvolume).
-  const sudoArgs = privileged === 'interactive'
-    ? ['sudo', '-E', ...args]
-    : ['sudo', '-n', ...args];
+  const sudoArgs = process.env.PBB_SUDO_DIRECT === '1'
+    ? args
+    : (privileged === 'interactive' ? ['sudo', '-E', ...args] : ['sudo', '-n', ...args]);
 
   const child = spawn(sudoArgs[0], sudoArgs.slice(1), {
     stdio: ['ignore', 'pipe', 'pipe'],

package/src/backup/restore.js

@@ -69,6 +69,10 @@ export async function restoreSnapshot({ id, accounts, cfg, toDir, confirm = fals
     }
   }
 
+  // Let Timeshift mount its own repo — our temporary subvolid=5 mount is no
+  // longer needed and must not linger.
+  await cleanupRestoreMount();
+
   // Run the actual restore (interactive sudo → the password prompt is visible).
   console.log(`\n🔄 Restoring snapshot ${id} over the current system…\n`);
   await ensureSudo();
@@ -150,11 +154,12 @@ async function restoreBtrfsStream({ manifest, snapId, cfg, privileged, onProgres
   }
 
   const btrfsCfg = cfg.jobs.snapshots.btrfs || {};
-  const base = determineSnapshotBase();
-  
-  // Ensure base directory exists
-  await ensureSudo();
-  await sudoInteractive(['mkdir', '-p', base]);
+  const { path: base } = await resolveTimeshiftSnapshotRepo({ privileged });
+  const snapDir = path.join(base, snapId);
+
+  // Ensure the per-snapshot container directory exists (root-owned on real setups).
+  const mk = await runPrivileged(['mkdir', '-p', snapDir], privileged);
+  if (mk.exitCode !== 0) throw new Error(`could not create snapshot dir ${snapDir} (exit ${mk.exitCode})`);
 
   // Build reverse pipeline
   const { spawn } = await import('node:child_process');
@@ -220,12 +225,13 @@ async function restoreBtrfsStream({ manifest, snapId, cfg, privileged, onProgres
     currentStream = zstd.stdout;
   }
 
-  // Stage 4: BTRFS receive
-  console.log(`   💾 Receiving into ${base}...`);
-  const sudoArgs = privileged === 'interactive' 
-    ? ['sudo', '-E', 'btrfs', 'receive', base]
-    : ['sudo', '-n', 'btrfs', 'receive', base];
-  const receive = spawn(sudoArgs[0], sudoArgs.slice(1), {
+  // Stage 4: BTRFS receive — into the per-snapshot container dir so the
+  // received subvolume lands at <snapDir>/@ (Timeshift's BTRFS layout).
+  console.log(`   💾 Receiving into ${snapDir}...`);
+  const recvArgs = process.env.PBB_SUDO_DIRECT === '1'
+    ? ['btrfs', 'receive', snapDir]
+    : ((privileged === 'interactive' ? ['sudo', '-E', 'btrfs', 'receive', snapDir] : ['sudo', '-n', 'btrfs', 'receive', snapDir]));
+  const receive = spawn(recvArgs[0], recvArgs.slice(1), {
     stdio: ['pipe', 'pipe', 'inherit'],
   });
   currentStream.pipe(receive.stdin);
@@ -240,10 +246,132 @@ async function restoreBtrfsStream({ manifest, snapId, cfg, privileged, onProgres
     });
     last.on('error', reject);
   });
-  
+
+  await registerSnapshotWithTimeshift({ snapDir, snapId, privileged });
   journal('restore', `btrfs receive completed for ${snapId}`);
 }
 
+/* ------------------------------------------------------------------ */
+/* Timeshift BTRFS repository resolution + snapshot registration       */
+/* ------------------------------------------------------------------ */
+
+let _restoreMountPoint = null;
+
+/** Run a privileged command honoring the interactive/non-interactive mode. */
+async function runPrivileged(args, privileged) {
+  const { sudoExec } = await import('../util/sudo.js');
+  return sudoExec(args, { interactive: privileged === 'interactive' });
+}
+
+/**
+ * Resolve where Timeshift stores BTRFS snapshots on THIS machine.
+ *
+ * On a classic BTRFS install the snapshot repo lives at
+ * `<root-subvolume>/timeshift-btrfs/snapshots`, reachable only after mounting
+ * the top-level subvolume (subvolid=5) — the same shape snapshotDirFor() uses
+ * on the upload side. Static paths cover rsync-mode and sandbox setups.
+ *
+ * @returns {Promise<{path: string, unmount: string|null}>}
+ */
+async function resolveTimeshiftSnapshotRepo({ privileged }) {
+  const staticPaths = [
+    path.join(timeshiftDir(), 'snapshots'),                 // rsync mode & sandbox stub
+    path.join(timeshiftDir(), 'timeshift-btrfs', 'snapshots'),
+    '/run/timeshift/backup/timeshift-btrfs/snapshots',
+  ];
+  for (const p of staticPaths) {
+    if (fs.existsSync(p)) return { path: p, unmount: null };
+  }
+
+  // BTRFS mode: mount the top-level subvolume where Timeshift keeps repos.
+  if (!_restoreMountPoint) {
+    const mountPoint = `/run/parrot-blackbox-restore-${Date.now()}`;
+    const { execaSync } = await import('execa');
+    const findmnt = execaSync('findmnt', ['-n', '-o', 'SOURCE', '/'], { reject: false });
+    const device = findmnt.stdout?.trim().split('[')[0];
+    if (device && findmnt.exitCode === 0) {
+      const mk = await runPrivileged(['mkdir', '-p', mountPoint], privileged);
+      if (mk.exitCode === 0) {
+        const mnt = await runPrivileged(['mount', '-o', 'subvolid=5', device, mountPoint], privileged);
+        if (mnt.exitCode === 0) {
+          const repo = path.join(mountPoint, 'timeshift-btrfs', 'snapshots');
+          if (fs.existsSync(repo)) {
+            _restoreMountPoint = mountPoint;
+            return { path: repo, unmount: mountPoint };
+          }
+          await runPrivileged(['umount', mountPoint], privileged).catch(() => null);
+        }
+        await runPrivileged(['rmdir', mountPoint], privileged).catch(() => null);
+      }
+    }
+  } else {
+    const repo = path.join(_restoreMountPoint, 'timeshift-btrfs', 'snapshots');
+    if (fs.existsSync(repo)) return { path: repo, unmount: null };
+  }
+
+  // Last resort — will produce a clear failure if it's not a real repo path.
+  return { path: path.join(timeshiftDir(), 'snapshots'), unmount: null };
+}
+
+/** Unmount the temporary subvolid=5 mount (best effort), when one was made. */
+export async function cleanupRestoreMount() {
+  const mountPoint = _restoreMountPoint;
+  _restoreMountPoint = null;
+  if (!mountPoint) return;
+  await runPrivileged(['umount', mountPoint], 'interactive').catch(() => null);
+  await runPrivileged(['rmdir', mountPoint], 'interactive').catch(() => null);
+}
+
+/** Parse a Timeshift snapshot name "2026-09-03_12-08-44" into local epoch seconds. */
+export function snapshotEpochFromName(name) {
+  const m = /^(\d{4}-\d{2}-\d{2})_(\d{2}-\d{2}-\d{2})$/.exec(String(name || '').trim());
+  if (m) {
+    const t = new Date(`${m[1].replace(/-/g, '/')} ${m[2].replace(/-/g, ':')}`);
+    if (!Number.isNaN(t.getTime())) return Math.floor(t.getTime() / 1000);
+  }
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Register a freshly received BTRFS subvolume with Timeshift so
+ * `timeshift --list` / `timeshift --restore --snapshot <id>` recognize it.
+ *
+ * Timeshift validates a BTRFS snapshot by the control file `info.json` inside
+ * the container directory and the read-only "@" subvolume — exactly the shape
+ * `btrfs receive <snapDir>` produced.
+ */
+async function registerSnapshotWithTimeshift({ snapDir, snapId, privileged }) {
+  const receivedSubvol = path.join(snapDir, '@');
+  if (!fs.existsSync(receivedSubvol)) {
+    throw new Error(`btrfs receive did not create ${receivedSubvol} — stream name did not match "@"?`);
+  }
+
+  const ctl = {
+    created: String(snapshotEpochFromName(snapId)),
+    'sys-uuid': '',
+    'sys-distro': '',
+    'app-version': '24.06.4',
+    file_count: '0',
+    tags: 'O',
+    comments: 'restored via parrot-blackbox',
+    live: 'false',
+    type: 'btrfs',
+  };
+  const ctlPath = path.join(snapDir, 'info.json');
+  const tmpCtl = path.join(stateDir(), `.ts-info-${snapId}-${process.pid}.json`);
+  fs.writeFileSync(tmpCtl, JSON.stringify(ctl, null, 2) + '\n');
+  try {
+    const cp = await runPrivileged(['cp', tmpCtl, ctlPath], privileged);
+    if (cp.exitCode !== 0) throw new Error(`could not write Timeshift control file (exit ${cp.exitCode})`);
+    await runPrivileged(['chown', 'root:root', ctlPath], privileged).catch(() => null);
+    // Timeshift BTR snapshots are read-only; receive produces writable subvols.
+    await runPrivileged(['btrfs', 'property', 'set', '-ts', receivedSubvol, 'ro', 'true'], privileged).catch(() => null);
+    console.log(`   ✅ Registered snapshot ${snapId} with Timeshift`);
+  } finally {
+    try { fs.rmSync(tmpCtl, { force: true }); } catch { /* best effort */ }
+  }
+}
+
 /** Move a downloaded snapshot tree into the Timeshift snapshot folder (root-owned). */
 async function placeIntoTimeshift(id, tmpRoot, cfg, privileged, manifest) {
   const base = determineSnapshotBase();

package/src/backup/snapshot.js

@@ -259,6 +259,31 @@ export async function deleteAllSnapshots({ privileged = 'interactive', onProgres
 
   return { deleted, failed };
 }
+/**
+ * A module-level registry of all temporary BTRFS mounts created during this
+ * process lifetime, so we can unmount them all at exit even if the snapshot
+ * object that originally held the reference was garbage-collected.
+ */
+const _activeTempMounts = new Set();
+
+/**
+ * Unmount and remove all temporary BTRFS mount points created by this process.
+ * Called on process exit and also by cleanupSnapshotMount.
+ */
+function _cleanupAllTempMounts() {
+  for (const mp of _activeTempMounts) {
+    try { sudoExecSync(['umount', mp]); } catch { /* best effort */ }
+    try { sudoExecSync(['rmdir', mp]); } catch { /* best effort */ }
+    _activeTempMounts.delete(mp);
+  }
+}
+
+// Register a process exit handler so stale mounts are always cleaned up,
+// even if the snapshot object holding _tempMount was discarded before cleanup.
+process.on('exit', _cleanupAllTempMounts);
+// Also handle abnormal exits so the mount isn't left behind after Ctrl+C
+// (SIGINT/SIGTERM handlers in cli.js call process.exit(), which fires 'exit').
+
 /**
  * Resolve the on-disk directory of a snapshot.
  * 
@@ -270,6 +295,11 @@ export async function deleteAllSnapshots({ privileged = 'interactive', onProgres
  * 2. Check static paths (rsync mode)
  * 3. Mount the BTRFS root subvolume ourselves to access snapshots persistently
  * 4. Fall back to triggering timeshift --list
+ *
+ * IMPORTANT: the mount point is registered in _activeTempMounts so that
+ * _cleanupAllTempMounts() can release it on process exit even if the snapshot
+ * object is later discarded (e.g. after a resume-upload path that builds a new
+ * snapshot object from just the name).
  */
 export function snapshotDirFor(snapshot, { privileged = 'noninteractive' } = {}) {
   if (snapshot.dir && fs.existsSync(snapshot.dir)) return snapshot.dir;
@@ -301,6 +331,9 @@ export function snapshotDirFor(snapshot, { privileged = 'noninteractive' } = {})
       const mountResult = sudoExecSync(['mount', '-o', 'subvolid=5', device, mountPoint]);
       
       if (mountResult.exitCode === 0) {
+        // Register in the global set so it is always cleaned up on exit.
+        _activeTempMounts.add(mountPoint);
+
         // Search for the snapshot in the mounted root subvolume
         const searchPaths = [
           `${mountPoint}/timeshift-btrfs/snapshots/${snapshot.name}`,
@@ -311,12 +344,13 @@ export function snapshotDirFor(snapshot, { privileged = 'noninteractive' } = {})
         const found = searchPaths.find((p) => fs.existsSync(p));
         
         if (found) {
-          // Store the mount point for cleanup later
+          // Store the mount point on the snapshot object for explicit early cleanup.
           snapshot._tempMount = mountPoint;
           return found;
         }
         
-        // Unmount if we didn't find anything
+        // Unmount immediately if we didn't find anything useful.
+        _activeTempMounts.delete(mountPoint);
         sudoExecSync(['umount', mountPoint]);
         sudoExecSync(['rmdir', mountPoint]);
       }
@@ -331,14 +365,16 @@ export function snapshotDirFor(snapshot, { privileged = 'noninteractive' } = {})
 
 /** Cleanup temporary BTRFS mount if one was created */
 export function cleanupSnapshotMount(snapshot) {
-  if (snapshot._tempMount) {
+  if (snapshot && snapshot._tempMount) {
+    const mp = snapshot._tempMount;
     try {
-      sudoExecSync(['umount', snapshot._tempMount]);
-      sudoExecSync(['rmdir', snapshot._tempMount]);
-      delete snapshot._tempMount;
+      sudoExecSync(['umount', mp]);
+      sudoExecSync(['rmdir', mp]);
     } catch {
       /* best effort */
     }
+    _activeTempMounts.delete(mp);
+    delete snapshot._tempMount;
   }
 }
 
@@ -423,15 +459,41 @@ export async function runSnapshotBackup(cfg, state, { due, privileged = 'noninte
   const dir = snapshotDirFor(created, { privileged });
   const parentDir = parentSnap ? snapshotDirFor(parentSnap, { privileged }) : null;
 
+  // Timeshift (BTRFS mode) stores each snapshot as a *directory* containing an
+  // "@" snapshot subvolume. The container directory itself is NOT a subvolume
+  // and `btrfs send` fails on it with "Invalid argument". Resolve the real
+  // subvolume here, and drop to file-copy mode when the snapshots genuinely
+  // aren't subvolumes (e.g. Timeshift rsync mode).
+  const { findSnapshotSubvolume } = await import('./btrfs-send.js');
+  let subvolPath = null;
+  let parentSubvolPath = null;
+  if (useBtrfs) {
+    subvolPath = await findSnapshotSubvolume(dir, { privileged });
+    if (!subvolPath) {
+      console.log('⚠ Timeshift snapshots are not BTRFS subvolumes (rsync mode?) — falling back to file-copy mode');
+      useBtrfs = false;
+    } else if (parentDir) {
+      parentSubvolPath = await findSnapshotSubvolume(parentDir, { privileged });
+      if (!parentSubvolPath) {
+        console.log('⚠ Parent snapshot has no BTRFS subvolume — running a full send instead');
+        parentSnap = null;
+      }
+    }
+  }
+
+  // File-copy source: when the snapshot dir is a Timeshift BTRFS container
+  // (<dir>/@), walk the "@" contents so the actual system tree is uploaded.
+  const fileCopyDir = fs.existsSync(path.join(dir, '@')) ? path.join(dir, '@') : dir;
+
   let manifest;
   try {
     if (useBtrfs) {
       // V2 BTRFS send/receive path
       manifest = await uploadViaBtrfsSend({
         snapshot: created,
-        snapshotDir: dir,
+        subvolPath,
         parentSnapshot: parentSnap,
-        parentDir,
+        parentSubvolPath,
         accounts,
         cfg,
         due,
@@ -442,8 +504,7 @@ export async function runSnapshotBackup(cfg, state, { due, privileged = 'noninte
       // Legacy file-copy fallback (v2 behavior)
       manifest = await uploadViaFileCopy({
         snapshot: created,
-        snapshotDir: dir,
-        parentDir,
+        snapshotDir: fileCopyDir,
         accounts,
         cfg,
         due,
@@ -454,10 +515,10 @@ export async function runSnapshotBackup(cfg, state, { due, privileged = 'noninte
   } catch (e) {
     // The local snapshot exists and is safe; the cloud upload failed.
     journal('snapshots', `upload failed for ${created.name}: ${e.message}`, 'error');
-    cleanupSnapshotMount(created);
     throw e;
   } finally {
     cleanupSnapshotMount(created);
+    if (parentSnap) cleanupSnapshotMount(parentSnap);
   }
 
   manifest.due = due;
@@ -493,19 +554,34 @@ export async function runSnapshotBackup(cfg, state, { due, privileged = 'noninte
  * Upload a snapshot using BTRFS send/receive streaming.
  * Creates: btrfs send [-p parent] | zstd | [openssl] | rclone rcat (chunked)
  *
- * Uses the path resolved by snapshotDirFor() (which mounts the BTRFS root subvolume
- * at a temporary mount point) so that `btrfs send` receives an actual subvolume path,
- * not a directory inside a regular mount.
+ * `subvolPath` / `parentSubvolPath` are the actual BTRFS subvolumes (resolved by
+ * findSnapshotSubvolume() — Timeshift keeps snapshots at <snapshot-dir>/@), so
+ * `btrfs send` always receives a real subvolume, never a plain directory.
  */
-async function uploadViaBtrfsSend({ snapshot, snapshotDir, parentSnapshot, parentDir, accounts, cfg, due, privileged, onProgress }) {
-  const { createSendStream, estimateSendSize } = await import('./btrfs-send.js');
+async function uploadViaBtrfsSend({ snapshot, subvolPath, parentSnapshot, parentSubvolPath, accounts, cfg, due, privileged, onProgress }) {
+  const { createSendStream, estimateSendSize, isValidBtrfsStreamManifest, isSubvolumeReadOnly, setSubvolumeReadOnly } = await import('./btrfs-send.js');
   const { planAndPlaceStream } = await import('../storage/allocator.js');
 
-  // snapshotDir was resolved by snapshotDirFor() — it is the real subvolume path
-  // (e.g. /run/parrot-blackbox-btrfs-<ts>/timeshift-btrfs/snapshots/<name>).
-  // Use it directly; do NOT fall back to a hardcoded absolute path.
-  const subvolPath = snapshotDir;
-  const parentSubvolPath = parentDir || null;
+  if (!subvolPath) throw new Error('no BTRFS subvolume path for snapshot upload');
+
+  // ── RO guard ──────────────────────────────────────────────────────────────
+  // btrfs send requires the subvolume to be read-only (ro=true). Timeshift
+  // always creates snapshots as RO, but when they are accessed via a
+  // subvolid=5 bind-mount the kernel may report the inner @ subvolume as
+  // rw=false (writable) depending on mount flags. Detect and fix this before
+  // handing the path to btrfs send, otherwise the send exits 1 with
+  // "subvolume … is not read-only".
+  const isRO = await isSubvolumeReadOnly(subvolPath, { privileged });
+  if (!isRO) {
+    journal('snapshots', `subvolume ${subvolPath} is not read-only — setting ro=true before send`);
+    try {
+      await setSubvolumeReadOnly(subvolPath, true, { privileged });
+      journal('snapshots', `set ${subvolPath} read-only OK`);
+    } catch (e) {
+      throw new Error(`btrfs send requires a read-only subvolume but ${subvolPath} is writable and could not be set read-only: ${e.message}`);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
 
   journal('snapshots', `btrfs send subvolPath=${subvolPath} parent=${parentSubvolPath || 'null'}`);
 
@@ -562,34 +638,78 @@ async function uploadViaBtrfsSend({ snapshot, snapshotDir, parentSnapshot, paren
     originalSize: estimatedSize,
   });
 
-  // Wait for all pipeline stages (including btrfs send itself) to exit cleanly
-  await Promise.all(pipeline.map((proc) =>
-    new Promise((resolve, reject) => {
-      proc.on('close', (code) => {
-        if (code === 0 || code === null) {
-          resolve();
-        } else {
-          const stderr = Buffer.concat(sendStderr).toString().trim();
-          reject(new Error(
-            proc === sendChild
-              ? `btrfs send failed (exit ${code})${stderr ? ': ' + stderr : ''} — is ${subvolPath} a BTRFS subvolume?`
-              : `Pipeline stage failed (exit ${code})`
-          ));
-        }
-      });
-      proc.on('error', reject);
-    })
-  ));
+  /**
+   * Abort a failed/incomplete upload so no fragment stream or manifest is left
+   * behind — exactly the corruption that previously let 13-byte phantom
+   * streams appear in the cloud and break the incremental chain.
+   */
+  const abortGhostUpload = async () => {
+    for (const proc of pipeline) { try { proc.kill('SIGKILL'); } catch { /* already gone */ } }
+    try { currentStream.destroy(); } catch { /* best effort */ }
+    // Let the concurrent uploader settle (bounded) so it can't write a manifest after we return.
+    await Promise.race([
+      manifestPromise.catch(() => {}),
+      new Promise((r) => setTimeout(r, 5000)),
+    ]);
+    const { removeArtifact } = await import('../storage/archive.js');
+    try { await removeArtifact('snapshots', snapshot.name, accounts, cfg.storage.remoteRoot); } catch { /* best effort */ }
+    try { fs.rmSync(path.join(manifestsDir(), `snapshots-${snapshot.name}.json`), { force: true }); } catch { /* best effort */ }
+  };
 
-  const manifest = await manifestPromise;
+  try {
+    // Wait for all pipeline stages (including btrfs send itself) to exit cleanly
+    await Promise.all(pipeline.map((proc) =>
+      new Promise((resolve, reject) => {
+        proc.on('close', (code) => {
+          if (code === 0 || code === null) {
+            resolve();
+          } else {
+            const stderr = Buffer.concat(sendStderr).toString().trim();
+            reject(new Error(
+              proc === sendChild
+                ? `btrfs send failed (exit ${code})${stderr ? ': ' + stderr : ''} — is ${subvolPath} a BTRFS subvolume?`
+                : `Pipeline stage failed (exit ${code})`
+            ));
+          }
+        });
+        proc.on('error', reject);
+      })
+    ));
+
+    const manifest = await manifestPromise;
+
+    // A real system stream is orders of magnitude larger than 1 MiB. A tiny
+    // stream means the send failed and must never be recorded as a backup.
+    if (!isValidBtrfsStreamManifest(manifest)) {
+      await abortGhostUpload();
+      throw new Error(`btrfs send produced an undersized stream (${manifest?.totalSize ?? 0} bytes) — aborting`);
+    }
 
-  // Save manifest locally
-  const manifestPath = path.join(manifestsDir(), `snapshots-${snapshot.name}.json`);
-  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    // Enrich the manifest with the parent-chain info BEFORE persisting it, and
+    // push the enriched copy back to the cloud so a restore from a wiped
+    // machine can still resolve the incremental chain.
+    manifest.snapshot = snapshot.name;
+    manifest.parent = parentSnapshot?.name || null;
+
+    // Save manifest locally
+    const manifestPath = path.join(manifestsDir(), `snapshots-${snapshot.name}.json`);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+    // Re-upload the enriched manifest (now carrying the parent link) to the cloud.
+    if (manifest.account) {
+      const { copyToFile } = await import('../storage/rclone.js');
+      const remotePath = `${manifest.account}:${manifest.remoteRoot}/snapshots/${snapshot.name}/__MANIFEST__.json`;
+      const res = await copyToFile(manifestPath, remotePath);
+      if (!res.ok) journal('snapshots', `could not refresh cloud manifest for ${snapshot.name}`, 'warn');
+    }
 
-  console.log(`\n✓ Uploaded ${(manifest.totalSize / (1024 ** 3)).toFixed(2)} GiB to cloud`);
-  return manifest;
+    console.log(`\n✓ Uploaded ${(manifest.totalSize / (1024 ** 3)).toFixed(2)} GiB to cloud`);
+    return manifest;
+  } catch (err) {
+    await abortGhostUpload();
+    throw err;
+  }
 }
 
 /**
@@ -604,7 +724,10 @@ async function uploadViaFileCopy({ snapshot, snapshotDir, parentDir, accounts, c
     HOME: process.env.HOME,
     PBB_STATE_DIR: stateDir(),
     PBB_CONFIG_FILE: configFile(),
-    PBB_PARENT_DIR: parentDir || '',
+    // The subprocess must never re-enable BTRFS send — file-copy mode was
+    // chosen because the snapshots are NOT subvolumes (rsync mode, or tools
+    // missing). Re-detection in the child would resurrect the failing send.
+    PBB_DISABLE_BTRFS: '1',
   };
   const cmdArgs = [process.execPath, bin, '_internal_upload', snapshotDir, 'snapshots', snapshot.name, cfg.storage.remoteRoot, String(cfg.storage.chunkSize), outPath];
   const args = process.env.PBB_SUDO_DIRECT === '1' ? cmdArgs : ['-E', ...cmdArgs];

package/src/cli.js

@@ -2,6 +2,8 @@ import { defineCommand, runMain } from 'citty';
 import pc from 'picocolors';
 import * as p from '@clack/prompts';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
 import { runSetup } from './commands/setup.js';
 import { runWizard } from './commands/wizard.js';
 import { runRepair } from './commands/manage.js';
@@ -421,7 +423,7 @@ const main = defineCommand({
         if (sub === 'prune') {
           const cfg = loadConfig();
           try {
-            const pruned = await pruneSnapshots(cfg, loadState(), listAccounts(), { privileged: 'interactive' });
+            const pruned = await pruneSnapshots(cfg, listAccounts(), { privileged: 'interactive' });
             if (pruned.length) console.log(pc.green(`✔ Pruned: ${pruned.join(', ')} (local + cloud).`));
             else console.log(pc.dim('Nothing to prune.'));
           } catch (e) {
@@ -667,7 +669,7 @@ const main = defineCommand({
             });
           }
           s.stop('✔ Upload complete');
-          import('node:fs').then(fs => fs.writeFileSync(outPath, JSON.stringify(manifest)));
+          fs.writeFileSync(outPath, JSON.stringify(manifest));
           process.exitCode = 0;
         } catch (e) {
           s.stop('✖ Upload failed');
@@ -677,16 +679,12 @@ const main = defineCommand({
           // If we are running as root via sudo, rclone might have refreshed OAuth tokens
           // and rewritten rclone.conf as root:root. Restore ownership to the real user.
           if (process.getuid && process.getuid() === 0 && process.env.SUDO_UID && process.env.SUDO_GID) {
-            import('node:fs').then(fs => {
-              import('node:path').then(path => {
-                const confPath = path.join(process.env.HOME, '.config', 'rclone', 'rclone.conf');
-                if (fs.existsSync(confPath)) {
-                  try {
-                    fs.chownSync(confPath, parseInt(process.env.SUDO_UID, 10), parseInt(process.env.SUDO_GID, 10));
-                  } catch { /* best effort */ }
-                }
-              });
-            });
+            const confPath = path.join(process.env.HOME, '.config', 'rclone', 'rclone.conf');
+            if (fs.existsSync(confPath)) {
+              try {
+                fs.chownSync(confPath, parseInt(process.env.SUDO_UID, 10), parseInt(process.env.SUDO_GID, 10));
+              } catch { /* best effort */ }
+            }
           }
         }
         return;
@@ -702,4 +700,11 @@ const main = defineCommand({
         process.exitCode = 1;
     }
   },
-});runMain(main);
+});
+
+runMain(main).then(() => {
+  // Force the process to exit cleanly regardless of any open file descriptors or
+  // kernel mounts left by subvolid=5 bind-mounts created in snapshotDirFor.
+  // process.on('exit') in snapshot.js will unmount them before we terminate.
+  process.exit(process.exitCode ?? 0);
+});

package/src/storage/archive.js

@@ -14,9 +14,20 @@ import { createWriteStream } from 'node:fs';
 import { execa } from 'execa';
 import { catRemote, lsjson, purge, copyToFile, downloadBatch } from './rclone.js';
 import { MANIFEST_NAME } from './allocator.js';
+import { isValidBtrfsStreamManifest } from '../backup/btrfs-send.js';
 
 export { MANIFEST_NAME };
 
+/**
+ * A schema-2 snapshot manifest whose stream never made it (failed `btrfs send`
+ * leaves a dozens-of-bytes phantom) is garbage: it must not be listed, offered
+ * for restore, or used as an incremental parent. Schema-1 (legacy file-tree)
+ * backups are always kept.
+ */
+function isPhantom(kind, manifest) {
+  return kind === 'snapshots' && manifest.schema === 2 && !isValidBtrfsStreamManifest(manifest);
+}
+
 function manifestMirrorPath(kind, id) {
   const dir = process.env.PBB_MANIFESTS_DIR || path.join(process.env.PBB_STATE_DIR || '.', 'manifests');
   return path.join(dir, `${kind}-${id}.json`);
@@ -35,7 +46,9 @@ export async function discoverManifest(kind, id, accounts, remoteRoot) {
     if (res.ok) {
       try {
         const manifest = JSON.parse(res.stdout);
-        if (manifest.kind === kind && manifest.id === id) return { account: acc, manifest };
+        if (manifest.kind === kind && manifest.id === id && !isPhantom(kind, manifest)) {
+          return { account: acc, manifest };
+        }
       } catch {
         /* corrupt manifest — skip */
       }
@@ -217,6 +230,7 @@ export async function listArtifacts(kind, accounts, remoteRoot, onProgress) {
           if (!cat.ok) return null;
           try {
             const manifest = JSON.parse(cat.stdout);
+            if (isPhantom(kind, manifest)) return null;
             return { kind, id, createdAt: manifest.createdAt, totalSize: manifest.totalSize, account: acc.remote, manifest };
           } catch {
             return null;