crewhaus 0.1.8 → 0.2.0

package/dist/state-backup.js

@@ -0,0 +1,648 @@
+/**
+ * Item 69 — `crewhaus state backup|restore`: snapshot and transport the
+ * cwd-local `.crewhaus/` state directory.
+ *
+ * A harness's entire accumulated state — sessions, feedback, memories,
+ * datasets, spec registry, optimize runs, durable-state sqlite — lives in
+ * `.crewhaus/` next to wherever the harness runs. That locality is a feature
+ * (the standalone-harness convention) until the box dies, or until feedback
+ * captured on a DEPLOYED bot needs to travel back to the dev machine before
+ * `crewhaus distill` can learn from it. `backup` packs the dir into a
+ * gzipped tarball with a manifest; `restore` unpacks it — full replace
+ * (`--force`, existing state moved aside, never deleted) or additive merges
+ * (`--merge feedback|all`).
+ *
+ * Like `feedback.ts` / `justification-gate.ts`, this module has NO
+ * import-time side effects (the entry file `index.ts` runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * The exported functions do touch the filesystem and spawn the system `tar`
+ * binary: Bun (1.3.x) ships gzip (`Bun.gzipSync`) but no tar API and the
+ * repo takes no archive dependency, so the ubiquitous system `tar` (bsdtar
+ * on macOS/Windows, GNU tar on Linux) does the packing/unpacking via
+ * `Bun.spawn` argv arrays (no shell). Backup NEVER modifies a source file:
+ * every archived file is staged as an exact byte copy — which is what makes
+ * the round-trip byte-identical, so a hash-chained `.crewhaus/audit` dir
+ * still passes `@crewhaus/audit-log`'s `verify()` after backup → restore.
+ *
+ * SQLITE SAFETY: a live `@crewhaus/durable-state` writer (WAL journaling)
+ * can tear a naive byte copy — the main db file alone is missing whatever
+ * sits in `-wal`. Any file carrying the SQLite magic header is therefore
+ * snapshotted through `bun:sqlite`: open read-only, `db.serialize()` (the
+ * sqlite serialize API — a consistent point-in-time image with WAL frames
+ * folded in), and the snapshot bytes are archived in place of the raw file;
+ * its `-wal`/`-shm`/`-journal` sidecars are dropped as folded. When a
+ * snapshot fails (corrupt file, exclusive lock) the raw bytes are copied
+ * instead and the manifest records `sqliteConsistent: false` so the
+ * operator knows the copy may be torn.
+ *
+ * Deliberately OUT OF SCOPE: S3/R2 upload (sync the tarball with your own
+ * tooling — `aws s3 cp`, rclone, …) and a scheduled-cron template (a
+ * `templates/` convention is landing on another branch).
+ */
+import { Database } from "bun:sqlite";
+import { closeSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { extractFeedbackRecords, mergeFeedback } from "./feedback";
+/** Manifest file name at the archive root (NOT restored into `.crewhaus`). */
+export const MANIFEST_FILENAME = "backup-manifest.json";
+/** First 16 bytes of every SQLite main database file: "SQLite format 3\\0"
+ *  (spelled as code points so the source carries no literal NUL). */
+const SQLITE_MAGIC_BYTES = new Uint8Array([
+    0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74, 0x20, 0x33, 0x00,
+]);
+/** Sidecar suffixes a live sqlite writer leaves next to the main db file. */
+const SQLITE_SIDECAR_SUFFIXES = ["-wal", "-shm", "-journal"];
+/** Thrown for every operational failure (missing dir, tar failure, bad
+ *  archive). The CLI entry file catches it and routes the message through
+ *  `die()`; tests assert on `.message` without the process exiting. The
+ *  `name` stays a plain string so `StateRestoreRefusedError` can narrow it. */
+export class StateBackupError extends Error {
+    name = "StateBackupError";
+}
+/** Thrown when `restore` (without --force/--merge) would overwrite an
+ *  existing non-empty `.crewhaus`. Carries a preformatted message listing
+ *  what is there and how to proceed. */
+export class StateRestoreRefusedError extends StateBackupError {
+    stateDir;
+    name = "StateRestoreRefusedError";
+    constructor(stateDir, entries) {
+        const listing = entries
+            .map((e) => (e.kind === "dir" ? `${e.name}/ (${e.files} file(s))` : e.name))
+            .join(", ");
+        super([
+            `refusing to overwrite existing non-empty ${stateDir}`,
+            `  contains: ${listing}`,
+            "  rerun with --force to replace it (the current dir is moved aside to " +
+                ".crewhaus.bak-<ts>, never deleted), or --merge feedback|all to fold " +
+                "the archive into it",
+        ].join("\n"));
+        this.stateDir = stateDir;
+    }
+}
+/** Pure manifest assembly from the archived file list + backup metadata. */
+export function buildManifest(files, meta) {
+    const subdirs = {};
+    let totalFiles = 0;
+    let totalBytes = 0;
+    for (const f of files) {
+        const slash = f.relPath.indexOf("/");
+        const top = slash === -1 ? "." : f.relPath.slice(0, slash);
+        const stat = subdirs[top] ?? { files: 0, bytes: 0 };
+        stat.files += 1;
+        stat.bytes += f.bytes;
+        subdirs[top] = stat;
+        totalFiles += 1;
+        totalBytes += f.bytes;
+    }
+    return {
+        schemaVersion: 1,
+        createdAt: meta.createdAt,
+        sourceDir: meta.sourceDir,
+        crewhausVersion: meta.crewhausVersion,
+        totals: { files: totalFiles, bytes: totalBytes },
+        subdirs,
+        sqliteConsistent: meta.sqliteConsistent,
+        sqlite: meta.sqlite,
+    };
+}
+/** Narrow a parsed JSON value to a BackupManifest (tolerant structural check —
+ *  a hand-made or future-versioned manifest should degrade to a warning, not
+ *  a crash). */
+export function isBackupManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (v["schemaVersion"] === 1 &&
+        typeof v["createdAt"] === "string" &&
+        typeof v["sourceDir"] === "string" &&
+        typeof v["crewhausVersion"] === "string" &&
+        typeof v["totals"] === "object" &&
+        v["totals"] !== null &&
+        typeof v["subdirs"] === "object" &&
+        v["subdirs"] !== null);
+}
+// ---------------------------------------------------------------------------
+// Pure helpers — names, exclude globs, sqlite detection, merge planning
+// ---------------------------------------------------------------------------
+/** Collapse a harness name / dir basename to a filename-safe label. */
+export function sanitizeBackupLabel(label) {
+    const cleaned = label.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned === "" ? "state" : cleaned;
+}
+/** Default tarball name: `crewhaus-state-<label>-<ISO date>.tar.gz`. */
+export function defaultBackupFileName(label, now) {
+    return `crewhaus-state-${sanitizeBackupLabel(label)}-${now.toISOString().slice(0, 10)}.tar.gz`;
+}
+/** Split a comma-separated `--exclude` value into trimmed non-empty globs. */
+export function parseExcludeGlobs(raw) {
+    if (raw === undefined)
+        return [];
+    return raw
+        .split(",")
+        .map((g) => g.trim())
+        .filter((g) => g !== "");
+}
+/**
+ * Whether a state-dir-relative path (always "/"-separated) matches any
+ * exclude glob. A glob is matched against the full relative path; a bare
+ * pattern (no "/") additionally matches any single path segment, mirroring
+ * tar's basename `--exclude` ergonomics — so `sessions` drops the whole
+ * subdir and `*.sqlite` drops sqlite files anywhere in the tree.
+ */
+export function isExcluded(relPath, globs) {
+    for (const g of globs) {
+        const glob = new Bun.Glob(g);
+        if (glob.match(relPath))
+            return true;
+        if (!g.includes("/") && relPath.split("/").some((segment) => glob.match(segment))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Whether `bytes` starts with the 16-byte SQLite main-db magic header. */
+export function isSqliteHeader(bytes) {
+    if (bytes.length < SQLITE_MAGIC_BYTES.length)
+        return false;
+    for (let i = 0; i < SQLITE_MAGIC_BYTES.length; i++) {
+        if (bytes[i] !== SQLITE_MAGIC_BYTES[i])
+            return false;
+    }
+    return true;
+}
+/** For a `-wal`/`-shm`/`-journal` sidecar path, the main db path it belongs
+ *  to; undefined for everything else. */
+export function sqliteSidecarBase(relPath) {
+    for (const suffix of SQLITE_SIDECAR_SUFFIXES) {
+        if (relPath.endsWith(suffix))
+            return relPath.slice(0, -suffix.length);
+    }
+    return undefined;
+}
+/** Plan a `--merge all` additive copy: only files that don't exist locally
+ *  are copied; existing local files always win. Pure via the injected
+ *  existence predicate. */
+export function planAdditiveMerge(archiveFiles, existsLocally) {
+    const copy = [];
+    const skip = [];
+    for (const f of archiveFiles) {
+        (existsLocally(f) ? skip : copy).push(f);
+    }
+    return { copy, skip };
+}
+function feedbackKey(r) {
+    return `${r.sessionId}#${r.turnNumber}`;
+}
+/** Key-order-insensitive record identity, so a re-folded record that carries
+ *  exactly the local information counts as unchanged. */
+function canonicalRecord(r) {
+    const rec = r;
+    const sorted = {};
+    for (const k of Object.keys(rec).sort())
+        sorted[k] = rec[k];
+    return JSON.stringify(sorted);
+}
+/**
+ * Plan a `--merge feedback` fold using the exact dedupe semantics `crewhaus
+ * distill` applies: `mergeFeedback` collapses records to one per
+ * (sessionId, turnNumber), newest field wins, and a later comment-only
+ * record never erases an earlier rating. Local and archived records are
+ * each folded first, then each archived fold is folded AGAINST the local
+ * fold for its key — imported only when the archive actually contributes
+ * something (new key, or a fold that differs from the local one). Running
+ * the same merge twice is therefore a no-op.
+ */
+export function planFeedbackMerge(local, archived) {
+    const localByKey = new Map();
+    for (const r of mergeFeedback(local))
+        localByKey.set(feedbackKey(r), r);
+    const toImport = [];
+    let added = 0;
+    let updated = 0;
+    let unchanged = 0;
+    for (const a of mergeFeedback(archived)) {
+        const l = localByKey.get(feedbackKey(a));
+        if (l === undefined) {
+            toImport.push(a);
+            added += 1;
+            continue;
+        }
+        const folded = mergeFeedback([l, a])[0];
+        if (canonicalRecord(folded) === canonicalRecord(l)) {
+            unchanged += 1;
+        }
+        else {
+            toImport.push(folded);
+            updated += 1;
+        }
+    }
+    return { toImport, added, updated, unchanged };
+}
+function walkFiles(root) {
+    const files = [];
+    const dirs = [];
+    const symlinks = [];
+    const visit = (rel) => {
+        const abs = rel === "" ? root : join(root, rel);
+        for (const entry of readdirSync(abs, { withFileTypes: true })) {
+            const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isSymbolicLink()) {
+                symlinks.push(childRel);
+            }
+            else if (entry.isDirectory()) {
+                dirs.push(childRel);
+                visit(childRel);
+            }
+            else if (entry.isFile()) {
+                files.push(childRel);
+            }
+        }
+    };
+    visit("");
+    files.sort();
+    dirs.sort();
+    symlinks.sort();
+    return { files, dirs, symlinks };
+}
+/** Run the system `tar` binary (argv array — no shell). Throws
+ *  StateBackupError with tar's stderr on a non-zero exit. */
+async function runTar(args) {
+    let proc;
+    try {
+        proc = Bun.spawn(["tar", ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    }
+    catch (err) {
+        const detail = err.message;
+        throw new StateBackupError(`could not spawn the system \`tar\` binary (${detail}) — crewhaus state backup/restore needs tar on PATH`);
+    }
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    if (exitCode !== 0) {
+        throw new StateBackupError(`tar ${args[0]} failed (exit ${exitCode}): ${stderr.trim()}`);
+    }
+    return stdout;
+}
+/** Read the first 16 bytes of a file and test the SQLite magic. */
+function fileHasSqliteHeader(absPath) {
+    const buf = new Uint8Array(SQLITE_MAGIC_BYTES.length);
+    let fd;
+    try {
+        fd = openSync(absPath, "r");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        return n === buf.length && isSqliteHeader(buf);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Archive `stateDir` to a gzipped tarball. Every regular file is staged as
+ * an exact byte copy (sqlite files as a consistent read-only snapshot — see
+ * the file header), a manifest is written at the archive root, and the
+ * system `tar` packs the staging dir. Source files are never modified.
+ */
+export async function createStateBackup(opts) {
+    const stateDir = resolve(opts.stateDir);
+    if (!existsSync(stateDir) || !statSync(stateDir).isDirectory()) {
+        throw new StateBackupError(`no state directory at ${stateDir} — nothing to back up`);
+    }
+    const globs = opts.excludeGlobs ?? [];
+    const warnings = [];
+    const { files, dirs, symlinks } = walkFiles(stateDir);
+    for (const s of symlinks) {
+        warnings.push(`skipped symlink ${s} (backups archive regular files only)`);
+    }
+    const excluded = [];
+    const kept = [];
+    for (const f of files) {
+        (isExcluded(f, globs) ? excluded : kept).push(f);
+    }
+    const outFile = resolve(opts.outFile);
+    mkdirSync(dirname(outFile), { recursive: true });
+    const staging = mkdtempSync(join(tmpdir(), "crewhaus-state-backup-"));
+    try {
+        // Preserve the directory shape (including empty dirs) so a restore
+        // reproduces the layout, not just the files.
+        for (const d of dirs) {
+            if (!isExcluded(d, globs))
+                mkdirSync(join(staging, d), { recursive: true });
+        }
+        // SQLITE SAFETY — snapshot every magic-headed file via a read-only
+        // serialize; fall back to a raw byte copy (recorded in the manifest)
+        // when the snapshot fails.
+        const snapshotted = [];
+        const copiedRaw = [];
+        const foldedSidecars = new Set();
+        let sqliteConsistent = true;
+        const keptSet = new Set(kept);
+        for (const rel of kept) {
+            if (!fileHasSqliteHeader(join(stateDir, rel)))
+                continue;
+            try {
+                const db = new Database(join(stateDir, rel), { readonly: true });
+                let snapshot;
+                try {
+                    snapshot = db.serialize();
+                }
+                finally {
+                    db.close();
+                }
+                mkdirSync(dirname(join(staging, rel)), { recursive: true });
+                writeFileSync(join(staging, rel), snapshot);
+                // Adversarial-review F4: `serialize()` preserves the source's
+                // journal mode, so a WAL-mode source yields a WAL-mode snapshot —
+                // which a READ-ONLY consumer cannot open (SQLite needs to create
+                // `-wal`/`-shm` on the first open of a WAL db, and we archive no
+                // sidecars). Flip the STAGED copy to a rollback journal before it
+                // is packed; the live source db is untouched. A failure here falls
+                // through to the raw-copy path below like any other snapshot error.
+                const staged = new Database(join(staging, rel));
+                try {
+                    staged.run("PRAGMA journal_mode=DELETE");
+                }
+                finally {
+                    staged.close();
+                }
+                // The mode flip itself can leave a stray `-shm` beside the staged
+                // file (observed on bun 1.3 / macOS even after close) — scrub any
+                // sidecars so they don't get packed.
+                for (const suffix of SQLITE_SIDECAR_SUFFIXES) {
+                    rmSync(join(staging, `${rel}${suffix}`), { force: true });
+                }
+                snapshotted.push(rel);
+                // The snapshot folds WAL frames in; archiving the sidecars alongside
+                // it would restore a db whose WAL disagrees with its main file.
+                for (const suffix of SQLITE_SIDECAR_SUFFIXES) {
+                    const sidecar = `${rel}${suffix}`;
+                    if (keptSet.has(sidecar))
+                        foldedSidecars.add(sidecar);
+                }
+            }
+            catch (err) {
+                sqliteConsistent = false;
+                copiedRaw.push(rel);
+                const detail = err.message;
+                warnings.push(`could not snapshot sqlite file ${rel} (${detail}) — copied raw bytes instead; the copy may be inconsistent if a writer was active (manifest records sqliteConsistent: false)`);
+            }
+        }
+        const snapshottedSet = new Set(snapshotted);
+        const archived = [];
+        for (const rel of kept) {
+            if (foldedSidecars.has(rel))
+                continue;
+            const dst = join(staging, rel);
+            if (!snapshottedSet.has(rel)) {
+                mkdirSync(dirname(dst), { recursive: true });
+                copyFileSync(join(stateDir, rel), dst);
+            }
+            archived.push({ relPath: rel, bytes: statSync(dst).size });
+        }
+        const manifest = buildManifest(archived, {
+            createdAt: (opts.now?.() ?? new Date()).toISOString(),
+            sourceDir: stateDir,
+            crewhausVersion: opts.crewhausVersion,
+            sqliteConsistent,
+            sqlite: {
+                snapshotted,
+                copiedRaw,
+                foldedSidecars: [...foldedSidecars].sort(),
+            },
+        });
+        writeFileSync(join(staging, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`);
+        await runTar(["-czf", outFile, "-C", staging, "."]);
+        return { manifest, outFile, excluded, warnings };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** What (if anything) currently occupies the target `.crewhaus` dir. */
+export function inspectStateDir(stateDir) {
+    if (!existsSync(stateDir))
+        return { state: "absent" };
+    const top = readdirSync(stateDir, { withFileTypes: true });
+    if (top.length === 0)
+        return { state: "empty" };
+    const entries = top
+        .map((e) => {
+        if (!e.isDirectory())
+            return { name: e.name, kind: "file", files: 1 };
+        return { name: e.name, kind: "dir", files: walkFiles(join(stateDir, e.name)).files.length };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { state: "occupied", entries };
+}
+function assertArchiveExists(archiveFile) {
+    if (!existsSync(archiveFile)) {
+        throw new StateBackupError(`archive not found at ${archiveFile}`);
+    }
+}
+/** Extract `archiveFile` into a fresh temp dir under `parentDir` and return
+ *  the temp path (caller cleans up). */
+async function extractToTemp(archiveFile, parentDir) {
+    mkdirSync(parentDir, { recursive: true });
+    const temp = mkdtempSync(join(parentDir, ".crewhaus.extract-"));
+    try {
+        await runTar(["-xzf", archiveFile, "-C", temp]);
+    }
+    catch (err) {
+        rmSync(temp, { recursive: true, force: true });
+        throw err;
+    }
+    return temp;
+}
+function readExtractedManifest(extractedDir, warnings) {
+    const p = join(extractedDir, MANIFEST_FILENAME);
+    if (!existsSync(p)) {
+        warnings.push(`archive carries no ${MANIFEST_FILENAME} — not created by \`crewhaus state backup\`?`);
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        if (isBackupManifest(parsed))
+            return parsed;
+        warnings.push(`archive's ${MANIFEST_FILENAME} has an unrecognized shape — ignored`);
+    }
+    catch {
+        warnings.push(`archive's ${MANIFEST_FILENAME} is not valid JSON — ignored`);
+    }
+    return undefined;
+}
+/** Collision-safe `.crewhaus.bak-<ts>` sibling path. */
+function bakPath(stateDir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let candidate = `${stateDir}.bak-${stamp}`;
+    let n = 2;
+    while (existsSync(candidate)) {
+        candidate = `${stateDir}.bak-${stamp}-${n}`;
+        n += 1;
+    }
+    return candidate;
+}
+/**
+ * Full restore of a backup into `<intoDir>/.crewhaus`. Refuses (throws
+ * `StateRestoreRefusedError`) when the target is non-empty and `force` is
+ * not set. Extraction happens in a sibling temp dir which is renamed into
+ * place, so a half-extracted archive can never corrupt existing state, and
+ * restored file bytes are exactly the archived bytes (tar preserves them;
+ * nothing is rewritten).
+ */
+export async function restoreStateArchive(opts) {
+    const archiveFile = resolve(opts.archiveFile);
+    assertArchiveExists(archiveFile);
+    const stateDir = join(resolve(opts.intoDir), ".crewhaus");
+    const inspection = inspectStateDir(stateDir);
+    if (inspection.state === "occupied" && !opts.force) {
+        throw new StateRestoreRefusedError(stateDir, inspection.entries);
+    }
+    const warnings = [];
+    // Sibling temp dir (same filesystem as the target) so the final move is a
+    // plain rename.
+    const temp = await extractToTemp(archiveFile, dirname(stateDir));
+    try {
+        const manifest = readExtractedManifest(temp, warnings);
+        // The manifest describes the backup; it is not state. Drop our extracted
+        // copy so the restored `.crewhaus` contains exactly the archived state
+        // (provenance stays inside the tarball).
+        rmSync(join(temp, MANIFEST_FILENAME), { force: true });
+        let movedAsideTo;
+        if (inspection.state === "empty") {
+            rmdirSync(stateDir); // empty — nothing to preserve
+        }
+        else if (inspection.state === "occupied") {
+            movedAsideTo = bakPath(stateDir);
+            renameSync(stateDir, movedAsideTo);
+        }
+        renameSync(temp, stateDir);
+        return {
+            stateDir,
+            ...(movedAsideTo !== undefined ? { movedAsideTo } : {}),
+            ...(manifest !== undefined ? { manifest } : {}),
+            filesRestored: walkFiles(stateDir).files.length,
+            warnings,
+        };
+    }
+    finally {
+        // No-op after the successful rename; cleans up on any earlier failure.
+        rmSync(temp, { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// --merge feedback | --merge all
+// ---------------------------------------------------------------------------
+/** Parse a JSONL blob into objects, skipping blank/malformed lines (mirrors
+ *  the entry file's tolerant reader — one corrupt line must not abort a
+ *  merge). */
+function parseJsonlObjects(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // tolerated
+        }
+    }
+    return out;
+}
+/**
+ * Every FeedbackRecord a state dir carries, read exactly the way `crewhaus
+ * distill` reads them: `user_feedback` event-log lines in
+ * `sessions/*.jsonl` PLUS bare records in `feedback/*.jsonl` (the web-UI
+ * host sink). `extractFeedbackRecords` accepts both encodings and validates
+ * each record.
+ */
+function collectFeedbackRecords(stateDir) {
+    const objects = [];
+    for (const sub of ["sessions", "feedback"]) {
+        const dir = join(stateDir, sub);
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            objects.push(...parseJsonlObjects(readFileSync(join(dir, f), "utf-8")));
+        }
+    }
+    return extractFeedbackRecords(objects);
+}
+/**
+ * `--merge feedback`: fold ONLY the archive's feedback records into the
+ * local store. Imported folds land as bare records in a new
+ * `feedback/restored-<ts>.jsonl` — the exact sink `crewhaus distill`
+ * already reads — so local session transcripts are never rewritten and the
+ * next distill sees local + imported records merged by `mergeFeedback`.
+ */
+export async function mergeFeedbackFromArchive(opts) {
+    const archiveFile = resolve(opts.archiveFile);
+    assertArchiveExists(archiveFile);
+    const stateDir = join(resolve(opts.intoDir), ".crewhaus");
+    const temp = await extractToTemp(archiveFile, tmpdir());
+    try {
+        const archived = collectFeedbackRecords(temp);
+        if (archived.length === 0) {
+            throw new StateBackupError("archive carries no feedback records — nothing to merge " +
+                "(looked at sessions/*.jsonl user_feedback events and feedback/*.jsonl)");
+        }
+        const plan = planFeedbackMerge(collectFeedbackRecords(stateDir), archived);
+        let wroteFile;
+        if (plan.toImport.length > 0) {
+            const feedbackDir = join(stateDir, "feedback");
+            mkdirSync(feedbackDir, { recursive: true });
+            const stamp = (opts.now?.() ?? new Date()).toISOString().replace(/[:.]/g, "-");
+            wroteFile = join(feedbackDir, `restored-${stamp}.jsonl`);
+            let n = 2;
+            while (existsSync(wroteFile)) {
+                wroteFile = join(feedbackDir, `restored-${stamp}-${n}.jsonl`);
+                n += 1;
+            }
+            writeFileSync(wroteFile, `${plan.toImport.map((r) => JSON.stringify(r)).join("\n")}\n`, {
+                mode: 0o600,
+            });
+        }
+        return {
+            ...plan,
+            archivedRecords: archived.length,
+            ...(wroteFile !== undefined ? { wroteFile } : {}),
+        };
+    }
+    finally {
+        rmSync(temp, { recursive: true, force: true });
+    }
+}
+/**
+ * `--merge all`: per-subdir additive copy. Only archive files that do NOT
+ * exist locally are written; an existing local file is never overwritten
+ * (the skips are reported). The archive manifest is metadata, not state,
+ * and is never copied.
+ */
+export async function mergeAllFromArchive(opts) {
+    const archiveFile = resolve(opts.archiveFile);
+    assertArchiveExists(archiveFile);
+    const stateDir = join(resolve(opts.intoDir), ".crewhaus");
+    const temp = await extractToTemp(archiveFile, tmpdir());
+    try {
+        const archiveFiles = walkFiles(temp).files.filter((f) => f !== MANIFEST_FILENAME);
+        const plan = planAdditiveMerge(archiveFiles, (rel) => existsSync(join(stateDir, rel)));
+        for (const rel of plan.copy) {
+            const dst = join(stateDir, rel);
+            mkdirSync(dirname(dst), { recursive: true });
+            copyFileSync(join(temp, rel), dst);
+        }
+        return { stateDir, copied: plan.copy, skipped: plan.skip };
+    }
+    finally {
+        rmSync(temp, { recursive: true, force: true });
+    }
+}