@tpsdev-ai/flair 0.8.3 → 0.9.0

package/README.md

@@ -38,6 +38,12 @@ Most agent memory systems store *facts*. Flair stores facts AND the agent's iden
 
 `flair memory add` writes a memory; `flair search` finds it by meaning, not keywords. The same memory is then visible to every harness in the catalog above.
 
+### Same identity, every orchestrator
+
+![Flair cross-orchestrator: one agent, one memory store, three MCP-capable CLIs](docs/assets/flair-cross-orchestrator.gif)
+
+Same Ed25519 identity, same memory store, three different MCP-capable CLIs (Claude Code, Codex CLI, Gemini CLI). A memory written from one is immediately retrievable from the next. This is the load-bearing differentiation vs vendor-locked memory systems — your agent's identity and history aren't bound to a single orchestrator's runtime.
+
 ## How Flair compares
 
 | | Flair | Mem0 | Honcho | Letta (MemGPT) | Built-ins (OAI/Anthropic/Google) |
@@ -61,6 +67,27 @@ The honest gaps:
 
 If you need any of those specifically, use them. If you need crypto-pinned identity + federation + cross-orchestrator breadth + soul-as-a-feature — that's the gap Flair fills.
 
+### Memory curation: vs Claude Dreams
+
+Anthropic shipped [Claude Dreams](https://platform.claude.com/docs/en/managed-agents/dreams) (research preview, April 2026) — async pipeline that reads a memory store + session transcripts and produces a curated output store: duplicates merged, stale entries replaced, insights surfaced. Validates the category: agent memory accumulates drift and needs cleanup.
+
+Flair ships an on-demand curation surface today: `flair rem rapid`. Scheduled nightly REM is in the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md) and partially built.
+
+- **`flair rem rapid`** (ships now) — on-demand reflection. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. Outputs *candidates*, not a wholesale store swap.
+- **`flair rem candidates` / `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id>`** (ship now) — review and promote distilled candidates with required rationale.
+- **`flair rem nightly`** (planned, P0 for 1.0) — scheduled automation with pre-cycle snapshot, `rem restore <date>` rollback, trust-tier filtering. Spec'd; not yet implemented.
+
+The substantive difference is the **promotion contract**:
+
+| | Claude Dreams | Flair REM (today) |
+|---|---|---|
+| **Output** | New memory store — accept or discard | Staged candidates — per-candidate decision |
+| **Promotion gate** | None — accept the whole store | `flair rem promote <id> --rationale "<why>"` |
+| **Reversibility** | Input store is never modified (real safety property) | In-place modifications; nightly snapshot/restore is on the roadmap |
+| **Where it runs** | Anthropic Managed Agents (SaaS, Anthropic models only) | Self-hosted, any model |
+
+Dreams is easier to start with — one API call, and the input-never-modified contract gives you a clean rollback by simply not accepting the output. REM is the more granular surface — per-candidate decisions with required rationale — for operators who want to merge what's right and reject what's wrong on the same nightly cycle. Both are legitimate choices; the right one depends on whether you want store-level or candidate-level review.
+
 ## Why this exists
 
 Every agent framework gives you chat history. None of them give you *identity*.

package/dist/cli.js

@@ -4,7 +4,7 @@ import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, } from "node:fs";
 import { homedir, hostname, tmpdir } from "node:os";
-import { join, resolve, sep } from "node:path";
+import { join, resolve, sep, dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
@@ -2741,16 +2741,51 @@ federation
             console.log("No peers configured. Use 'flair federation pair' to connect to a hub.");
         }
         else {
-            console.log(`${"Peer".padEnd(20)} ${"Role".padEnd(8)} ${"Status".padEnd(14)} ${"Last Sync".padEnd(22)} Relay`);
+            // Compute lastSync staleness so an operator can tell at a glance whether sync is current.
+            const now = Date.now();
+            const stale = (iso) => {
+                if (!iso)
+                    return "never";
+                const t = Date.parse(iso);
+                if (!Number.isFinite(t))
+                    return "never";
+                const ageMs = now - t;
+                if (ageMs < 60_000)
+                    return "<1m ago";
+                if (ageMs < 3_600_000)
+                    return `${Math.floor(ageMs / 60_000)}m ago`;
+                if (ageMs < 86_400_000)
+                    return `${Math.floor(ageMs / 3_600_000)}h ago`;
+                return `${Math.floor(ageMs / 86_400_000)}d ago`;
+            };
+            console.log(`${"Peer".padEnd(20)} ${"Role".padEnd(8)} ${"Status".padEnd(14)} ${"Last Sync".padEnd(14)} Relay`);
             console.log("─".repeat(80));
             for (const p of peers) {
-                const lastSync = p.lastSyncAt?.slice(0, 19) ?? "never";
-                console.log(`${p.id.padEnd(20)} ${(p.role ?? "—").padEnd(8)} ${(p.status ?? "—").padEnd(14)} ${lastSync.padEnd(22)} ${p.relayOnly ? "yes" : "no"}`);
+                console.log(`${p.id.padEnd(20)} ${(p.role ?? "—").padEnd(8)} ${(p.status ?? "—").padEnd(14)} ${stale(p.lastSyncAt).padEnd(14)} ${p.relayOnly ? "yes" : "no"}`);
+            }
+            const haveStale = peers.some((p) => {
+                if (!p.lastSyncAt)
+                    return true;
+                return now - Date.parse(p.lastSyncAt) > 86_400_000;
+            });
+            if (haveStale) {
+                console.log();
+                console.log("⚠  One or more peers haven't synced in >24h. Run 'flair federation sync' or check the launchd watchdog.");
             }
         }
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        // Better UX on the common auth failure: tell the user what to set.
+        const msg = String(err.message ?? err);
+        if (msg.includes("missing_or_invalid_authorization") || msg.includes("401")) {
+            console.error("Error: federation status requires auth.");
+            console.error("  Set one of:");
+            console.error("    FLAIR_AGENT_ID=<your-agent-id>     (Ed25519 — uses ~/.flair/keys/<id>.key)");
+            console.error("    FLAIR_ADMIN_PASS=<admin-password>  (admin Basic auth, remote targets)");
+            console.error("    FLAIR_TOKEN=<bearer>               (legacy)");
+            process.exit(1);
+        }
+        console.error(`Error: ${msg}`);
         process.exit(1);
     }
 });
@@ -3991,6 +4026,346 @@ rem
         process.exit(1);
     }
 });
+// ─── flair rem nightly run-once ──────────────────────────────────────────────
+// Slice 1 of FLAIR-NIGHTLY-REM § 3. Manually invokes the nightly cycle code
+// path — same module the scheduler will call in PR-2. Useful for:
+//   - First-time operators verifying the cycle works before turning on the
+//     scheduled timer.
+//   - The dry-run-first-run guard (spec § 10) when the scheduler isn't yet
+//     installed.
+//   - Debugging a stale snapshot or audit row.
+//
+// `nightly enable` / `disable` / `status` land in PR-2 (scheduler templates).
+const remNightly = rem.command("nightly").description("Scheduled REM nightly cycle (manual trigger + scheduler management)");
+// `enable` / `disable` / `status` — scheduler install/uninstall (slice-1 PR-2).
+// macOS: writes ~/Library/LaunchAgents/dev.flair.rem.nightly.plist and bootstraps it.
+// Linux: writes ~/.config/systemd/user/flair-rem-nightly.{timer,service} and enables the timer.
+// Snapshot data and the audit log are preserved through enable/disable cycles.
+remNightly
+    .command("enable")
+    .description("Install the nightly scheduler (launchd on macOS, systemd timer on Linux)")
+    .option("--agent <id>", "Agent id (or FLAIR_AGENT_ID env)")
+    .option("--at <HH:MM>", "Local time to run nightly (default 03:00)", "03:00")
+    .option("--flair-url <url>", "Flair HTTP URL the runner will hit (default http://127.0.0.1:<port>)")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("Error: --agent or FLAIR_AGENT_ID env required");
+        process.exit(1);
+    }
+    const match = /^(\d{1,2}):(\d{2})$/.exec(opts.at);
+    if (!match) {
+        console.error(`Error: --at must be HH:MM (got: ${opts.at})`);
+        process.exit(1);
+    }
+    const hour = parseInt(match[1], 10);
+    const minute = parseInt(match[2], 10);
+    const port = readPortFromConfig() ?? DEFAULT_PORT;
+    const flairUrl = opts.flairUrl || process.env.FLAIR_URL || `http://127.0.0.1:${port}`;
+    const { enableScheduler } = await import("./rem/scheduler.js");
+    try {
+        const r = enableScheduler({ agentId, flairUrl, hour, minute });
+        console.log(`✅ REM nightly scheduler enabled (${r.platform})`);
+        console.log(`   Schedule:    ${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")} local time`);
+        console.log(`   Scheduler:   ${r.schedulerPath}`);
+        console.log(`   Shim:        ${r.shimPath}`);
+        console.log(`   Agent:       ${agentId}`);
+        console.log(`   Flair URL:   ${flairUrl}`);
+        if (r.loadResult) {
+            if (r.loadResult.code === 0) {
+                console.log(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+            }
+            else {
+                console.log(`   Load:        ${r.loadCommand.join(" ")} → code ${r.loadResult.code}`);
+                if (r.loadResult.stderr)
+                    console.log(`     stderr: ${r.loadResult.stderr.trim()}`);
+            }
+        }
+        console.log(`\nTip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
+        console.log(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+remNightly
+    .command("disable")
+    .description("Remove the nightly scheduler (keeps snapshots + audit log)")
+    .option("--remove-shim", "Also delete the ~/.flair/bin/flair-rem-nightly shim")
+    .action(async (opts) => {
+    const { disableScheduler } = await import("./rem/scheduler.js");
+    try {
+        const r = disableScheduler({ removeShim: !!opts.removeShim });
+        if (r.removed.length === 0) {
+            console.log(`(REM nightly scheduler was not installed on ${r.platform})`);
+            return;
+        }
+        console.log(`✅ REM nightly scheduler disabled (${r.platform})`);
+        console.log(`   Removed:`);
+        for (const p of r.removed)
+            console.log(`     ${p}`);
+        if (r.unloadResult && r.unloadResult.code !== 0) {
+            console.log(`   Unload:      ${r.unloadCommand.join(" ")} → code ${r.unloadResult.code}`);
+            if (r.unloadResult.stderr)
+                console.log(`     stderr: ${r.unloadResult.stderr.trim()}`);
+        }
+        console.log(`\nSnapshots at ~/.flair/snapshots/ and the audit log at`);
+        console.log(`~/.flair/logs/rem-nightly.jsonl are preserved.`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+remNightly
+    .command("status")
+    .description("Show whether the nightly scheduler is installed")
+    .action(async () => {
+    const { schedulerStatus } = await import("./rem/scheduler.js");
+    try {
+        const s = schedulerStatus();
+        console.log(`REM nightly scheduler (${s.platform}):`);
+        console.log(`  Installed:   ${s.installed ? "yes" : "no"}`);
+        console.log(`  Scheduler:   ${s.schedulerPath}`);
+        console.log(`  Shim:        ${s.shimPath}${s.shimExists ? "" : " (missing)"}`);
+        if (!s.installed) {
+            console.log(`\nEnable with: flair rem nightly enable --agent <id> [--at HH:MM]`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+remNightly
+    .command("run-once")
+    .description("Run one nightly cycle now (snapshot + log). Same code path the scheduler will use.")
+    .option("--agent <id>", "Agent id (or FLAIR_AGENT_ID env)")
+    .option("--dry-run", "Log the row but skip the snapshot write")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("Error: --agent or FLAIR_AGENT_ID env required");
+        process.exit(1);
+    }
+    const { runNightlyCycle } = await import("./rem/runner.js");
+    try {
+        const result = await runNightlyCycle({
+            agentId,
+            flairVersion: __pkgVersion,
+            apiCall: api,
+            dryRun: !!opts.dryRun,
+        });
+        const row = result.logRow;
+        console.log(`-- rem nightly run-once${opts.dryRun ? " (dry-run)" : ""} --`);
+        console.log(`Agent:      ${agentId}`);
+        console.log(`Status:     ${result.status}`);
+        if (result.snapshotPath) {
+            console.log(`Snapshot:   ${result.snapshotPath}`);
+        }
+        console.log(`Memories:   ${row.memoryCount ?? "—"}`);
+        console.log(`Souls:      ${row.soulCount ?? "—"}`);
+        console.log(`Pending:    ${row.pendingCandidates ?? "—"}`);
+        if (typeof row.archived === "number" || typeof row.expired === "number") {
+            console.log(`Archived:   ${row.archived ?? "—"}`);
+            console.log(`Expired:    ${row.expired ?? "—"}`);
+        }
+        console.log(`Duration:   ${row.durationMs}ms`);
+        if (row.errors.length > 0) {
+            console.log(`Errors:`);
+            for (const e of row.errors)
+                console.log(`  - ${e}`);
+            process.exit(1);
+        }
+        if (result.status === "paused") {
+            console.log(`\nNote: REM is paused (sentinel ~/.flair/rem.paused or FLAIR_REM_PAUSE env).`);
+            console.log(`Resume with: flair rem resume`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair rem snapshot list ─────────────────────────────────────────────────
+// Slice 1 of FLAIR-NIGHTLY-REM (ops-2qq). Lists snapshot tarballs under
+// ~/.flair/snapshots/<agent>/. Snapshot creation lives inside the nightly
+// runner (and exposed via `flair rem nightly run-once`) — there is no
+// user-facing `rem snapshot create` because that would invite operators to
+// create snapshots out of sync with the audit log. The list is the surface.
+const remSnapshot = rem.command("snapshot").description("REM nightly snapshots (tar.gz archives of agent memory + soul)");
+remSnapshot
+    .command("list")
+    .description("List REM snapshots for an agent (or all agents)")
+    .option("--agent <id>", "Filter to a single agent")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { listSnapshots } = await import("./rem/snapshot.js");
+    const rows = listSnapshots(opts.agent);
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("(no REM snapshots — ~/.flair/snapshots/ is empty or absent)");
+        console.log("\nSnapshots are produced by the nightly cycle. Run `flair rem nightly run-once`");
+        console.log("to generate one manually (slice 1).");
+        return;
+    }
+    const agentW = Math.max(5, ...rows.map((r) => r.agent.length));
+    const fileW = Math.max(20, ...rows.map((r) => r.file.length));
+    console.log(`  ${"agent".padEnd(agentW)}  ${"file".padEnd(fileW)}  size      age`);
+    for (const r of rows) {
+        console.log(`  ${r.agent.padEnd(agentW)}  ${r.file.padEnd(fileW)}  ${humanBytes(r.size).padEnd(8)}  ${relativeTime(r.mtime)}`);
+    }
+    console.log(`\n${rows.length} snapshot${rows.length > 1 ? "s" : ""}.`);
+});
+// ─── flair rem restore <date> ────────────────────────────────────────────────
+// Slice 1 + 2 of FLAIR-NIGHTLY-REM § 9.
+//
+// Default (no --apply): filesystem-only extract for inspection. Writes
+//   memories.jsonl / soul.json / metadata.json to a target directory.
+//   Harper state is unchanged.
+//
+// --apply: live replay. Reads the snapshot contents, takes a pre-restore
+//   snapshot of the agent's CURRENT state (so this restore is itself
+//   reversible), then DELETEs current memories/souls for the agent and PUTs
+//   the snapshot's rows back. Per-row failures are captured per-row; the
+//   pre-restore snapshot's path is reported so operator can roll back if
+//   something goes wrong mid-flight.
+//
+// The <date> argument is an ISO-timestamp prefix or date-only prefix; the
+// command picks the latest snapshot matching that prefix.
+rem
+    .command("restore <date>")
+    .description("Restore from a REM snapshot (inspect by default; --apply rewinds Harper state)")
+    .option("--agent <id>", "Agent id (or FLAIR_AGENT_ID env)")
+    .option("--target <dir>", "Directory to extract into (default: <snapshot>.restored, only used without --apply)")
+    .option("--dry-run", "Plan-only — list contents or planned counts without writing")
+    .option("--apply", "Live replay: rewind Harper state to the snapshot (irreversible without the pre-restore snapshot)")
+    .action(async (date, opts) => {
+    const { listSnapshots, extractSnapshot } = await import("./rem/snapshot.js");
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("Error: --agent or FLAIR_AGENT_ID env required");
+        process.exit(1);
+    }
+    let rows;
+    try {
+        rows = listSnapshots(agentId);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+    const matches = rows.filter((r) => r.file.startsWith(date));
+    if (matches.length === 0) {
+        console.error(`Error: no snapshot found for agent '${agentId}' matching date '${date}'`);
+        if (rows.length > 0) {
+            console.error(`  Available: ${rows.slice(0, 5).map((r) => r.file.replace(/\.tar\.gz$/, "")).join(", ")}`);
+        }
+        else {
+            console.error(`  No snapshots exist for ${agentId}. Run \`flair rem nightly run-once\` to create one.`);
+        }
+        process.exit(1);
+    }
+    // listSnapshots returns descending by mtime, so matches[0] is the newest
+    // snapshot for the date prefix.
+    const match = matches[0];
+    // --apply path: live replay via src/rem/restore.ts
+    if (opts.apply) {
+        const { applySnapshot } = await import("./rem/restore.js");
+        try {
+            const result = await applySnapshot({
+                agentId,
+                snapshotPath: match.path,
+                flairVersion: __pkgVersion,
+                apiCall: api,
+                dryRun: !!opts.dryRun,
+            });
+            const verb = opts.dryRun ? "(dry-run) would" : "";
+            console.log(`${opts.dryRun ? "(dry-run) " : ""}flair rem restore --apply${opts.dryRun ? "" : ""}`);
+            console.log(`  Status:       ${result.status}`);
+            console.log(`  Snapshot:     ${match.path}`);
+            if (result.preRestoreSnapshotPath) {
+                console.log(`  Pre-restore:  ${result.preRestoreSnapshotPath}`);
+                console.log(`                (rollback: flair rem restore <pre-restore-date> --agent ${agentId} --apply)`);
+            }
+            console.log(`  Deleted:      ${result.deleted.memories} memories, ${result.deleted.souls} souls`);
+            console.log(`  Restored:     ${result.restored.memories} memories, ${result.restored.souls} souls`);
+            if (result.errors.length > 0) {
+                console.log(`  Errors:`);
+                for (const e of result.errors)
+                    console.log(`    - ${e}`);
+            }
+            if (result.status === "failed")
+                process.exit(1);
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Default: filesystem extract.
+    try {
+        const result = await extractSnapshot({
+            snapshotPath: match.path,
+            targetDir: opts.target,
+            dryRun: !!opts.dryRun,
+        });
+        if (opts.dryRun) {
+            console.log(`(dry-run) snapshot: ${match.path}`);
+            for (const e of result.entries) {
+                console.log(`  ${e.path}  (${humanBytes(e.size)})`);
+            }
+            return;
+        }
+        console.log(`✅ Extracted: ${match.path}`);
+        console.log(`   To:        ${result.targetDir}`);
+        for (const e of result.entries) {
+            console.log(`     ${e.path}  (${humanBytes(e.size)})`);
+        }
+        console.log(`\nNote: this is a filesystem extract — Harper state is unchanged.`);
+        console.log(`To actually rewind state, re-run with --apply.`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair rem pause / resume ────────────────────────────────────────────────
+// Slice 1 of FLAIR-NIGHTLY-REM § 9. The pause sentinel is checked by the
+// nightly runner before any side effects. Env-var FLAIR_REM_PAUSE=1 is also
+// honored — lets ops pause fleet-wide without writing a file.
+const REM_PAUSE_FLAG = resolve(homedir(), ".flair", "rem.paused");
+rem
+    .command("pause")
+    .description("Pause nightly REM runs — writes ~/.flair/rem.paused sentinel")
+    .action(() => {
+    const dir = dirname(REM_PAUSE_FLAG);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(REM_PAUSE_FLAG, new Date().toISOString() + "\n", { mode: 0o600 });
+    console.log(`✅ REM nightly runs paused (sentinel: ${REM_PAUSE_FLAG})`);
+    console.log(`   Resume with: flair rem resume`);
+});
+rem
+    .command("resume")
+    .description("Resume nightly REM runs — removes the pause sentinel")
+    .action(() => {
+    if (existsSync(REM_PAUSE_FLAG)) {
+        rmSync(REM_PAUSE_FLAG);
+        console.log(`✅ REM nightly runs resumed (removed ${REM_PAUSE_FLAG})`);
+    }
+    else {
+        console.log(`(REM was not paused — no sentinel at ${REM_PAUSE_FLAG})`);
+    }
+    if (process.env.FLAIR_REM_PAUSE === "1") {
+        console.log(`\n⚠ FLAIR_REM_PAUSE=1 env var is also set; unset it to fully resume.`);
+    }
+});
 // ─── flair status ─────────────────────────────────────────────────────────────
 function humanBytes(n) {
     if (!Number.isFinite(n) || n < 0)

package/dist/rem/restore.js

@@ -0,0 +1,205 @@
+/**
+ * REM live replay — atomic state rewind from a snapshot tarball.
+ *
+ * Slice-2 PR-4. Implements the "every cycle is reversible" property:
+ *   `flair rem restore <date> --apply` actually rewinds Harper state to the
+ *   snapshot, not just extracts the tarball for inspection.
+ *
+ * Approach: client-side. The CLI sequentially calls existing `/Memory` and
+ * `/Soul` endpoints (DELETE current rows for the agent, PUT snapshot rows).
+ * No new server endpoint — keeps the auth surface unchanged and avoids the
+ * Harper body-size limit on uploading large memory exports inline.
+ *
+ * Reversibility-of-restore guarantee: before any destructive op, this
+ * module creates a pre-restore snapshot of the CURRENT state. If something
+ * fails mid-flight, the operator can restore from the pre-restore snapshot
+ * to roll back.
+ *
+ * Multi-agent restore (admin restoring another agent's state) is not in
+ * scope here; the operator's agent can only restore its own memories.
+ * Cross-agent restore is a 1.1+ feature.
+ */
+import { readFileSync, existsSync, rmSync, mkdtempSync } from "node:fs";
+import { resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { extractSnapshot, createSnapshot } from "./snapshot.js";
+function asArray(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        if (Array.isArray(obj.results))
+            return obj.results;
+        if (Array.isArray(obj.items))
+            return obj.items;
+    }
+    return [];
+}
+function parseJsonlSafe(text) {
+    if (!text.trim())
+        return [];
+    return text
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Applies a snapshot tarball to live Harper state for the given agent.
+ *
+ * Steps:
+ *   1. Extract the snapshot to a tmpdir.
+ *   2. Parse memories.jsonl + soul.json + metadata.json.
+ *   3. Verify metadata.agentId matches opts.agentId (prevents accidental
+ *      cross-agent restore — the file might have been hand-copied).
+ *   4. Create a pre-restore snapshot of current state (skip in dry-run).
+ *   5. Fetch + delete current memories/souls for the agent (skip in dry-run).
+ *   6. PUT snapshot memories/souls back into Harper (skip in dry-run).
+ *   7. Return counts.
+ *
+ * On any error after step 4: the result reports `status: "failed"` with
+ * the pre-restore snapshot path included so the operator can roll back.
+ */
+export async function applySnapshot(opts) {
+    const errors = [];
+    const result = {
+        status: "completed",
+        agentId: opts.agentId,
+        snapshotPath: opts.snapshotPath,
+        deleted: { memories: 0, souls: 0 },
+        restored: { memories: 0, souls: 0 },
+        errors,
+    };
+    if (!existsSync(opts.snapshotPath)) {
+        errors.push(`snapshot does not exist: ${opts.snapshotPath}`);
+        result.status = "failed";
+        return result;
+    }
+    // 1+2. Extract and parse. mkdtempSync creates an empty dir; extractSnapshot
+    // refuses to extract into an existing dir, so we point it at a non-existing
+    // subdir of the tmp scratch space.
+    const tmpRoot = opts.tmpRootOverride ?? tmpdir();
+    const tmp = mkdtempSync(resolve(tmpRoot, "flair-rem-restore-"));
+    const extractTo = resolve(tmp, "snapshot");
+    let memories;
+    let souls;
+    let metadata;
+    try {
+        await extractSnapshot({ snapshotPath: opts.snapshotPath, targetDir: extractTo });
+        const memText = readFileSync(resolve(extractTo, "memories.jsonl"), "utf-8");
+        memories = parseJsonlSafe(memText);
+        const soulRaw = JSON.parse(readFileSync(resolve(extractTo, "soul.json"), "utf-8"));
+        souls = Array.isArray(soulRaw)
+            ? soulRaw
+            : soulRaw && typeof soulRaw === "object"
+                ? [soulRaw]
+                : [];
+        metadata = JSON.parse(readFileSync(resolve(extractTo, "metadata.json"), "utf-8"));
+    }
+    catch (err) {
+        errors.push(`extract: ${err?.message ?? String(err)}`);
+        result.status = "failed";
+        rmSync(tmp, { recursive: true, force: true });
+        return result;
+    }
+    // 3. Verify agent id matches.
+    if (metadata.agentId && metadata.agentId !== opts.agentId) {
+        errors.push(`snapshot agentId (${metadata.agentId}) does not match target (${opts.agentId}) — refusing to restore cross-agent`);
+        result.status = "failed";
+        rmSync(tmp, { recursive: true, force: true });
+        return result;
+    }
+    if (opts.dryRun) {
+        // In dry-run, report planned counts. Still fetch current state for
+        // accurate deleted-counts reporting.
+        try {
+            const currentMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));
+            const currentSouls = asArray(await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`));
+            result.deleted.memories = currentMem.length;
+            result.deleted.souls = currentSouls.length;
+            result.restored.memories = memories.length;
+            result.restored.souls = souls.length;
+            result.status = "dry-run";
+        }
+        catch (err) {
+            errors.push(`fetch-current: ${err?.message ?? String(err)}`);
+            result.status = "failed";
+        }
+        rmSync(tmp, { recursive: true, force: true });
+        return result;
+    }
+    // 4. Pre-restore snapshot of current state.
+    let currentMem;
+    let currentSouls;
+    try {
+        currentMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));
+        currentSouls = asArray(await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`));
+        const preRestore = await createSnapshot({
+            agentId: opts.agentId,
+            flairVersion: opts.flairVersion,
+            memories: currentMem,
+            soul: currentSouls.length === 1 ? currentSouls[0] : currentSouls.length > 1 ? currentSouls : null,
+            pendingCandidateCount: 0, // not load-bearing at restore time
+            rootOverride: opts.preRestoreSnapshotRoot,
+            runId: `rem-restore-pre-${(opts.nowOverride ?? new Date()).toISOString().replace(/[:.]/g, "-")}`,
+            nowOverride: opts.nowOverride,
+        });
+        result.preRestoreSnapshotPath = preRestore.path;
+    }
+    catch (err) {
+        errors.push(`pre-restore-snapshot: ${err?.message ?? String(err)}`);
+        result.status = "failed";
+        rmSync(tmp, { recursive: true, force: true });
+        return result;
+    }
+    // 5. Delete current memories + souls (sequential to keep error semantics).
+    for (const m of currentMem) {
+        if (!m?.id)
+            continue;
+        try {
+            await opts.apiCall("DELETE", `/Memory/${encodeURIComponent(String(m.id))}`);
+            result.deleted.memories++;
+        }
+        catch (err) {
+            errors.push(`delete-memory ${m.id}: ${err?.message ?? String(err)}`);
+        }
+    }
+    for (const s of currentSouls) {
+        if (!s?.id)
+            continue;
+        try {
+            await opts.apiCall("DELETE", `/Soul/${encodeURIComponent(String(s.id))}`);
+            result.deleted.souls++;
+        }
+        catch (err) {
+            errors.push(`delete-soul ${s.id}: ${err?.message ?? String(err)}`);
+        }
+    }
+    // 6. PUT snapshot rows.
+    for (const m of memories) {
+        if (!m?.id)
+            continue;
+        try {
+            await opts.apiCall("PUT", `/Memory/${encodeURIComponent(String(m.id))}`, m);
+            result.restored.memories++;
+        }
+        catch (err) {
+            errors.push(`put-memory ${m.id}: ${err?.message ?? String(err)}`);
+        }
+    }
+    for (const s of souls) {
+        if (!s?.id)
+            continue;
+        try {
+            await opts.apiCall("PUT", `/Soul/${encodeURIComponent(String(s.id))}`, s);
+            result.restored.souls++;
+        }
+        catch (err) {
+            errors.push(`put-soul ${s.id}: ${err?.message ?? String(err)}`);
+        }
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    if (errors.length > 0) {
+        result.status = "failed";
+    }
+    return result;
+}