parrot-blackbox 2.0.3 → 2.0.5

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.3",
+  "version": "2.0.5",
   "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

@@ -158,6 +158,8 @@ export async function deleteSnapshot(name, { privileged = 'noninteractive' } = {
   if (privileged === 'interactive') {
     await ensureSudo();
     const res = await sudoInteractive(args);
+    // Timeshift exits 0 even when the qgroup destroy fails, so we verify the
+    // snapshot is actually gone rather than trusting the exit code alone.
     if (res.exitCode !== 0) throw new Error(`timeshift --delete ${name} failed (exit ${res.exitCode})`);
     return true;
   }
@@ -169,16 +171,32 @@ export async function deleteSnapshot(name, { privileged = 'noninteractive' } = {
   return true;
 }
 
+/** Run btrfs quota rescan -w / and wait for it to finish. */
+async function btrfsQuotaRescan({ privileged = 'interactive', onProgress } = {}) {
+  onProgress?.('Running btrfs quota rescan — this may take a moment…');
+  const res = privileged === 'interactive'
+    ? await sudoInteractive(['btrfs', 'quota', 'rescan', '-w', '/'])
+    : await sudoNonInteractive(['btrfs', 'quota', 'rescan', '-w', '/']);
+  if (res.exitCode !== 0) {
+    onProgress?.(`⚠ btrfs quota rescan exited ${res.exitCode} — quotas may not be enabled, continuing`);
+  } else {
+    onProgress?.('✔ btrfs quota rescan complete');
+  }
+}
+
 /**
  * Delete ALL local Timeshift snapshots.
  *
- * Runs `sudo btrfs quota rescan -w /` first to re-sync qgroup accounting —
- * without this, a stale qgroup entry can cause `timeshift --delete` to fail
- * with "Failed to destroy qgroup" even though the subvolume itself was removed.
- *
- * After the rescan, each snapshot is deleted in a loop.  If a delete still
- * fails the function records the error and carries on so the rest can be
- * cleaned up; it throws at the end if any deletions failed.
+ * Strategy (matches the confirmed-working pattern from research):
+ * 1. Run `btrfs quota rescan -w /` upfront.
+ * 2. For each snapshot: attempt delete, then verify it is GONE from
+ *    `timeshift --list`. Timeshift exits 0 even when it prints
+ *    "E: Failed to remove snapshot" (qgroup destroy fails silently).
+ *    Verification catches that.
+ * 3. If a snapshot is still present after the first attempt:
+ *    run another rescan (the delete itself may have left a new stale entry)
+ *    and retry exactly once.
+ * 4. If it still persists after retry, record it as failed and move on.
  *
  * @param {object} opts
  * @param {'interactive'|'noninteractive'} opts.privileged
@@ -188,40 +206,53 @@ export async function deleteSnapshot(name, { privileged = 'noninteractive' } = {
 export async function deleteAllSnapshots({ privileged = 'interactive', onProgress } = {}) {
   if (privileged === 'interactive') await ensureSudo();
 
-  // Step 1: rescan qgroups so stale entries don't block the deletes.
-  onProgress?.('Running btrfs quota rescan — this may take a moment…');
-  const rescanRes = privileged === 'interactive'
-    ? await sudoInteractive(['btrfs', 'quota', 'rescan', '-w', '/'])
-    : await sudoNonInteractive(['btrfs', 'quota', 'rescan', '-w', '/']);
-
-  // A non-zero exit here is not fatal — it just means quotas may not be enabled
-  // (e.g. rsync-mode Timeshift).  Log and continue.
-  if (rescanRes.exitCode !== 0) {
-    onProgress?.(`⚠ btrfs quota rescan exited ${rescanRes.exitCode} — continuing anyway`);
-  } else {
-    onProgress?.('✔ btrfs quota rescan complete');
-  }
+  // Step 1: initial rescan to clear stale qgroup entries.
+  await btrfsQuotaRescan({ privileged, onProgress });
 
-  // Step 2: list, then delete each snapshot.
+  // Step 2: delete each snapshot, verifying it's actually gone.
   const snapshots = await listLocalSnapshots({ privileged });
   const deleted = [];
   const failed = [];
 
   for (const sn of snapshots) {
     onProgress?.(`Deleting snapshot: ${sn.name}`);
-    try {
-      await deleteSnapshot(sn.name, { privileged });
+    let success = false;
+
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      try {
+        await deleteSnapshot(sn.name, { privileged });
+      } catch {
+        // Timeshift may have removed the subvolume but still exit non-zero.
+        // Fall through to the verify step.
+      }
+
+      // Verify the snapshot is actually gone from timeshift --list.
+      const remaining = await listLocalSnapshots({ privileged });
+      const stillPresent = remaining.some((s) => s.name === sn.name);
+
+      if (!stillPresent) {
+        success = true;
+        break;
+      }
+
+      if (attempt === 1) {
+        // The delete left a new stale qgroup entry — rescan and retry once.
+        onProgress?.(`  ⚠ ${sn.name} still present after delete — rescanning qgroups and retrying…`);
+        await btrfsQuotaRescan({ privileged, onProgress });
+      }
+    }
+
+    if (success) {
       deleted.push(sn.name);
-    } catch (e) {
-      // qgroup bookkeeping might still fail on the first pass — caller can retry.
-      failed.push({ name: sn.name, error: e.message });
-      onProgress?.(`  ✖ ${sn.name}: ${e.message}`);
+    } else {
+      failed.push({ name: sn.name, error: 'still present after 2 attempts + qgroup rescan' });
+      onProgress?.(`  ✖ ${sn.name}: could not delete after rescan — try deleting it individually`);
     }
   }
 
   if (failed.length > 0) {
     throw Object.assign(
-      new Error(`${failed.length} snapshot(s) could not be deleted — try running again after a fresh qgroup rescan`),
+      new Error(`${failed.length} snapshot(s) could not be deleted`),
       { deleted, failed },
     );
   }
@@ -300,7 +331,7 @@ 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) {
     try {
       sudoExecSync(['umount', snapshot._tempMount]);
       sudoExecSync(['rmdir', snapshot._tempMount]);
@@ -392,15 +423,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,
@@ -411,8 +468,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,
@@ -423,10 +479,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;
@@ -462,19 +518,15 @@ 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 } = 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');
 
   journal('snapshots', `btrfs send subvolPath=${subvolPath} parent=${parentSubvolPath || 'null'}`);
 
@@ -531,34 +583,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;
+  }
 }
 
 /**
@@ -573,7 +669,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

@@ -421,7 +421,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) {

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;