@chibitek/chibi 0.1.172 → 0.1.173

package/dist-server/server/workspace-backup.js

@@ -1,24 +1,26 @@
-// An encrypted filesystem snapshot, not an additive import. The caller must
-// quiesce writers before create/commit. Restore runs before config/store load.
-import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, scrypt } from "node:crypto";
-import { chmodSync, closeSync, constants, cpSync, createReadStream, createWriteStream, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+// A filesystem snapshot, not an additive import, encrypted unless the person
+// turns that off (workspace-backup-archive.ts). The caller must quiesce
+// writers before create/commit. Restore runs before config/store load.
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, copyFileSync, cpSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
 import { isAbsolute, join, parse, posix, relative, resolve, win32 } from "node:path";
 import { homedir } from "node:os";
 import { backup, DatabaseSync } from "node:sqlite";
-import { pipeline } from "node:stream/promises";
 import * as tar from "tar";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { writeFileAtomic } from "./atomic.js";
 import { escapeAttribute, splitTranscriptAttachments } from "../src/lib/composer-attachments.js";
 import { WORKSPACE_BACKUP_CLIENT_KEYS } from "../shared/workspace-backup-client.js";
 import { ephemeralWorkspaceTokenPath, excludedWorkspaceAuthPath, portableWorkspaceConfig, restoredWorkspaceConfig } from "./workspace-backup-policy.js";
-export const MAX_WORKSPACE_BACKUP_BYTES = 10 * 1024 ** 3;
+import { privateBotIds, privateBotPath, scrubPrivateMessages } from "./workspace-backup-private.js";
+import { MAX_WORKSPACE_BACKUP_BYTES, passwordKey, readArchive, writeArchive } from "./workspace-backup-archive.js";
+import { SECRET_TOP_LEVEL, secretWorkspacePath, validSecretsBundle } from "./workspace-backup-secrets.js";
+import { absolutePath, rebaseFields, rebasePath, rebaseTree, reclonableCheckout, restoreLinks, restorePathPairs, validRelative, } from "./workspace-restore-paths.js";
+export { MAX_WORKSPACE_BACKUP_BYTES, MAX_WORKSPACE_BACKUP_UPLOAD_BYTES } from "./workspace-backup-archive.js";
+export { privateBotIds, privateBotPath } from "./workspace-backup-private.js";
 export const MAX_WORKSPACE_BACKUP_FILES = 100_000;
-export const MAX_WORKSPACE_BACKUP_UPLOAD_BYTES = MAX_WORKSPACE_BACKUP_BYTES + 256 * 1024 ** 2;
 const MAX_METADATA_BYTES = 16 * 1024 ** 2;
-const MAGIC = Buffer.from("OMB-WORKSPACE-1\n");
-const HEADER_BYTES = MAGIC.length + 16 + 12;
-const TAG_BYTES = 16;
+const MAX_REPORTED_PATHS = 200;
 const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const EXCLUDED = new Set([
     ".backups", "tools", "cache", ".cache", "tmp", ".tmp", "dist-native", "tunnel-runtime",
@@ -33,102 +35,38 @@ const REINSTALLABLE_DIRS = new Set(["node_modules", ".pnpm-store", ".venv", "ven
 /** Links a running browser creates to mark its profile in use; they point
  * at a process, not at data, and a restored profile must not carry them. */
 const BROWSER_LOCK_LINKS = new Set(["lock", ".parentlock", "SingletonLock", "SingletonSocket", "SingletonCookie"]);
+const SECRETS_NOTE = "Saved credentials, provider and MCP connections, managed provider login homes and browser login profiles are not transferred. Destination connections are preserved; reconnect on a new device.";
 const EXCLUSION_NOTES = [
     "Device pairing, server identity, live leases and runtime files (existing destination identities are preserved).",
-    "Saved credentials, provider and MCP connections, managed provider login homes and browser login profiles are not transferred. Destination connections are preserved; reconnect on a new device.",
+    SECRETS_NOTE,
     "Downloaded tools and caches; these can be installed again.",
     "Project dependency and build folders (node_modules, .venv, __pycache__, .next, .turbo, .build, DerivedData); reinstall them in each project after restoring.",
     "External project folders, CLI login homes, browser session homes, OS keychains, companion devices and other servers.",
     "VM/container disk layers and remote cloud data; durable files inside this workspace are included.",
 ];
 const RESTORE_WARNING = "Restoring pauses routines, webhooks and calendar calls, and does not resume pending delegations, queued chat messages or queued runs. Definitions and historical receipts are retained; review before enabling them again.";
-/** The Private Bot's ids and thread ids in a data folder, from bots.json. */
-export function privateBotIds(dataDir) {
-    const botIds = new Set();
-    const threadIds = new Set();
-    const path = join(dataDir, "bots.json");
-    if (!existsSync(path))
-        return { botIds, threadIds };
-    let value;
-    try {
-        value = JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return { botIds, threadIds };
-    }
-    if (!Array.isArray(value))
-        return { botIds, threadIds };
-    for (const bot of value) {
-        if (!record(bot) || bot.personal !== true || typeof bot.id !== "string")
-            continue;
-        botIds.add(bot.id);
-        if (typeof bot.threadId === "string")
-            threadIds.add(bot.threadId);
-        if (Array.isArray(bot.tasks))
-            for (const task of bot.tasks)
-                if (record(task) && typeof task.threadId === "string")
-                    threadIds.add(task.threadId);
-    }
-    return { botIds, threadIds };
-}
-/** Whether a data-folder path belongs to the Private Bot: a folder or file
- * named after its id or one of its threads, anywhere below the top level
- * (workspaces/<id>, task-workspaces/<id>, events/<thread>.jsonl, ...). */
-export function privateBotPath(path, ids) {
-    if (ids.size === 0)
-        return false;
-    const parts = path.split("/");
-    return parts.slice(1).some((part) => {
-        const stem = part.split(".")[0] ?? part;
-        return ids.has(part) || ids.has(stem);
-    });
-}
-/** Remove the Private Bot's rows from a copy of the message database, and
- * return the attachment names its messages referenced. */
-function scrubPrivateMessages(dbPath, botIds, threadIds) {
-    const attachments = new Set();
-    if (!existsSync(dbPath) || (botIds.size === 0 && threadIds.size === 0))
-        return attachments;
-    const db = new DatabaseSync(dbPath);
-    try {
-        const threads = [...threadIds];
-        const bots = [...botIds];
-        const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => String(row.name)));
-        const marks = (count) => Array.from({ length: count }, () => "?").join(", ");
-        if (threads.length && tables.has("messages")) {
-            for (const row of db.prepare(`SELECT json FROM messages WHERE thread_id IN (${marks(threads.length)})`).all(...threads)) {
-                for (const match of String(row.json).matchAll(/\/api\/attachments\/([A-Za-z0-9._-]{1,200})/g))
-                    attachments.add(match[1]);
-            }
-            db.prepare(`DELETE FROM messages WHERE thread_id IN (${marks(threads.length)})`).run(...threads);
-        }
-        if (threads.length && tables.has("thread_state"))
-            db.prepare(`DELETE FROM thread_state WHERE thread_id IN (${marks(threads.length)})`).run(...threads);
-        if (tables.has("chat_followups") && (threads.length || bots.length)) {
-            db.prepare(`DELETE FROM chat_followups WHERE thread_id IN (${marks(threads.length || 1)}) OR owner_id IN (${marks(bots.length || 1)})`)
-                .run(...(threads.length ? threads : [""]), ...(bots.length ? bots : [""]));
-        }
-        if (bots.length && tables.has("memory_files"))
-            db.prepare(`DELETE FROM memory_files WHERE bot_id IN (${marks(bots.length)})`).run(...bots);
-        db.exec("VACUUM");
-    }
-    finally {
-        db.close();
-    }
-    return attachments;
-}
+/** Encrypted backups can carry everything a new computer needs to sign in
+ * again; these still cannot move, because they are sealed to this one. */
+const SECRETS_KEPT_NOTE = "Phone pairing, companion devices, the Chibitek sign-in, browser login profiles and command-line logins kept in this computer's keychain stay on this computer; sign in to those again after restoring.";
 function excluded(name) {
     return EXCLUDED.has(name) || excludedWorkspaceAuthPath(name) || name.startsWith("openmausbot-server.lease.") || name.startsWith("box-create-requests.lock.") || /^perm-[A-Za-z0-9_-]+\.sock$/.test(name);
 }
-function forbiddenArchivePath(path) {
+function forbiddenArchivePath(path, secrets = false) {
     const folded = path.toLowerCase();
+    // Inside a canonical secret root, names keep their case (provider project
+    // folders are named after paths like /Users/...); only the vault key file,
+    // which each computer keeps for itself, may not arrive under another case.
+    if (secrets && secretWorkspacePath(path) && folded !== "providers/native-vault/key.bin")
+        return false;
     return excluded(folded.split("/")[0]) || excludedWorkspaceAuthPath(folded) ||
         (path !== folded && ["config.json", "webhooks.json"].includes(folded));
 }
-function preserved(name) {
+function preserved(name, secrets = false) {
     // Existing WAL/SHM belong to the old database and must move into safety,
     // never accompany a different restored main database.
     const folded = name.toLowerCase();
+    if (secrets && SECRET_TOP_LEVEL.has(name))
+        return false;
     return excluded(folded) && folded !== "messages.db-wal" && folded !== "messages.db-shm";
 }
 function folder(path) {
@@ -166,11 +104,6 @@ function newJob(dataDir) {
     mkdirSync(directory, { mode: 0o700 });
     return { id, directory };
 }
-function validRelative(path) {
-    return !!path && path.length <= 4096 && !isAbsolute(path) && !/[\\\0:]/.test(path) &&
-        path.split("/").every((part) => !!part && part !== "." && part !== ".." && !/[. ]$/.test(part) &&
-            !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part));
-}
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -240,19 +173,6 @@ function assertLocalAuthOutsideSnapshot(dataDir) {
         check(instance.config.configDir, "config.configDir", String(environment.HOME || environment.USERPROFILE || homedir()));
     }
 }
-function passwordKey(password, salt) {
-    if (typeof password !== "string" || password.length < 12 || Buffer.byteLength(password) > 1024) {
-        throw new Error("Use a backup password of at least 12 characters (at most 1024 bytes).");
-    }
-    return new Promise((resolveKey, reject) => {
-        scrypt(password, salt, 32, { N: 131_072, r: 8, p: 1, maxmem: 256 * 1024 ** 2 }, (error, key) => {
-            if (error)
-                reject(error);
-            else
-                resolveKey(key);
-        });
-    });
-}
 // Open without following links and copy synchronously so this server cannot
 // interleave a mutation. External writers are detected where stat permits.
 function copyRegular(source, destination) {
@@ -261,7 +181,7 @@ function copyRegular(source, destination) {
     try {
         const before = fstatSync(input);
         if (!before.isFile() || before.size > MAX_WORKSPACE_BACKUP_BYTES)
-            throw new Error("A workspace file is not regular or exceeds the 10 GB backup limit.");
+            throw new Error("A workspace file is not regular or exceeds the 64 GB backup limit.");
         const mode = before.mode & 0o100 ? 0o700 : 0o600;
         output = openSync(destination, "wx", mode);
         const chunk = Buffer.allocUnsafe(1024 * 1024);
@@ -351,16 +271,27 @@ function databaseCounts(path) {
 export async function createWorkspaceBackup(dataDir, options) {
     if (Object.hasOwn(options, "credentials"))
         throw new Error("Workspace backups do not transfer credentials.");
+    const encrypted = options.password !== undefined;
+    const secrets = options.includeSecrets === true;
+    if (secrets && !encrypted)
+        throw new Error("Keys, passwords and tokens are only included in an encrypted backup. Set a backup password.");
+    if (options.secrets && (!secrets || !validSecretsBundle(options.secrets)))
+        throw new Error("Invalid secrets for this workspace backup.");
     assertLocalAuthOutsideSnapshot(dataDir);
     const salt = randomBytes(16);
-    const key = await passwordKey(options.password, salt);
+    const key = encrypted ? await passwordKey(options.password, salt) : null;
     const job = newJob(dataDir);
     const snapshot = join(job.directory, "snapshot");
     folder(join(snapshot, "data"));
     const entries = [];
-    const warnings = ["Stop external editors and managed desktops before exporting; files written outside this server cannot be frozen by the backup gate.", "Conversation text and user files are not redacted and may contain secrets you pasted. Keep the encrypted backup private.", RESTORE_WARNING];
+    const links = [];
+    const checkouts = [];
+    const warnings = ["Stop external editors and managed desktops before exporting; files written outside this server cannot be frozen by the backup gate.",
+        encrypted ? "Conversation text and user files are not redacted and may contain secrets you pasted. Keep the encrypted backup private." : "This backup is not encrypted. Anyone with the file can read your conversations and files; keep it private.",
+        ...(secrets ? ["This backup holds your keys, passwords and tokens. Anyone with the file and its password can use them."] : []), RESTORE_WARNING];
     let bytes = 0;
     let skippedLinks = 0;
+    const progress = () => options.onProgress?.({ phase: "copying", files: entries.length, bytes });
     try {
         const root = realpathSync(dataDir);
         const sourceDb = join(root, "messages.db");
@@ -399,7 +330,7 @@ export async function createWorkspaceBackup(dataDir, options) {
             warnings.push("Your Private Bot is not in this backup: its conversations, memory and files stay only on this computer.");
         const walk = (directory, prefix = "") => {
             for (const name of readdirSync(directory).sort()) {
-                if (!prefix && excluded(name))
+                if (!prefix && excluded(name) && !(secrets && SECRET_TOP_LEVEL.has(name)))
                     continue;
                 const path = prefix ? `${prefix}/${name}` : name;
                 if (privateBotPath(path, hiddenIds) || (prefix === "attachments" && hiddenAttachments.has(name)))
@@ -411,11 +342,12 @@ export async function createWorkspaceBackup(dataDir, options) {
                 // refills itself, so the company's copy leaves it out.
                 if (options.excludePrivateBot && !prefix && name === "nexus-outbox")
                     continue;
-                if (excludedWorkspaceAuthPath(path) || ephemeralWorkspaceTokenPath(path))
+                const secret = secrets && secretWorkspacePath(path);
+                if ((excludedWorkspaceAuthPath(path) && !secret) || ephemeralWorkspaceTokenPath(path) || path === "providers/native-vault/key.bin")
                     continue;
                 // Do not silently skip noncanonical source spellings: reject them so
                 // a case-sensitive host cannot export auth paths active on Windows/Mac.
-                if (forbiddenArchivePath(path))
+                if (forbiddenArchivePath(path, secrets))
                     throw new Error("A workspace filename conflicts with a protected authentication or runtime path.");
                 if (!validRelative(path))
                     throw new Error("A workspace filename cannot be safely restored on supported platforms.");
@@ -426,29 +358,25 @@ export async function createWorkspaceBackup(dataDir, options) {
                 if (stat.isSymbolicLink() && BROWSER_LOCK_LINKS.has(name))
                     continue;
                 if (stat.isSymbolicLink()) {
-                    let target;
-                    try {
-                        target = realpathSync(source);
-                    }
-                    catch {
-                        throw new Error(`Cannot back up dangling symbolic link: ${path}`);
-                    }
-                    const rel = relative(root, target);
-                    if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
-                        throw new Error(`Cannot back up symbolic link outside the workspace: ${path}`);
+                    // The app's disposable native-discovery links are recreated by the app.
+                    if (/^workspaces\/[^/]+\/\.(?:claude|agents|grok)\/skills\/[^/]+$/.test(path)) {
+                        skippedLinks++;
+                        continue;
                     }
-                    // Only the app's disposable native-discovery links may be omitted.
-                    // An arbitrary user link represents user data, even inside the root.
-                    if (!/^workspaces\/[^/]+\/\.(?:claude|agents|grok)\/skills\/[^/]+$/.test(path) ||
-                        !rel.replaceAll("\\", "/").startsWith(`workspaces/${path.split("/")[1]}/skills/`)) {
-                        throw new Error(`Cannot back up user-created symbolic link; replace it with regular files first: ${path}`);
-                    }
-                    skippedLinks++;
+                    // Any other link is recorded, never followed: the restore remakes
+                    // it with its target rebased to the new computer (restoreLinks).
+                    links.push({ path, target: readlinkSync(source) });
                     continue;
                 }
-                if (entries.length >= MAX_WORKSPACE_BACKUP_FILES)
+                if (entries.length + links.length >= MAX_WORKSPACE_BACKUP_FILES)
                     throw new Error("The workspace exceeds the 100,000-entry backup limit.");
                 const destination = join(snapshot, "data", path);
+                // A clean checkout that origin already holds is cloned again, not copied.
+                const remote = stat.isDirectory() && prefix && !secret && entryExists(join(source, ".git")) ? reclonableCheckout(source) : null;
+                if (remote) {
+                    checkouts.push({ path, remote });
+                    continue;
+                }
                 if (stat.isDirectory()) {
                     folder(destination);
                     entries.push({ path, type: "directory", size: 0, mode: 0o700 });
@@ -467,7 +395,7 @@ export async function createWorkspaceBackup(dataDir, options) {
                         writeFileSync(destination, kept.join("\n"), { mode: 0o600, flag: "wx" });
                         copied = { size: lstatSync(destination).size, mode: 0o600, sha256: hashFile(destination) };
                     }
-                    else if (path === "config.json" || path === "webhooks.json") {
+                    else if ((path === "config.json" || path === "webhooks.json") && !secrets) {
                         const value = privateJson(source);
                         if (path === "config.json")
                             writeJson(destination, portableWorkspaceConfig(value));
@@ -486,46 +414,43 @@ export async function createWorkspaceBackup(dataDir, options) {
                         copied = copyRegular(path === "messages.db" ? join(snapshot, "messages-snapshot.db") : source, destination);
                     bytes += copied.size;
                     if (bytes > MAX_WORKSPACE_BACKUP_BYTES)
-                        throw new Error("The workspace exceeds the 10 GB backup limit.");
+                        throw new Error("The workspace exceeds the 64 GB backup limit.");
                     entries.push({ path, type: "file", ...copied });
+                    if (entries.length % 500 === 0)
+                        progress();
                 }
-                else
+                else if (!secret)
                     throw new Error(`Cannot back up special or live runtime file: ${path}`);
             }
         };
         walk(root);
         if (skippedLinks)
             warnings.push(`${skippedLinks} managed skill discovery link(s) were omitted and are recreated by the app.`);
+        if (checkouts.length)
+            warnings.push(`${checkouts.length} project checkout(s) with no local changes were left out; clone them again from their remote. Files git ignores in them (such as .env) are not included.`);
+        if (secrets && !options.secrets)
+            warnings.push("This computer's secure credential store was not available, so connection keys saved there are not in this backup.");
         const summary = {
             format: "openmaus.workspace-backup", version: 1, id: job.id, createdAt: new Date().toISOString(),
             appVersion: options.appVersion ?? "unknown", files: entries.filter((entry) => entry.type === "file").length,
             directories: entries.filter((entry) => entry.type === "directory").length, bytes,
             bots: countJsonArray(join(snapshot, "data", "bots.json")), groups: countJsonArray(join(snapshot, "data", "groups.json")),
             ...databaseCounts(join(snapshot, "data", "messages.db")),
-            exclusions: EXCLUSION_NOTES, warnings,
+            exclusions: secrets ? [SECRETS_KEPT_NOTE, ...EXCLUSION_NOTES.filter((note) => note !== SECRETS_NOTE)] : EXCLUSION_NOTES, warnings,
+            encrypted, secrets, checkouts,
         };
         const manifest = {
-            summary, sourceDataDir: resolve(dataDir), clientState: options.clientState ?? {}, entries,
+            summary, sourceDataDir: resolve(dataDir), sourceHome: homedir(), clientState: options.clientState ?? {}, links, entries,
         };
         writeJson(join(snapshot, "manifest.json"), manifest);
         // Validate our own output too: JSON serialization must never silently
         // discard metadata or produce a backup the importer cannot read.
         validateManifest(privateJson(join(snapshot, "manifest.json")));
+        if (options.secrets)
+            writeJson(join(snapshot, "secrets.json"), options.secrets);
+        options.onProgress?.({ phase: "writing", files: entries.length, bytes });
         const path = join(job.directory, "workspace.ombbackup");
-        const iv = randomBytes(12);
-        const header = Buffer.concat([MAGIC, salt, iv]);
-        const cipher = createCipheriv("aes-256-gcm", key, iv);
-        cipher.setAAD(header);
-        writeFileSync(path, header, { mode: 0o600, flag: "wx" });
-        await pipeline(tar.c({ cwd: snapshot, portable: true, strict: true }, ["manifest.json", "data"]), cipher, createWriteStream(path, { flags: "a", mode: 0o600 }));
-        const fd = openSync(path, "a");
-        try {
-            writeSync(fd, cipher.getAuthTag());
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
+        await writeArchive(path, snapshot, ["manifest.json", ...(options.secrets ? ["secrets.json"] : []), "data"], key ? { key, salt } : null);
         rmSync(snapshot, { recursive: true, force: true });
         return { id: job.id, path, summary };
     }
@@ -534,7 +459,7 @@ export async function createWorkspaceBackup(dataDir, options) {
         throw error;
     }
     finally {
-        key.fill(0);
+        key?.fill(0);
     }
 }
 function validateManifest(value) {
@@ -545,8 +470,11 @@ function validateManifest(value) {
         value.sourceDataDir.length > 4096 || value.sourceDataDir.includes("\0") ||
         value.sourceDataDir === posix.parse(value.sourceDataDir).root || value.sourceDataDir === win32.parse(value.sourceDataDir).root ||
         value.sourceDataDir.replaceAll("\\", "/").split("/").some((part) => part === "." || part === "..") ||
-        Object.keys(value).some((key) => !["summary", "sourceDataDir", "clientState", "entries"].includes(key)) ||
-        Object.keys(value.summary).some((key) => !["format", "version", "id", "createdAt", "appVersion", "files", "directories", "bytes", "bots", "groups", "threads", "messages", "exclusions", "warnings"].includes(key)) || !record(value.clientState) ||
+        Object.keys(value).some((key) => !["summary", "sourceDataDir", "sourceHome", "clientState", "links", "entries"].includes(key)) ||
+        (value.sourceHome !== undefined && (typeof value.sourceHome !== "string" || !absolutePath(value.sourceHome) || value.sourceHome.length > 4096 || value.sourceHome.includes("\0"))) ||
+        Object.keys(value.summary).some((key) => !["format", "version", "id", "createdAt", "appVersion", "files", "directories", "bytes", "bots", "groups", "threads", "messages", "exclusions", "warnings", "encrypted", "secrets", "checkouts"].includes(key)) ||
+        !["undefined", "boolean"].includes(typeof value.summary.encrypted) || !["undefined", "boolean"].includes(typeof value.summary.secrets) ||
+        (value.summary.secrets === true && value.summary.encrypted === false) || !record(value.clientState) ||
         !Object.values(value.clientState).every((item) => typeof item === "string") || !Array.isArray(value.entries) ||
         value.entries.length > MAX_WORKSPACE_BACKUP_FILES)
         throw new Error("Invalid or unsupported workspace backup metadata.");
@@ -561,11 +489,16 @@ function validateManifest(value) {
         if (!Array.isArray(value.summary[key]) || !value.summary[key].every((item) => typeof item === "string"))
             throw new Error("Invalid workspace backup summary.");
     }
+    const checkouts = value.summary.checkouts ?? [];
+    if (!Array.isArray(checkouts) || !checkouts.every((item) => record(item) && Object.keys(item).length === 2 && typeof item.path === "string" && validRelative(item.path) &&
+        typeof item.remote === "string" && item.remote.length <= 4096))
+        throw new Error("Invalid workspace backup summary.");
+    const secrets = value.summary.secrets === true;
     const names = new Map();
     let bytes = 0;
     let files = 0;
     for (const raw of value.entries) {
-        if (!record(raw) || typeof raw.path !== "string" || !validRelative(raw.path) || forbiddenArchivePath(raw.path) ||
+        if (!record(raw) || typeof raw.path !== "string" || !validRelative(raw.path) || forbiddenArchivePath(raw.path, secrets) ||
             Object.keys(raw).some((key) => !["path", "type", "size", "mode", "sha256"].includes(key)) ||
             !["file", "directory"].includes(String(raw.type)) || !Number.isSafeInteger(raw.size) || raw.size < 0 ||
             ![0o600, 0o700].includes(raw.mode) || names.has(raw.path.toLowerCase()))
@@ -584,6 +517,15 @@ function validateManifest(value) {
         names.size - files !== value.summary.directories) {
         throw new Error("Workspace backup contents do not match their summary or exceed the limit.");
     }
+    const links = value.links ?? [];
+    if (!Array.isArray(links) || links.length + names.size > MAX_WORKSPACE_BACKUP_FILES)
+        throw new Error("Invalid workspace backup links.");
+    for (const link of links) {
+        if (!record(link) || Object.keys(link).length !== 2 || typeof link.path !== "string" || !validRelative(link.path) || forbiddenArchivePath(link.path, secrets) ||
+            typeof link.target !== "string" || !link.target || link.target.length > 4096 || link.target.includes("\0") || names.has(link.path.toLowerCase()))
+            throw new Error("Unsafe or duplicate workspace backup link.");
+        names.set(link.path.toLowerCase(), "link");
+    }
     for (const path of names.keys()) {
         const parts = path.split("/");
         for (let i = 1; i < parts.length; i++)
@@ -592,34 +534,6 @@ function validateManifest(value) {
     }
     return value;
 }
-async function decryptArchive(inputPath, plaintext, password) {
-    const fd = openSync(inputPath, constants.O_RDONLY | constants.O_NOFOLLOW);
-    let key;
-    try {
-        const stat = fstatSync(fd);
-        if (!stat.isFile() || stat.size < HEADER_BYTES + TAG_BYTES || stat.size > MAX_WORKSPACE_BACKUP_UPLOAD_BYTES)
-            throw new Error("Invalid or oversized workspace backup file.");
-        const header = Buffer.alloc(HEADER_BYTES);
-        const tag = Buffer.alloc(TAG_BYTES);
-        if (readSync(fd, header, 0, header.length, 0) !== header.length || !header.subarray(0, MAGIC.length).equals(MAGIC) ||
-            readSync(fd, tag, 0, tag.length, stat.size - TAG_BYTES) !== tag.length)
-            throw new Error("This is not a supported encrypted workspace backup.");
-        key = await passwordKey(password, header.subarray(MAGIC.length, MAGIC.length + 16));
-        const decipher = createDecipheriv("aes-256-gcm", key, header.subarray(MAGIC.length + 16));
-        decipher.setAAD(header);
-        decipher.setAuthTag(tag);
-        try {
-            await pipeline(createReadStream(inputPath, { fd, autoClose: false, start: HEADER_BYTES, end: stat.size - TAG_BYTES - 1 }), decipher, createWriteStream(plaintext, { flags: "wx", mode: 0o600 }));
-        }
-        catch {
-            throw new Error("The backup password is incorrect, or the backup file is damaged. Nothing was restored.");
-        }
-    }
-    finally {
-        key?.fill(0);
-        closeSync(fd);
-    }
-}
 async function inspectTar(path) {
     const fd = openSync(path, "r");
     const signature = Buffer.alloc(2);
@@ -639,7 +553,7 @@ async function inspectTar(path) {
     let problem = "";
     await tar.t({ file: path, strict: true, onReadEntry(entry) {
             const name = entry.type === "Directory" ? entry.path.replace(/\/$/, "") : entry.path;
-            const expectedRoot = name === "manifest.json" || name === "data" || name.startsWith("data/");
+            const expectedRoot = name === "manifest.json" || name === "secrets.json" || name === "data" || name.startsWith("data/");
             // ReadEntry normalizes backslashes on Windows; inspect the raw header too
             // so the same hostile archive is rejected before extraction on every OS.
             if (entry.header.path?.includes("\\") || !validRelative(name) || !expectedRoot || !["File", "Directory"].includes(entry.type) ||
@@ -648,7 +562,7 @@ async function inspectTar(path) {
                 problem ||= "The archive contains unsafe, duplicate or unsupported entries.";
                 return;
             }
-            if (name === "manifest.json" && (entry.type !== "File" || entry.size > MAX_METADATA_BYTES))
+            if ((name === "manifest.json" || name === "secrets.json") && (entry.type !== "File" || entry.size > MAX_METADATA_BYTES))
                 problem ||= "Invalid backup metadata file.";
             bytes += entry.size;
             if (bytes > MAX_WORKSPACE_BACKUP_BYTES + MAX_METADATA_BYTES)
@@ -670,7 +584,7 @@ async function inspectTar(path) {
 }
 function validateStaged(directory, expected) {
     const manifest = validateManifest(privateJson(join(directory, "manifest.json")));
-    if (expected && expected.size !== manifest.entries.length + 2)
+    if (expected && expected.size !== manifest.entries.length + (expected.has("secrets.json") ? 3 : 2))
         throw new Error("Archive entries do not match the backup manifest.");
     const declared = new Set(manifest.entries.map((entry) => entry.path));
     const inspect = (root, prefix = "") => {
@@ -704,14 +618,14 @@ function validateStaged(directory, expected) {
     const data = join(directory, "data");
     if (countJsonArray(join(data, "bots.json")) !== manifest.summary.bots || countJsonArray(join(data, "groups.json")) !== manifest.summary.groups)
         throw new Error("The backup roster does not match its summary.");
-    if (existsSync(join(data, "config.json"))) {
+    if (existsSync(join(data, "config.json")) && !manifest.summary.secrets) {
         const config = privateJson(join(data, "config.json"));
         if (JSON.stringify(config) !== JSON.stringify(portableWorkspaceConfig(config)))
             throw new Error("Workspace backup contains non-portable connection settings.");
     }
     if (existsSync(join(data, "webhooks.json"))) {
         const value = privateJson(join(data, "webhooks.json"));
-        if (!record(value) || Array.isArray(value.webhooks) && value.webhooks.some((webhook) => record(webhook) && Object.hasOwn(webhook, "secretHash")))
+        if (!record(value) || !manifest.summary.secrets && Array.isArray(value.webhooks) && value.webhooks.some((webhook) => record(webhook) && Object.hasOwn(webhook, "secretHash")))
             throw new Error("Workspace backup contains webhook credentials.");
     }
     const counts = databaseCounts(join(data, "messages.db"));
@@ -724,13 +638,30 @@ export async function stageWorkspaceBackup(dataDir, archivePath, options) {
     const plaintext = join(job.directory, "archive.tar");
     try {
         // No extraction, parser or metadata processing occurs until GCM final()
-        // authenticates the complete encrypted file.
-        await decryptArchive(archivePath, plaintext, options.password);
+        // authenticates the complete encrypted file (or its checksum matches).
+        options.onProgress?.({ phase: "checking" });
+        const { encrypted } = await readArchive(archivePath, plaintext, options.password);
         const expected = await inspectTar(plaintext);
         const staged = join(job.directory, "staged");
         folder(staged);
+        options.onProgress?.({ phase: "unpacking" });
         await tar.x({ file: plaintext, cwd: staged, strict: true, preservePaths: false, umask: 0o077, noChmod: true });
+        // The desktop secrets leave the staging tree at once; the caller holds
+        // them in memory until the person confirms the restore.
+        let secrets = null;
+        if (expected.has("secrets.json")) {
+            const value = privateJson(join(staged, "secrets.json"));
+            rmSync(join(staged, "secrets.json"));
+            if (!validSecretsBundle(value))
+                throw new Error("The backup's saved credentials are unreadable. Nothing was restored.");
+            secrets = value;
+        }
+        options.onProgress?.({ phase: "verifying" });
         const manifest = validateStaged(staged, expected);
+        // A plain file is only checksummed, so it can never claim to hold secrets;
+        // backups from before these fields existed were always encrypted.
+        if ((manifest.summary.encrypted ?? true) !== encrypted || (!!secrets && !manifest.summary.secrets))
+            throw new Error("This backup's contents do not match its encryption. Nothing was restored.");
         const versions = [manifest.summary.appVersion, options.currentAppVersion ?? ""].map((version) => /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version)?.slice(1).map(Number));
         if (versions[0] && versions[1]) {
             for (let i = 0; i < 3; i++) {
@@ -742,7 +673,7 @@ export async function stageWorkspaceBackup(dataDir, archivePath, options) {
         }
         rmSync(plaintext);
         writeJson(join(job.directory, "ready.json"), { id: job.id, summary: manifest.summary });
-        return { id: job.id, summary: manifest.summary };
+        return { id: job.id, summary: manifest.summary, secrets };
     }
     catch (error) {
         rmSync(job.directory, { recursive: true, force: true });
@@ -786,7 +717,7 @@ function readJournal(path) {
     if (!record(raw) || typeof raw.id !== "string" || !ID.test(raw.id) || !["applying", "committed", "rolled-back"].includes(String(raw.phase)))
         throw new Error("Invalid restore recovery journal. Original data was preserved; recovery needs attention.");
     for (const key of ["existing", "incoming"]) {
-        if (!Array.isArray(raw[key]) || !raw[key].every((name) => typeof name === "string" && validRelative(name) && !name.includes("/") && !preserved(name)) || new Set(raw[key]).size !== raw[key].length)
+        if (!Array.isArray(raw[key]) || !raw[key].every((name) => typeof name === "string" && validRelative(name) && !name.includes("/") && !preserved(name, raw.secrets === true)) || new Set(raw[key]).size !== raw[key].length)
             throw new Error("Invalid restore recovery paths.");
     }
     return raw;
@@ -823,38 +754,11 @@ function rollback(dataDir, journal) {
             rmSync(last);
     }
 }
-function rebasePath(value, source, destination) {
-    // Explicit old-root prefix, not a free-form text replacement. Normalize
-    // Windows separators without interpreting unrelated external paths.
-    const normalized = value.replaceAll("\\", "/");
-    const original = source.replaceAll("\\", "/").replace(/\/$/, "");
-    if (normalized !== original && !normalized.startsWith(`${original}/`))
-        return value;
-    const suffix = normalized.slice(original.length).replace(/^\//, "");
-    if (suffix && !validRelative(suffix))
-        return value;
-    return suffix ? join(destination, suffix) : destination;
-}
-const PATH_KEYS = new Set(["cwd", "pinnedCwd", "workspace", "configDir", "profileDirectory", "agentDir", "dataDir", "home", "cli", "path", "filePath", "localPath"]);
-function rebaseFields(value, source, destination) {
-    if (Array.isArray(value)) {
-        for (const item of value)
-            rebaseFields(item, source, destination);
-    }
-    else if (record(value)) {
-        for (const [key, item] of Object.entries(value)) {
-            if (PATH_KEYS.has(key) && typeof item === "string")
-                value[key] = rebasePath(item, source, destination);
-            else if (typeof item === "object")
-                rebaseFields(item, source, destination);
-        }
-    }
-}
-function rebaseMessage(message, source, destination) {
+function rebaseMessage(message, pairs) {
     if (!record(message))
         return;
     for (const field of ["attachments", "images", "fileAttachments", "file", "card"])
-        rebaseFields(message[field], source, destination);
+        rebaseFields(message[field], pairs);
     if (typeof message.text !== "string")
         return;
     // Only actual top-level attachment markup is rewritten. Quoted prose,
@@ -877,7 +781,7 @@ function rebaseMessage(message, source, destination) {
             continue;
         const next = node.value.replace(/(<attached-(?:image|file)[\t ]+path=")([^"\r\n]*)(")/g, (whole, before, encoded, after) => {
             const attachment = [...parsed.images, ...parsed.files].find((item) => escapeAttribute(item.path) === encoded);
-            return attachment ? `${before}${escapeAttribute(rebasePath(attachment.path, source, destination))}${after}` : whole;
+            return attachment ? `${before}${escapeAttribute(rebasePath(attachment.path, pairs))}${after}` : whole;
         });
         if (next !== node.value)
             edits.push({ from: node.position.start.offset, to: node.position.end.offset, text: next });
@@ -887,8 +791,14 @@ function rebaseMessage(message, source, destination) {
         next = next.slice(0, edit.from) + edit.text + next.slice(edit.to);
     message.text = next;
 }
+/** Old roots to new ones for this computer: data folder, then home folder. */
+function pathPairs(dataDir, manifest) {
+    return restorePathPairs({ dataDir: manifest.sourceDataDir, home: manifest.sourceHome }, { dataDir: resolve(dataDir), home: homedir() });
+}
 function prepareRestore(dataDir, id, manifest) {
     assertLocalAuthOutsideSnapshot(dataDir);
+    const pairs = pathPairs(dataDir, manifest);
+    const secrets = manifest.summary.secrets === true;
     const job = jobPath(dataDir, id);
     const prepared = join(job, "apply", "data");
     if (existsSync(join(job, "apply")))
@@ -906,6 +816,14 @@ function prepareRestore(dataDir, id, manifest) {
         if (entry.type === "file")
             copyRegular(join(job, "staged", "data", entry.path), destination);
     }
+    // Paths are judged against the copy being installed, as it will be.
+    const unresolved = { paths: new Set(), exists: (path) => {
+            const inside = relative(resolve(dataDir), path);
+            return inside && !inside.startsWith("..") && !isAbsolute(inside) ? entryExists(join(prepared, inside)) : existsSync(path);
+        } };
+    const skippedLinks = restoreLinks(prepared, dataDir, manifest.links ?? [], pairs, unresolved.paths);
+    if (pairs.length)
+        rebaseTree(prepared, pairs);
     const changeJson = (name, change) => {
         const path = join(prepared, name);
         if (!existsSync(path))
@@ -914,8 +832,8 @@ function prepareRestore(dataDir, id, manifest) {
         change(value);
         writeJson(path, value);
     };
-    for (const name of ["bots.json", "groups.json", "config.json", "routines.json", "calendar-calls.json"]) {
-        changeJson(name, (value) => rebaseFields(value, manifest.sourceDataDir, resolve(dataDir)));
+    for (const name of ["bots.json", "groups.json", "routines.json", "calendar-calls.json"]) {
+        changeJson(name, (value) => rebaseFields(value, pairs, unresolved));
     }
     // Voice provider configuration and credentials deliberately stay with the
     // destination installation. Imported per-agent ids belong to the source
@@ -928,13 +846,23 @@ function prepareRestore(dataDir, id, manifest) {
             if (record(bot))
                 delete bot.voice;
     });
-    // Never install source connection settings. Destination keys, endpoints,
-    // driver environments and MCP configuration remain paired and unchanged.
+    // Without secrets, never install source connection settings: destination
+    // keys, endpoints, driver environments and MCP configuration stay paired.
+    // A secrets backup is a clone and brings its own, with every path rebased.
     const oldConfig = join(dataDir, "config.json");
     const newConfig = join(prepared, "config.json");
-    if (existsSync(oldConfig) || existsSync(newConfig)) {
+    if (!secrets && (existsSync(oldConfig) || existsSync(newConfig))) {
         writeJson(newConfig, restoredWorkspaceConfig(existsSync(newConfig) ? privateJson(newConfig) : {}, existsSync(oldConfig) ? privateJson(oldConfig) : {}));
     }
+    changeJson("config.json", (value) => rebaseFields(value, pairs, unresolved));
+    // The native vault's key is sealed to this computer; the desktop replaces
+    // it with the backup's own key once the restored files are in place.
+    const vaultKey = join(dataDir, "providers", "native-vault", "key.bin");
+    if (secrets && entryExists(vaultKey)) {
+        // The restored providers folder replaces this one; this computer's sealed key stays.
+        folder(join(prepared, "providers", "native-vault"));
+        copyFileSync(vaultKey, join(prepared, "providers", "native-vault", "key.bin"));
+    }
     // Browser authentication lives alongside ordinary VM files. Copy only the
     // destination's excluded subtrees into the install copy, never the archive.
     // They then participate in the same top-level swap and crash rollback.
@@ -988,6 +916,8 @@ function prepareRestore(dataDir, id, manifest) {
                     webhook.enabled = false;
                     webhook.verificationPending = false;
                     const previous = oldHooks.find((old) => record(old) && old.id === webhook.id && old.endpointId === webhook.endpointId);
+                    if (secrets && typeof webhook.secretHash === "string" && /^[a-f0-9]{64}$/.test(webhook.secretHash))
+                        continue;
                     // Unknown random hashes cannot authenticate a caller. A migrated hook
                     // needs an explicit secret rotation before it can receive anything.
                     webhook.secretHash = record(previous) && typeof previous.secretHash === "string" && /^[a-f0-9]{64}$/.test(previous.secretHash) ? previous.secretHash : randomBytes(32).toString("hex");
@@ -1010,10 +940,10 @@ function prepareRestore(dataDir, id, manifest) {
             changeJson(entry.path, (value) => {
                 if (Array.isArray(value))
                     for (const message of value)
-                        rebaseMessage(message, manifest.sourceDataDir, resolve(dataDir));
+                        rebaseMessage(message, pairs);
                 else if (record(value) && Array.isArray(value.messages))
                     for (const message of value.messages)
-                        rebaseMessage(message, manifest.sourceDataDir, resolve(dataDir));
+                        rebaseMessage(message, pairs);
             });
     }
     const dbPath = join(prepared, "messages.db");
@@ -1021,11 +951,11 @@ function prepareRestore(dataDir, id, manifest) {
         const db = new DatabaseSync(dbPath);
         try {
             db.exec("BEGIN");
-            if (manifest.sourceDataDir !== resolve(dataDir)) {
+            if (pairs.length) {
                 const update = db.prepare("UPDATE messages SET json = ?, text = ? WHERE thread_id = ? AND id = ?");
                 for (const row of db.prepare("SELECT thread_id, id, json FROM messages").iterate()) {
                     const message = JSON.parse(String(row.json));
-                    rebaseMessage(message, manifest.sourceDataDir, resolve(dataDir));
+                    rebaseMessage(message, pairs);
                     const json = JSON.stringify(message);
                     if (json !== row.json)
                         update.run(json, record(message) && typeof message.text === "string" ? message.text : null, row.thread_id, row.id);
@@ -1038,7 +968,7 @@ function prepareRestore(dataDir, id, manifest) {
                 const pause = db.prepare("UPDATE chat_followups SET status = 'interrupted', payload = ? WHERE id = ?");
                 for (const row of db.prepare("SELECT id, payload FROM chat_followups WHERE status IN ('pending', 'dispatching', 'interrupted')").iterate()) {
                     const payload = JSON.parse(String(row.payload));
-                    rebaseMessage(payload, manifest.sourceDataDir, resolve(dataDir));
+                    rebaseMessage(payload, pairs);
                     if (record(payload))
                         delete payload.prompt;
                     pause.run(JSON.stringify(payload), row.id);
@@ -1050,6 +980,8 @@ function prepareRestore(dataDir, id, manifest) {
             db.close();
         }
     }
+    // finishRestore puts these on the receipt Settings shows after restart.
+    writeJson(join(job, "unresolved.json"), [...unresolved.paths, ...skippedLinks.map((path) => join(resolve(dataDir), path))].slice(0, MAX_REPORTED_PATHS));
     return prepared;
 }
 export function readLastWorkspaceRestore(dataDir) {
@@ -1070,12 +1002,15 @@ function finishRestore(dataDir, id, consumePending = true) {
         try {
             const value = JSON.parse(draftAttachments);
             const manifest = validateManifest(privateJson(join(jobPath(dataDir, id), "staged", "manifest.json")));
-            rebaseFields(value, manifest.sourceDataDir, resolve(dataDir));
+            rebaseFields(value, pathPairs(dataDir, manifest));
             clientState["omb-draft-attachments"] = JSON.stringify(value);
         }
         catch { /* A malformed client draft must not jeopardize durable server data. */ }
     }
-    const result = { restored: true, id, safetyCopyPath: join(root, `safety-${id}`), summary, clientState };
+    const unresolvedFile = join(jobPath(dataDir, id), "unresolved.json");
+    const listed = existsSync(unresolvedFile) ? privateJson(unresolvedFile) : [];
+    const unresolvedPaths = Array.isArray(listed) ? listed.filter((path) => typeof path === "string") : [];
+    const result = { restored: true, id, safetyCopyPath: join(root, `safety-${id}`), summary, clientState, unresolvedPaths };
     writeJson(join(root, "last-restore.json"), result);
     if (consumePending)
         rmSync(join(root, "pending-restore.json"), { force: true });
@@ -1113,15 +1048,16 @@ export function applyPendingWorkspaceRestore(dataDir) {
     if (existsSync(safetyCopyPath))
         throw new Error("A safety copy already exists for this restore. Original files have not been changed.");
     folder(join(safetyCopyPath, "data"));
+    const secrets = manifest.summary.secrets === true;
     const journal = {
         id: pending.id, phase: "applying",
-        existing: readdirSync(dataDir).filter((name) => !preserved(name)).sort(),
-        incoming: readdirSync(prepared).sort(),
+        existing: readdirSync(dataDir).filter((name) => !preserved(name, secrets)).sort(),
+        incoming: readdirSync(prepared).sort(), secrets,
     };
     // Top-level source and destination names are checked before recording any
     // move; a restored root never traverses an archive-controlled directory.
     for (const name of [...journal.existing, ...journal.incoming]) {
-        if (!validRelative(name) || name.includes("/") || preserved(name))
+        if (!validRelative(name) || name.includes("/") || preserved(name, secrets))
             throw new Error("Unsafe workspace restore target.");
     }
     writeJson(join(safetyCopyPath, "manifest.json"), { id: pending.id, createdAt: new Date().toISOString(), originalEntries: journal.existing });