@jungjaehoon/mama-os 0.76.0 → 0.78.0

package/dist/cli/runtime/restore.js

@@ -0,0 +1,756 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PATH_COLUMNS = void 0;
+exports.targetPaths = targetPaths;
+exports.readManifest = readManifest;
+exports.validateManifest = validateManifest;
+exports.extractVerified = extractVerified;
+exports.applyModes = applyModes;
+exports.restoredConfigText = restoredConfigText;
+exports.pathPairs = pathPairs;
+exports.rewritePaths = rewritePaths;
+exports.rewriteDatabase = rewriteDatabase;
+exports.hostJobsInFlight = hostJobsInFlight;
+exports.removeTree = removeTree;
+exports.journalPath = journalPath;
+exports.switchUnits = switchUnits;
+exports.rollBack = rollBack;
+exports.finishSwitch = finishSwitch;
+exports.destinationOf = destinationOf;
+exports.prefixesIn = prefixesIn;
+exports.workspaceInRoot = workspaceInRoot;
+exports.unitsFor = unitsFor;
+exports.clearOwnerThreads = clearOwnerThreads;
+exports.newRestoreId = newRestoreId;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const codex_thread_registry_1 = require("@jungjaehoon/mama-core/runtime/drivers/codex-thread-registry");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const yaml = __importStar(require("js-yaml"));
+const tar = __importStar(require("tar"));
+const daemon_js_1 = require("../commands/daemon.js");
+const backup_js_1 = require("./backup.js");
+const daemon_control_js_1 = require("./daemon-control.js");
+/** Every archive prefix a backup writes, and the configured key its destination comes from. */
+const PREFIX_KEYS = {
+    root: 'root',
+    workspace: 'workspace',
+    members: 'member_root',
+    skills: 'tools_root',
+    wiki: 'wiki',
+    'jev-vocab': 'jev_vocab',
+    'log-file': 'log_file',
+    database: 'database',
+    'credentials/auth.env': 'root',
+    'credentials/jev-key': 'jev_key',
+    'credentials/codex-auth.json': 'codex_home',
+    'credentials/mcp-config.json': 'mcp_config',
+};
+/** Prefixes whose entry is a folder; the rest are single files. */
+const FOLDER_PREFIXES = new Set(['root', 'workspace', 'members', 'skills', 'wiki']);
+/**
+ * Stored paths MAMA reads back to open a file: attachments in mailbox payloads (turn orders) and
+ * in the connector event index (deferred deliveries). The raw stores' content hash covers their
+ * metadata, so they, observation versions (evidence) and tool traces (history) keep the paths
+ * they recorded.
+ */
+exports.PATH_COLUMNS = [
+    ['mailbox_inputs', 'payload_json'],
+    ['connector_event_index', 'metadata_json'],
+];
+/** The folder roots that stored attachment paths sit under. */
+const REWRITTEN_KEYS = ['root', 'workspace', 'member_root', 'tools_root', 'wiki'];
+/**
+ * Config keys that name a place. A restored config keeps the backup's settings with this
+ * install's values for these, so the files and the config agree.
+ */
+const PATH_KEYS = [
+    ['member_root'],
+    ['tools_root'],
+    ['database', 'path'],
+    ['logging', 'file'],
+    ['jev', 'keyFile'],
+    ['jev', 'vocabFile'],
+    ['wiki', 'vaultPath'],
+    ['wiki', 'wikiDir'],
+    ['agent', 'codex_home'],
+    ['agent', 'codex_cwd'],
+    ['agent', 'tools', 'mcp_config'],
+];
+/** Where an install keeps each configured path. */
+function targetPaths(config, configPath, home) {
+    const paths = (0, daemon_js_1.pathsFor)(configPath, config);
+    return {
+        root: (0, node_path_1.resolve)(paths.mamaRoot),
+        workspace: (0, node_path_1.resolve)(paths.workspaceDir),
+        database: (0, node_path_1.resolve)(config.database.path),
+        member_root: config.member_root ? (0, node_path_1.resolve)(config.member_root) : null,
+        tools_root: config.tools_root ? (0, node_path_1.resolve)(config.tools_root) : null,
+        codex_home: (0, node_path_1.resolve)(config.agent.codex_home ?? (0, node_path_1.join)(paths.mamaRoot, '.codex')),
+        mcp_config: (0, node_path_1.resolve)(paths.mcpConfigPath),
+        log_file: (0, node_path_1.resolve)(config.logging.file),
+        jev_vocab: (0, node_path_1.resolve)(config.jev.vocabFile),
+        jev_key: (0, node_path_1.resolve)(config.jev.keyFile),
+        wiki: config.wiki?.enabled && config.wiki.vaultPath && config.wiki.wikiDir
+            ? (0, node_path_1.resolve)(config.wiki.vaultPath, config.wiki.wikiDir)
+            : null,
+        home: (0, node_path_1.resolve)(home),
+    };
+}
+function lexists(path) {
+    try {
+        (0, node_fs_1.lstatSync)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function prefixOf(path) {
+    const prefixes = Object.keys(PREFIX_KEYS).sort((left, right) => right.length - left.length);
+    return prefixes.find((prefix) => path === prefix || path.startsWith(`${prefix}/`)) ?? null;
+}
+function safeArchivePath(path) {
+    if (path === '' || (0, node_path_1.isAbsolute)(path) || path.includes('\0') || path.includes('\\'))
+        return false;
+    return path.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+/** The archive reads its first entry as the manifest and checks it as untrusted. */
+async function readManifest(archive) {
+    let first = null;
+    let text = '';
+    await tar.t({
+        file: archive,
+        onReadEntry: (entry) => {
+            const isFirst = first === null;
+            first ??= entry.path;
+            if (isFirst && entry.path === 'manifest.json') {
+                entry.on('data', (chunk) => (text += chunk.toString('utf8')));
+            }
+            else {
+                entry.resume();
+            }
+        },
+    });
+    if (first !== 'manifest.json')
+        throw new Error('the archive does not start with a manifest');
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch {
+        throw new Error('the archive manifest cannot be parsed');
+    }
+    validateManifest(manifest);
+    return manifest;
+}
+/**
+ * Hold a manifest to what `mama backup` writes. Anyone who can write the backups folder can
+ * replace an archive, and an archive can come from elsewhere, so the rules are structural:
+ * known prefixes and safe relative paths, only the root names a backup keeps, nothing beneath a
+ * link (a backup never walks through one), credentials only in a backup that says it has them.
+ */
+function validateManifest(manifest) {
+    if (manifest?.format !== 'mama-backup' || manifest.version !== 1) {
+        throw new Error('not a MAMA backup this version can read');
+    }
+    if (!Array.isArray(manifest.entries) || !Array.isArray(manifest.databases)) {
+        throw new Error('the archive manifest has no entry list');
+    }
+    const refuse = (path, why) => {
+        throw new Error(`the archive manifest names ${JSON.stringify(path)}, which ${why}`);
+    };
+    const configured = manifest.configured ?? {};
+    for (const [key, value] of Object.entries(configured)) {
+        if (value !== null && (!(0, node_path_1.isAbsolute)(value.configured) || !(0, node_path_1.isAbsolute)(value.physical))) {
+            throw new Error(`the archive manifest gives ${key} a relative path`);
+        }
+    }
+    const workspaceTop = workspaceInRoot(manifest);
+    const rootNames = new Set([
+        ...backup_js_1.ROOT_FILES,
+        ...backup_js_1.ROOT_DIRS,
+        ...(workspaceTop ? [workspaceTop] : []),
+    ]);
+    const runtimeNames = new Set([...backup_js_1.RUNTIME_FILES, ...backup_js_1.RUNTIME_DIRS]);
+    // Agents make links in workspaces, and published skills are links; nothing else a daemon
+    // writes through may be one (a planted downloads/ link would take the next attachment).
+    const linkAllowed = (parts) => {
+        const inWorkspace = parts.indexOf('workspace');
+        return ((parts[0] === 'workspace' && parts.length >= 2) ||
+            (parts[0] === 'root' &&
+                workspaceTop !== null &&
+                parts[1] === workspaceTop &&
+                parts.length >= 3) ||
+            (parts[0] === 'skills' && parts.length === 2) ||
+            (parts[0] === 'members' && inWorkspace >= 2 && inWorkspace < parts.length - 1));
+    };
+    if (workspaceTop && manifest.entries.some((entry) => prefixOf(entry.path) === 'workspace')) {
+        throw new Error('the archive manifest holds the workspace both inside the root and on its own');
+    }
+    const links = [];
+    const seen = new Set();
+    for (const entry of manifest.entries) {
+        const path = entry.path;
+        if (typeof path !== 'string' || !safeArchivePath(path) || seen.has(path)) {
+            refuse(String(path), 'is not a safe archive path');
+        }
+        const prefix = prefixOf(path);
+        if (prefix === null)
+            return refuse(path, 'is under no known prefix');
+        if (!['file', 'dir', 'symlink'].includes(entry.type))
+            refuse(path, 'has an unknown type');
+        if (entry.type === 'file' && !/^[0-9a-f]{64}$/.test(entry.sha256 ?? '')) {
+            refuse(path, 'has no hash');
+        }
+        if (prefix.startsWith('credentials/') && !manifest.includesSecrets) {
+            refuse(path, 'is a credential in a backup that says it holds none');
+        }
+        const folder = FOLDER_PREFIXES.has(prefix);
+        if (path === prefix && entry.type !== (folder ? 'dir' : 'file')) {
+            refuse(path, `is not a ${folder ? 'folder' : 'file'}`);
+        }
+        if (!folder && path !== prefix)
+            refuse(path, 'sits beneath a single-file prefix');
+        const parts = path.split('/');
+        if (prefix === 'root' && parts.length >= 2 && !rootNames.has(parts[1])) {
+            refuse(path, 'is not a name a backup keeps in the MAMA root');
+        }
+        if (prefix === 'root' && parts[1] === 'runtime' && parts.length >= 3) {
+            if (!runtimeNames.has(parts[2]))
+                refuse(path, 'is not a runtime file a backup keeps');
+        }
+        if (entry.type === 'symlink') {
+            if (typeof entry.target !== 'string' || entry.target === '')
+                refuse(path, 'links nowhere');
+            if (!linkAllowed(parts))
+                refuse(path, 'is a link where a backup holds none');
+            links.push(path);
+        }
+        seen.add(path);
+    }
+    for (const link of links) {
+        if (manifest.entries.some((entry) => entry.path.startsWith(`${link}/`))) {
+            refuse(link, 'is a link with entries beneath it');
+        }
+    }
+}
+function hashFile(path) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = (0, node_crypto_1.createHash)('sha256');
+        (0, node_fs_1.createReadStream)(path)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('end', () => resolvePromise(hash.digest('hex')))
+            .on('error', reject);
+    });
+}
+/**
+ * Extract the listed files and folders into a fresh folder and hold each to the manifest; links
+ * are made afterwards from the manifest itself (tar refuses absolute link targets, which a
+ * workspace can hold, and making them last means nothing is ever written through one).
+ */
+async function extractVerified(archive, manifest, staging) {
+    const expected = new Map(manifest.entries.map((entry) => [entry.path, entry]));
+    (0, node_fs_1.mkdirSync)(staging, { recursive: false, mode: 0o700 });
+    await tar.x({
+        file: archive,
+        cwd: staging,
+        strict: true,
+        // Each entry's tar type must be what the manifest says: a hard link listed as a file could
+        // tie a restored path to a file outside the archive.
+        filter: (path, entry) => {
+            const want = expected.get(path.replace(/\/+$/, ''));
+            const type = entry.type;
+            if (want?.type === 'file')
+                return type === 'File' || type === 'OldFile';
+            if (want?.type === 'dir')
+                return type === 'Directory';
+            return false;
+        },
+    });
+    const problems = [];
+    for (const entry of manifest.entries) {
+        if (entry.type === 'symlink')
+            continue;
+        const path = (0, node_path_1.join)(staging, ...entry.path.split('/'));
+        if (!lexists(path)) {
+            problems.push(`${entry.path} is missing`);
+            continue;
+        }
+        const stat = (0, node_fs_1.lstatSync)(path);
+        const type = stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'dir' : 'file';
+        if (type !== entry.type)
+            problems.push(`${entry.path} is a ${type}, not a ${entry.type}`);
+        else if (type === 'file' && (await hashFile(path)) !== entry.sha256) {
+            problems.push(`${entry.path} does not match its hash`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new Error(`the archive does not match its manifest (${problems.length}: ${problems.slice(0, 5).join('; ')})`);
+    }
+    for (const entry of manifest.entries) {
+        if (entry.type !== 'symlink')
+            continue;
+        const path = (0, node_path_1.join)(staging, ...entry.path.split('/'));
+        // The validator refused anything beneath a link, so the parent is a real staged folder.
+        if (!(0, node_fs_1.lstatSync)((0, node_path_1.dirname)(path)).isDirectory())
+            throw new Error(`${entry.path} has no folder`);
+        (0, node_fs_1.symlinkSync)(entry.target, path);
+    }
+}
+/** Set every entry's recorded mode: files first, then folders from the deepest up. */
+function applyModes(staging, entries) {
+    const at = (entry) => (0, node_path_1.join)(staging, ...entry.path.split('/'));
+    for (const entry of entries)
+        if (entry.type === 'file')
+            (0, node_fs_1.chmodSync)(at(entry), entry.mode);
+    const folders = entries
+        .filter((entry) => entry.type === 'dir')
+        .sort((left, right) => right.path.split('/').length - left.path.split('/').length);
+    for (const entry of folders)
+        (0, node_fs_1.chmodSync)(at(entry), entry.mode);
+}
+/**
+ * The backup's config with this install's places: every path key takes the value this install's
+ * config gives it, or is removed so this install's default applies. Comments do not survive.
+ */
+function restoredConfigText(backupText, targetText) {
+    const backup = (yaml.load(backupText) ?? {});
+    const target = (yaml.load(targetText) ?? {});
+    const read = (object, keys) => keys.reduce((node, key) => node && typeof node === 'object' ? node[key] : undefined, object);
+    for (const keys of PATH_KEYS) {
+        const value = read(target, keys);
+        const last = keys[keys.length - 1];
+        if (value !== undefined) {
+            // Create the parents a target value needs (a wiki the backup did not configure).
+            let node = backup;
+            for (const key of keys.slice(0, -1)) {
+                if (!node[key] || typeof node[key] !== 'object')
+                    node[key] = {};
+                node = node[key];
+            }
+            node[last] = value;
+        }
+        else {
+            const holder = keys.length === 1 ? backup : read(backup, keys.slice(0, -1));
+            if (holder && typeof holder === 'object')
+                delete holder[last];
+        }
+    }
+    return yaml.dump(backup, { lineWidth: -1, noRefs: true });
+}
+/** Old folder roots (both recorded forms) and their new places, longest first. */
+function pathPairs(configured, target) {
+    const pairs = new Map();
+    for (const key of REWRITTEN_KEYS) {
+        const old = configured[key];
+        const next = target[key];
+        if (!old || !next)
+            continue;
+        for (const form of [old.configured, old.physical]) {
+            if (form !== next && !pairs.has(form))
+                pairs.set(form, next);
+        }
+    }
+    return [...pairs].sort((left, right) => right[0].length - left[0].length);
+}
+/** Replace, in one pass, each JSON string that starts with an old root by the new root. */
+function rewritePaths(text, pairs) {
+    if (pairs.length === 0)
+        return text;
+    const next = new Map(pairs);
+    const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`"(${pairs.map(([old]) => escape(old)).join('|')})(?=[/"])`, 'g');
+    return text.replace(pattern, (_match, old) => `"${next.get(old)}`);
+}
+/**
+ * Rewrite stored attachment paths in a staged database. Update triggers on these tables would
+ * treat a changed row as a new event (connector_event_index renumbers its ingest sequence), so
+ * they are dropped and recreated from their own text around the update, in one transaction.
+ */
+function rewriteDatabase(path, columns, pairs) {
+    const db = new better_sqlite3_1.default(path, { fileMustExist: true });
+    let changed = 0;
+    try {
+        db.transaction(() => {
+            for (const [table, column] of columns) {
+                const exists = db
+                    .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?")
+                    .get(table);
+                if (!exists)
+                    continue;
+                const triggers = db
+                    .prepare("SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND tbl_name = ?")
+                    .all(table);
+                // The staged database came from the archive: its schema text is data, run one
+                // statement at a time and only as what it claims to be.
+                for (const trigger of triggers) {
+                    if (!/^\s*CREATE\s+TRIGGER\b/i.test(trigger.sql ?? '')) {
+                        throw new Error(`trigger ${JSON.stringify(trigger.name)} has no CREATE TRIGGER text`);
+                    }
+                    db.prepare(`DROP TRIGGER "${trigger.name.replace(/"/g, '""')}"`).run();
+                }
+                const update = db.prepare(`UPDATE "${table}" SET "${column}" = ? WHERE rowid = ?`);
+                const rows = db
+                    .prepare(`SELECT rowid AS id, "${column}" AS value FROM "${table}" WHERE instr("${column}", '"/') > 0`)
+                    .all();
+                for (const row of rows) {
+                    const value = rewritePaths(row.value, pairs);
+                    if (value !== row.value)
+                        changed += update.run(value, row.id).changes;
+                }
+                // prepare() compiles exactly one statement and refuses a string with more.
+                for (const trigger of triggers)
+                    db.prepare(trigger.sql).run();
+            }
+        })();
+    }
+    finally {
+        db.close();
+    }
+    return changed;
+}
+/** Host jobs in flight hold absolute paths and inode snapshots that cannot survive a move. */
+function hostJobsInFlight(path) {
+    const db = new better_sqlite3_1.default(path, { readonly: true, fileMustExist: true });
+    try {
+        const exists = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'mailbox_host_checkpoints'")
+            .get();
+        if (!exists)
+            return 0;
+        // A finished or abandoned job keeps its row until its input is pruned; only open ones count.
+        return db
+            .prepare(`SELECT COUNT(*) AS n FROM mailbox_host_checkpoints c
+             JOIN mailbox_inputs m ON m.id = c.input_id
+            WHERE m.status IN ('pending', 'claimed')`)
+            .get().n;
+    }
+    finally {
+        db.close();
+    }
+}
+/** Remove a tree whose folders may be sealed read-only, without following links. */
+function removeTree(path) {
+    if (!lexists(path))
+        return;
+    const open = (current) => {
+        const stat = (0, node_fs_1.lstatSync)(current);
+        if (!stat.isDirectory())
+            return;
+        (0, node_fs_1.chmodSync)(current, 0o700);
+        for (const name of (0, node_fs_1.readdirSync)(current))
+            open((0, node_path_1.join)(current, name));
+    };
+    open(path);
+    (0, node_fs_1.rmSync)(path, { recursive: true, force: true });
+}
+function journalPath(root) {
+    return (0, daemon_control_js_1.restoreJournalPath)(root);
+}
+/** Write the journal so it survives a power cut: whole, flushed, then renamed into place. */
+function writeJournal(root, journal) {
+    const path = journalPath(root);
+    const staged = `${path}.${process.pid}.tmp`;
+    const fd = (0, node_fs_1.openSync)(staged, 'w', 0o600);
+    try {
+        (0, node_fs_1.writeSync)(fd, `${JSON.stringify(journal)}\n`);
+        (0, node_fs_1.fsyncSync)(fd);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    (0, node_fs_1.renameSync)(staged, path);
+    const folder = (0, node_fs_1.openSync)((0, node_path_1.dirname)(path), 'r');
+    try {
+        (0, node_fs_1.fsyncSync)(folder);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(folder);
+    }
+}
+/** Move a staged tree beside its destination, so the switch is a rename on one filesystem. */
+function moveBeside(staged, sibling) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(sibling), { recursive: true });
+    try {
+        (0, node_fs_1.renameSync)(staged, sibling);
+    }
+    catch (error) {
+        // Another filesystem (a Docker volume, a separate disk): copy, keeping links and modes.
+        if (error.code !== 'EXDEV')
+            throw error;
+        (0, node_fs_1.cpSync)(staged, sibling, {
+            recursive: true,
+            verbatimSymlinks: true,
+            preserveTimestamps: true,
+            errorOnExist: true,
+            force: false,
+        });
+        removeTree(staged);
+    }
+}
+function moveWith(from, to, ends) {
+    for (const end of ends)
+        if (lexists(from + end))
+            (0, node_fs_1.renameSync)(from + end, to + end);
+}
+/**
+ * Put every staged copy in place. For each unit the copy moves beside its destination, the
+ * destination goes aside, and the copy takes its name. The journal records each step before it
+ * happens; a failure, or a later `mama restore --rollback`, puts every destination back from what
+ * is on disk. Nothing set aside is deleted until the journal says the whole switch held.
+ */
+function switchUnits(root, units, id, rename = node_fs_1.renameSync) {
+    // Two units with one destination, or one inside another, would set aside each other's copy.
+    const destinations = units.map((unit) => (0, node_path_1.resolve)(unit.destination)).sort();
+    destinations.forEach((destination, index) => {
+        const next = destinations[index + 1];
+        if (next !== undefined && (next === destination || next.startsWith(`${destination}/`))) {
+            throw new Error(`two parts of the archive go to ${next}`);
+        }
+    });
+    const journal = {
+        id,
+        committed: false,
+        steps: units.map((unit) => ({
+            destination: unit.destination,
+            sibling: (0, node_path_1.join)((0, node_path_1.dirname)(unit.destination), `.mama-restore-${id}-${(0, node_path_1.basename)(unit.destination)}`),
+            aside: (0, node_path_1.join)((0, node_path_1.dirname)(unit.destination), `.mama-restore-${id}-old-${(0, node_path_1.basename)(unit.destination)}`),
+            companionEnds: (unit.companions ?? []).map((path) => path.slice(unit.destination.length)),
+            existed: lexists(unit.destination),
+            state: 'planned',
+        })),
+    };
+    writeJournal(root, journal);
+    try {
+        units.forEach((unit, index) => {
+            const step = journal.steps[index];
+            moveBeside(unit.staged, step.sibling);
+            step.state = 'moving-aside';
+            writeJournal(root, journal);
+            if (step.existed)
+                rename(step.destination, step.aside);
+            moveWith(step.destination, step.aside, step.companionEnds);
+            step.state = 'switching';
+            writeJournal(root, journal);
+            rename(step.sibling, step.destination);
+            step.state = 'switched';
+            writeJournal(root, journal);
+        });
+    }
+    catch (error) {
+        try {
+            rollBack(root);
+        }
+        catch (rollbackError) {
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; putting it back also failed (${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}), so the journal at ${journalPath(root)} is kept for mama restore --rollback`);
+        }
+        throw error;
+    }
+    journal.committed = true;
+    writeJournal(root, journal);
+}
+/**
+ * Undo an uncommitted switch from what is on disk, then drop the journal. A committed switch
+ * held: its leftovers are cleared instead. Returns how many destinations were put back, or null
+ * when the switch had committed.
+ */
+function rollBack(root, rename = node_fs_1.renameSync) {
+    const path = journalPath(root);
+    if (!(0, node_fs_1.existsSync)(path))
+        return 0;
+    const journal = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    if (journal.committed) {
+        finishSwitch(root);
+        return null;
+    }
+    let undone = 0;
+    for (const step of [...journal.steps].reverse()) {
+        // Each step's undoing is recorded as it is done, so a rollback that stops can run again.
+        if (step.state === 'rolled-back')
+            continue;
+        const reached = step.state === 'switching' || step.state === 'switched';
+        // The copy is in place only if it left its sibling name: move it back out first.
+        if (reached && !lexists(step.sibling) && lexists(step.destination)) {
+            rename(step.destination, step.sibling);
+            for (const end of step.companionEnds) {
+                if (lexists(step.destination + end))
+                    rename(step.destination + end, step.sibling + end);
+            }
+        }
+        if (lexists(step.aside)) {
+            if (lexists(step.destination)) {
+                throw new Error(`${step.destination} and its set-aside copy both exist; resolve by hand`);
+            }
+            rename(step.aside, step.destination);
+            for (const end of step.companionEnds) {
+                if (lexists(step.aside + end))
+                    rename(step.aside + end, step.destination + end);
+            }
+            undone += 1;
+        }
+        else if (step.existed && !lexists(step.destination)) {
+            throw new Error(`${step.destination} is missing and nothing was set aside for it`);
+        }
+        removeTree(step.sibling);
+        for (const end of step.companionEnds)
+            (0, node_fs_1.rmSync)(step.sibling + end, { force: true });
+        step.state = 'rolled-back';
+        writeJournal(root, journal);
+    }
+    (0, node_fs_1.rmSync)(path, { force: true });
+    return undone;
+}
+/** After a committed switch: drop what went aside, then the journal. */
+function finishSwitch(root) {
+    const path = journalPath(root);
+    const journal = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    if (!journal.committed)
+        throw new Error('the restore journal is not committed');
+    // A committed switch put every copy in place; a missing one means something moved it, and
+    // the set-aside copy may then be the only one left.
+    const missing = journal.steps.filter((step) => !lexists(step.destination) && lexists(step.aside));
+    if (missing.length > 0) {
+        throw new Error(`${missing.map((step) => step.destination).join(', ')} is missing while its set-aside copy remains; resolve by hand`);
+    }
+    for (const step of journal.steps) {
+        removeTree(step.aside);
+        for (const end of step.companionEnds)
+            (0, node_fs_1.rmSync)(step.aside + end, { force: true });
+    }
+    (0, node_fs_1.rmSync)(path, { force: true });
+}
+/** Each archive prefix's destination, from the restored install's configuration by key. */
+function destinationOf(prefix, target) {
+    const key = PREFIX_KEYS[prefix];
+    const base = target[key];
+    if (!base) {
+        throw new Error(`the archive holds ${prefix}, but this install has no ${key} configured; set it in config.yaml first`);
+    }
+    if (prefix === 'skills')
+        return (0, node_path_1.join)(base, 'skills');
+    if (prefix === 'credentials/auth.env')
+        return (0, node_path_1.join)(base, 'auth.env');
+    if (prefix === 'credentials/codex-auth.json')
+        return (0, node_path_1.join)(base, 'auth.json');
+    return base;
+}
+/** The archive prefixes present, in the manifest's order. */
+function prefixesIn(manifest) {
+    const found = [];
+    for (const entry of manifest.entries) {
+        const prefix = prefixOf(entry.path);
+        if (prefix && !found.includes(prefix))
+            found.push(prefix);
+    }
+    return found;
+}
+/** The workspace's folder name when the backup kept it inside the MAMA root. */
+function workspaceInRoot(manifest) {
+    const root = manifest.configured?.root?.physical;
+    const workspace = manifest.configured?.workspace?.physical;
+    return root && workspace && (0, node_path_1.dirname)(workspace) === root ? (0, node_path_1.basename)(workspace) : null;
+}
+/** The units a prefix switches: a folder's children one by one, never the folder itself. */
+function unitsFor(prefix, staging, destination, manifest, workspace) {
+    const staged = (0, node_path_1.join)(staging, ...prefix.split('/'));
+    if (!FOLDER_PREFIXES.has(prefix)) {
+        return [
+            {
+                staged,
+                destination,
+                // A WAL left beside the old database would be applied to the new one.
+                ...(prefix === 'database'
+                    ? { companions: ['-wal', '-shm', '-journal'].map((end) => destination + end) }
+                    : {}),
+            },
+        ];
+    }
+    const folder = manifest.entries.find((entry) => entry.path === prefix);
+    if (!lexists(destination)) {
+        (0, node_fs_1.mkdirSync)(destination, { recursive: true, mode: folder?.mode ?? 0o700 });
+    }
+    const units = [];
+    for (const name of (0, node_fs_1.readdirSync)(staged)) {
+        // start.sh names this machine's Node and paths; mama service install writes it.
+        if (prefix === 'root' && name === 'start.sh')
+            continue;
+        // A workspace the backup kept inside the root goes where this install keeps its own.
+        if (prefix === 'root' && workspace && name === workspaceInRoot(manifest)) {
+            if (!lexists(workspace))
+                (0, node_fs_1.mkdirSync)(workspace, { recursive: true, mode: 0o700 });
+            for (const child of (0, node_fs_1.readdirSync)((0, node_path_1.join)(staged, name))) {
+                units.push({ staged: (0, node_path_1.join)(staged, name, child), destination: (0, node_path_1.join)(workspace, child) });
+            }
+            continue;
+        }
+        // runtime/ holds the install lock, so its files are switched one by one.
+        if (prefix === 'root' && name === 'runtime') {
+            const runtime = (0, node_path_1.join)(destination, 'runtime');
+            if (!lexists(runtime))
+                (0, node_fs_1.mkdirSync)(runtime, { recursive: true, mode: 0o700 });
+            for (const child of (0, node_fs_1.readdirSync)((0, node_path_1.join)(staged, 'runtime'))) {
+                units.push({ staged: (0, node_path_1.join)(staged, 'runtime', child), destination: (0, node_path_1.join)(runtime, child) });
+            }
+            continue;
+        }
+        units.push({ staged: (0, node_path_1.join)(staged, name), destination: (0, node_path_1.join)(destination, name) });
+    }
+    return units;
+}
+/** The owner's Codex threads belong to the state before the restore; they start over. */
+function clearOwnerThreads(root) {
+    const threadRoot = (0, node_path_1.join)(root, 'codex-runtime', 'threads');
+    if (!(0, node_fs_1.existsSync)(threadRoot))
+        return 0;
+    const registry = new codex_thread_registry_1.CodexThreadRegistry({ rootDir: threadRoot });
+    let cleared = 0;
+    for (const key of ['owner:runtime', 'owner:replay']) {
+        if (registry.load(key)) {
+            registry.remove(key);
+            cleared += 1;
+        }
+    }
+    return cleared;
+}
+function newRestoreId() {
+    return (0, node_crypto_1.randomUUID)().slice(0, 8);
+}
+//# sourceMappingURL=restore.js.map