parrot-blackbox 2.0.7 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parrot-blackbox",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "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/git-exclude.js

@@ -49,7 +49,21 @@ export function collectFiles(sources, { exclude = [], home = process.env.HOME }
 
   for (const src of sources) {
     const abs = expandPath(src, home);
-    if (!fs.existsSync(abs)) {
+    let st;
+    try {
+      st = fs.statSync(abs); // throws → source is missing
+    } catch {
+      missing.push(src);
+      continue;
+    }
+
+    // A bare FILE source (e.g. `~/.gitconfig`) is backed up verbatim.
+    if (st.isFile()) {
+      files.push({ abs, rel: path.basename(abs) || 'file' });
+      continue;
+    }
+    // Sockets / FIFOs / devices aren't copyable as sources — skip cleanly.
+    if (!st.isDirectory()) {
       missing.push(src);
       continue;
     }
@@ -91,9 +105,10 @@ export function collectFiles(sources, { exclude = [], home = process.env.HOME }
           continue;
         }
         walk(eAbs, rel, sourceRoot);
-      } else {
+      } else if (st.isFile()) {
         files.push({ abs: eAbs, rel });
       }
+      // sockets / FIFOs / devices can't be copied — silently skipped.
     }
   }
 

package/src/backup/restore.js

@@ -22,16 +22,15 @@ import { listLocalSnapshots } from './snapshot.js';
 import { ensureSudo, sudoInteractive } from '../util/sudo.js';
 import { bytesHuman } from '../util/misc.js';
 
-/** Restore a file backup generation into a writable local directory. */
-export async function restoreFiles({ id, toDir, accounts, cfg, onProgress }) {
-  const found = await discoverManifest('files', id, accounts, cfg.storage.remoteRoot);
+/** Restore a file-backup generation (or an urgent backup) into a writable local directory. */
+export async function restoreFiles({ id, toDir, accounts, cfg, kind = 'files', onProgress }) {
+  const found = await discoverManifest(kind, id, accounts, cfg.storage.remoteRoot);
   if (!found) {
-    // Fall back to scanning every account for the artifact id.
-    throw new Error(`no file backup found for id "${id}" — check with \`parrot-blackbox list\``);
+    throw new Error(`no ${kind} backup found for id "${id}" — check with \`parrot-blackbox list\``);
   }
   fs.mkdirSync(toDir, { recursive: true });
   const res = await restoreArtifact(found.manifest, toDir, { onProgress });
-  journal('restore', `files id=${id} -> ${toDir} files=${res.files} bytes=${res.bytes}`);
+  journal('restore', `${kind} id=${id} -> ${toDir} files=${res.files} bytes=${res.bytes}`);
   return { id, toDir, ...res, manifest: found.manifest };
 }
 

package/src/backup/snapshot.js

@@ -10,6 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execa, execaSync } from 'execa';
+import pc from 'picocolors';
 import { loadConfig, loadState, saveState, journal, hasCommandSync } from '../core/store.js';
 import { timeshiftDir, stateDir, configFile, manifestsDir } from '../core/paths.js';
 import { iso, clock } from '../core/time.js';
@@ -589,6 +590,15 @@ async function uploadViaBtrfsSend({ snapshot, subvolPath, parentSnapshot, parent
   const estimatedSize = await estimateSendSize(subvolPath, { parent: parentSubvolPath });
   const btrfsCfg = cfg.jobs.snapshots.btrfs || {};
 
+  // A missing parent means this is the unavoidable FULL baseline: `btrfs send -p`
+  // needs the parent subvolume to exist on disk, so there is no smaller option.
+  // Say so loudly BEFORE the upload starts — the wizard also confirmation-gates it.
+  if (!parentSubvolPath) {
+    console.log(pc.yellow('⚠  No parent snapshot available — this is a FULL baseline upload of the entire system subvolume.'));
+    console.log(pc.yellow(`   Estimated ${(estimatedSize / (1024 ** 3)).toFixed(1)} GiB raw — on a typical uplink this can take hours.`));
+    console.log(pc.yellow('   Once a snapshot is fully uploaded and kept, subsequent backups become small increments.'));
+  }
+
   console.log(`\n📤 Uploading ${parentSubvolPath ? 'incremental' : 'full'} BTRFS stream...`);
   console.log(`   Estimated size: ${(estimatedSize / (1024 ** 3)).toFixed(2)} GiB`);
   if (btrfsCfg.compression !== false) console.log(`   Compression: zstd enabled`);
@@ -834,6 +844,38 @@ export async function runSnapshotNow(cfg = loadConfig(), state = loadState(), op
   return runSnapshotBackup(cfg, state, { due, privileged: 'interactive', ...opts });
 }
 
+/**
+ * Decide whether the NEXT snapshot upload would be a small incremental (a
+ * fully-uploaded parent snapshot still exists on disk) or a FULL baseline send.
+ *
+ * Lightweight probe — it only lists local snapshots and reads local manifests;
+ * it never creates anything.  The wizard uses this to warn and confirm BEFORE
+ * a multi-hour full baseline upload is kicked off.
+ *
+ * @param {object} opts
+ * @param {object} [opts.cfg]                  config object (defaults to on-disk config)
+ * @param {'interactive'|'noninteractive'} [opts.privileged]
+ * @param {Array|null} [opts.localSnaps]         injectable snapshot list (tests)
+ * @param {string|null} [opts.manifestsDirOverride]  injectable manifests dir (tests)
+ * @returns {Promise<{full: boolean, parent: string|null, reason: string|null}>}
+ */
+export async function nextSnapshotUploadMode({ cfg = loadConfig(), privileged = 'noninteractive', localSnaps = null, manifestsDirOverride = null } = {}) {
+  const btrfsCfg = cfg?.jobs?.snapshots?.btrfs || {};
+  if (btrfsCfg.enabled === false || process.env.PBB_DISABLE_BTRFS) {
+    return { full: false, parent: null, reason: 'BTRFS streaming disabled — file-copy mode in use' };
+  }
+  if (btrfsCfg.incremental === false) {
+    return { full: false, parent: null, reason: 'incremental uploads disabled in config (full sends are intentional)' };
+  }
+
+  const snaps = localSnaps ?? (await listLocalSnapshots({ privileged }).catch(() => []));
+  const { findLastUploadedSnapshot } = await import('./btrfs-send.js');
+  const parent = findLastUploadedSnapshot(manifestsDirOverride || manifestsDir(), snaps);
+  return parent
+    ? { full: false, parent, reason: null }
+    : { full: true, parent: null, reason: 'no fully-uploaded parent snapshot on disk' };
+}
+
 export function timeshiftAvailable() {
   return hasCommandSync('timeshift');
 }

package/src/backup/urgent.js

@@ -0,0 +1,147 @@
+/**
+ * The URGENT backup — a fast, one-off rescue artifact for a fresh install.
+ *
+ * It bundles the user's real working files (Desktop / Downloads / Documents /
+ * Music / Pictures / Programming / Videos / Learning) PLUS the tooling needed
+ * to be productive on day one:
+ *   - VS Codium data profile + extensions (+ shared storage / user config)
+ *   - gitswitch bookkeeping + the SSH keys it manages + git config
+ *
+ * Design notes (why this is intentionally NOT the daily files job):
+ *   - It uses its own fixed source list, so it never depends on the user's
+ *     config having the right sources enabled.
+ *   - It still honours the golden rule: git-tracked trees are skipped (GitHub
+ *     already owns them) and the lean exclude list drops bloat (node_modules,
+ *     caches, session noise).
+ *   - It uploads through the same smart storage pool under a DISTINCT kind
+ *     ('urgent') so it is never confused with — or pruned by — scheduled
+ *     backups, and is cleanly restorable via the existing restore flow.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, loadState, saveState, journal } from '../core/store.js';
+import { stagingDir } from '../core/paths.js';
+import { iso, clock } from '../core/time.js';
+import { refreshAccounts } from '../storage/accounts.js';
+import { planAndPlace } from '../storage/allocator.js';
+import { collectFiles, stageFiles, sumFiles } from './git-exclude.js';
+
+/** Cloud artifact kind (a distinct bucket from 'files' / 'snapshots'). */
+export const KIND = 'urgent';
+
+/** Everything the urgent backup takes from the home directory. */
+export const URGENT_SOURCES = [
+  // Working files
+  '~/Desktop',
+  '~/Downloads',
+  '~/Documents',
+  '~/Learning',
+  '~/Music',
+  '~/Pictures',
+  '~/Programming',
+  '~/Videos',
+  // VS Codium — data profile + extensions + shared storage + user config
+  '~/.vscode-oss',
+  '~/.vscode-oss-shared',
+  '~/.config/VSCodium/User',
+  // gitswitch — accounts/SSH bookkeeping, the SSH keys it manages, git config
+  '~/.gitswitch',
+  '~/.ssh',
+  '~/.gitconfig',
+];
+
+/** Lean exclude list — git repos + bloat are out, real files are in. */
+export const URGENT_EXCLUDE = [
+  '**/.cache/**',
+  '**/.git/**',
+  '**/node_modules/**',
+  '**/__pycache__/**',
+  '**/*.tmp',
+  '**/*.swp',
+  '**/*.log',
+  '**/lost+found/**',
+  // VS Codium cache / session noise — the profile is what matters, not caches.
+  '**/Cache/**',
+  '**/CachedData/**',
+  '**/CachedExtensionVSIXs/**',
+  '**/GPUCache/**',
+  '**/blob_storage/**',
+  '**/Code Cache/**',
+  '**/Crashpad/**',
+  '**/Service Worker/**',
+  '**/WebStorage/**',
+  '**/Local Storage/**',
+  '**/Session Storage/**',
+];
+
+/**
+ * Collect + stage the urgent sources into a fresh bundle dir.
+ * @returns {{dir:string, files:Array, sizeBytes:number, skippedRepos:string[], missing:string[], skipped:number}}
+ */
+export function buildUrgentBundle({ home = process.env.HOME } = {}) {
+  const col = collectFiles(URGENT_SOURCES, { exclude: URGENT_EXCLUDE, home });
+  const dir = path.join(stagingDir(), `urgent-${Date.now()}-${process.pid}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  stageFiles(col.files, dir);
+  return {
+    dir,
+    files: col.files,
+    sizeBytes: sumFiles(col.files),
+    skippedRepos: col.skippedRepos,
+    missing: col.missing,
+    skipped: col.skipped,
+  };
+}
+
+/**
+ * Run one URGENT backup generation — bundle → stage → upload to the pool.
+ * Unlike scheduled backups this does NOT run retention, so the rescue artifact
+ * is never auto-deleted.
+ * @returns {Promise<{id:string, manifest:object, sizeBytes:number, skippedRepos:string[], missing:string[]}>}
+ */
+export async function runUrgentBackup(cfg = loadConfig(), state = loadState(), { onProgress } = {}) {
+  const now = clock();
+  const id = iso(now);
+  journal('urgent', `start id=${id}`);
+  const bundle = buildUrgentBundle();
+
+  const accounts = await refreshAccounts(cfg);
+  if (!accounts.length) {
+    fs.rmSync(bundle.dir, { recursive: true, force: true });
+    throw new Error('No cloud accounts configured — run `parrot-blackbox account add` (or Guided Setup) first.');
+  }
+
+  let manifest;
+  try {
+    manifest = await planAndPlace(bundle.dir, {
+      kind: KIND,
+      id,
+      accounts,
+      remoteRoot: cfg.storage.remoteRoot,
+      chunkSize: cfg.storage.chunkSize,
+      onProgress,
+    });
+  } finally {
+    fs.rmSync(bundle.dir, { recursive: true, force: true });
+  }
+
+  state.manifests[`${KIND}-${manifest.id}`] = {
+    kind: KIND,
+    id: manifest.id,
+    createdAt: manifest.createdAt,
+    totalSize: manifest.totalSize,
+    entryCount: manifest.entries?.length || 0,
+  };
+  saveState(state);
+  journal('urgent', `done id=${id} bytes=${manifest.totalSize}`);
+
+  return {
+    id,
+    manifest,
+    sizeBytes: manifest.totalSize,
+    skippedRepos: bundle.skippedRepos,
+    missing: bundle.missing,
+  };
+}

package/src/cli.js

@@ -14,6 +14,7 @@ import { installService, removeService } from './commands/service.js';
 import { runDueJobs } from './daemon/scheduler.js';
 import { startDaemon, stopDaemon, daemonRunning } from './daemon/daemon.js';
 import { runSnapshotNow, listLocalSnapshots, pruneSnapshots, deleteSnapshot, deleteAllSnapshots } from './backup/snapshot.js';
+import { runUrgentBackup } from './backup/urgent.js';
 import { restoreSnapshot, restoreFiles } from './backup/restore.js';
 import { listAccounts, addAccount, removeAccount, refreshAccounts, poolSummary } from './storage/accounts.js';
 import { listArtifacts } from './storage/archive.js';
@@ -52,6 +53,7 @@ ${pc.bold('Usage:')}
   parrot-blackbox snapshot list       List local & cloud snapshots
   parrot-blackbox snapshot delete [<name>|--all]  Delete one or all local snapshots  ${pc.dim('[sudo]')}
   parrot-blackbox snapshot prune      Delete snapshots beyond the keep limit  ${pc.dim('[sudo]')}
+  parrot-blackbox urgent              ⚡ One-off rescue backup: working files + VS Codium + gitswitch/SSH data
   parrot-blackbox list [files]        List cloud file backups
   parrot-blackbox restore             Restore a snapshot or file backup       ${pc.dim('[sudo]')}
   parrot-blackbox account add         Add a MEGA / Google Drive account (remote must already exist)
@@ -132,6 +134,12 @@ async function listFiles() {
   for (const a of artifacts) {
     console.log(`  - ${pc.cyan(a.id)}  ${bytesHuman(a.totalSize)}  ${pc.dim(a.account)}`);
   }
+  const urgent = await listArtifacts('urgent', accs, cfg.storage.remoteRoot);
+  console.log(`\n${pc.bold('Cloud urgent backups:')}`);
+  if (urgent.length === 0) console.log(`  ${pc.dim('none yet — run `parrot-blackbox urgent`')}`);
+  for (const a of urgent) {
+    console.log(`  - ${pc.cyan(a.id)}  ${bytesHuman(a.totalSize)}  ${pc.dim(a.account)}`);
+  }
   console.log();
 }
 
@@ -162,13 +170,14 @@ async function restoreFlow(rest) {
     options: [
       { value: 'snapshot', label: 'System snapshot (Timeshift) — overwrites the whole system', hint: '[sudo]' },
       { value: 'files', label: 'File backup — recover fonts/images/docs into a folder' },
+      { value: 'urgent', label: 'Urgent backup — user files + tool profiles (fresh install)' },
     ],
   }));
   if (p.isCancel(kind)) return;
 
-  if (kind === 'files') {
-    const artifacts = await listArtifacts('files', accs, cfg.storage.remoteRoot);
-    if (artifacts.length === 0) { p.log.warn('No file backups found.'); return; }
+  if (kind === 'files' || kind === 'urgent') {
+    const artifacts = await listArtifacts(kind, accs, cfg.storage.remoteRoot);
+    if (artifacts.length === 0) { p.log.warn(`No ${kind === 'urgent' ? 'urgent' : 'file'} backups found.`); return; }
     const id = rest[1] || (await p.select({
       message: 'Pick a backup generation:',
       options: artifacts.map((a) => ({ value: a.id, label: `${a.id}  (${bytesHuman(a.totalSize)})` })),
@@ -181,7 +190,7 @@ async function restoreFlow(rest) {
     const s = p.spinner();
     s.start('Restoring…');
     try {
-      const res = await restoreFiles({ id, toDir, accounts: accs, cfg });
+      const res = await restoreFiles({ id, toDir, accounts: accs, cfg, kind });
       s.stop(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
     } catch (e) {
       s.stop('✖ Restore failed.');
@@ -408,6 +417,23 @@ const main = defineCommand({
         return;
       }
 
+      case 'urgent': {
+        // One-off rescue backup — working files + VS Codium + gitswitch/SSH data.
+        const progress = makeProgressRenderer();
+        try {
+          const r = await runUrgentBackup(undefined, undefined, { onProgress: progress });
+          progress.stop();
+          console.log(`${pc.green('✔')} Urgent backup stored (${bytesHuman(r.sizeBytes)}). Restore with: \`parrot-blackbox restore urgent\`.`);
+          if (r.skippedRepos?.length) console.log(pc.dim(`Skipped ${r.skippedRepos.length} git-tracked folder(s).`));
+          if (r.missing?.length) console.log(pc.dim(`Source(s) not present, skipped: ${r.missing.join(', ')}.`));
+        } catch (e) {
+          progress.stop();
+          console.error(pc.red(`✖ ${e.message}`));
+          process.exitCode = 1;
+        }
+        return;
+      }
+
       case 'snapshot': {
         const [sub, ...args] = rest;
         if (sub === 'now' || sub === 'create' || sub === 'force') {

package/src/commands/manage.js

@@ -231,6 +231,7 @@ export async function runRepair({ auto = false } = {}) {
   }
 
   // 5. Optional npm reinstall (repair a broken CLI install)
+  let updated = false;
   if (!auto) {
     const want = await p.confirm({
       message: 'Reinstall parrot-blackbox from npm to repair the executable?',
@@ -239,10 +240,11 @@ export async function runRepair({ auto = false } = {}) {
     if (!p.isCancel(want) && want) {
       const { runSelfUpdate } = await import('../lib/self.js');
       p.log.step('Reinstalling from npm…');
-      const did = await runSelfUpdate({ force: true });
-      if (did) fixed.push('npm');
+      updated = await runSelfUpdate({ force: true });
+      if (updated) fixed.push('npm');
     }
   }
 
   p.outro(pc.green(fixed.length ? `Repair complete — fixed: ${fixed.join(', ')}.` : 'Nothing to repair — everything looks healthy.'));
+  return { updated };
 }

package/src/commands/wizard.js

@@ -17,18 +17,23 @@ import { guidedRemoteAdd } from './remote.js';
 import { listAccounts, refreshAccounts, poolSummary, addAccount, removeAccount } from '../storage/accounts.js';
 import { loadConfig, saveConfig } from '../core/store.js';
 import { runDueJobs } from '../daemon/scheduler.js';
-import { runSnapshotNow, listLocalSnapshots, deleteSnapshot, deleteAllSnapshots } from '../backup/snapshot.js';
+import { runSnapshotNow, listLocalSnapshots, deleteSnapshot, deleteAllSnapshots, nextSnapshotUploadMode } from '../backup/snapshot.js';
+import { runUrgentBackup } from '../backup/urgent.js';
 import { listArtifacts } from '../storage/archive.js';
 import { restoreFiles, restoreSnapshot } from '../backup/restore.js';
 import { installService, removeService } from './service.js';
 import { startDaemon, stopDaemon, daemonRunning } from '../daemon/daemon.js';
 import { runDoctor, runStatus, runUninstallWizard } from './manage.js';
 import { runSetup } from './setup.js';
-import { bytesHuman, makeProgressRenderer } from '../util/misc.js';
+import { bytesHuman, makeClackProgressRenderer } from '../util/misc.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
 
+/** Set once a self-update happened inside THIS process — the wizard then
+ *  warns that it is still running the OLD code until restarted. */
+let updatedInSession = false;
+
 async function importSelf() {
   return import('../lib/self.js');
 }
@@ -38,7 +43,7 @@ async function autoUpdateCheck() {
   const { checkForUpdate, promptSelfUpdate } = await importSelf();
   try {
     const { outdated } = await checkForUpdate();
-    if (outdated) await promptSelfUpdate();
+    if (outdated && await promptSelfUpdate()) updatedInSession = true;
   } catch {
     /* offline / npm missing — never block the wizard on the update check */
   }
@@ -139,10 +144,23 @@ async function accountsMenu() {
 
 /** Run every enabled backup right now. */
 async function backupNowAction() {
-  const s = p.spinner();
-  s.start('Running backup…');
-  s.stop('');
-  const res = await runDueJobs({ force: true, privileged: 'interactive' });
+  p.log.message(pc.dim('Running backup…'));
+  const cfg = loadConfig();
+  // Warn BEFORE a FULL baseline snapshot upload (10s of GiB, hours long) is
+  // accidentally started from "Run all backups".
+  if (cfg.jobs?.snapshots?.enabled !== false) {
+    const mode = await nextSnapshotUploadMode({ cfg, privileged: 'interactive' });
+    if (mode.full) {
+      const ok = await p.confirm({
+        message: pc.red('⚠ No previous snapshot found — the snapshot backup will be a FULL baseline upload of the ENTIRE system (10s of GiB, can take hours). Continue?'),
+        initialValue: false,
+      });
+      if (p.isCancel(ok) || !ok) { p.log.message(pc.dim('Aborted — nothing was uploaded.')); return; }
+    }
+  }
+  const progress = makeClackProgressRenderer(p);
+  const res = await runDueJobs({ force: true, privileged: 'interactive', onProgress: progress });
+  progress.stop();
   const report = res.report || [];
   if (report.length === 0) { p.log.message(pc.dim('No enabled backup jobs.')); return; }
   for (const r of report) {
@@ -160,10 +178,50 @@ async function backupNowAction() {
   }
 }
 
+/** One-off rescue backup: working files + VS Codium + gitswitch/SSH data (fast, for a fresh install). */
+async function urgentBackupAction() {
+  const cfg = loadConfig();
+  if (!listAccounts().length) { p.log.warn('No cloud accounts configured — add one from the menu first.'); return; }
+  const { URGENT_SOURCES } = await import('../backup/urgent.js');
+  const names = URGENT_SOURCES.map((s) => s.replace(/^~\//, ''));
+  const ok = await p.confirm({
+    message: pc.bold(`⚡ Urgent backup: ${names.length} sources`) +
+      pc.dim(` — ${names.join(', ')}.`) +
+      pc.dim('\nGit-tracked folders are skipped (already on GitHub); only real files + tool profiles are stored. Continue?'),
+    initialValue: true,
+  });
+  if (p.isCancel(ok) || !ok) { p.log.message(pc.dim('Cancelled — nothing was backed up.')); return; }
+
+  const progress = makeClackProgressRenderer(p);
+  try {
+    const r = await runUrgentBackup(cfg, undefined, { onProgress: progress });
+    p.log.success(`✔ Urgent backup stored (${bytesHuman(r.sizeBytes)}). Restore later via: Restore backup → Urgent backup.`);
+    if (r.skippedRepos?.length) p.log.message(pc.dim(`Skipped ${r.skippedRepos.length} git-tracked folder(s).`));
+    if (r.missing?.length) p.log.message(pc.dim(`Source(s) not present, skipped: ${r.missing.join(', ')}.`));
+  } catch (e) {
+    p.log.warn(`✖ ${e.message}`);
+  } finally {
+    progress.stop();
+  }
+}
+
 /** Create + upload a snapshot immediately. */
 async function snapshotNowAction() {
   try {
-    const progress = makeProgressRenderer();
+    // A full baseline sends the ENTIRE system subvolume (10s of GiB, hours).
+    // Confirm BEFORE creating the snapshot so the user can back out cheaply.
+    const mode = await nextSnapshotUploadMode({ cfg: loadConfig(), privileged: 'interactive' });
+    if (mode.full) {
+      const ok = await p.confirm({
+        message: pc.red('⚠ No previous snapshot found — this will be a FULL baseline upload of the ENTIRE system (10s of GiB, can take hours). Continue?'),
+        initialValue: false,
+      });
+      if (p.isCancel(ok) || !ok) { p.log.message(pc.dim('Aborted — nothing was uploaded.')); return; }
+    } else if (mode.parent) {
+      p.log.message(pc.dim(`Incremental upload (parent: ${mode.parent}).`));
+    }
+
+    const progress = makeClackProgressRenderer(p);
     const r = await runSnapshotNow(undefined, undefined, { onProgress: progress });
     progress.stop();
     p.log.success(`✔ Snapshot ${r.snapshot} created & uploaded (${bytesHuman(r.manifest?.totalSize ?? 0)}).`);
@@ -194,6 +252,10 @@ async function listBackupsAction() {
     const files = await listArtifacts('files', accs, cfg.storage.remoteRoot);
     if (!files.length) p.log.message(pc.dim('  none'));
     for (const f of files) p.log.message(`  - ${pc.cyan(f.id)}  ${bytesHuman(f.totalSize)}`);
+    p.log.message(pc.bold('Cloud urgent backups:'));
+    const urgent = await listArtifacts('urgent', accs, cfg.storage.remoteRoot);
+    if (!urgent.length) p.log.message(pc.dim('  none'));
+    for (const u of urgent) p.log.message(`  - ${pc.cyan(u.id)}  ${bytesHuman(u.totalSize)}`);
   } else {
     p.log.message(pc.dim('No accounts configured — add one from the menu.'));
   }
@@ -235,7 +297,8 @@ async function deleteSnapshotsMenu() {
   // ── Delete ALL ─────────────────────────────────────────────────────────────
   if (pick === '__all') {
     const confirm = await p.confirm({
-      message: pc.red(`Delete ALL ${snapshots.length} local snapshot(s)? This cannot be undone.`),
+      message: pc.red(`Delete ALL ${snapshots.length} local snapshot(s)? This cannot be undone.`) +
+        pc.yellow(' No parent snapshot will remain — the NEXT backup becomes a FULL baseline upload of the entire system (10s of GiB, can take hours).'),
       initialValue: false,
     });
     if (p.isCancel(confirm) || !confirm) {
@@ -265,7 +328,8 @@ async function deleteSnapshotsMenu() {
 
   // ── Delete ONE ─────────────────────────────────────────────────────────────
   const confirm = await p.confirm({
-    message: pc.yellow(`Delete snapshot ${pc.bold(pick)}?`),
+    message: pc.yellow(`Delete snapshot ${pc.bold(pick)}?`) +
+      (snapshots.length === 1 ? pc.yellow(' This is the last snapshot — the next backup will be a FULL baseline upload.') : ''),
     initialValue: false,
   });
   if (p.isCancel(confirm) || !confirm) {
@@ -282,7 +346,27 @@ async function deleteSnapshotsMenu() {
   }
 }
 
-/** Restore files or a system snapshot. */
+/** Restore a file-like artifact ('files' or 'urgent') into a fresh directory. */
+async function restoreFileLike(kind, accs, cfg) {
+  const artifacts = await listArtifacts(kind, accs, cfg.storage.remoteRoot);
+  if (!artifacts.length) { p.log.warn(`No ${kind === 'urgent' ? 'urgent' : 'file'} backups found.`); return; }
+  const id = await p.select({
+    message: 'Pick a backup to restore:',
+    options: artifacts.map((a) => ({ value: a.id, label: `${a.id}  (${bytesHuman(a.totalSize)})` })).concat([{ value: '__back', label: '← Back' }]),
+  });
+  if (p.isCancel(id) || id === '__back') return;
+  const toDir = await p.text({ message: 'Restore into which directory?', initialValue: `./restored-${id}` });
+  if (p.isCancel(toDir) || !toDir) return;
+  fs.mkdirSync(toDir, { recursive: true });
+  try {
+    const res = await restoreFiles({ id, toDir, accounts: accs, cfg, kind });
+    p.log.success(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
+  } catch (e) {
+    p.log.warn(`✖ ${e.message}`);
+  }
+}
+
+/** Restore files / urgent backup / system snapshot. */
 async function restoreMenu() {
   const accs = listAccounts();
   if (!accs.length) { p.log.warn('No cloud accounts configured yet.'); return; }
@@ -291,29 +375,15 @@ async function restoreMenu() {
     message: '♻️  Restore backup',
     options: [
       { value: 'files', label: '📄 Files', hint: 'recover documents, images, etc.' },
+      { value: 'urgent', label: '⚡ Urgent backup', hint: 'user files + tool profiles (fresh install)' },
       { value: 'snapshot', label: '💽 System snapshot', hint: 'full system restore [sudo]' },
       { value: 'back', label: '← Back' },
     ],
   });
   if (p.isCancel(kind) || kind === 'back') return;
 
-  if (kind === 'files') {
-    const artifacts = await listArtifacts('files', accs, cfg.storage.remoteRoot);
-    if (!artifacts.length) { p.log.warn('No file backups found.'); return; }
-    const id = await p.select({
-      message: 'Pick a backup generation:',
-      options: artifacts.map((a) => ({ value: a.id, label: `${a.id}  (${bytesHuman(a.totalSize)})` })).concat([{ value: '__back', label: '← Back' }]),
-    });
-    if (p.isCancel(id) || id === '__back') return;
-    const toDir = await p.text({ message: 'Restore into which directory?', initialValue: `./restored-${id}` });
-    if (p.isCancel(toDir) || !toDir) return;
-    fs.mkdirSync(toDir, { recursive: true });
-    try {
-      const res = await restoreFiles({ id, toDir, accounts: accs, cfg });
-      p.log.success(`✔ Restored ${res.files} file(s), ${bytesHuman(res.bytes)} into ${toDir}`);
-    } catch (e) {
-      p.log.warn(`✖ ${e.message}`);
-    }
+  if (kind === 'files' || kind === 'urgent') {
+    await restoreFileLike(kind, accs, cfg);
     return;
   }
 
@@ -401,10 +471,19 @@ export async function runWizard() {
   await autoUpdateCheck();
 
   for (;;) {
+    // After an in-session self-update THIS process is still running the loaded
+    // (old) code — that's exactly the trap that makes uploads look silent in a
+    // stale session. Remind once per update so the user restarts.
+    if (updatedInSession) {
+      p.log.warn(`⚠ Updated earlier this session — this process still runs the OLD v${pkg.version} code. Exit and re-run \`parrot-blackbox\` to use the new version.`);
+      updatedInSession = false;
+    }
+
     const action = await p.select({
       message: 'What would you like to do?',
       options: [
         { value: 'snapshot', label: '📸 Create snapshot', hint: 'backup your system now' },
+        { value: 'urgent', label: '⚡ Urgent backup', hint: 'files + tool profiles, fast — rescue for a fresh install' },
         { value: 'resume', label: '⏳ Resume upload', hint: 'resume incomplete backup uploads' },
         { value: 'backup', label: '💾 Run all backups', hint: 'snapshots + file backups' },
         { value: 'restore', label: '♻️  Restore backup', hint: 'files or system snapshot' },
@@ -436,6 +515,7 @@ export async function runWizard() {
         case 'accounts': await accountsMenu(); break;
         case 'tools': await runToolsCheck(); break;
         case 'snapshot': await snapshotNowAction(); break;
+        case 'urgent': await urgentBackupAction(); break;
         case 'resume': await snapshotNowAction(); break;
         case 'backup': await backupNowAction(); break;
         case 'list': await listBackupsAction(); break;
@@ -446,8 +526,8 @@ export async function runWizard() {
         case 'setup': await runSetup(); break;
         case 'status': await runStatus(); break;
         case 'doctor': await runDoctor(); break;
-        case 'repair': { const { runRepair } = await import('./manage.js'); await runRepair(); break; }
-        case 'update': { const { runSelfUpdate } = await import('../lib/self.js'); await runSelfUpdate(); break; }
+        case 'repair': { const { runRepair } = await import('./manage.js'); const res = await runRepair(); if (res?.updated) updatedInSession = true; break; }
+        case 'update': { const { runSelfUpdate } = await import('../lib/self.js'); if (await runSelfUpdate()) updatedInSession = true; break; }
         case 'uninstall': await runUninstallWizard(); p.outro('parrot-blackbox removed — cloud backups are safe.'); return;
         default: break;
       }

package/src/util/misc.js

@@ -129,22 +129,23 @@ export function makeProgressRenderer() {
   const BAR_WIDTH = 25;
   let lastLine = '';
 
-  function render({ done = 0, total = 0, speedMBs = 0, remote = '' } = {}) {
-    const doneMB = done / (1024 * 1024);
-    const totalMB = total / (1024 * 1024);
+  function buildLine({ done = 0, total = 0, speedMBs = 0, remote = '' } = {}) {
+    const doneMB   = done / (1024 * 1024);
+    const totalMB  = total / (1024 * 1024);
     const speedStr = speedMBs > 0 ? `  ${speedMBs.toFixed(1)} MB/s` : '';
     const destStr  = remote ? `  → ${remote}` : '';
 
-    let line;
     if (total > 0) {
       const pct    = Math.min(100, Math.round((done / total) * 100));
       const filled = Math.round((pct / 100) * BAR_WIDTH);
       const bar    = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
-      line = `  [${bar}] ${String(pct).padStart(3)}%  ${doneMB.toFixed(1)} MB / ${totalMB.toFixed(1)} MB${speedStr}${destStr}`;
-    } else {
-      line = `  ⬆  ${doneMB.toFixed(1)} MB streamed${speedStr}${destStr}`;
+      return `  [${bar}] ${String(pct).padStart(3)}%  ${doneMB.toFixed(1)} MB / ${totalMB.toFixed(1)} MB${speedStr}${destStr}`;
     }
+    return `  ⬆  ${doneMB.toFixed(1)} MB streamed${speedStr}${destStr}`;
+  }
 
+  function render(evt = {}) {
+    const line = buildLine(evt);
     if (isTTY) {
       process.stdout.write(`\r${line}\x1b[K`);
     } else if (line !== lastLine) {
@@ -160,5 +161,61 @@ export function makeProgressRenderer() {
     lastLine = '';
   };
 
+  return render;
+}
+
+/**
+ * A @clack/prompts-aware progress renderer.
+ *
+ * Inside the clack wizard the terminal is managed by clack's ANSI cursor
+ * tracking — raw `\r` writes get clobbered.  This variant throttles output
+ * to at most one `p.log.message()` call per second so clack can handle
+ * rendering, and the bar stays readable.
+ *
+ * Usage:
+ *   import * as p from '@clack/prompts';
+ *   const progress = makeClackProgressRenderer(p);
+ *   await runSnapshotNow(undefined, undefined, { onProgress: progress });
+ *   progress.stop();
+ *
+ * Expected event shape: same as makeProgressRenderer().
+ */
+export function makeClackProgressRenderer(p) {
+  const BAR_WIDTH = 20;
+  const THROTTLE_MS = 800; // max one clack log line per 800 ms
+  let lastEmitAt = 0;
+  let lastLine = '';
+
+  function buildLine({ done = 0, total = 0, speedMBs = 0, remote = '' } = {}) {
+    const doneMB   = done / (1024 * 1024);
+    const totalMB  = total / (1024 * 1024);
+    const speedStr = speedMBs > 0 ? `  ${speedMBs.toFixed(1)} MB/s` : '';
+    const destStr  = remote ? `  → ${remote}` : '';
+
+    if (total > 0) {
+      const pct    = Math.min(100, Math.round((done / total) * 100));
+      const filled = Math.round((pct / 100) * BAR_WIDTH);
+      const bar    = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+      return `[${bar}] ${String(pct).padStart(3)}%  ${doneMB.toFixed(1)} / ${totalMB.toFixed(1)} MB${speedStr}${destStr}`;
+    }
+    return `⬆  ${doneMB.toFixed(1)} MB streamed${speedStr}${destStr}`;
+  }
+
+  function render(evt = {}) {
+    const now  = Date.now();
+    const line = buildLine(evt);
+    if (line === lastLine) return;           // nothing changed
+    if (now - lastEmitAt < THROTTLE_MS) return; // too soon
+    lastEmitAt = now;
+    lastLine   = line;
+    p.log.message(line);
+  }
+
+  render.stop = function stop() {
+    // emit the final state unconditionally so the user sees 100% or final MB
+    if (lastLine) p.log.message(lastLine);
+    lastLine = '';
+  };
+
   return render;
 }