jishushell 0.4.2-beta2 → 0.4.10

package/dist/services/backup-manager.js

@@ -0,0 +1,2014 @@
+import { execFileSync, spawn as spawnChild } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { posix as pathPosix } from "path";
+import { BACKUPS_DIR, INSTANCES_DIR, TMP_DIR } from "../config.js";
+/**
+ * Encode an absolute filesystem path for use inside backup archives.
+ * Ported from OpenClaw official: encodeAbsolutePathForBackupArchive.
+ */
+export function encodeAbsolutePathForArchive(sourcePath) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const windowsMatch = normalized.match(/^([A-Za-z]):\/(.*)$/);
+    if (windowsMatch) {
+        const drive = (windowsMatch[1] ?? "UNKNOWN").toUpperCase();
+        const rest = windowsMatch[2] ?? "";
+        return pathPosix.join("windows", drive, rest);
+    }
+    if (normalized.startsWith("/"))
+        return pathPosix.join("posix", normalized.slice(1));
+    return pathPosix.join("relative", normalized);
+}
+/**
+ * Try to create a backup by calling the official `openclaw backup create` CLI.
+ * Returns ok:false if the binary is missing or the command fails.
+ */
+export async function callOpenclawBackup(instanceId, outputDir, opts) {
+    const { getResolvedOpenclawBin, getOpenclawHome } = await import("./instance-manager.js");
+    const openclawBin = getResolvedOpenclawBin();
+    const openclawHome = getOpenclawHome(instanceId);
+    if (!existsSync(openclawBin)) {
+        return { ok: false, error: `openclaw binary not found: ${openclawBin}` };
+    }
+    if (!existsSync(outputDir))
+        mkdirSync(outputDir, { recursive: true });
+    // Snapshot existing .tar.gz files so we can identify what the CLI actually
+    // produced, instead of "newest tarball in dir" — which mis-picks any
+    // unrelated pre-existing archive (e.g. a stale auto-backup from earlier).
+    const preExisting = new Set(readdirSync(outputDir).filter(f => f.endsWith(".tar.gz")));
+    const args = ["backup", "create", "--output", outputDir];
+    if (opts.onlyConfig)
+        args.push("--only-config");
+    if (opts.noWorkspace)
+        args.push("--no-include-workspace");
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawnChild(openclawBin, args, {
+                env: { ...process.env, OPENCLAW_HOME: openclawHome },
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 120_000,
+            });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+            child.on("close", (code) => {
+                if (code !== 0)
+                    reject(new Error(`openclaw backup create exited ${code}: ${stderr.slice(0, 500)}`));
+                else
+                    resolve();
+            });
+            child.on("error", (err) => reject(err));
+        });
+        // Pick up only entries created by THIS CLI run. If the CLI happens to
+        // produce more than one archive (it currently produces exactly one),
+        // take the newest by mtime.
+        const newFiles = readdirSync(outputDir)
+            .filter(f => f.endsWith(".tar.gz") && !preExisting.has(f))
+            .map(f => ({ name: f, mtime: statSync(join(outputDir, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        if (newFiles.length === 0) {
+            return { ok: false, error: "openclaw backup create produced no new .tar.gz file" };
+        }
+        return { ok: true, archivePath: join(outputDir, newFiles[0].name) };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+// ── Directory initialization ──
+/** Ensure backup and tmp directories exist */
+export function ensureBackupDirs() {
+    for (const dir of [BACKUPS_DIR, TMP_DIR]) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o755 });
+    }
+}
+// ── Tmp file management ──
+const TMP_MAX_AGE_MS = 30 * 60 * 1000; // 30 minutes
+const EXPORTS_SUBDIR = "exports";
+/**
+ * Get the per-instance export output directory (TMP_DIR/exports/<id>/).
+ * Exports live in an isolated subdirectory so the download route can enforce
+ * `:id` → file ownership and one instance's URL can't reach another's archive.
+ */
+export function getInstanceExportDir(instanceId) {
+    const dir = join(TMP_DIR, EXPORTS_SUBDIR, instanceId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o755 });
+    return dir;
+}
+/** Clean up stale tmp files older than 30 minutes. Call on startup and periodically. */
+export function cleanupStaleTmpFiles() {
+    if (!existsSync(TMP_DIR))
+        return 0;
+    let cleaned = 0;
+    const now = Date.now();
+    for (const entry of readdirSync(TMP_DIR)) {
+        const fullPath = join(TMP_DIR, entry);
+        // Exports live in per-instance subdirs; sweep them one file at a time so
+        // we don't wipe an active export collection because of a stale sibling.
+        if (entry === EXPORTS_SUBDIR) {
+            try {
+                for (const instanceEntry of readdirSync(fullPath)) {
+                    const instanceDir = join(fullPath, instanceEntry);
+                    try {
+                        if (!statSync(instanceDir).isDirectory())
+                            continue;
+                        for (const fileEntry of readdirSync(instanceDir)) {
+                            const filePath = join(instanceDir, fileEntry);
+                            try {
+                                const stat = statSync(filePath);
+                                if (now - stat.mtimeMs > TMP_MAX_AGE_MS) {
+                                    rmSync(filePath, { recursive: true, force: true });
+                                    cleaned++;
+                                    console.log(`[backup] Cleaned stale export: ${instanceEntry}/${fileEntry}`);
+                                }
+                            }
+                            catch { /* skip */ }
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            catch { /* skip */ }
+            continue;
+        }
+        try {
+            const stat = statSync(fullPath);
+            if (now - stat.mtimeMs > TMP_MAX_AGE_MS) {
+                rmSync(fullPath, { recursive: true, force: true });
+                cleaned++;
+                console.log(`[backup] Cleaned stale tmp: ${entry}`);
+            }
+        }
+        catch {
+            // Skip entries that disappeared during iteration
+        }
+    }
+    return cleaned;
+}
+// ── Tmp cleanup scheduler ──
+let cleanupTimer = null;
+const CLEANUP_INTERVAL_MS = 10 * 60 * 1000; // Check every 10 minutes
+/** Start periodic tmp cleanup. Call once at server startup. */
+export function startTmpCleanupScheduler() {
+    // Run immediately on startup
+    ensureBackupDirs();
+    cleanupStaleTmpFiles();
+    // Schedule periodic cleanup
+    if (cleanupTimer)
+        clearInterval(cleanupTimer);
+    cleanupTimer = setInterval(() => {
+        cleanupStaleTmpFiles();
+    }, CLEANUP_INTERVAL_MS);
+    // Don't prevent process exit
+    if (cleanupTimer.unref)
+        cleanupTimer.unref();
+}
+/** Stop the cleanup scheduler (for graceful shutdown). */
+export function stopTmpCleanupScheduler() {
+    if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+    }
+}
+// ── Backup directory helpers ──
+/** Get the backup directory for an instance (creates if needed) */
+export function getInstanceBackupDir(instanceId) {
+    const dir = join(BACKUPS_DIR, instanceId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o755 });
+    return dir;
+}
+/** List all backup files for an instance, sorted by mtime descending (newest first) */
+export function listInstanceBackups(instanceId) {
+    const dir = join(BACKUPS_DIR, instanceId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith(".tar.gz"))
+        .map(filename => {
+        const stat = statSync(join(dir, filename));
+        let type = "manual-backup";
+        if (filename.startsWith("auto-backup"))
+            type = "auto-backup";
+        else if (filename.startsWith("pre-restore"))
+            type = "pre-restore";
+        return {
+            filename,
+            size: stat.size,
+            created_at: stat.mtime.toISOString(),
+            type,
+        };
+    })
+        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+}
+/** List all instance IDs that have backups (including orphans) */
+export function listAllBackupInstanceIds() {
+    if (!existsSync(BACKUPS_DIR))
+        return [];
+    return readdirSync(BACKUPS_DIR).filter(entry => {
+        const dir = join(BACKUPS_DIR, entry);
+        try {
+            return statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+const instanceLocks = new Map();
+const HEARTBEAT_STALE_MS = 2 * 60 * 1000; // 2 minutes without heartbeat = stale
+/** Acquire an exclusive lock for an instance. Returns false if already locked. */
+export function acquireInstanceLock(instanceId, operation) {
+    const existing = instanceLocks.get(instanceId);
+    if (existing) {
+        if (Date.now() - existing.lastHeartbeat > HEARTBEAT_STALE_MS) {
+            console.warn(`[backup] Force-releasing stale lock for ${instanceId} (op: ${existing.operation}, age: ${Math.round((Date.now() - existing.since) / 1000)}s)`);
+            instanceLocks.delete(instanceId);
+        }
+        else {
+            return false;
+        }
+    }
+    instanceLocks.set(instanceId, { operation, since: Date.now(), lastHeartbeat: Date.now() });
+    return true;
+}
+/** Update heartbeat for a held lock. Call periodically during long operations. */
+export function touchInstanceLock(instanceId) {
+    const lock = instanceLocks.get(instanceId);
+    if (lock)
+        lock.lastHeartbeat = Date.now();
+}
+/** Release the lock for an instance. */
+export function releaseInstanceLock(instanceId) {
+    instanceLocks.delete(instanceId);
+}
+/** Get current lock status for an instance (for status API). */
+export function getInstanceLockStatus(instanceId) {
+    const lock = instanceLocks.get(instanceId);
+    if (!lock)
+        return null;
+    if (Date.now() - lock.lastHeartbeat > HEARTBEAT_STALE_MS) {
+        instanceLocks.delete(instanceId);
+        return null;
+    }
+    return { locked: true, operation: lock.operation };
+}
+/** Start a heartbeat interval for long operations. Returns a cleanup function. */
+export function startLockHeartbeat(instanceId, intervalMs = 15_000) {
+    const timer = setInterval(() => touchInstanceLock(instanceId), intervalMs);
+    return () => clearInterval(timer);
+}
+/** Check if instance is locked. Throws with 409 status if locked. */
+export function assertNotLocked(instanceId) {
+    const lock = getInstanceLockStatus(instanceId);
+    if (lock?.locked) {
+        const err = new Error(`Instance ${instanceId} is locked: ${lock.operation}`);
+        err.statusCode = 409;
+        throw err;
+    }
+}
+// ── Tar variant detection ──
+let _tarVariant = null;
+/** Detect whether system tar is GNU or BSD. Cached after first call. */
+export function detectTarVariant() {
+    if (_tarVariant)
+        return _tarVariant;
+    try {
+        const output = execFileSync("tar", ["--version"], { encoding: "utf-8", timeout: 5000 });
+        _tarVariant = output.includes("GNU tar") ? "gnu" : "bsd";
+    }
+    catch {
+        // BSD tar may not support --version, or tar may not exist
+        try {
+            execFileSync("tar", ["--help"], { encoding: "utf-8", timeout: 5000 });
+            _tarVariant = "bsd";
+        }
+        catch {
+            throw new Error("tar command not found. Please install tar.");
+        }
+    }
+    console.log(`[backup] Detected tar variant: ${_tarVariant}`);
+    return _tarVariant;
+}
+// ── Secure extraction ──
+const MAX_UNCOMPRESSED_SIZE = 2 * 1024 * 1024 * 1024; // 2GB
+/** Parse tar -tvzf output into structured entries */
+function parseTarVerboseOutput(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        if (!line.trim())
+            continue;
+        // Format: -rw-r--r-- user/group   12345 2026-04-08 10:00 path/to/file
+        // Or:     lrwxrwxrwx user/group       0 2026-04-08 10:00 link -> target
+        // Or:     drwxr-xr-x user/group       0 2026-04-08 10:00 dir/
+        const perms = line.charAt(0);
+        let type = "-";
+        if (perms === "l")
+            type = "l"; // symlink
+        else if (perms === "h")
+            type = "h"; // hardlink
+        else if (perms === "d")
+            type = "d"; // directory
+        // Parse size (field after user/group)
+        const parts = line.split(/\s+/);
+        // parts: [perms, user/group, size, date, time, path...]
+        const size = parseInt(parts[2], 10) || 0;
+        // Path is everything after the time field
+        // Find the path by looking for the portion after date+time
+        const pathMatch = line.match(/\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\s+(.+)/);
+        const path = pathMatch ? pathMatch[1].replace(/ -> .+$/, "").trim() : parts.slice(5).join(" ");
+        // Also detect symlinks from " -> " in the path
+        if (line.includes(" -> ") && type !== "l")
+            type = "l";
+        entries.push({ type, size, path });
+    }
+    return entries;
+}
+/**
+ * Pre-scan a tar.gz archive for security threats.
+ * Throws on: path traversal, symlinks, hardlinks, absolute paths, oversized.
+ */
+export function preScanArchive(archivePath) {
+    detectTarVariant(); // Ensure tar exists
+    const output = execFileSync("tar", ["-tvzf", archivePath], {
+        encoding: "utf-8",
+        timeout: 60_000, // 60s timeout for large archives
+        maxBuffer: 50 * 1024 * 1024, // 50MB buffer for listing
+    });
+    const entries = parseTarVerboseOutput(output);
+    let totalSize = 0;
+    for (const entry of entries) {
+        // Symlinks are allowed — npm packages routinely contain
+        // node_modules/.bin/ symlinks pointing at sibling paths within the
+        // archive. The post-extract walk (verifyNoEscapes) will reject any
+        // symlink whose real target resolves outside the extraction directory.
+        // We only hard-ban hardlinks here because they can reference files
+        // by inode in ways that bypass the extraction root without a
+        // resolvable path.
+        // Reject hardlinks
+        if (entry.type === "h") {
+            throw new Error(`Archive contains hardlink: ${entry.path}`);
+        }
+        // Reject path traversal
+        if (entry.path.includes("../") || entry.path.includes("..\\")) {
+            throw new Error(`Archive contains path traversal: ${entry.path}`);
+        }
+        // Reject absolute paths
+        if (entry.path.startsWith("/")) {
+            throw new Error(`Archive contains absolute path: ${entry.path}`);
+        }
+        // Accumulate size
+        totalSize += entry.size;
+        if (totalSize > MAX_UNCOMPRESSED_SIZE) {
+            throw new Error(`Archive uncompressed size exceeds 2GB limit (${Math.round(totalSize / 1024 / 1024)}MB)`);
+        }
+    }
+    return { entries, totalSize };
+}
+/**
+ * Safely extract a tar.gz archive to destDir.
+ * Pre-scans for security threats, then extracts with safety flags.
+ */
+export async function safeExtract(archivePath, destDir) {
+    // Step 1: Pre-scan
+    const scanResult = preScanArchive(archivePath);
+    // Step 2: Ensure dest directory exists
+    if (!existsSync(destDir))
+        mkdirSync(destDir, { recursive: true });
+    // Step 3: Build extract args based on tar variant
+    const variant = detectTarVariant();
+    const args = ["-xzf", archivePath, "-C", destDir, "--no-same-owner"];
+    if (variant === "gnu") {
+        args.push("--no-same-permissions");
+    }
+    // Step 4: Extract via spawn (non-blocking)
+    await new Promise((resolve, reject) => {
+        const child = spawnChild("tar", args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`tar extract failed (exit ${code}): ${stderr.slice(0, 500)}`));
+            }
+            else {
+                resolve();
+            }
+        });
+        child.on("error", reject);
+    });
+    // Step 5: Post-extract verification — ensure no entry's real path
+    // escapes the extraction directory.
+    //
+    // Symlinks get special-cased: we treat them as opaque blobs that will
+    // never be followed by downstream cpSync calls (those pass
+    // verbatimSymlinks: true). That eliminates the "symlink-to-/etc/passwd
+    // then write through it" attack surface, which means a symlink's
+    // target doesn't need to resolve at all for the archive to be safe.
+    // This matters because real archives routinely contain:
+    //   - npm node_modules/.bin/* pointing at siblings by relative path
+    //   - docker-originated absolute paths like `/app/...` that are
+    //     intentionally dangling on the host but valid inside a container
+    // Escape detection still runs for non-symlink entries via realpathSync.
+    const destDirReal = realpathSync(destDir);
+    function verifyNoEscapes(dir) {
+        for (const entry of readdirSync(dir)) {
+            const fullPath = join(dir, entry);
+            const stat = lstatSync(fullPath);
+            if (stat.isSymbolicLink()) {
+                // Opaque blob — skip real-path check and do not recurse.
+                continue;
+            }
+            // Regular files/dirs: realpath is defined. If anything resolves
+            // outside destDir, it's an escape attempt that slipped past the
+            // pre-scan (e.g. via hardlink creativity).
+            const real = realpathSync(fullPath);
+            if (!real.startsWith(destDirReal + "/") && real !== destDirReal) {
+                throw new Error(`Extracted entry escaped target directory: ${fullPath} -> ${real}`);
+            }
+            if (stat.isDirectory()) {
+                verifyNoEscapes(fullPath);
+            }
+        }
+    }
+    verifyNoEscapes(destDir);
+    return scanResult;
+}
+// ── Pack / backup helpers ──
+/** Calculate SHA-256 checksum of files in a directory, sorted by relative path */
+function calculateContentChecksum(baseDir, files) {
+    const hash = createHash("sha256");
+    const sorted = [...files].sort();
+    for (const f of sorted) {
+        const fullPath = join(baseDir, f);
+        // Use lstat so we never follow a symlink during hashing; `files` is
+        // built by collectFiles which already excludes symlinks, but be
+        // defensive in case another caller passes a symlinked entry.
+        let stat;
+        try {
+            stat = lstatSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isFile()) {
+            hash.update(readFileSync(fullPath));
+        }
+    }
+    return hash.digest("hex");
+}
+/**
+ * Best-effort libc detection. Returns "glibc", "musl", "unknown", or "n/a" for non-Linux.
+ */
+function detectLibc() {
+    if (process.platform !== "linux")
+        return "n/a";
+    try {
+        const output = execFileSync("ldd", ["--version"], { encoding: "utf-8", timeout: 2000 }).toString();
+        if (/musl/i.test(output))
+            return "musl";
+        if (/glibc|GNU libc/i.test(output))
+            return "glibc";
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Copy a directory tree preserving symlinks as-is, without ever following
+ * them. Uses lstat exclusively so dangling / absolute-path symlinks (e.g.
+ * `app/openclaw.mjs -> /app/...` from a docker-cp'd container tree) do not
+ * crash the copy with ENOENT.
+ *
+ * `filter(rel)` returns false to skip the entry; for directories, returning
+ * false also skips the entire subtree. `rel` is the source-relative path
+ * using forward slashes.
+ *
+ * Used instead of `fs.cpSync` because Node's cpSync internally calls
+ * `stat` (not `lstat`) during bookkeeping, which follows symlinks and
+ * fails on broken targets even with `verbatimSymlinks: true`.
+ */
+function copyTreeLstat(src, dst, filter, baseRel = "") {
+    // Create the destination directory itself (no-op if it exists).
+    if (!existsSync(dst))
+        mkdirSync(dst, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        const rel = baseRel ? `${baseRel}/${entry}` : entry;
+        if (!filter(rel, entry))
+            continue;
+        let stat;
+        try {
+            stat = lstatSync(srcPath);
+        }
+        catch {
+            continue;
+        }
+        const dstPath = join(dst, entry);
+        if (stat.isSymbolicLink()) {
+            // Preserve the link target verbatim — never read through it.
+            try {
+                const target = readlinkSync(srcPath);
+                try {
+                    rmSync(dstPath, { force: true });
+                }
+                catch { /* ignore */ }
+                symlinkSync(target, dstPath);
+            }
+            catch { /* best effort — skip unreadable symlinks */ }
+        }
+        else if (stat.isDirectory()) {
+            copyTreeLstat(srcPath, dstPath, filter, rel);
+        }
+        else if (stat.isFile()) {
+            try {
+                copyFileSync(srcPath, dstPath);
+            }
+            catch { /* best effort */ }
+        }
+        // Special files (sockets, devices, fifos) are silently skipped — they
+        // don't belong in a backup archive.
+    }
+}
+/**
+ * Recursively collect all regular files under a directory.
+ *
+ * Uses `lstat` so symlinks are identified as symlinks (not followed) — we
+ * intentionally skip them so dangling/absolute symlinks (like
+ * `app/openclaw.mjs -> /app/...` from a docker-cp'd tree) don't blow up
+ * checksum calculation with ENOENT. Symlinks are preserved in the tar
+ * archive by the packing step; they simply don't contribute file bytes
+ * to the content checksum.
+ */
+function collectFiles(dir, baseDir, excludes) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    for (const entry of readdirSync(dir)) {
+        const fullPath = join(dir, entry);
+        const relPath = fullPath.slice(baseDir.length + 1); // relative to baseDir
+        // Check exclusions
+        if (excludes.some(ex => relPath.startsWith(ex) || relPath.endsWith(ex)))
+            continue;
+        let stat;
+        try {
+            stat = lstatSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue; // skip; don't follow
+        if (stat.isDirectory()) {
+            results.push(...collectFiles(fullPath, baseDir, excludes));
+        }
+        else if (stat.isFile()) {
+            results.push(relPath);
+        }
+    }
+    return results;
+}
+/** Create a manual or auto backup of an instance */
+export async function backupInstance(instanceId, opts = {}) {
+    const backupDir = getInstanceBackupDir(instanceId);
+    const type = opts.type || "manual-backup";
+    // Auto-backup is always state-scope (small, frequent).
+    // Manual backup defaults to home-scope (full disaster recovery).
+    const scope = type === "auto-backup" ? "state" : (opts.scope ?? "home");
+    // Workspace is included by default; callers can pass `includeWorkspace: false`
+    // to drop it. `onlyConfig` implies no workspace (it's a config-only subset).
+    const includeWorkspace = opts.onlyConfig ? false : (opts.includeWorkspace ?? true);
+    // Only state scope can use the official CLI; home scope must self-pack.
+    if (scope === "state") {
+        const cliResult = await callOpenclawBackup(instanceId, backupDir, {
+            onlyConfig: opts.onlyConfig,
+            noWorkspace: !includeWorkspace,
+        });
+        if (cliResult.ok && cliResult.archivePath) {
+            // Rename the CLI's output to JishuShell's canonical
+            // "<type>-<timestamp>.tar.gz" pattern. Both listInstanceBackups()
+            // (filename-prefix classification) and cleanOldAutoBackups() (prefix-
+            // based rolling deletion) depend on this convention. Without it, an
+            // auto-backup created by the official CLI — whose naming is not under
+            // our control — would be misclassified as "manual-backup" AND would
+            // never be rolled out of the backups directory, causing unbounded growth.
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "").replace("T", "-").slice(0, 19);
+            const canonicalName = `${type}-${timestamp}.tar.gz`;
+            const canonicalPath = join(backupDir, canonicalName);
+            let finalArchivePath = cliResult.archivePath;
+            if (canonicalPath !== cliResult.archivePath) {
+                try {
+                    // rename may fail if the canonical path already exists (extremely
+                    // unlikely at second-precision timestamp, but guard anyway).
+                    if (existsSync(canonicalPath))
+                        rmSync(canonicalPath, { force: true });
+                    renameSync(cliResult.archivePath, canonicalPath);
+                    finalArchivePath = canonicalPath;
+                }
+                catch (e) {
+                    console.warn(`[backup] Failed to rename CLI output ${cliResult.archivePath} -> ${canonicalPath}: ${e.message}. ` +
+                        `File will be kept under its original name; it will be listed as "manual-backup" and will NOT be auto-rotated.`);
+                }
+            }
+            // Official CLI produced the archive — read its manifest for return value
+            const tmpDir = join(TMP_DIR, `manifest-read-${Date.now()}`);
+            try {
+                mkdirSync(tmpDir, { recursive: true });
+                // Full extract (state-scope archives are small) so resolveArchiveRoot
+                // can locate manifest.json regardless of whether the CLI wrapped it
+                // inside a <basename>/ top-level directory.
+                try {
+                    execFileSync("tar", ["-xzf", finalArchivePath, "-C", tmpDir], { timeout: 30_000 });
+                }
+                catch { /* extraction may fail, continue with defaults */ }
+                const archiveRoot = resolveArchiveRoot(tmpDir);
+                const manifestPath = join(archiveRoot, "manifest.json");
+                const manifest = existsSync(manifestPath)
+                    ? JSON.parse(readFileSync(manifestPath, "utf-8"))
+                    : { schemaVersion: 1, type };
+                // Ensure scope + type fields match what JishuShell asked for (official
+                // CLI doesn't know about our scope enum and may not write type).
+                if (!manifest.scope)
+                    manifest.scope = "state";
+                if (!manifest.type)
+                    manifest.type = type;
+                const size = statSync(finalArchivePath).size;
+                return {
+                    filename: finalArchivePath.split("/").pop(),
+                    filepath: finalArchivePath,
+                    size,
+                    manifest,
+                };
+            }
+            finally {
+                rmSync(tmpDir, { recursive: true, force: true });
+            }
+        }
+        console.log(`[backup] Official CLI unavailable (${cliResult.error}), using self-pack fallback`);
+    }
+    // Self-pack path: used for home scope always, or as fallback for state scope
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "").replace("T", "-").slice(0, 19);
+    const filename = `${type}-${timestamp}.tar.gz`;
+    const outputPath = opts.outputPath || join(backupDir, filename);
+    return selfPackOfficialFormat(instanceId, outputPath, {
+        type,
+        scope,
+        includeSessions: opts.includeSessions,
+        includeWorkspace,
+        onlyConfig: opts.onlyConfig,
+    });
+}
+/**
+ * Pack an instance in the official OpenClaw backup archive format.
+ * Layout: manifest.json at root + payload/<encoded-path>/.openclaw/...
+ * This is the fallback when `openclaw backup create` CLI is unavailable.
+ */
+export async function selfPackOfficialFormat(instanceId, outputPath, opts) {
+    const { getInstance, getOpenclawHome } = await import("./instance-manager.js");
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Instance ${instanceId} not found`);
+    const openclawHome = getOpenclawHome(instanceId);
+    const stateDir = join(openclawHome, ".openclaw");
+    if (!existsSync(stateDir))
+        throw new Error(`State directory not found: ${stateDir}`);
+    const scope = opts.scope ?? "state";
+    const encodedPath = encodeAbsolutePathForArchive(openclawHome);
+    const stagingDir = join(TMP_DIR, `selfpack-${instanceId}-${Date.now()}`);
+    const stagingHomeDir = join(stagingDir, "payload", encodedPath);
+    const payloadStateDir = join(stagingHomeDir, ".openclaw");
+    try {
+        if (scope === "home") {
+            // Home scope: pack entire openclaw-home/ tree minus cache dirs
+            mkdirSync(stagingHomeDir, { recursive: true });
+            const homeTopLevelExcludes = [
+                ".npm/_cacache",
+                ".npm/_logs",
+                ".npm/_npx",
+                ".npm/_update-notifier-last-checked",
+                ".cache",
+                ".node_compile_cache",
+            ];
+            const stateSubExcludes = [
+                ".npm",
+                ".cache",
+                ".node_compile_cache",
+                "workspace/.npm-global",
+            ];
+            const sessionExcludes = opts.includeSessions ? [] : ["agents/main/sessions"];
+            const workspaceExcludes = opts.includeWorkspace === false ? ["workspace"] : [];
+            if (opts.onlyConfig) {
+                // Only include openclaw.json inside .openclaw/
+                mkdirSync(payloadStateDir, { recursive: true });
+                const configSrc = join(stateDir, "openclaw.json");
+                if (existsSync(configSrc)) {
+                    copyFileSync(configSrc, join(payloadStateDir, "openclaw.json"));
+                }
+            }
+            else {
+                // Use copyTreeLstat so we never follow symlinks (even dangling
+                // ones like `app/openclaw.mjs -> /app/...` from a docker-cp'd
+                // container tree). fs.cpSync cannot be used here: even with
+                // verbatimSymlinks: true, its internal bookkeeping calls `stat`
+                // on dest entries which follows broken links and crashes with
+                // ENOENT on the first dangling symlink.
+                copyTreeLstat(openclawHome, stagingHomeDir, (rel) => {
+                    if (!rel)
+                        return true;
+                    if (homeTopLevelExcludes.some(ex => rel === ex || rel.startsWith(ex + "/")))
+                        return false;
+                    if (rel.startsWith(".npm-global/") && rel.includes("/.cache/"))
+                        return false;
+                    if (rel === ".openclaw" || rel.startsWith(".openclaw/")) {
+                        const stateRel = rel === ".openclaw" ? "" : rel.slice(".openclaw/".length);
+                        if (!stateRel)
+                            return true;
+                        if (stateSubExcludes.some(ex => stateRel === ex || stateRel.startsWith(ex + "/")))
+                            return false;
+                        if (sessionExcludes.some(ex => stateRel === ex || stateRel.startsWith(ex + "/")))
+                            return false;
+                        if (workspaceExcludes.some(ex => stateRel === ex || stateRel.startsWith(ex + "/")))
+                            return false;
+                    }
+                    return true;
+                });
+            }
+        }
+        else {
+            // State scope (default): only .openclaw/ contents
+            mkdirSync(payloadStateDir, { recursive: true });
+            // Build exclusion list
+            const excludes = [
+                ".npm/",
+                ".cache/",
+                ".node_compile_cache/",
+                "workspace/.npm-global/",
+            ];
+            if (!opts.includeSessions)
+                excludes.push("agents/main/sessions/");
+            if (opts.includeWorkspace === false)
+                excludes.push("workspace/");
+            if (opts.onlyConfig) {
+                // Only copy openclaw.json
+                const configSrc = join(stateDir, "openclaw.json");
+                if (existsSync(configSrc)) {
+                    copyFileSync(configSrc, join(payloadStateDir, "openclaw.json"));
+                }
+            }
+            else {
+                // Copy .openclaw/ contents (respecting excludes). Manual lstat
+                // walker — same rationale as the home-scope branch above.
+                copyTreeLstat(stateDir, payloadStateDir, (rel) => {
+                    if (!rel)
+                        return true; // root dir
+                    return !excludes.some(ex => rel.startsWith(ex));
+                });
+            }
+        }
+        // Collect all files for checksum (excluding manifest which doesn't exist yet)
+        const allFiles = collectFiles(stagingDir, stagingDir, []);
+        // Calculate checksum from staged files
+        const checksum = calculateContentChecksum(stagingDir, allFiles);
+        const hasSessions = opts.includeSessions ?? false;
+        // Generate manifest (minimum required fields matching official format)
+        const manifest = {
+            schemaVersion: 1,
+            type: opts.type,
+            scope,
+            createdAt: new Date().toISOString(),
+            name: meta.name || instanceId,
+            description: meta.description || "",
+            platform: process.platform,
+            arch: process.arch,
+            libc: detectLibc(),
+            nodeVersion: process.version,
+            paths: {
+                stateDir: `payload/${encodedPath}/.openclaw`,
+            },
+            has_sessions: hasSessions,
+            checksum: `sha256:${checksum}`,
+            checksum_scope: "content-excluding-manifest",
+        };
+        // Write manifest to staging root
+        writeFileSync(join(stagingDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+        // Single-pass tar via spawn with heartbeat
+        const stopHeartbeat = startLockHeartbeat(instanceId);
+        try {
+            await new Promise((resolve, reject) => {
+                const child = spawnChild("tar", ["-czf", outputPath, "."], {
+                    cwd: stagingDir,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                let stderr = "";
+                child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+                child.on("close", (code) => {
+                    if (code !== 0)
+                        reject(new Error(`tar pack failed (exit ${code}): ${stderr.slice(0, 500)}`));
+                    else
+                        resolve();
+                });
+                child.on("error", reject);
+            });
+        }
+        finally {
+            stopHeartbeat();
+        }
+        const finalSize = statSync(outputPath).size;
+        return { filename: outputPath.split("/").pop(), filepath: outputPath, size: finalSize, manifest };
+    }
+    finally {
+        // Cleanup staging
+        rmSync(stagingDir, { recursive: true, force: true });
+    }
+}
+/** Dynamically resolve the service manager (nomad or process) based on panel config. */
+async function getSvc() {
+    const { getServiceManagerType } = await import("../config.js");
+    const type = getServiceManagerType();
+    if (type === "nomad") {
+        return import("./nomad-manager.js");
+    }
+    return import("./process-manager.js");
+}
+/**
+ * Restore an instance from a backup file.
+ * Full flow: lock -> extract -> validate -> pre-restore backup -> stop -> restore -> rebuild -> start -> healthcheck -> rollback on failure
+ */
+export async function restoreInstance(instanceId, backupFilePath) {
+    const { getInstance } = await import("./instance-manager.js");
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Instance ${instanceId} not found`);
+    const warnings = [];
+    // Default to "preserved"; promoted to "lost" below if we detect the archive
+    // was built on a different machine (platform/arch mismatch is a proxy signal).
+    let apiKeyStatus = "preserved";
+    // Step 1: Acquire lock
+    if (!acquireInstanceLock(instanceId, "restoring")) {
+        const lock = getInstanceLockStatus(instanceId);
+        throw Object.assign(new Error(`Instance ${instanceId} is locked: ${lock?.operation}`), { statusCode: 409 });
+    }
+    const stopHeartbeat = startLockHeartbeat(instanceId);
+    const tmpDir = join(TMP_DIR, `restore-${instanceId}-${Date.now()}`);
+    try {
+        // Step 2: Safe extract to temp dir
+        mkdirSync(tmpDir, { recursive: true });
+        await safeExtract(backupFilePath, tmpDir);
+        touchInstanceLock(instanceId);
+        // Step 3: Resolve the archive root (handles both self-pack layout and
+        // official CLI's top-level wrapper directory) and validate manifest
+        const archiveRoot = resolveArchiveRoot(tmpDir);
+        const manifestPath = join(archiveRoot, "manifest.json");
+        if (!existsSync(manifestPath))
+            throw new Error("Archive missing manifest.json");
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        if (manifest.schemaVersion && manifest.schemaVersion > 1) {
+            warnings.push(`Archive schemaVersion ${manifest.schemaVersion} is newer than supported (1)`);
+        }
+        // Step 4: Locate .openclaw/ via payload/ directory
+        const payloadDir = join(archiveRoot, "payload");
+        if (!existsSync(payloadDir))
+            throw new Error("Archive missing payload/ directory");
+        const extractedStateDir = findStateDir(payloadDir);
+        if (!extractedStateDir)
+            throw new Error("Could not locate .openclaw directory in archive");
+        // extractedHomeDir is the parent of .openclaw — source for home-scope restore
+        const extractedHomeDir = dirname(extractedStateDir);
+        // Verify openclaw.json exists in located dir
+        const extractedConfigPath = join(extractedStateDir, "openclaw.json");
+        if (!existsSync(extractedConfigPath))
+            throw new Error("Archive missing openclaw.json");
+        JSON.parse(readFileSync(extractedConfigPath, "utf-8")); // verify parseable
+        // Determine effective scope and check arch compatibility
+        const archiveScope = manifest.scope === "home" ? "home" : "state";
+        let effectiveScope = archiveScope;
+        const platformMismatch = manifest.platform && manifest.platform !== process.platform;
+        const archMismatch = manifest.arch && manifest.arch !== process.arch;
+        if (platformMismatch || archMismatch) {
+            // Archive was built elsewhere — openclaw.json may reference API key env
+            // vars that this machine's provider.env doesn't have set.
+            apiKeyStatus = "lost";
+        }
+        if (archiveScope === "home" && (platformMismatch || archMismatch)) {
+            warnings.push(`Architecture mismatch: archive built for ${manifest.platform}/${manifest.arch}, ` +
+                `current host is ${process.platform}/${process.arch}. ` +
+                `Downgrading to state-only restore. You may need to re-run "openclaw update" after restore.`);
+            effectiveScope = "state";
+        }
+        touchInstanceLock(instanceId);
+        // Step 5: Create pre-restore backup at the SAME scope we're about to
+        // overwrite, so rollback can actually put everything back. If we're doing
+        // a home-scope restore (which clears .npm-global/, .codex/, outer files),
+        // the pre-restore must include those; otherwise rollback would only
+        // recover .openclaw/ and leave the rest in a half-deleted state.
+        try {
+            const preRestoreDir = getInstanceBackupDir(instanceId);
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "").replace("T", "-").slice(0, 19);
+            const preRestorePath = join(preRestoreDir, `pre-restore-${timestamp}.tar.gz`);
+            await selfPackOfficialFormat(instanceId, preRestorePath, {
+                type: "pre-restore",
+                scope: effectiveScope,
+                includeSessions: true,
+                includeWorkspace: true,
+            });
+        }
+        catch (e) {
+            warnings.push(`Pre-restore backup failed (continuing anyway): ${e.message}`);
+        }
+        touchInstanceLock(instanceId);
+        // Step 6: Stop instance
+        try {
+            const svc = await getSvc();
+            await svc.stopInstance(instanceId);
+        }
+        catch {
+            // Instance may not be running -- ignore stop failures
+        }
+        // Clean proxy state
+        try {
+            const llmProxy = await import("./llm-proxy/index.js");
+            llmProxy.cleanupInstance(instanceId);
+        }
+        catch { /* ignore */ }
+        touchInstanceLock(instanceId);
+        // Step 7: Clear current target directory based on effective scope
+        const instanceDir = join(INSTANCES_DIR, instanceId);
+        const openclawHome = meta.openclaw_home || join(instanceDir, "openclaw-home");
+        const stateDir = join(openclawHome, ".openclaw");
+        const cacheKeepDirs = new Set([".npm", ".cache", ".node_compile_cache"]);
+        if (effectiveScope === "home") {
+            // Home scope: clear openclaw-home except cache dirs
+            if (existsSync(openclawHome)) {
+                for (const entry of readdirSync(openclawHome)) {
+                    if (cacheKeepDirs.has(entry))
+                        continue;
+                    rmSync(join(openclawHome, entry), { recursive: true, force: true });
+                }
+            }
+            else {
+                mkdirSync(openclawHome, { recursive: true });
+            }
+        }
+        else {
+            // State scope: clear only .openclaw/, keep cache subdirs inside
+            const legacyConfig = join(openclawHome, "openclaw.json");
+            if (existsSync(legacyConfig))
+                rmSync(legacyConfig, { force: true });
+            if (existsSync(stateDir)) {
+                for (const entry of readdirSync(stateDir)) {
+                    if (cacheKeepDirs.has(entry))
+                        continue;
+                    rmSync(join(stateDir, entry), { recursive: true, force: true });
+                }
+            }
+            else {
+                mkdirSync(stateDir, { recursive: true });
+            }
+        }
+        touchInstanceLock(instanceId);
+        // Step 8: Copy restored content based on effective scope. Uses the
+        // manual lstat walker (not fs.cpSync) so dangling/absolute symlinks
+        // survive the round-trip without ENOENT.
+        if (effectiveScope === "home") {
+            // Home scope: copy entire extracted home dir into openclawHome
+            copyTreeLstat(extractedHomeDir, openclawHome, () => true);
+        }
+        else {
+            // State scope: copy only .openclaw/
+            if (existsSync(extractedStateDir)) {
+                copyTreeLstat(extractedStateDir, stateDir, () => true);
+            }
+        }
+        touchInstanceLock(instanceId);
+        // Step 10: Rebuild runtime state
+        try {
+            const { bootstrapInstanceProxy } = await import("./llm-proxy/index.js");
+            await bootstrapInstanceProxy(instanceId);
+        }
+        catch (e) {
+            warnings.push(`Proxy bootstrap warning: ${e.message}`);
+        }
+        touchInstanceLock(instanceId);
+        // Step 11: Start instance
+        let started = false;
+        try {
+            const svc = await getSvc();
+            const result = await svc.startInstance(instanceId);
+            started = result.ok !== false;
+        }
+        catch { /* ignore start failures */ }
+        touchInstanceLock(instanceId);
+        // Step 12: Health check (30s timeout)
+        if (started) {
+            let healthy = false;
+            const deadline = Date.now() + 30_000;
+            while (Date.now() < deadline) {
+                touchInstanceLock(instanceId);
+                try {
+                    const svc = await getSvc();
+                    const status = await svc.getStatus(instanceId);
+                    if (status.status === "running") {
+                        healthy = true;
+                        break;
+                    }
+                }
+                catch { /* keep polling */ }
+                await new Promise(r => setTimeout(r, 2000));
+            }
+            if (!healthy) {
+                warnings.push("Health check failed after restore. Attempting auto-rollback...");
+                try {
+                    await _rollbackFromPreRestore(instanceId, meta);
+                    warnings.push("Auto-rollback completed. Instance restored to pre-restore state.");
+                    return { ok: false, warnings, api_key_status: apiKeyStatus, rolled_back: true };
+                }
+                catch (e) {
+                    warnings.push(`Auto-rollback also failed: ${e.message}. Manual recovery needed.`);
+                    return { ok: false, warnings, api_key_status: apiKeyStatus, rolled_back: false };
+                }
+            }
+        }
+        return { ok: true, warnings, api_key_status: apiKeyStatus };
+    }
+    finally {
+        stopHeartbeat();
+        if (existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+        releaseInstanceLock(instanceId);
+    }
+}
+/**
+ * Create a new instance from a backup file.
+ * Does NOT copy model.env (new proxy token), provider.env (can't decrypt), or IM credentials.
+ * Hard rule: provider.env is always ignored — no decrypt attempt, no migration.
+ */
+export async function createFromBackup(backupFilePath, opts) {
+    const warnings = [];
+    const tmpDir = join(TMP_DIR, `create-from-backup-${opts.newId}-${Date.now()}`);
+    try {
+        // Extract and validate
+        mkdirSync(tmpDir, { recursive: true });
+        await safeExtract(backupFilePath, tmpDir);
+        // Resolve root — handles both self-pack and official CLI wrapper layouts
+        const archiveRoot = resolveArchiveRoot(tmpDir);
+        // Detect archive scope — for home-scope archives we restore the full
+        // openclaw-home tree, not just .openclaw (see importInstance for the
+        // rationale).
+        let archiveScope = "state";
+        const manifestPath = join(archiveRoot, "manifest.json");
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+            if (manifest.has_api_keys === false || !manifest.has_api_keys) {
+                warnings.push("No API Key in this backup. You will need to configure one.");
+            }
+            if (manifest?.scope === "home")
+                archiveScope = "home";
+        }
+        // Locate .openclaw/ via payload/ directory (official format)
+        const payloadDir = join(archiveRoot, "payload");
+        if (!existsSync(payloadDir))
+            throw new Error("Archive missing payload/ directory");
+        const extractedStateDir = findStateDir(payloadDir);
+        if (!extractedStateDir)
+            throw new Error("Could not locate .openclaw directory in archive");
+        // Create the new instance via existing createInstance
+        const { createInstance } = await import("./instance-manager.js");
+        const newMeta = await createInstance(opts.newId, opts.newName, opts.newDescription || "");
+        // Copy content to the new instance's openclaw-home. Manual lstat
+        // walker preserves symlinks as opaque blobs (see pack-side notes).
+        const newOpenclawHome = newMeta.openclaw_home || join(INSTANCES_DIR, opts.newId, "openclaw-home");
+        const newStateDir = join(newOpenclawHome, ".openclaw");
+        if (archiveScope === "home") {
+            // Home scope: copy the entire extracted home tree.
+            const extractedHomeDir = dirname(extractedStateDir);
+            copyTreeLstat(extractedHomeDir, newOpenclawHome, (rel) => {
+                if (!rel)
+                    return true;
+                if (rel === ".openclaw/openclaw-weixin")
+                    return false;
+                if (rel.startsWith(".openclaw/openclaw-weixin/"))
+                    return false;
+                return true;
+            });
+        }
+        else {
+            // State scope: copy only .openclaw/.
+            copyTreeLstat(extractedStateDir, newStateDir, (rel) => {
+                if (!rel)
+                    return true;
+                if (rel.startsWith("openclaw-weixin"))
+                    return false;
+                return true;
+            });
+        }
+        // Scrub channel credentials from copied openclaw.json (new instance should not inherit IM bindings)
+        await scrubNewInstanceConfig(join(newStateDir, "openclaw.json"));
+        // DO NOT copy model.env — bootstrapInstanceProxy will generate a new proxy token
+        // DO NOT copy provider.env — encrypted with source machine's key, can't decrypt
+        // DO NOT copy instance.json — already created by createInstance
+        // Bootstrap proxy for new instance (generates new token)
+        try {
+            const { bootstrapInstanceProxy } = await import("./llm-proxy/index.js");
+            await bootstrapInstanceProxy(opts.newId);
+        }
+        catch (e) {
+            warnings.push(`Proxy bootstrap warning: ${e.message}`);
+        }
+        warnings.push("Instance created. Configure API Key before starting.");
+        return { ok: true, instance_id: opts.newId, warnings };
+    }
+    finally {
+        if (existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Internal rollback helper -- restores from the most recent pre-restore backup.
+ * Does NOT re-acquire lock (caller already holds it).
+ * Does NOT create another pre-restore backup.
+ */
+async function _rollbackFromPreRestore(instanceId, meta) {
+    const backupDir = join(BACKUPS_DIR, instanceId);
+    if (!existsSync(backupDir))
+        throw new Error("No backup directory for rollback");
+    // Find most recent pre-restore backup
+    const preRestores = readdirSync(backupDir)
+        .filter(f => f.startsWith("pre-restore-") && f.endsWith(".tar.gz"))
+        .sort()
+        .reverse();
+    if (preRestores.length === 0)
+        throw new Error("No pre-restore backup found for rollback");
+    const preRestorePath = join(backupDir, preRestores[0]);
+    const tmpDir = join(TMP_DIR, `rollback-${instanceId}-${Date.now()}`);
+    try {
+        mkdirSync(tmpDir, { recursive: true });
+        await safeExtract(preRestorePath, tmpDir);
+        const openclawHome = meta.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
+        const stateDir = join(openclawHome, ".openclaw");
+        // Resolve archive root (pre-restore is always self-pack so this is
+        // usually a no-op, but handle either layout for safety).
+        const archiveRoot = resolveArchiveRoot(tmpDir);
+        // Locate .openclaw/ and its parent (source for home-scope rollback)
+        const payloadDir = join(archiveRoot, "payload");
+        const extractedStateDir = existsSync(payloadDir) ? findStateDir(payloadDir) : null;
+        if (!extractedStateDir)
+            throw new Error("pre-restore archive missing .openclaw directory");
+        const extractedHomeDir = dirname(extractedStateDir);
+        // Read the pre-restore's own manifest to decide rollback scope.
+        // If the pre-restore was packed as home scope, we must rollback the full
+        // home tree (.npm-global/, .codex/, outer openclaw.json) — not just
+        // .openclaw/ — otherwise we leave the instance in a half-deleted state.
+        let rollbackScope = "state";
+        const manifestPath = join(archiveRoot, "manifest.json");
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+                if (manifest?.scope === "home")
+                    rollbackScope = "home";
+            }
+            catch { /* fall back to state */ }
+        }
+        const cacheKeepDirs = new Set([".npm", ".cache", ".node_compile_cache"]);
+        if (rollbackScope === "home") {
+            // Clear openclaw-home/ except cache dirs, then restore the entire tree.
+            if (existsSync(openclawHome)) {
+                for (const entry of readdirSync(openclawHome)) {
+                    if (cacheKeepDirs.has(entry))
+                        continue;
+                    rmSync(join(openclawHome, entry), { recursive: true, force: true });
+                }
+            }
+            else {
+                mkdirSync(openclawHome, { recursive: true });
+            }
+            copyTreeLstat(extractedHomeDir, openclawHome, () => true);
+        }
+        else {
+            // State-scope rollback: clear and restore only .openclaw/.
+            if (existsSync(stateDir)) {
+                for (const entry of readdirSync(stateDir)) {
+                    if (cacheKeepDirs.has(entry))
+                        continue;
+                    rmSync(join(stateDir, entry), { recursive: true, force: true });
+                }
+            }
+            else {
+                mkdirSync(stateDir, { recursive: true });
+            }
+            copyTreeLstat(extractedStateDir, stateDir, () => true);
+        }
+        // Rebuild proxy state
+        try {
+            const { bootstrapInstanceProxy } = await import("./llm-proxy/index.js");
+            await bootstrapInstanceProxy(instanceId);
+        }
+        catch { /* best effort */ }
+        // Try to restart
+        try {
+            const svc = await getSvc();
+            await svc.startInstance(instanceId);
+        }
+        catch { /* best effort */ }
+    }
+    finally {
+        if (existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+// ── Export ──
+/**
+ * Export an instance for sharing. Uses WHITELIST strategy — only safe directories included.
+ * API keys and credentials are stripped. Sensitive fields in openclaw.json are scrubbed.
+ */
+export async function exportInstance(instanceId, opts = {}) {
+    const { getInstance, getOpenclawHome } = await import("./instance-manager.js");
+    const meta = getInstance(instanceId);
+    if (!meta)
+        throw new Error(`Instance ${instanceId} not found`);
+    const openclawHome = getOpenclawHome(instanceId);
+    const stateDir = join(openclawHome, ".openclaw");
+    if (!existsSync(stateDir))
+        throw new Error(`State directory not found: ${stateDir}`);
+    if (!acquireInstanceLock(instanceId, "exporting")) {
+        throw Object.assign(new Error(`Instance ${instanceId} is locked`), { statusCode: 409 });
+    }
+    const stopHeartbeat = startLockHeartbeat(instanceId);
+    // Export downloads are served per-instance from TMP_DIR/exports/<instanceId>/.
+    // The download route enforces this isolation so one instance's URL can't
+    // reach another's file.
+    const instanceExportDir = getInstanceExportDir(instanceId);
+    const outputPath = opts.outputPath || join(instanceExportDir, `export-${instanceId}-${Date.now()}.tar.gz`);
+    const stagingDir = join(TMP_DIR, `export-staging-${instanceId}-${Date.now()}`);
+    const tmpBackupPath = join(TMP_DIR, `export-raw-${instanceId}-${Date.now()}.tar.gz`);
+    try {
+        // Step 1: Self-pack in official format (always self-pack for export — we need to filter)
+        await selfPackOfficialFormat(instanceId, tmpBackupPath, {
+            type: "export",
+            includeSessions: opts.includeSessions,
+            includeWorkspace: true,
+        });
+        // Step 2: Extract to staging
+        mkdirSync(stagingDir, { recursive: true });
+        await safeExtract(tmpBackupPath, stagingDir);
+        if (existsSync(tmpBackupPath))
+            rmSync(tmpBackupPath, { force: true });
+        // Step 3: Resolve archive root + locate .openclaw/ via payload/.
+        // self-pack always writes at root so resolveArchiveRoot is a no-op here,
+        // but using it keeps all consumers on one canonical path.
+        const stagingRoot = resolveArchiveRoot(stagingDir);
+        const payloadDir = join(stagingRoot, "payload");
+        if (!existsSync(payloadDir))
+            throw new Error("Self-pack missing payload/ directory");
+        const foundDir = findStateDir(payloadDir);
+        if (!foundDir)
+            throw new Error("Could not locate .openclaw in self-pack");
+        // Step 4: Whitelist filter — remove everything outside allowed dirs
+        const allowedRoots = ["openclaw.json", "extensions", "workspace"];
+        if (opts.includeSessions)
+            allowedRoots.push("agents");
+        for (const entry of readdirSync(foundDir)) {
+            if (!allowedRoots.includes(entry)) {
+                rmSync(join(foundDir, entry), { recursive: true, force: true });
+            }
+        }
+        // Step 5: Scrub openclaw.json
+        const configPath = join(foundDir, "openclaw.json");
+        const scrubWarnings = [];
+        if (existsSync(configPath)) {
+            const config = JSON.parse(readFileSync(configPath, "utf-8"));
+            // Scrub provider API keys
+            const providers = config?.models?.providers;
+            if (providers) {
+                for (const [pid, prov] of Object.entries(providers)) {
+                    if (prov?.apiKey)
+                        prov.apiKey = "";
+                    // Remove proxy providers
+                    if (typeof prov?.baseUrl === "string" && prov.baseUrl.includes("/proxy/")) {
+                        delete providers[pid];
+                    }
+                }
+            }
+            // Scrub channel credentials
+            const channels = config?.channels;
+            if (channels) {
+                for (const [, ch] of Object.entries(channels)) {
+                    if (ch?.appSecret)
+                        ch.appSecret = "";
+                    if (ch?.appId)
+                        ch.appId = "";
+                    if (ch?.token)
+                        ch.token = "";
+                    if (ch?.secret)
+                        ch.secret = "";
+                    if (ch?.credentials)
+                        ch.credentials = {};
+                }
+            }
+            // Scrub gateway control-UI token — this is the token the panel uses
+            // to drive OpenClaw's gateway control API; leaking it would let anyone
+            // with the export package call the recipient's gateway once imported.
+            if (config?.gateway?.auth?.token)
+                config.gateway.auth.token = "";
+            // Remove proxy model reference
+            const defaultModel = config?.agents?.defaults?.model;
+            if (typeof defaultModel === "string" && (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
+                delete config.agents.defaults.model;
+            }
+            // Residual scan — walk the object and flag any string-valued field
+            // whose key name looks sensitive. The warning only records the JSON
+            // path and field length, NEVER the value itself, so a residual field
+            // can't leak through manifest.warnings.
+            const SENSITIVE_KEY_RE = /^(api_?key|token|secret|credential|password|auth_?key|app_?secret|app_?id)$/i;
+            const walk = (node, path) => {
+                if (!node || typeof node !== "object")
+                    return;
+                for (const [key, val] of Object.entries(node)) {
+                    const here = path ? `${path}.${key}` : key;
+                    if (typeof val === "string" && val.length >= 4 && SENSITIVE_KEY_RE.test(key)) {
+                        scrubWarnings.push(`Possible residual sensitive field at ${here} (${val.length} chars)`);
+                    }
+                    else if (val && typeof val === "object") {
+                        walk(val, here);
+                    }
+                }
+            };
+            walk(config, "");
+            writeFileSync(configPath, JSON.stringify(config, null, 2));
+        }
+        // Step 6: Update manifest
+        const manifestPath = join(stagingDir, "manifest.json");
+        const manifest = existsSync(manifestPath)
+            ? JSON.parse(readFileSync(manifestPath, "utf-8"))
+            : { schemaVersion: 1 };
+        manifest.type = "export";
+        manifest.has_api_keys = false;
+        manifest.has_sessions = opts.includeSessions ?? false;
+        if (scrubWarnings.length > 0)
+            manifest.warnings = scrubWarnings;
+        // Recalculate checksum
+        const allFiles = collectFiles(stagingDir, stagingDir, []);
+        const nonManifest = allFiles.filter(f => f !== "manifest.json");
+        const checksum = calculateContentChecksum(stagingDir, nonManifest);
+        manifest.checksum = `sha256:${checksum}`;
+        manifest.checksum_scope = "content-excluding-manifest";
+        manifest.stats = { total_files: allFiles.length };
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        // Step 7: Repack
+        touchInstanceLock(instanceId);
+        await new Promise((resolve, reject) => {
+            const child = spawnChild("tar", ["-czf", outputPath, "."], {
+                cwd: stagingDir,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+            child.on("close", (code) => {
+                if (code !== 0)
+                    reject(new Error(`tar pack failed (exit ${code}): ${stderr.slice(0, 500)}`));
+                else
+                    resolve();
+            });
+            child.on("error", reject);
+        });
+        const finalSize = statSync(outputPath).size;
+        return { filename: outputPath.split("/").pop(), filepath: outputPath, size: finalSize, manifest };
+    }
+    finally {
+        stopHeartbeat();
+        if (existsSync(stagingDir))
+            rmSync(stagingDir, { recursive: true, force: true });
+        if (existsSync(tmpBackupPath))
+            rmSync(tmpBackupPath, { force: true });
+        releaseInstanceLock(instanceId);
+    }
+}
+// ── Import (three-step) ──
+/** Step 1: Store uploaded file to tmp. Returns temp_id for subsequent calls. */
+export async function storeUpload(filePath) {
+    const tempId = randomUUID();
+    const destPath = join(TMP_DIR, `import-${tempId}.tar.gz`);
+    ensureBackupDirs();
+    copyFileSync(filePath, destPath);
+    return { temp_id: tempId };
+}
+/** Step 2: Preview an uploaded archive without creating an instance. */
+export async function previewImport(tempId) {
+    const archivePath = join(TMP_DIR, `import-${tempId}.tar.gz`);
+    if (!existsSync(archivePath))
+        throw new Error("Upload not found or expired");
+    const tmpDir = join(TMP_DIR, `preview-${tempId}`);
+    const warnings = [];
+    try {
+        mkdirSync(tmpDir, { recursive: true });
+        const scanResult = await safeExtract(archivePath, tmpDir);
+        // Resolve archive root — handles both self-pack and CLI wrapper layouts
+        const archiveRoot = resolveArchiveRoot(tmpDir);
+        // Read manifest
+        const manifestPath = join(archiveRoot, "manifest.json");
+        let manifest = null;
+        if (existsSync(manifestPath)) {
+            manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        }
+        // Detect format — all archives use the official payload/ layout
+        let format = "unknown";
+        if (existsSync(join(archiveRoot, "payload"))) {
+            format = "official";
+        }
+        // Check for missing API keys
+        if (manifest?.has_api_keys === false) {
+            warnings.push("This package does not contain API keys. You will need to configure them.");
+        }
+        // Check sessions
+        if (manifest?.has_sessions === false) {
+            warnings.push("This package does not contain conversation history.");
+        }
+        // Version compatibility
+        if (manifest?.runtimeVersion) {
+            warnings.push(`Created with OpenClaw ${manifest.runtimeVersion}`);
+        }
+        return {
+            manifest,
+            warnings,
+            estimated_size: scanResult.totalSize,
+            format,
+        };
+    }
+    finally {
+        if (existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** Step 3: Create a new instance from a previously uploaded archive. */
+export async function importInstance(tempId, opts) {
+    const archivePath = join(TMP_DIR, `import-${tempId}.tar.gz`);
+    if (!existsSync(archivePath))
+        throw new Error("Upload not found or expired");
+    const warnings = [];
+    const tmpDir = join(TMP_DIR, `import-create-${tempId}`);
+    try {
+        mkdirSync(tmpDir, { recursive: true });
+        await safeExtract(archivePath, tmpDir);
+        // Resolve archive root — handles both self-pack and CLI wrapper layouts
+        const archiveRoot = resolveArchiveRoot(tmpDir);
+        // Locate .openclaw/ via payload/ directory (official format)
+        const payloadDir = join(archiveRoot, "payload");
+        if (!existsSync(payloadDir))
+            throw new Error("Archive missing payload/ directory");
+        const extractedStateDir = findStateDir(payloadDir);
+        if (!extractedStateDir)
+            throw new Error("Could not locate .openclaw directory in archive");
+        // Detect archive scope — for home-scope archives we restore the full
+        // openclaw-home tree (app/, .npm-global/, .codex/, etc.), not just
+        // the .openclaw state dir. Without this, importing a home-scope
+        // backup silently drops the runtime/app tree that motivated the
+        // home-scope in the first place.
+        let archiveScope = "state";
+        const manifestPath = join(archiveRoot, "manifest.json");
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+                if (manifest?.scope === "home")
+                    archiveScope = "home";
+            }
+            catch { /* fall back to state */ }
+        }
+        // Create new instance
+        const { createInstance } = await import("./instance-manager.js");
+        const newMeta = await createInstance(opts.id, opts.name, opts.description || "");
+        const newOpenclawHome = newMeta.openclaw_home || join(INSTANCES_DIR, opts.id, "openclaw-home");
+        const newStateDir = join(newOpenclawHome, ".openclaw");
+        // Manual lstat walker preserves symlinks as opaque blobs and never
+        // follows dangling targets.
+        if (archiveScope === "home") {
+            // Home scope: copy the full extracted home tree so app/,
+            // .npm-global/ (upgraded runtime), .codex/, and outer files survive.
+            // Still exclude IM credentials — same channel can't bind multiple
+            // instances.
+            const extractedHomeDir = dirname(extractedStateDir);
+            copyTreeLstat(extractedHomeDir, newOpenclawHome, (rel) => {
+                if (!rel)
+                    return true;
+                if (rel === ".openclaw/openclaw-weixin")
+                    return false;
+                if (rel.startsWith(".openclaw/openclaw-weixin/"))
+                    return false;
+                return true;
+            });
+        }
+        else {
+            // State scope: copy only .openclaw/.
+            copyTreeLstat(extractedStateDir, newStateDir, (rel) => {
+                if (!rel)
+                    return true;
+                if (rel.startsWith("openclaw-weixin"))
+                    return false;
+                return true;
+            });
+        }
+        // Scrub channel credentials from copied openclaw.json (new instance should not inherit IM bindings)
+        await scrubNewInstanceConfig(join(newStateDir, "openclaw.json"));
+        // DO NOT copy model.env, provider.env, instance.json
+        // Bootstrap proxy
+        try {
+            const { bootstrapInstanceProxy } = await import("./llm-proxy/index.js");
+            await bootstrapInstanceProxy(opts.id);
+        }
+        catch (e) {
+            warnings.push(`Proxy bootstrap: ${e.message}`);
+        }
+        // Check if default_provider can be injected
+        try {
+            const { getPanelConfig } = await import("../config.js");
+            const panelConfig = getPanelConfig();
+            if (panelConfig?.default_provider?.apiKey && !panelConfig.default_provider.skipped) {
+                warnings.push("Default provider detected. You may configure API Key from the config page.");
+            }
+        }
+        catch { /* ignore */ }
+        warnings.push("Instance created. Configure API Key before starting.");
+        // Clean up the upload file
+        rmSync(archivePath, { force: true });
+        return { ok: true, instance_id: opts.id, warnings };
+    }
+    finally {
+        if (existsSync(tmpDir))
+            rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Scrub proxy identity and IM bindings from a copied openclaw.json before it
+ * is handed to a brand-new instance (importInstance / createFromBackup).
+ *
+ * Matches the domain-clone behavior in `createInstance` so both paths produce
+ * identical "clean slate" configs: no inherited proxy provider, no inherited
+ * channel bindings, no dangling IM plugin entries. This avoids the hazard
+ * where imported configs kept `channels.*.enabled = true` with scrubbed
+ * credentials, leaving the plugin loader to boot a half-configured binding.
+ *
+ * **Important**: JishuShell double-writes openclaw.json to both the runtime
+ * path (`.openclaw/openclaw.json`) and the legacy alias
+ * (`openclaw-home/openclaw.json`). `loadEffectiveConfig` deep-merges both
+ * when read back, so scrubbing only the runtime path leaves the legacy copy
+ * as a ghost writer that resurrects deleted fields on the next saveConfig.
+ * Both paths must be scrubbed — or kept in sync — before any subsequent
+ * read. This function accepts the runtime path and scrubs the sibling
+ * legacy path too when present.
+ */
+async function scrubNewInstanceConfig(configPath) {
+    const { stripImBindings } = await import("./instance-manager.js");
+    const scrubOne = (path) => {
+        if (!existsSync(path))
+            return;
+        try {
+            const config = JSON.parse(readFileSync(path, "utf-8"));
+            // Remove proxy providers (will be regenerated by bootstrapInstanceProxy)
+            const providers = config?.models?.providers;
+            if (providers) {
+                for (const [pid, prov] of Object.entries(providers)) {
+                    if (typeof prov?.baseUrl === "string" && prov.baseUrl.includes("/proxy/")) {
+                        delete providers[pid];
+                    }
+                }
+            }
+            // Remove proxy model reference from agent defaults
+            const defaultModel = config?.agents?.defaults?.model;
+            if (typeof defaultModel === "string" && (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))) {
+                delete config.agents.defaults.model;
+            }
+            // Unified IM scrub: delete channels block + matching plugin entries
+            stripImBindings(config);
+            writeFileSync(path, JSON.stringify(config, null, 2));
+        }
+        catch { /* best effort */ }
+    };
+    scrubOne(configPath);
+    // Also scrub the legacy outer-home alias if it exists. The runtime path
+    // is .openclaw/openclaw.json and the legacy path is the parent dir's
+    // openclaw.json (i.e. openclaw-home/openclaw.json).
+    try {
+        const runtimeDir = dirname(configPath); // .../openclaw-home/.openclaw
+        const homeDir = dirname(runtimeDir); // .../openclaw-home
+        const legacyPath = join(homeDir, "openclaw.json");
+        if (legacyPath !== configPath)
+            scrubOne(legacyPath);
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Resolve the effective "archive root" inside an extracted tarball.
+ *
+ * Returns the directory where `manifest.json` and `payload/` live. Two
+ * archive layouts are supported:
+ *
+ *   1. **JishuShell self-pack** (`selfPackOfficialFormat`): writes
+ *      `manifest.json` and `payload/` directly at the archive root, so the
+ *      effective root is the extraction dir itself.
+ *
+ *   2. **Official OpenClaw `backup create`**: wraps everything inside a
+ *      single top-level directory named after the archive basename, e.g.
+ *      `2026-04-10T03-06-23.257Z-openclaw-backup/`. The wrapper name is
+ *      also advertised via `manifest.archiveRoot`.
+ *
+ * Detection strategy (cheapest first):
+ *   a. If `<tmpDir>/manifest.json` exists → self-pack → return tmpDir.
+ *   b. Else scan top-level entries; if exactly one is a directory containing
+ *      `manifest.json`, that's the official CLI wrapper → return it.
+ *   c. Fall back to tmpDir; the caller will throw its own missing-manifest
+ *      error with a meaningful path.
+ *
+ * Without this helper, `restoreInstance` / `importInstance` / `verifyArchive`
+ * would throw "Archive missing manifest.json" on every state-scope archive
+ * produced by the official CLI.
+ */
+export function resolveArchiveRoot(tmpDir) {
+    if (existsSync(join(tmpDir, "manifest.json")))
+        return tmpDir;
+    try {
+        for (const entry of readdirSync(tmpDir)) {
+            const candidate = join(tmpDir, entry);
+            try {
+                if (statSync(candidate).isDirectory() && existsSync(join(candidate, "manifest.json"))) {
+                    return candidate;
+                }
+            }
+            catch { /* skip inaccessible */ }
+        }
+    }
+    catch { /* skip */ }
+    return tmpDir;
+}
+/**
+ * Locate the OpenClaw state directory inside an extracted archive.
+ *
+ * Finds a directory **literally named `.openclaw`** that contains an
+ * `openclaw.json` file. Uses BFS so the shallowest match wins, which guards
+ * against nested copies inside extensions/ or workspace/.
+ *
+ * This is intentionally stricter than "any directory containing
+ * openclaw.json". JishuShell's `saveConfig` double-writes the config to both
+ * `.openclaw/openclaw.json` and an outer legacy alias at
+ * `openclaw-home/openclaw.json`, so a naive "first dir with openclaw.json"
+ * search would incorrectly pick the `openclaw-home/` root for home-scope
+ * archives.
+ */
+export function findStateDir(rootDir) {
+    const queue = [rootDir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        try {
+            for (const entry of readdirSync(current)) {
+                const fullPath = join(current, entry);
+                try {
+                    if (!statSync(fullPath).isDirectory())
+                        continue;
+                    if (entry === ".openclaw" && existsSync(join(fullPath, "openclaw.json"))) {
+                        return fullPath;
+                    }
+                    queue.push(fullPath);
+                }
+                catch { /* skip inaccessible entries */ }
+            }
+        }
+        catch { /* skip inaccessible dirs */ }
+    }
+    return null;
+}
+// ── Auto-backup scheduler ──
+const autoBackupTimers = new Map();
+/** Get auto-backup config from instance.json */
+export async function getAutoBackupConfig(instanceId) {
+    try {
+        const { getInstance } = await import("./instance-manager.js");
+        const meta = getInstance(instanceId);
+        return meta?.auto_backup || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Update auto-backup status in instance.json */
+async function updateAutoBackupStatus(instanceId, patch) {
+    const { updateInstanceMeta, getInstance } = await import("./instance-manager.js");
+    const meta = getInstance(instanceId);
+    const current = meta?.auto_backup || {};
+    updateInstanceMeta(instanceId, { auto_backup: { ...current, ...patch } });
+}
+/** Check if instance has changed since last backup (mtime-based) */
+async function hasChangedSince(instanceId, sinceMs) {
+    try {
+        const { getInstance } = await import("./instance-manager.js");
+        const meta = getInstance(instanceId);
+        const openclawHome = meta?.openclaw_home || join(INSTANCES_DIR, instanceId, "openclaw-home");
+        const stateDir = join(openclawHome, ".openclaw");
+        if (!existsSync(stateDir))
+            return false;
+        return getMaxMtime(stateDir, 0) > sinceMs;
+    }
+    catch {
+        return true; // On error, assume changed (safe default)
+    }
+}
+/** Recursively find max mtime in a directory, skipping cache dirs */
+function getMaxMtime(dir, currentMax) {
+    const skipDirs = new Set([".npm", ".cache", ".node_compile_cache", ".npm-global"]);
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (skipDirs.has(entry))
+                continue;
+            const fullPath = join(dir, entry);
+            try {
+                const stat = statSync(fullPath);
+                if (stat.mtimeMs > currentMax)
+                    currentMax = stat.mtimeMs;
+                if (stat.isDirectory()) {
+                    currentMax = getMaxMtime(fullPath, currentMax);
+                }
+            }
+            catch { /* skip inaccessible */ }
+        }
+    }
+    catch { /* skip */ }
+    return currentMax;
+}
+/** Clean old auto-backup files, keeping only the newest `keepCount` */
+export async function cleanOldAutoBackups(instanceId, keepCount) {
+    const backupDir = join(BACKUPS_DIR, instanceId);
+    if (!existsSync(backupDir))
+        return 0;
+    const autoBackups = readdirSync(backupDir)
+        .filter(f => f.startsWith("auto-backup-") && f.endsWith(".tar.gz"))
+        .map(f => ({ name: f, mtime: statSync(join(backupDir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime); // newest first
+    let cleaned = 0;
+    for (let i = keepCount; i < autoBackups.length; i++) {
+        rmSync(join(backupDir, autoBackups[i].name), { force: true });
+        cleaned++;
+    }
+    return cleaned;
+}
+/** Check available disk space (returns bytes) */
+function getAvailableDiskSpace() {
+    try {
+        const output = execFileSync("df", ["-B1", "--output=avail", BACKUPS_DIR], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        const lines = output.trim().split("\n");
+        return parseInt(lines[lines.length - 1].trim(), 10) || 0;
+    }
+    catch {
+        try {
+            // macOS fallback
+            const output = execFileSync("df", ["-k", BACKUPS_DIR], { encoding: "utf-8", timeout: 5000 });
+            const lines = output.trim().split("\n");
+            const parts = lines[lines.length - 1].split(/\s+/);
+            return (parseInt(parts[3], 10) || 0) * 1024; // Convert KB to bytes
+        }
+        catch {
+            return Infinity; // Can't check, don't block
+        }
+    }
+}
+const MIN_DISK_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const jobQueue = [];
+const jobHistory = [];
+const MAX_HISTORY = 20;
+let currentJob = null;
+let queueProcessing = false;
+// Map of job ID to resolve/reject for callers that want to await completion
+const jobWaiters = new Map();
+// Store execute functions for queued jobs
+const jobExecutors = new Map();
+/** Enqueue a backup operation. Returns the job immediately (non-blocking). */
+export function enqueueJob(instanceId, operation, executeFn) {
+    const job = {
+        id: randomUUID(),
+        instanceId,
+        operation,
+        status: "queued",
+        createdAt: Date.now(),
+    };
+    jobQueue.push(job);
+    // Store the execute function for when this job's turn comes
+    jobExecutors.set(job.id, executeFn);
+    // Start processing if not already running
+    if (!queueProcessing) {
+        processQueue();
+    }
+    return job;
+}
+/** Enqueue and wait for completion. Returns the completed job. */
+export function enqueueJobAndWait(instanceId, operation, executeFn) {
+    const job = enqueueJob(instanceId, operation, executeFn);
+    return new Promise((resolve, reject) => {
+        jobWaiters.set(job.id, { resolve, reject });
+    });
+}
+async function processQueue() {
+    if (queueProcessing)
+        return;
+    queueProcessing = true;
+    while (jobQueue.length > 0) {
+        const job = jobQueue.shift();
+        currentJob = job;
+        job.status = "running";
+        job.startedAt = Date.now();
+        // Get the executor function
+        const executeFn = jobExecutors.get(job.id);
+        jobExecutors.delete(job.id);
+        if (!executeFn) {
+            job.status = "failed";
+            job.error = "No executor function found";
+            job.completedAt = Date.now();
+            moveToHistory(job);
+            continue;
+        }
+        try {
+            const result = await executeFn(job);
+            job.status = "completed";
+            job.result = result;
+        }
+        catch (e) {
+            job.status = "failed";
+            job.error = e.message || "Unknown error";
+        }
+        finally {
+            job.completedAt = Date.now();
+            currentJob = null;
+            moveToHistory(job);
+            // Notify waiter if any
+            const waiter = jobWaiters.get(job.id);
+            if (waiter) {
+                jobWaiters.delete(job.id);
+                if (job.status === "completed") {
+                    waiter.resolve(job);
+                }
+                else {
+                    waiter.reject(new Error(job.error || "Job failed"));
+                }
+            }
+        }
+    }
+    queueProcessing = false;
+}
+function moveToHistory(job) {
+    jobHistory.unshift(job);
+    if (jobHistory.length > MAX_HISTORY)
+        jobHistory.pop();
+}
+/** Update progress message for the currently running job */
+export function updateJobProgress(jobId, progress) {
+    if (currentJob?.id === jobId) {
+        currentJob.progress = progress;
+    }
+}
+/** Get full queue status */
+export function getQueueStatus() {
+    return {
+        current: currentJob,
+        queued: [...jobQueue],
+        recent: jobHistory.slice(0, 10),
+    };
+}
+/** Get a specific job by ID (checks current, queue, and history) */
+export function getJob(jobId) {
+    if (currentJob?.id === jobId)
+        return currentJob;
+    const queued = jobQueue.find(j => j.id === jobId);
+    if (queued)
+        return queued;
+    const historic = jobHistory.find(j => j.id === jobId);
+    return historic || null;
+}
+/** Cancel a queued job (cannot cancel running jobs) */
+export function cancelJob(jobId) {
+    const idx = jobQueue.findIndex(j => j.id === jobId);
+    if (idx === -1)
+        return false;
+    const job = jobQueue.splice(idx, 1)[0];
+    job.status = "failed";
+    job.error = "Cancelled";
+    job.completedAt = Date.now();
+    moveToHistory(job);
+    jobExecutors.delete(jobId);
+    const waiter = jobWaiters.get(jobId);
+    if (waiter) {
+        jobWaiters.delete(jobId);
+        waiter.reject(new Error("Job cancelled"));
+    }
+    return true;
+}
+/** Schedule auto-backup for an instance */
+export function scheduleAutoBackup(instanceId, config) {
+    cancelAutoBackup(instanceId);
+    if (!config.enabled)
+        return;
+    const lastAt = config.last_backup_at ? new Date(config.last_backup_at).getTime() : 0;
+    const intervalMs = config.interval_hours * 3600_000;
+    const delay = Math.max(0, intervalMs - (Date.now() - lastAt));
+    const timer = setTimeout(async () => {
+        // Always work against the freshest persisted config so we don't race
+        // against user edits or updateAutoBackupStatus writes. The `config` arg
+        // is only used for scheduling delay above.
+        const liveConfig = (await getAutoBackupConfig(instanceId)) || config;
+        const liveLastAt = liveConfig.last_backup_at
+            ? new Date(liveConfig.last_backup_at).getTime()
+            : 0;
+        const keepCount = liveConfig.keep_count || 7;
+        try {
+            // Check disk space
+            const available = getAvailableDiskSpace();
+            if (available < MIN_DISK_BYTES) {
+                await updateAutoBackupStatus(instanceId, {
+                    last_backup_ok: false,
+                    consecutive_failures: (liveConfig.consecutive_failures || 0) + 1,
+                    warnings: ["Auto-backup paused: disk space below 2GB"],
+                });
+                console.warn(`[auto-backup] ${instanceId}: paused, disk below 2GB`);
+                // Still reschedule to check again later
+                const fresh = await getAutoBackupConfig(instanceId);
+                if (fresh?.enabled)
+                    scheduleAutoBackup(instanceId, fresh);
+                return;
+            }
+            // Check if changed since last backup
+            if (await hasChangedSince(instanceId, liveLastAt)) {
+                // Enqueue to avoid parallel I/O contention on RPi SD card
+                await enqueueJobAndWait(instanceId, "auto-backup", async (job) => {
+                    updateJobProgress(job.id, "Backing up...");
+                    const result = await backupInstance(instanceId, { type: "auto-backup" });
+                    updateJobProgress(job.id, "Cleaning old backups...");
+                    await cleanOldAutoBackups(instanceId, keepCount);
+                    return result;
+                });
+                await updateAutoBackupStatus(instanceId, {
+                    last_backup_at: new Date().toISOString(),
+                    last_backup_ok: true,
+                    consecutive_failures: 0,
+                    warnings: [],
+                });
+                console.log(`[auto-backup] ${instanceId}: completed`);
+            }
+            else {
+                console.log(`[auto-backup] ${instanceId}: skipped (no changes)`);
+            }
+        }
+        catch (e) {
+            const failures = (liveConfig.consecutive_failures || 0) + 1;
+            const warnings = failures >= 3
+                ? [`Auto-backup failed ${failures} times: ${e.message}`]
+                : [];
+            await updateAutoBackupStatus(instanceId, {
+                last_backup_ok: false,
+                consecutive_failures: failures,
+                warnings,
+            });
+            console.error(`[auto-backup] ${instanceId} failed (${failures}x):`, e.message);
+        }
+        // Reschedule (re-read config in case user changed it)
+        const freshConfig = await getAutoBackupConfig(instanceId);
+        if (freshConfig?.enabled)
+            scheduleAutoBackup(instanceId, freshConfig);
+    }, delay);
+    timer.unref(); // Don't prevent process exit
+    autoBackupTimers.set(instanceId, timer);
+}
+/** Cancel auto-backup for an instance */
+export function cancelAutoBackup(instanceId) {
+    const t = autoBackupTimers.get(instanceId);
+    if (t) {
+        clearTimeout(t);
+        autoBackupTimers.delete(instanceId);
+    }
+}
+/** Initialize auto-backup for all instances (call on server startup) */
+export async function initAutoBackup() {
+    try {
+        const { listInstances } = await import("./instance-manager.js");
+        const instances = listInstances();
+        let jitterIndex = 0;
+        for (const inst of instances) {
+            const config = inst.auto_backup;
+            if (config?.enabled) {
+                // Stagger startup: if multiple instances are due at the same time,
+                // add incremental jitter (2 min per instance) to avoid I/O contention
+                if (!config.last_backup_at) {
+                    const jitterMs = jitterIndex * 2 * 60_000; // 2 min apart
+                    const jitteredConfig = { ...config, last_backup_at: new Date(Date.now() - (config.interval_hours * 3600_000) + jitterMs).toISOString() };
+                    scheduleAutoBackup(inst.id, jitteredConfig);
+                }
+                else {
+                    scheduleAutoBackup(inst.id, config);
+                }
+                jitterIndex++;
+                console.log(`[auto-backup] ${inst.id}: scheduled (interval: ${config.interval_hours}h, keep: ${config.keep_count})`);
+            }
+        }
+    }
+    catch (e) {
+        console.error("[auto-backup] Init failed:", e.message);
+    }
+}
+//# sourceMappingURL=backup-manager.js.map