@tpsdev-ai/flair 0.7.0 → 0.8.0

package/dist/cli.js

@@ -2,12 +2,12 @@
 import { Command } from "commander";
 import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, } from "node:fs";
+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 { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
-import { create as tarCreate } from "tar";
+import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
 import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
@@ -681,6 +681,82 @@ export async function provisionFabric(target, opsTarget, clusterAdminUser, clust
         }
     }
 }
+// ─── flair_pair_initiator role ──────────────────────────────────────────────
+//
+// Hub instances need a `flair_pair_initiator` role so that bootstrap credentials
+// (created in PR-2) can pass platform auth on Harper Fabric before reaching the
+// FederationPair resource handler.  The role carries no table permissions itself
+// — the resource's own allowCreate bypass handles route-level access once the
+// request gets through the auth gate.
+/** Canonical permission spec for flair_pair_initiator. */
+const PAIR_INITIATOR_PERMISSION = {
+    super_user: false,
+    cluster_user: false,
+    structure_user: false,
+    flair: {
+        tables: {
+            Memory: { read: false, insert: false, update: false, delete: false },
+            Soul: { read: false, insert: false, update: false, delete: false },
+            Agent: { read: false, insert: false, update: false, delete: false },
+            Workspace: { read: false, insert: false, update: false, delete: false },
+            Event: { read: false, insert: false, update: false, delete: false },
+            OAuth: { read: false, insert: false, update: false, delete: false },
+            Instance: { read: false, insert: false, update: false, delete: false },
+            Peer: { read: false, insert: false, update: false, delete: false },
+            PairingToken: { read: false, insert: false, update: false, delete: false },
+            SyncLog: { read: false, insert: false, update: false, delete: false },
+        },
+    },
+};
+/**
+ * Idempotently ensures the `flair_pair_initiator` role exists on the Harper
+ * instance at `opsUrl` with the canonical permission spec.
+ *
+ * - If the role is absent → `add_role`
+ * - If it exists with different permissions → `alter_role` to bring it into spec
+ * - If it already matches → no-op
+ */
+export async function ensureFlairPairInitiatorRole(opsUrl, adminUser, adminPass) {
+    const ROLE_NAME = "flair_pair_initiator";
+    // 1. Check for existing role
+    let roles = [];
+    try {
+        const result = await callOpsApi(opsUrl, { operation: "list_roles" }, adminUser, adminPass);
+        roles = Array.isArray(result) ? result : [];
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`ensureFlairPairInitiatorRole: list_roles failed: ${msg}`);
+    }
+    const existing = roles.find((r) => r.role === ROLE_NAME || r.name === ROLE_NAME);
+    if (!existing) {
+        // 2a. Role absent → create it
+        console.log(`Creating role '${ROLE_NAME}'...`);
+        await callOpsApi(opsUrl, {
+            operation: "add_role",
+            role: ROLE_NAME,
+            permission: PAIR_INITIATOR_PERMISSION,
+        }, adminUser, adminPass);
+        console.log(`Role '${ROLE_NAME}' created ✓`);
+        return;
+    }
+    // 2b. Role exists — check if permissions match the canonical spec
+    const existingPerm = existing.permission ?? existing.role?.permission;
+    const canonicalStr = JSON.stringify(PAIR_INITIATOR_PERMISSION);
+    const existingStr = JSON.stringify(existingPerm);
+    if (existingStr === canonicalStr) {
+        console.log(`Role '${ROLE_NAME}' already exists with correct permissions — skipping`);
+        return;
+    }
+    // 2c. Permissions differ → bring into spec via alter_role
+    console.log(`Role '${ROLE_NAME}' exists but permissions differ — updating...`);
+    await callOpsApi(opsUrl, {
+        operation: "alter_role",
+        role: ROLE_NAME,
+        permission: PAIR_INITIATOR_PERMISSION,
+    }, adminUser, adminPass);
+    console.log(`Role '${ROLE_NAME}' updated ✓`);
+}
 // ─── Upgrade presence probes ──────────────────────────────────────────────────
 //
 // `flair upgrade` previously called `npm list -g <pkg>` to detect the installed
@@ -726,6 +802,35 @@ export function probeLibVersion(pkgName) {
         return null;
     }
 }
+/**
+ * Read the version of an OpenClaw plugin from `~/.openclaw/extensions/<name>/package.json`.
+ *
+ * `flair upgrade` uses this to surface the installed `@tpsdev-ai/openclaw-flair`
+ * version even though it isn't a globally-installed bin or a flair lib dep.
+ * Returns null if openclaw isn't installed, the extension isn't installed, or
+ * the package.json can't be parsed.
+ *
+ * @param extensionName — the directory name under `~/.openclaw/extensions/`
+ *                        (typically the plugin name without scope, e.g. `openclaw-flair`)
+ */
+export function probeOpenclawPluginVersion(extensionName) {
+    try {
+        const { existsSync, readFileSync } = require("node:fs");
+        const { homedir } = require("node:os");
+        const { resolve } = require("node:path");
+        // process.env.HOME first so tests can override; homedir() as fallback —
+        // homedir() doesn't honor runtime HOME changes (caches at module load).
+        const home = process.env.HOME ?? homedir();
+        const pkgJsonPath = resolve(home, ".openclaw", "extensions", extensionName, "package.json");
+        if (!existsSync(pkgJsonPath))
+            return null;
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function templateSoul(choice) {
     const templates = {
         "1": [
@@ -957,6 +1062,12 @@ program
             // Atomic provisioning: deploy + wait + provision user
             await provisionFabric(baseUrl, opsUrl, clusterAdminUser, clusterAdminPass, flairAdminPass);
             didProvision = true;
+            // Hub instances (--remote) receive federation pair requests and need
+            // the flair_pair_initiator role so bootstrap credentials can pass
+            // platform auth before reaching the FederationPair resource handler.
+            if (opts.remote) {
+                await ensureFlairPairInitiatorRole(opsUrl, DEFAULT_ADMIN_USER, flairAdminPass);
+            }
         }
         else {
             // ── Existing behavior: --admin-pass required for already-running Flair ──
@@ -1643,8 +1754,8 @@ program
             // all/none handled below
         }
         else {
-            // Filter to only the selected client
-            clients = [{ id: selectedClients[0], label: selectedClients[0], detected: true }];
+            // Filter to only the selected client (preserving wire function from detectClients)
+            clients = clients.filter(c => selectedClients.includes(c.id));
         }
     }
     if (!clientOpt && !noMcp) {
@@ -1717,7 +1828,7 @@ program
             let result;
             switch (clientId) {
                 case "claude-code":
-                    result = wireClaudeCode(mcpEnv, httpUrl);
+                    result = wireClaudeCode(mcpEnv);
                     break;
                 case "codex":
                     result = wireCodex(mcpEnv);
@@ -2595,9 +2706,19 @@ async function loadInstanceSecretKey(instanceId, opts) {
  * Sign a request body and return a new body with the signature field added.
  */
 function signRequestBody(body, secretKey) {
-    const sig = signBody(body, secretKey);
-    return { ...body, signature: sig };
+    // Fresh signing with anti-replay: embeds _ts and _nonce before signing.
+    // Equivalent to federation-crypto.ts signBodyFresh — duplicated here because
+    // the CLI module has its own local signBody for dependency isolation.
+    const freshBody = {
+        ...body,
+        _ts: Date.now(),
+        _nonce: Buffer.from(nacl.randomBytes(16)).toString("base64url"),
+    };
+    const sig = signBody(freshBody, secretKey);
+    return { ...freshBody, signature: sig };
 }
+// Alias: signBodyFresh for clarity at call sites
+const signBodyFresh = signRequestBody;
 // ─── flair federation ────────────────────────────────────────────────────────
 const federation = program.command("federation").description("Manage federation (hub-and-spoke sync)");
 federation
@@ -2633,13 +2754,158 @@ federation
         process.exit(1);
     }
 });
+// `flair federation reachability` — probe local instance + all paired peers.
+// Productizes ~/ops/scripts/flair-boot-probe.sh: a single command that tells
+// you whether memories CAN flow across the federation right now. Read-only;
+// no mutations, no side effects beyond a single tagged status read per peer.
+federation
+    .command("reachability")
+    .description("Probe local Flair + each paired peer for reachability (read-only)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--quiet", "Suppress output on full success")
+    .option("--json", "Emit machine-readable JSON instead of text")
+    .option("--peer-timeout <seconds>", "HTTP timeout per peer probe (default 5)", "5")
+    .action(async (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    const timeoutMs = (Number(opts.peerTimeout) || 5) * 1000;
+    const results = [];
+    // 1. Local probe.
+    try {
+        const inst = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+        results.push({ host: "local", port: null, status: "ok", detail: `instance ${inst.id} (${inst.role}, ${inst.status})` });
+    }
+    catch (e) {
+        results.push({ host: "local", port: null, status: "fail", detail: e.message });
+    }
+    // 2. Per-peer probes. For each peer with an `endpoint` (URL), probe it.
+    // Peers without an endpoint are reverse-tunnel-paired (the spoke can't
+    // reach the hub directly without the tunnel) and we skip.
+    let peers = [];
+    try {
+        const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        peers = r.peers ?? [];
+    }
+    catch (e) {
+        results.push({ host: "/FederationPeers", port: null, status: "fail", detail: e.message });
+    }
+    for (const p of peers) {
+        const endpoint = p.endpoint;
+        if (!endpoint) {
+            results.push({ host: p.id, port: null, status: "skip", detail: `${p.role ?? "—"} (no endpoint — needs tunnel)` });
+            continue;
+        }
+        // Any HTTP response (including 401) means the peer is reachable + responding.
+        // We're checking the network path, not auth; 401 is expected for unauth probes.
+        // Use new URL() to avoid path-swallowing when endpoint includes a query
+        // (Sherlock review on #314).
+        let probeUrl;
+        try {
+            probeUrl = new URL("/Health", endpoint);
+        }
+        catch {
+            results.push({ host: p.id, port: null, status: "fail", detail: `${p.role ?? "—"} invalid endpoint URL` });
+            continue;
+        }
+        if (probeUrl.protocol !== "http:" && probeUrl.protocol !== "https:") {
+            results.push({ host: p.id, port: null, status: "fail", detail: `${p.role ?? "—"} unsupported protocol ${probeUrl.protocol}` });
+            continue;
+        }
+        try {
+            const ctrl = new AbortController();
+            const t = setTimeout(() => ctrl.abort(), timeoutMs);
+            const res = await fetch(probeUrl, { signal: ctrl.signal });
+            clearTimeout(t);
+            results.push({ host: p.id, port: null, status: "ok", detail: `${p.role ?? "—"} HTTP ${res.status}` });
+        }
+        catch (e) {
+            const msg = e.name === "AbortError" ? `timeout after ${opts.peerTimeout}s` : e.message;
+            results.push({ host: p.id, port: null, status: "fail", detail: `${p.role ?? "—"} ${msg}` });
+        }
+    }
+    const failures = results.filter(r => r.status === "fail").length;
+    if (opts.json) {
+        console.log(JSON.stringify({ ts: new Date().toISOString(), failures, results }, null, 2));
+    }
+    else if (!(opts.quiet && failures === 0)) {
+        console.log(`── Flair reachability — ${new Date().toISOString()} ──`);
+        for (const r of results) {
+            const tag = r.status === "ok" ? "OK  " : r.status === "skip" ? "SKIP" : "FAIL";
+            console.log(`${tag} ${r.host.padEnd(40)} ${r.detail}`);
+        }
+        if (failures > 0) {
+            console.log(`── ${failures} path(s) FAILED ──`);
+        }
+        else {
+            console.log("── all reachable ──");
+        }
+    }
+    if (failures > 0)
+        process.exit(1);
+});
+/** Parse a JSON triple file for --token-from.
+ *  Expected shape: { "token": "...", "user": "pair-bootstrap-<id>", "password": "...", "expiresAt": "<ISO>" }
+ *  Returns the triple on success. Validation failures exit(1).
+ */
+function parseTokenFromFile(filePath) {
+    let raw;
+    if (filePath === "-") {
+        raw = readFileSync("/dev/stdin", "utf-8");
+    }
+    else {
+        if (!existsSync(filePath)) {
+            console.error(`Error: --token-from file not found: ${filePath}`);
+            process.exit(1);
+        }
+        raw = readFileSync(filePath, "utf-8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        console.error(`Error: --token-from file is not valid JSON: ${filePath}`);
+        process.exit(1);
+    }
+    // Validate all four fields present and non-empty
+    const required = ["token", "user", "password", "expiresAt"];
+    for (const field of required) {
+        if (!parsed[field] || typeof parsed[field] !== "string" || parsed[field].trim() === "") {
+            console.error(`Error: --token-from JSON is missing or has empty required field "${field}"`);
+            process.exit(1);
+        }
+    }
+    // Validate expiresAt is a parseable date and is in the future
+    const expiry = new Date(parsed.expiresAt);
+    if (isNaN(expiry.getTime())) {
+        console.error(`Error: --token-from JSON has invalid expiresAt date: "${parsed.expiresAt}"`);
+        process.exit(1);
+    }
+    const now = new Date();
+    if (expiry <= now) {
+        console.error(`Error: --token-from JSON has expired token (expiresAt: ${parsed.expiresAt})`);
+        process.exit(1);
+    }
+    const fiveMin = 5 * 60 * 1000;
+    if (expiry.getTime() - now.getTime() < fiveMin) {
+        console.error(`warning: pairing token expires in less than 5 minutes (expiresAt: ${parsed.expiresAt})`);
+    }
+    return {
+        token: parsed.token.trim(),
+        user: parsed.user.trim(),
+        password: parsed.password.trim(),
+        expiresAt: parsed.expiresAt.trim(),
+    };
+}
 federation
     .command("pair <hub-url>")
     .description("Pair this spoke with a hub instance")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
     .option("--ops-port <port>", "Harper operations API port")
-    .option("--token <token>", "One-time pairing token from hub admin (env: FLAIR_PAIRING_TOKEN)")
+    .option("--token <token>", "One-time pairing token from hub admin (env: FLAIR_PAIRING_TOKEN) [deprecated: use --token-from]")
+    .option("--token-from <file>", "Read bootstrap triple from JSON file (use '-' for stdin)")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (hubUrl, opts) => {
@@ -2648,34 +2914,50 @@ federation
     try {
         const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
         console.log(`${target ? "Remote" : "Local"} instance: ${instance.id} (${instance.role})`);
-        if (!opts.token) {
-            console.error("Error: --token is required. Ask the hub admin to run 'flair federation token' and provide the token.");
+        // Determine token source: --token-from wins if both specified
+        if (opts.tokenFrom && opts.token) {
+            console.error("warning: --token-from takes precedence over --token. The --token flag is deprecated; use --token-from <file> instead.");
+        }
+        let pairingToken;
+        let authHeader;
+        if (opts.tokenFrom) {
+            // ── Bootstrap triple path (--token-from) ──
+            const triple = parseTokenFromFile(opts.tokenFrom);
+            pairingToken = triple.token;
+            authHeader = `Basic ${Buffer.from(`${triple.user}:${triple.password}`).toString("base64")}`;
+            console.log(`Using bootstrap user: ${triple.user}`);
+        }
+        else if (opts.token) {
+            // ── Bare token path (--token) — deprecated ──
+            pairingToken = opts.token || process.env.FLAIR_PAIRING_TOKEN;
+            console.error("warning: --token is deprecated. Use --token-from <file> to keep credentials out of shell history.");
+            // Warning: inline token may leak to shell history.
+            const tokenFromEnv = !opts.token && !!process.env.FLAIR_PAIRING_TOKEN;
+            if (shouldShowInlineSecretWarning(opts.token, tokenFromEnv, new Set(["--token"]), "--token")) {
+                console.error("warning: --token passed inline. Consider --token-from <file> or FLAIR_PAIRING_TOKEN env " +
+                    "to keep secrets out of shell history.");
+            }
+        }
+        else {
+            console.error("Error: --token or --token-from is required. Ask the hub admin to run 'flair federation token' and provide the token.");
             process.exit(1);
         }
-        // Warning: inline token may leak to shell history.
-        // fromEnv is true ONLY when the resolved value came from env (no inline override).
-        const tokenFromEnv = !opts.token && !!process.env.FLAIR_PAIRING_TOKEN;
-        if (shouldShowInlineSecretWarning(opts.token, tokenFromEnv, new Set(["--token"]), "--token")) {
-            console.error("warning: --token passed inline. Consider --token-from <file> or FLAIR_PAIRING_TOKEN env " +
-                "to keep secrets out of shell history.");
-        }
-        // Load secret key and sign the pairing request. The pairing token is
-        // included in the signed body (not in an Authorization header) because
-        // Harper's auth layer claims any "Bearer X" Authorization header for
-        // itself and 401s before our resource ever runs.
+        // Load secret key and sign the pairing request.
         const secretKey = await loadInstanceSecretKey(instance.id, opts);
-        // Env var fallback for --token: FLAIR_PAIRING_TOKEN
-        const pairingToken = opts.token || process.env.FLAIR_PAIRING_TOKEN;
         const pairBody = {
             instanceId: instance.id,
             publicKey: instance.publicKey,
             role: "spoke",
             pairingToken,
         };
-        const signedBody = signRequestBody(pairBody, secretKey);
+        const signedBody = signBodyFresh(pairBody, secretKey);
+        const fetchHeaders = { "Content-Type": "application/json" };
+        if (authHeader) {
+            fetchHeaders.Authorization = authHeader;
+        }
         const res = await fetch(`${hubUrl}/FederationPair`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: fetchHeaders,
             body: JSON.stringify(signedBody),
         });
         if (!res.ok) {
@@ -2722,17 +3004,18 @@ federation
     .option("--ttl <minutes>", "Token TTL in minutes (default: 60)", "60")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
+    .option("--format <format>", "Output format: json (default) or text (bare token, deprecated)", "json")
     .action(async (opts) => {
     const target = resolveTarget(opts);
     const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     try {
-        const { randomBytes } = await import("node:crypto");
         const token = randomBytes(24).toString("base64url");
         const ttlMinutes = parseInt(opts.ttl, 10) || 60;
         const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000).toISOString();
         const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
         const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        // 1. Persist the PairingToken record
         const opsRes = await fetch(`${opsEndpoint}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: auth },
@@ -2750,10 +3033,64 @@ federation
             const detail = await opsRes.text().catch(() => "");
             throw new Error(`Failed to persist pairing token (${opsRes.status}): ${detail || "no body"}`);
         }
-        console.log(`Pairing token (expires in ${ttlMinutes}m):`);
-        console.log(`  ${token}`);
-        console.log(`\nGive this to the spoke admin to run:`);
-        console.log(`  flair federation pair <this-hub-url> --token ${token}`);
+        // 2. Create bootstrap user for this token
+        const bootstrapPassword = randomBytes(32).toString("base64url");
+        const bootstrapUsername = `pair-bootstrap-${token.slice(0, 8)}`;
+        let addUserRes;
+        try {
+            addUserRes = await fetch(`${opsEndpoint}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({
+                    operation: "add_user",
+                    username: bootstrapUsername,
+                    password: bootstrapPassword,
+                    role: "flair_pair_initiator",
+                    active: true,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch (err) {
+            // Network failure creating bootstrap user — roll back PairingToken
+            await fetch(`${opsEndpoint}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({
+                    operation: "delete",
+                    database: "flair",
+                    table: "PairingToken",
+                    hash_value: token,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            }).catch(() => { });
+            throw new Error(`Failed to create bootstrap user (network): ${err.message}`);
+        }
+        if (!addUserRes.ok) {
+            // add_user failed — roll back PairingToken so the two stay in sync
+            await fetch(`${opsEndpoint}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({
+                    operation: "delete",
+                    database: "flair",
+                    table: "PairingToken",
+                    hash_value: token,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            }).catch(() => { });
+            const detail = await addUserRes.text().catch(() => "");
+            throw new Error(`Failed to create bootstrap user (${addUserRes.status}): ${detail || "no body"}`);
+        }
+        // 3. Output
+        const format = (opts.format ?? "json").toLowerCase();
+        if (format === "text") {
+            process.stderr.write(`[DEPRECATION] --format text is deprecated. Default output is now JSON.\n`);
+            console.log(token);
+        }
+        else {
+            console.log(JSON.stringify({ token, user: bootstrapUsername, password: bootstrapPassword, expiresAt }, null, 2));
+        }
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -2764,6 +3101,8 @@ export async function runFederationSyncOnce(opts) {
     const target = resolveTarget(opts);
     const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     const apiOpts = baseUrl ? { baseUrl } : undefined;
+    let totalMerged = 0;
+    let totalSkipped = 0;
     try {
         const { peers } = await api("GET", "/FederationPeers", undefined, apiOpts);
         const hub = peers.find((p) => p.role === "hub" && p.status !== "revoked");
@@ -2776,8 +3115,35 @@ export async function runFederationSyncOnce(opts) {
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
         const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
         const tables = ["Memory", "Soul", "Agent", "Relationship"];
-        const records = [];
         const instance = await api("GET", "/FederationInstance", undefined, apiOpts);
+        const hubUrl = hub.endpoint ?? hub.id;
+        // ── Batching constants ──────────────────────────────────────────────
+        // 2MB JSON budget (server cap is 10MB; 2MB leaves headroom for headers
+        // and signature metadata) + 200 records max per batch.
+        const BUDGET_BYTES = 2_000_000;
+        const BUDGET_RECORDS = 200;
+        // ── sendBatch helper ────────────────────────────────────────────────
+        // Secret key is lazy-loaded: only needed when there are records to send.
+        // Loading earlier would cause a spurious error when SQL queries fail
+        // (e.g. 401) before we know we have records.
+        let secretKey;
+        async function sendBatch(batch) {
+            if (!secretKey)
+                secretKey = await loadInstanceSecretKey(instance.id, opts);
+            const syncBody = { instanceId: instance.id, records: batch, lamportClock: Date.now() };
+            const signedSyncBody = signBodyFresh(syncBody, secretKey);
+            const syncRes = await fetch(`${hubUrl}/FederationSync`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(signedSyncBody),
+            });
+            if (!syncRes.ok) {
+                const text = await syncRes.text().catch(() => "");
+                throw new Error(`Sync batch failed: ${syncRes.status} ${text}`);
+            }
+            return await syncRes.json();
+        }
+        let totalBatches = 0;
         for (const table of tables) {
             let res;
             try {
@@ -2789,39 +3155,49 @@ export async function runFederationSyncOnce(opts) {
                 });
             }
             catch (err) {
-                return { pushed: 0, skipped: 0, error: err instanceof Error ? err : new Error(String(err)) };
+                return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
             }
             if (!res.ok) {
                 const text = await res.text().catch(() => "");
-                return { pushed: 0, skipped: 0, error: new Error(`SQL query failed (${res.status}): ${text}`) };
+                return { pushed: totalMerged, skipped: totalSkipped, error: new Error(`SQL query failed (${res.status}): ${text}`) };
+            }
+            // Stream-collect records into batches
+            const rows = await res.json();
+            if (rows.length === 0)
+                continue;
+            let batch = [];
+            let batchBytes = 0;
+            for (const row of rows) {
+                const sr = { table, id: row.id, data: row, updatedAt: row.updatedAt ?? row.createdAt, originatorInstanceId: instance.id };
+                const srBytes = JSON.stringify(sr).length;
+                if (batch.length >= BUDGET_RECORDS || (batch.length > 0 && batchBytes + srBytes > BUDGET_BYTES)) {
+                    const result = await sendBatch(batch);
+                    totalMerged += result.merged;
+                    totalSkipped += result.skipped;
+                    totalBatches++;
+                    batch = [];
+                    batchBytes = 0;
+                }
+                batch.push(sr);
+                batchBytes += srBytes;
             }
-            for (const row of await res.json()) {
-                records.push({ table, id: row.id, data: row, updatedAt: row.updatedAt ?? row.createdAt, originatorInstanceId: instance.id });
+            // Send final partial batch for this table
+            if (batch.length > 0) {
+                const result = await sendBatch(batch);
+                totalMerged += result.merged;
+                totalSkipped += result.skipped;
+                totalBatches++;
             }
         }
-        if (records.length === 0) {
+        if (totalBatches === 0) {
             console.log("No changes since last sync.");
             return { pushed: 0, skipped: 0 };
         }
-        // Sign the sync request with our instance key
-        const secretKey = await loadInstanceSecretKey(instance.id, opts);
-        const syncBody = { instanceId: instance.id, records, lamportClock: Date.now() };
-        const signedSyncBody = signRequestBody(syncBody, secretKey);
-        const syncRes = await fetch(`${hub.endpoint ?? hub.id}/FederationSync`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(signedSyncBody),
-        });
-        if (!syncRes.ok) {
-            const text = await syncRes.text().catch(() => "");
-            return { pushed: 0, skipped: 0, error: new Error(`Sync failed: ${syncRes.status} ${text}`) };
-        }
-        const result = await syncRes.json();
-        console.log(`✅ Synced ${result.merged} records (${result.skipped} skipped) in ${result.durationMs}ms`);
-        return { pushed: result.merged ?? 0, skipped: result.skipped ?? 0 };
+        console.log(`✅ Synced ${totalMerged} records (${totalSkipped} skipped) across ${totalBatches} batches`);
+        return { pushed: totalMerged, skipped: totalSkipped };
     }
     catch (err) {
-        return { pushed: 0, skipped: 0, error: err instanceof Error ? err : new Error(String(err)) };
+        return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
     }
 }
 federation
@@ -2885,6 +3261,281 @@ federation
     .action(async (opts) => {
     await runFederationWatch(opts);
 });
+// `flair federation prune` — remove stale spoke peers (never the hub).
+// Productizes ~/ops/scripts/cleanup-stale-fed-peers.sh into a real CLI
+// subcommand with safety: dry-run is the default, --apply required to delete.
+function parseDuration(spec) {
+    // Accept forms like "30d", "12h", "90m". Returns milliseconds.
+    // Rejects zero and sub-1-minute durations: a 0-ms cutoff would equal Date.now()
+    // and prune every non-hub peer (Sherlock review on #314).
+    const m = spec.match(/^(\d+)\s*([smhd])$/i);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = m[2].toLowerCase();
+    const mul = { s: 1000, m: 60 * 1000, h: 60 * 60 * 1000, d: 24 * 60 * 60 * 1000 }[unit] ?? null;
+    if (mul == null)
+        return null;
+    const ms = n * mul;
+    const ONE_MINUTE = 60 * 1000;
+    if (ms < ONE_MINUTE)
+        return null;
+    return ms;
+}
+federation
+    .command("prune")
+    .description("Remove stale spoke peers (older than --older-than). Hub is never pruned. Default dry-run.")
+    .option("--older-than <duration>", "Duration spec (e.g. 30d, 12h, 90m)", "30d")
+    .option("--apply", "Actually delete (default is dry-run)")
+    .option("--include <pattern>", "Only consider peer IDs starting with this prefix")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--target <url>", "Remote Flair URL")
+    .option("--ops-target <url>", "Explicit ops API URL")
+    .action(async (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    const olderThanMs = parseDuration(opts.olderThan);
+    if (olderThanMs == null) {
+        console.error(`Error: invalid or unsafe --older-than '${opts.olderThan}'. Use forms like 30d, 12h, 90m. Minimum 1 minute.`);
+        process.exit(2);
+    }
+    const cutoff = Date.now() - olderThanMs;
+    let peers = [];
+    try {
+        const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        peers = r.peers ?? [];
+    }
+    catch (e) {
+        console.error(`Error fetching peers: ${e.message}`);
+        process.exit(1);
+    }
+    const candidates = peers.filter(p => {
+        // Hub-protection: never prune. Case-insensitive; null/undefined role is
+        // treated as "unknown — refuse to prune to be safe" (Sherlock review on #314).
+        const role = (p.role ?? "").toString().toLowerCase();
+        if (role === "hub" || role === "")
+            return false;
+        // Include filter.
+        if (opts.include && !String(p.id ?? "").startsWith(opts.include))
+            return false;
+        // Stale threshold: a peer with NO lastSyncAt is treated as having been
+        // born and immediately abandoned — qualifies if it's older than the
+        // threshold based on pairedAt instead.
+        const ts = p.lastSyncAt ?? p.pairedAt;
+        if (!ts)
+            return true; // truly orphaned record — prune candidate.
+        return new Date(ts).getTime() < cutoff;
+    });
+    if (candidates.length === 0) {
+        console.log(`flair federation prune: no peers older than ${opts.olderThan} (and not hub) — nothing to do.`);
+        return;
+    }
+    if (!opts.apply) {
+        console.log(`── flair federation prune — dry-run (use --apply to delete) ──`);
+        console.log(`Would delete ${candidates.length} peer(s) older than ${opts.olderThan}:`);
+        for (const p of candidates) {
+            const ts = p.lastSyncAt ?? p.pairedAt ?? "never";
+            const age = ts === "never" ? "(never synced/paired)" : `${Math.floor((Date.now() - new Date(ts).getTime()) / (24 * 60 * 60 * 1000))}d ago`;
+            console.log(`  ${p.id}  ${(p.role ?? "—").padEnd(8)} lastSyncAt ${ts} (${age})`);
+        }
+        console.log(`Run with --apply to actually delete.`);
+        return;
+    }
+    // Apply path. Delete each peer via the Harper ops API. We use the
+    // domain-socket form when local; otherwise we fall back to the resource
+    // DELETE which requires admin auth.
+    let deleted = 0;
+    let errors = 0;
+    for (const p of candidates) {
+        try {
+            const res = await api("DELETE", `/FederationPeers/${encodeURIComponent(p.id)}`, undefined, baseUrl ? { baseUrl } : undefined);
+            const ok = res?.ok ?? res?.deleted ?? true;
+            if (ok) {
+                deleted++;
+                const ts = p.lastSyncAt ?? p.pairedAt ?? "never";
+                console.log(`Deleted ${p.id} (last seen ${ts}).`);
+            }
+            else {
+                errors++;
+                console.log(`Failed to delete ${p.id}: ${JSON.stringify(res)}`);
+            }
+        }
+        catch (e) {
+            errors++;
+            console.log(`Failed to delete ${p.id}: ${e.message}`);
+        }
+    }
+    console.log(`${deleted} peer(s) deleted; ${errors} error(s).`);
+    if (errors > 0)
+        process.exit(1);
+});
+// `flair federation verify` — end-to-end roundtrip: write a tagged memory
+// locally, wait for federation push, probe peers for the tag. Productizes
+// ~/ops/scripts/verify-fed-sync.sh. Cleans up the test memory at the end.
+federation
+    .command("verify")
+    .description("End-to-end check: write a tagged memory locally and verify it shows up on each peer")
+    .option("--peer <id>", "Verify only against this peer ID (default: all hubs + spokes)")
+    .option("--wait <seconds>", "How long to wait for federation push (default 60)", "60")
+    .option("--tag <prefix>", "Memory tag prefix (default: fed-verify)", "fed-verify")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL")
+    .action(async (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    const waitMs = (Number(opts.wait) || 60) * 1000;
+    const tag = `${opts.tag}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    console.log(`── flair federation verify — ${new Date().toISOString()} ──`);
+    console.log(`Tag: ${tag}, wait window: ${opts.wait}s`);
+    // Resolve agent ID for the local write.
+    const agentId = process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("Error: FLAIR_AGENT_ID not set. Set it or use 'flair agent default <id>'.");
+        process.exit(1);
+    }
+    // 1. Write tagged ephemeral memory locally (mirror `flair memory add`).
+    // The whole post-write block is wrapped in try/finally so cleanup runs on
+    // every exit path (Sherlock review on #314: previous early-exits leaked
+    // the probe memory).
+    const memId = `${agentId}-${Date.now()}-fed-verify`;
+    try {
+        await api("PUT", `/Memory/${encodeURIComponent(memId)}`, {
+            id: memId,
+            agentId,
+            content: `${tag} — federation verify probe written at ${new Date().toISOString()}`,
+            type: "memory",
+            durability: "ephemeral",
+            tags: ["federation-verify", tag],
+            createdAt: new Date().toISOString(),
+        }, baseUrl ? { baseUrl } : undefined);
+        console.log(`1. Wrote local memory: ${memId}`);
+    }
+    catch (e) {
+        console.error(`1. Local write FAILED: ${e.message}`);
+        // No memory was written — nothing to clean up. Direct exit is safe.
+        process.exit(1);
+    }
+    // From here, memId is committed and MUST be cleaned up regardless of how
+    // we leave this block.
+    let exitCode = 0;
+    try {
+        // 2. List peers to probe.
+        let peers = [];
+        try {
+            const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+            peers = r.peers ?? [];
+            if (opts.peer)
+                peers = peers.filter(p => p.id === opts.peer);
+        }
+        catch (e) {
+            console.error(`Failed to list peers: ${e.message}`);
+        }
+        if (peers.length === 0) {
+            console.log("(no peers to probe)");
+            // Still falls through to finally for cleanup.
+        }
+        else {
+            console.log(`2. Probing ${peers.length} peer(s) over ${opts.wait}s window…`);
+            // 3. Poll each peer until found OR window elapses.
+            const started = Date.now();
+            const found = new Set();
+            const failed = new Set();
+            while (Date.now() - started < waitMs && (found.size + failed.size) < peers.length) {
+                for (const p of peers) {
+                    if (found.has(p.id) || failed.has(p.id))
+                        continue;
+                    const endpoint = p.endpoint;
+                    if (!endpoint) {
+                        // Tunnel-paired — no direct endpoint to probe. Mark as skipped.
+                        failed.add(p.id);
+                        console.log(`   ${p.id}  SKIP (no endpoint — tunnel-paired)`);
+                        continue;
+                    }
+                    // Reject non-http(s) endpoints to keep the probe surface small.
+                    // (Sherlock review on #314 — protocol allowlist.)
+                    let probeUrl;
+                    try {
+                        probeUrl = new URL("/SemanticSearch", endpoint);
+                    }
+                    catch {
+                        failed.add(p.id);
+                        console.log(`   ${p.id}  FAIL (invalid endpoint URL: ${endpoint})`);
+                        continue;
+                    }
+                    if (probeUrl.protocol !== "http:" && probeUrl.protocol !== "https:") {
+                        failed.add(p.id);
+                        console.log(`   ${p.id}  FAIL (unsupported endpoint protocol: ${probeUrl.protocol})`);
+                        continue;
+                    }
+                    try {
+                        const res = await fetch(probeUrl, {
+                            method: "POST",
+                            headers: { "Content-Type": "application/json" },
+                            body: JSON.stringify({ q: tag, limit: 5 }),
+                            signal: AbortSignal.timeout(5000),
+                        });
+                        if (res.status === 401) {
+                            // Auth-gated — can't verify without admin creds for the peer.
+                            // Fail the probe with diagnostic.
+                            failed.add(p.id);
+                            console.log(`   ${p.id}  FAIL (HTTP 401 — peer auth-gated; needs cross-instance admin auth)`);
+                            continue;
+                        }
+                        if (!res.ok) {
+                            failed.add(p.id);
+                            console.log(`   ${p.id}  FAIL (HTTP ${res.status})`);
+                            continue;
+                        }
+                        const data = await res.json().catch(() => ({}));
+                        const results = data.results ?? [];
+                        if (results.some((r) => (r.content ?? "").includes(tag))) {
+                            const elapsed = Math.floor((Date.now() - started) / 1000);
+                            console.log(`   ${p.id}  OK (memory found after ${elapsed}s)`);
+                            found.add(p.id);
+                        }
+                    }
+                    catch {
+                        // Don't mark failed yet — peer might just be slow. Retry next iteration.
+                    }
+                }
+                await new Promise(res => setTimeout(res, 5000));
+            }
+            // Anything still pending is a timeout failure.
+            for (const p of peers) {
+                if (!found.has(p.id) && !failed.has(p.id)) {
+                    failed.add(p.id);
+                    console.log(`   ${p.id}  FAIL (timeout — memory did not propagate within ${opts.wait}s)`);
+                }
+            }
+            // 5. Summary + diagnostics on failure.
+            if (failed.size > 0) {
+                console.log(`── FAIL: ${failed.size}/${peers.length} peer(s) did not see the memory ──`);
+                console.log(`Diagnostics to run next:`);
+                console.log(`  flair federation status     # confirm peers are paired + lastSyncAt is recent`);
+                console.log(`  flair federation reachability  # confirm peers are HTTP-reachable`);
+                console.log(`  launchctl list | grep fed-sync  # confirm federation-sync daemon is running (macOS)`);
+                console.log(`  curl <peer-endpoint>/Health  # raw probe`);
+                exitCode = 1;
+            }
+            else {
+                console.log(`── PASS: memory propagated to all ${peers.length} peer(s) ──`);
+            }
+        }
+    }
+    finally {
+        // 4. Cleanup: delete the local probe memory. Runs on EVERY exit path.
+        try {
+            await api("DELETE", `/Memory/${encodeURIComponent(memId)}`, undefined, baseUrl ? { baseUrl } : undefined);
+            console.log(`4. Cleanup: deleted local memory ${memId}`);
+        }
+        catch {
+            console.log(`4. Cleanup: could NOT delete local memory ${memId} (manual cleanup needed)`);
+        }
+    }
+    if (exitCode !== 0)
+        process.exit(exitCode);
+});
 // ─── flair rem ───────────────────────────────────────────────────────────────
 // Memory hygiene and reflection: light (NREM), rapid (REM), restorative (deep).
 const rem = program.command("rem").description("Memory hygiene and reflection");
@@ -3077,6 +3728,269 @@ rem
         process.exit(1);
     }
 });
+// ─── flair rem candidates ─────────────────────────────────────────────────────
+// Slice 1 of FLAIR-NIGHTLY-REM (ops-2qq). Lists staged distillations from the
+// MemoryCandidate table. Empty until the nightly cycle (later slice) starts
+// populating. Per spec § 5: candidates are NEVER auto-promoted; this command
+// is the operator's review surface.
+rem
+    .command("candidates")
+    .description("List staged memory candidates from the FLAIR-NIGHTLY-REM cycle (pending review)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
+    .option("--status <s>", "Filter by status: pending | promoted | rejected (default: pending)")
+    .option("--json", "Output as JSON for scripting")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    const status = opts.status ?? "pending";
+    const validStatuses = new Set(["pending", "promoted", "rejected"]);
+    if (!validStatuses.has(status)) {
+        console.error(`Error: --status must be one of: pending, promoted, rejected (got: ${status})`);
+        process.exit(1);
+    }
+    if (!agentId) {
+        console.error("Error: --agent is required (or set FLAIR_AGENT_ID)");
+        process.exit(1);
+    }
+    try {
+        const result = await api("POST", "/MemoryCandidate/search_by_conditions", {
+            operator: "and",
+            conditions: [
+                { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+                { search_attribute: "status", search_type: "equals", search_value: status },
+            ],
+            get_attributes: ["id", "claim", "generatedBy", "generatedAt", "status", "target", "reviewerId", "decidedAt", "supersedes"],
+        });
+        // search_by_conditions returns either an array or { error }; tolerate both shapes
+        const candidates = Array.isArray(result) ? result : (result?.results ?? []);
+        if (opts.json) {
+            console.log(JSON.stringify({ agentId, status, count: candidates.length, candidates }, null, 2));
+            return;
+        }
+        console.log(`\n-- rem candidates (agent=${agentId}, status=${status}) --\n`);
+        if (candidates.length === 0) {
+            console.log(`No ${status} candidates.`);
+            if (status === "pending") {
+                console.log("\n(Run `flair rem nightly enable` to start the nightly distillation cycle that populates this table.)");
+            }
+            return;
+        }
+        // Sort newest-first by generatedAt
+        candidates.sort((a, b) => String(b.generatedAt ?? "").localeCompare(String(a.generatedAt ?? "")));
+        for (const c of candidates) {
+            const tag = c.status === "promoted"
+                ? `[promoted → ${c.target ?? "?"} by ${c.reviewerId ?? "?"} @ ${relativeTime(c.decidedAt)}]`
+                : c.status === "rejected"
+                    ? `[rejected by ${c.reviewerId ?? "?"} @ ${relativeTime(c.decidedAt)}]`
+                    : `[pending — ${c.generatedBy ?? "?"} @ ${relativeTime(c.generatedAt)}]`;
+            console.log(`  ${c.id}  ${tag}`);
+            console.log(`    ${c.claim}`);
+            if (c.supersedes)
+                console.log(`    (supersedes ${c.supersedes} — recurring proposal)`);
+            console.log("");
+        }
+        console.log(`${candidates.length} candidate${candidates.length > 1 ? "s" : ""}.`);
+        if (status === "pending") {
+            console.log(`Promote: flair rem promote <id> --rationale "<why>" --to (soul|memory)`);
+            console.log(`Reject:  flair rem reject <id> --reason "<why>"`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair rem promote / reject helpers ──────────────────────────────────────
+// Pure validators extracted for testability. The action callbacks below thread
+// these through process.exit on failure; the helpers themselves are
+// side-effect-free.
+export function validatePromoteOpts(opts) {
+    if (!opts.rationale || !opts.rationale.trim()) {
+        return "--rationale is required (per spec § 5: no rubber-stamp)";
+    }
+    if (!opts.to || (opts.to !== "soul" && opts.to !== "memory")) {
+        return "--to must be 'soul' or 'memory'";
+    }
+    if (opts.to === "soul" && (!opts.key || !opts.key.trim())) {
+        return "--key is required when --to=soul (gives the Soul entry a meaningful identifier)";
+    }
+    return null;
+}
+export function validateRejectOpts(opts) {
+    if (!opts.reason || !opts.reason.trim()) {
+        return "--reason is required";
+    }
+    return null;
+}
+/**
+ * Decide whether a promote/reject action can proceed against a candidate's
+ * current state, and what message to surface to the operator. Pure function;
+ * action side effects happen in the CLI body after this returns ok.
+ */
+export function decideCandidateAction(candidate, action) {
+    if (!candidate)
+        return { ok: false, severity: "error", message: "candidate not found" };
+    const status = candidate.status;
+    if (status === "promoted") {
+        return action === "promote"
+            ? { ok: false, severity: "error", message: `already promoted (target=${candidate.target}, reviewer=${candidate.reviewerId})` }
+            : { ok: false, severity: "error", message: `already promoted; cannot reject after promotion` };
+    }
+    if (status === "rejected") {
+        return action === "reject"
+            ? { ok: false, severity: "info", message: `already rejected on ${candidate.decidedAt} by ${candidate.reviewerId}` }
+            : { ok: false, severity: "error", message: `already rejected; use a fresh candidate or reset status manually` };
+    }
+    return { ok: true };
+}
+// ─── flair rem promote ───────────────────────────────────────────────────────
+// Slice 2 of FLAIR-NIGHTLY-REM (ops-2qq). Promote a candidate to either Soul
+// or persistent Memory. Both --rationale and --to are required (spec § 5: no
+// rubber-stamp). When --to=soul, --key is also required so the resulting
+// Soul row has a meaningful identifier.
+//
+// Trust-tier policy is enforced by the caller's authentication today (1.0):
+// admin pass → any promote; agent key → can write to own Memory/Soul. Server-
+// side trust-tier enforcement (endorsed agents → memory only, never soul) is
+// scoped for slice 2b when agent-routed promotion lands. For now, the
+// human-operator workflow is the supported path.
+rem
+    .command("promote")
+    .description("Promote a memory candidate to Soul or persistent Memory (rationale required)")
+    .argument("<candidate-id>", "MemoryCandidate id to promote")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--rationale <text>", "Why this candidate is being promoted (required, no rubber-stamp)")
+    .option("--to <target>", "Promotion target: 'soul' or 'memory'")
+    .option("--key <key>", "Soul key (required when --to=soul; e.g. 'lessons', 'preference-X')")
+    .option("--reviewer <id>", "Reviewer agent id (default: FLAIR_AGENT_ID or 'admin')")
+    .action(async (candidateId, opts) => {
+    const validationErr = validatePromoteOpts(opts);
+    if (validationErr) {
+        console.error(`Error: ${validationErr}`);
+        process.exit(1);
+    }
+    const reviewerId = opts.reviewer || process.env.FLAIR_AGENT_ID || "admin";
+    try {
+        // Fetch the candidate
+        const candidate = await api("GET", `/MemoryCandidate/${encodeURIComponent(candidateId)}`);
+        const candidateData = (candidate && !candidate.error) ? candidate : null;
+        const decision = decideCandidateAction(candidateData, "promote");
+        if (!decision.ok) {
+            const msg = decision.message;
+            console.error(`Error: candidate ${candidateId} ${msg}`);
+            process.exit(1);
+        }
+        const decidedAt = new Date().toISOString();
+        // Write the resulting Soul or Memory entry
+        if (opts.to === "memory") {
+            const memId = `${candidate.agentId}-promoted-${Date.now()}`;
+            const memWrite = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, {
+                id: memId,
+                agentId: candidate.agentId,
+                content: candidate.claim,
+                durability: "persistent",
+                tags: ["nightly-rem-promoted", `from:${candidateId}`],
+                derivedFrom: candidate.sourceMemoryIds ?? [],
+                promotionStatus: "approved",
+                promotedAt: decidedAt,
+                promotedBy: reviewerId,
+                createdAt: decidedAt,
+            });
+            if (memWrite?.error) {
+                console.error(`Error writing Memory: ${memWrite.error}`);
+                process.exit(1);
+            }
+            console.log(`✅ Wrote Memory ${memId} (durability=persistent)`);
+        }
+        else {
+            // soul
+            const soulId = `${candidate.agentId}-${opts.key}`;
+            const soulWrite = await api("PUT", `/Soul/${encodeURIComponent(soulId)}`, {
+                id: soulId,
+                agentId: candidate.agentId,
+                key: opts.key,
+                value: candidate.claim,
+                priority: "standard",
+                durability: "persistent",
+                createdAt: decidedAt,
+                updatedAt: decidedAt,
+            });
+            if (soulWrite?.error) {
+                console.error(`Error writing Soul: ${soulWrite.error}`);
+                process.exit(1);
+            }
+            console.log(`✅ Wrote Soul ${soulId} (key=${opts.key})`);
+        }
+        // Update the candidate row
+        const upd = await api("PUT", `/MemoryCandidate/${encodeURIComponent(candidateId)}`, {
+            ...candidate,
+            status: "promoted",
+            target: opts.to,
+            reviewerId,
+            reviewRationale: opts.rationale,
+            decidedAt,
+        });
+        if (upd?.error) {
+            console.error(`Warning: candidate row update returned: ${upd.error}`);
+        }
+        console.log(`✅ Candidate ${candidateId} marked promoted → ${opts.to}, reviewer=${reviewerId}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair rem reject ────────────────────────────────────────────────────────
+// Reject a candidate with a required --reason. Per spec § 5, rejected
+// candidates retain full decision history so recurring proposals are visible
+// via the supersedes chain.
+rem
+    .command("reject")
+    .description("Reject a memory candidate with a required reason")
+    .argument("<candidate-id>", "MemoryCandidate id to reject")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--reason <text>", "Why this candidate is being rejected (required)")
+    .option("--reviewer <id>", "Reviewer agent id (default: FLAIR_AGENT_ID or 'admin')")
+    .action(async (candidateId, opts) => {
+    const validationErr = validateRejectOpts(opts);
+    if (validationErr) {
+        console.error(`Error: ${validationErr}`);
+        process.exit(1);
+    }
+    const reviewerId = opts.reviewer || process.env.FLAIR_AGENT_ID || "admin";
+    try {
+        const candidate = await api("GET", `/MemoryCandidate/${encodeURIComponent(candidateId)}`);
+        const candidateData = (candidate && !candidate.error) ? candidate : null;
+        const decision = decideCandidateAction(candidateData, "reject");
+        if (!decision.ok) {
+            const _d = decision;
+            if (_d.severity === "info") {
+                console.log(`(candidate ${candidateId} ${_d.message})`);
+                return;
+            }
+            console.error(`Error: candidate ${candidateId} ${_d.message}`);
+            process.exit(1);
+        }
+        const decidedAt = new Date().toISOString();
+        const upd = await api("PUT", `/MemoryCandidate/${encodeURIComponent(candidateId)}`, {
+            ...candidate,
+            status: "rejected",
+            reviewerId,
+            reviewRationale: opts.reason,
+            decidedAt,
+        });
+        if (upd?.error) {
+            console.error(`Error: candidate row update failed: ${upd.error}`);
+            process.exit(1);
+        }
+        console.log(`✅ Candidate ${candidateId} rejected by ${reviewerId}`);
+        console.log(`   Reason: ${opts.reason}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
 // ─── flair status ─────────────────────────────────────────────────────────────
 function humanBytes(n) {
     if (!Number.isFinite(n) || n < 0)
@@ -3145,6 +4059,59 @@ function oauthDetailLines(o) {
     }
     return out;
 }
+// Common localhost ports a running Flair daemon might be on. Used by
+// discoverLocalFlairPort when the configured URL is unreachable, to detect
+// config-vs-daemon port drift (ops-mbdi). Order is ad-hoc — first hit wins.
+//
+// 9926: original default (long-running rockit installs predate the bump)
+// 19926: current default (DEFAULT_PORT)
+// 19925: ops-anvil VM secondary
+const LOCAL_FLAIR_PROBE_PORTS = [9926, 19926, 19925];
+export function isLocalhostUrl(url) {
+    try {
+        const u = new URL(url);
+        // URL.hostname keeps brackets around IPv6 (e.g. "[::1]") so match both forms.
+        return (u.hostname === "127.0.0.1" ||
+            u.hostname === "localhost" ||
+            u.hostname === "::1" ||
+            u.hostname === "[::1]");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * When a configured-localhost URL is unreachable, probe a small candidate-port
+ * set to detect a daemon listening on a different port (config drift). Returns
+ * the first responsive port, or null if none. Excludes the original port from
+ * the probe set so we don't repeat the failed call.
+ *
+ * Runs sequentially with a 500ms timeout per probe — typical 3-port sweep
+ * completes in <1.5s on a healthy box, faster on an unhealthy one.
+ */
+export async function discoverLocalFlairPort(originalUrl) {
+    if (!isLocalhostUrl(originalUrl))
+        return null;
+    let originalPort = null;
+    try {
+        originalPort = Number(new URL(originalUrl).port) || null;
+    }
+    catch { /* ignore */ }
+    for (const port of LOCAL_FLAIR_PROBE_PORTS) {
+        if (port === originalPort)
+            continue;
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/Health`, { signal: AbortSignal.timeout(500) });
+            // Treat 401 (auth required) the same as 200 — the daemon is alive,
+            // we just can't see /Health without admin auth. The point is to detect
+            // "something is listening" not "we have full access".
+            if (res.ok || res.status === 401)
+                return port;
+        }
+        catch { /* port not listening, try next */ }
+    }
+    return null;
+}
 async function fetchHealthDetail(opts) {
     const port = resolveHttpPort(opts);
     // --target takes precedence, then --url, then FLAIR_TARGET, then FLAIR_URL, then localhost
@@ -3210,8 +4177,18 @@ const statusCmd = program
     .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
     .action(async (opts) => {
     const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
+    // When unreachable on a localhost URL, probe candidate ports to detect
+    // config-vs-daemon port drift (ops-mbdi). Surface the actually-listening
+    // port with a fix recipe — better UX than just "unreachable."
+    let discoveredPort = null;
+    if (!healthy && isLocalhostUrl(baseUrl)) {
+        discoveredPort = await discoverLocalFlairPort(baseUrl);
+    }
     if (opts.json) {
-        console.log(JSON.stringify({ healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData }, null, 2));
+        const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData };
+        if (discoveredPort != null)
+            out.discoveredPort = discoveredPort;
+        console.log(JSON.stringify(out, null, 2));
         if (!healthy)
             process.exit(1);
         return;
@@ -3219,7 +4196,17 @@ const statusCmd = program
     if (!healthy) {
         console.log(`Flair v${__pkgVersion} — 🔴 unreachable`);
         console.log(`  URL:  ${baseUrl}`);
-        console.log(`\n  Run: flair start  or  flair doctor`);
+        if (discoveredPort != null) {
+            const altUrl = `http://127.0.0.1:${discoveredPort}`;
+            console.log(`\n  ⚠ Found a Flair daemon listening on port ${discoveredPort} (URL: ${altUrl}).`);
+            console.log(`    Your config points at ${baseUrl} — drift detected.`);
+            console.log(`\n  Quick fix: FLAIR_URL=${altUrl} flair status`);
+            console.log(`  Permanent fix: edit ~/.flair/config.yaml to set port: ${discoveredPort}`);
+            console.log(`  Or: flair doctor (when port-drift detection lands there)`);
+        }
+        else {
+            console.log(`\n  Run: flair start  or  flair doctor`);
+        }
         process.exit(1);
     }
     const uptimeSec = healthData?.uptimeSeconds;
@@ -3530,37 +4517,39 @@ program
     .description("Upgrade Flair and related packages to latest versions")
     .option("--check", "Only check for updates, don't install")
     .option("--restart", "Restart Flair after upgrade")
+    .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
     .action(async (opts) => {
     const { execSync, execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
+    const showAll = opts.all ?? false;
     console.log("Checking for updates...\n");
-    // Per-package install probes. `npm list -g` assumed the default global
-    // prefix and silently mis-reported "not installed" for anyone using
-    // mise / fnm / nvm / volta / non-default-prefix npm — including the
-    // running flair binary itself, which was obviously installed. Each
-    // entry now has a locator that works regardless of install path:
-    //
-    //   - For packages with a bin: shell out to the bin with --version
-    //     (same PATH lookup that got them invokable in the first place).
-    //   - For library packages: require.resolve the package.json from the
-    //     running flair's module graph (works whether it's a sibling
-    //     global install or a bundled dep).
     const packages = [
         {
             name: "@tpsdev-ai/flair",
+            kind: "bin",
             probe: () => probeBinVersion(execFileSync, "flair"),
         },
-        {
-            name: "@tpsdev-ai/flair-client",
-            probe: () => probeLibVersion("@tpsdev-ai/flair-client"),
-        },
         {
             name: "@tpsdev-ai/flair-mcp",
+            kind: "bin",
             probe: () => probeBinVersion(execFileSync, "flair-mcp"),
         },
+        {
+            name: "@tpsdev-ai/openclaw-flair",
+            kind: "openclaw-plugin",
+            probe: () => probeOpenclawPluginVersion("openclaw-flair"),
+        },
+        {
+            name: "@tpsdev-ai/flair-client",
+            kind: "lib",
+            probe: () => probeLibVersion("@tpsdev-ai/flair-client"),
+            transitive: true,
+        },
     ];
     const findings = [];
-    for (const { name, probe } of packages) {
+    for (const { name, probe, kind, transitive } of packages) {
+        if (transitive && !showAll)
+            continue;
         try {
             const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5000) });
             if (!res.ok)
@@ -3568,18 +4557,45 @@ program
             const data = await res.json();
             const latest = data.version ?? "unknown";
             const installed = probe();
-            const status = installed === null ? "missing" : installed === latest ? "current" : "outdated";
-            findings.push({ name, installed, latest, status });
-            const icon = status === "current" ? "✅" : status === "outdated" ? "⬆️" : "❔";
-            const installedLabel = installed ?? "not detected";
-            const suffix = status === "current" ? " (current)" : status === "missing" ? " (run: npm install -g)" : "";
+            let status;
+            if (installed === null) {
+                // openclaw-plugin packages are optional — if openclaw isn't
+                // installed, don't surface a misleading "install with npm" advice.
+                status = kind === "openclaw-plugin" ? "optional" : "missing";
+            }
+            else if (installed === latest) {
+                status = "current";
+            }
+            else {
+                status = "outdated";
+            }
+            findings.push({ name, installed, latest, status, kind });
+            const icon = status === "current" ? "✅"
+                : status === "outdated" ? "⬆️"
+                    : status === "optional" ? "○"
+                        : "❔";
+            const installedLabel = installed ?? (status === "optional" ? "not installed (openclaw not detected)" : "not detected");
+            const suffix = status === "current" ? " (current)"
+                : status === "missing" ? " (run: npm install -g)"
+                    : status === "optional" ? " (install via: openclaw plugins install @tpsdev-ai/openclaw-flair)"
+                        : "";
             console.log(`  ${icon} ${name}: ${installedLabel} → ${latest}${suffix}`);
         }
         catch { /* skip unavailable packages */ }
     }
     const outdated = findings.filter((f) => f.status === "outdated");
     const missing = findings.filter((f) => f.status === "missing");
-    const upgrades = outdated.map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
+    // openclaw plugins upgrade through `openclaw plugins install`, not `npm
+    // install -g` (npm-installed wouldn't connect to OpenClaw's gateway slot).
+    // Split outdated into npm-upgradeable vs openclaw-plugin so we can use
+    // the right command for each.
+    const npmUpgrades = outdated
+        .filter((f) => f.kind !== "openclaw-plugin")
+        .map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
+    const openclawUpgrades = outdated
+        .filter((f) => f.kind === "openclaw-plugin")
+        .map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
+    const totalUpgrades = npmUpgrades.length + openclawUpgrades.length;
     if (outdated.length === 0 && missing.length === 0) {
         console.log("\n✅ Everything is up to date.");
         return;
@@ -3599,9 +4615,9 @@ program
     // Perform upgrade. `latest` comes from the npm registry's HTTP
     // response, so CodeQL (correctly) treats it as untrusted input.
     // Use execFileSync with argv — the spec `<name>@<version>` becomes a
-    // single argument to npm, no shell to inject into.
-    console.log(`\nUpgrading ${upgrades.length} package${upgrades.length > 1 ? "s" : ""}...\n`);
-    for (const { pkg, latest } of upgrades) {
+    // single argument to the upgrade command, no shell to inject into.
+    console.log(`\nUpgrading ${totalUpgrades} package${totalUpgrades > 1 ? "s" : ""}...\n`);
+    for (const { pkg, latest } of npmUpgrades) {
         try {
             console.log(`  Installing ${pkg}@${latest}...`);
             execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
@@ -3611,6 +4627,26 @@ program
             console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
         }
     }
+    for (const { pkg, latest } of openclawUpgrades) {
+        // OpenClaw plugins upgrade via `openclaw plugins install --force --pin`.
+        // Requires openclaw on PATH; if not, surface the manual recipe instead
+        // of a confusing failure.
+        try {
+            execFileSync("openclaw", ["--version"], { stdio: "pipe", timeout: 2000 });
+        }
+        catch {
+            console.error(`  ❌ ${pkg} upgrade skipped: openclaw not on PATH. Install manually: openclaw plugins install ${pkg}@${latest} --force --pin`);
+            continue;
+        }
+        try {
+            console.log(`  Installing ${pkg}@${latest} via openclaw...`);
+            execFileSync("openclaw", ["plugins", "install", `${pkg}@${latest}`, "--force", "--pin"], { stdio: "pipe" });
+            console.log(`  ✅ ${pkg}@${latest} installed`);
+        }
+        catch (err) {
+            console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
+        }
+    }
     if (opts.restart) {
         console.log("\nRestarting Flair...");
         try {
@@ -3963,21 +4999,40 @@ program
             console.error("❌ Admin password required when --agent is not specified (set FLAIR_ADMIN_PASS or HDB_ADMIN_PASSWORD)");
             process.exit(1);
         }
-        // Fetch all memories with admin auth
-        const searchRes = await fetch(`${baseUrl}/SemanticSearch`, {
+        // Fetch every memory via the Harper ops API (search_by_conditions on the
+        // Memory table) rather than POST /SemanticSearch. SemanticSearch goes
+        // through the HNSW cosine index, which throws "Cosine distance comparison
+        // requires an array" against rows whose stored embedding shape is
+        // incompatible with the running Harper version (e.g. data written under
+        // @harperfast/harper@5.0.1 read under 5.0.9). The ops API bypasses the
+        // vector index — exactly what we need when the goal is to replace every
+        // embedding with a freshly-computed one. Without this path, `flair
+        // reembed` could not recover from the very condition it exists to fix.
+        const opsPort = resolveOpsPort(opts);
+        const opsAuth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+        // Harper rejects empty-value conditions ("not indexed for nulls"). Use
+        // `createdAt > 1970-01-01` as the "select all" pattern: every Memory row
+        // has a createdAt, the index is built, and the comparison is total.
+        const searchRes = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`,
-            },
-            body: JSON.stringify({ limit: 10000 }),
+            headers: { "Content-Type": "application/json", Authorization: opsAuth },
+            body: JSON.stringify({
+                operation: "search_by_conditions",
+                database: "flair",
+                table: "Memory",
+                operator: "and",
+                conditions: [{ search_attribute: "createdAt", search_type: "greater_than", search_value: "1970-01-01" }],
+                get_attributes: ["*"],
+                limit: 100000,
+            }),
+            signal: AbortSignal.timeout(60_000),
         });
         if (!searchRes.ok) {
-            console.error(`❌ Failed to fetch memories: ${searchRes.status}`);
+            console.error(`❌ Failed to fetch memories via ops API: ${searchRes.status}`);
             process.exit(1);
         }
-        const data = await searchRes.json();
-        const allMemories = data.results ?? [];
+        const raw = await searchRes.json();
+        const allMemories = Array.isArray(raw) ? raw : (raw?.results ?? []);
         // Group by agentId
         const byAgent = new Map();
         for (const m of allMemories) {
@@ -4037,22 +5092,53 @@ program
         console.log(`\n\n✅ Re-embedding complete: ${totalProcessed} updated, ${totalErrors} errors`);
         return;
     }
-    // Original single-agent path
+    // Single-agent path. Same rationale as above: fetch via the ops API
+    // (search_by_value on agentId) so the vector index isn't in the read path.
+    // This requires admin pass — fall back to the old SemanticSearch fetch only
+    // if no admin pass is available, since that path still works on
+    // version-matched data and requires only the agent's own key.
     const keysDir = defaultKeysDir();
     const privPath = privKeyPath(agentId, keysDir);
     if (!existsSync(privPath)) {
         console.error(`❌ Key not found: ${privPath}`);
         process.exit(1);
     }
-    const searchRes = await authFetch(baseUrl, agentId, privPath, "POST", "/SemanticSearch", {
-        agentId, limit: 10000,
-    });
-    if (!searchRes.ok) {
-        console.error(`❌ Failed to fetch memories: ${searchRes.status}`);
-        process.exit(1);
+    const adminPassSingle = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+    let allMemories = [];
+    if (adminPassSingle) {
+        const opsPort = resolveOpsPort(opts);
+        const opsAuth = `Basic ${Buffer.from(`admin:${adminPassSingle}`).toString("base64")}`;
+        const searchRes = await fetch(`http://127.0.0.1:${opsPort}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: opsAuth },
+            body: JSON.stringify({
+                operation: "search_by_value",
+                database: "flair",
+                table: "Memory",
+                search_attribute: "agentId",
+                search_value: agentId,
+                get_attributes: ["*"],
+            }),
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!searchRes.ok) {
+            console.error(`❌ Failed to fetch memories via ops API: ${searchRes.status}`);
+            process.exit(1);
+        }
+        const raw = await searchRes.json();
+        allMemories = Array.isArray(raw) ? raw : (raw?.results ?? []);
+    }
+    else {
+        const searchRes = await authFetch(baseUrl, agentId, privPath, "POST", "/SemanticSearch", {
+            agentId, limit: 10000,
+        });
+        if (!searchRes.ok) {
+            console.error(`❌ Failed to fetch memories: ${searchRes.status}`);
+            process.exit(1);
+        }
+        const data = await searchRes.json();
+        allMemories = data.results ?? [];
     }
-    const data = await searchRes.json();
-    const allMemories = data.results ?? [];
     const candidates = allMemories.filter((m) => {
         if (!m.content)
             return false;
@@ -4505,11 +5591,164 @@ program
     if (issues > 0)
         process.exit(1);
 });
+// ─── flair session snapshot ──────────────────────────────────────────────────
+// Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B (ops-9wji-B / ops-ojht). Snapshot a
+// session jsonl + label metadata into a tar.gz under ~/.flair/snapshots/<agent>/sessions/.
+//
+// Three subcommands: create | list | restore. Mirrors FLAIR-NIGHTLY-REM's
+// snapshot pattern (tar.gz, 600 perms, 30-day retention enforced separately).
+//
+// Standalone-callable today; harness slices 3+4 will wire it into the
+// session-reset pipeline.
+const SNAPSHOT_ROOT = resolve(homedir(), ".flair", "snapshots");
+function sessionSnapshotDir(agent) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(agent))
+        throw new Error(`invalid agent id: ${agent}`);
+    return resolve(SNAPSHOT_ROOT, agent, "sessions");
+}
+const session = program.command("session").description("Agent session lifecycle (snapshot/restore for FLAIR-AGENT-CONTEXT-TIERS-B)");
+const sessionSnapshot = session.command("snapshot").description("Manage session snapshots (tar.gz of session jsonl + metadata)");
+sessionSnapshot
+    .command("create")
+    .description("Create a session snapshot tar.gz")
+    .requiredOption("--agent <id>", "Agent the session belongs to")
+    .requiredOption("--session-file <path>", "Path to the session jsonl to snapshot (e.g. /tmp/openclaw/openclaw-2026-05-03.log)")
+    .option("--label <text>", "Label for the snapshot file (e.g. ops-ID); default: ISO timestamp")
+    .action(async (opts) => {
+    const sessionFile = resolve(opts.sessionFile);
+    if (!existsSync(sessionFile)) {
+        console.error(`Error: --session-file does not exist: ${sessionFile}`);
+        process.exit(1);
+    }
+    const dir = sessionSnapshotDir(opts.agent);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const safeLabel = opts.label ? String(opts.label).replace(/[^a-zA-Z0-9._-]/g, "_") : ts;
+    const tarballName = opts.label ? `${safeLabel}-${ts}.tar.gz` : `${ts}.tar.gz`;
+    const tarballPath = resolve(dir, tarballName);
+    // Write a metadata.json into a tmp dir alongside the session file for the
+    // tarball, so the snapshot is self-describing.
+    const meta = {
+        agent: opts.agent,
+        label: opts.label ?? null,
+        sessionFile,
+        sessionFileSize: statSync(sessionFile).size,
+        createdAt: new Date().toISOString(),
+        flairVersion: __pkgVersion,
+    };
+    const tmpDir = resolve(dir, `.tmp-${process.pid}-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    try {
+        const sessionBaseName = sessionFile.split("/").pop() ?? "session.jsonl";
+        writeFileSync(resolve(tmpDir, sessionBaseName), readFileSync(sessionFile));
+        writeFileSync(resolve(tmpDir, "metadata.json"), JSON.stringify(meta, null, 2) + "\n");
+        await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, [sessionBaseName, "metadata.json"]);
+        // Tarball perms: 600 (owner-only) — matches FLAIR-NIGHTLY-REM
+        chmodSync(tarballPath, 0o600);
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    const size = statSync(tarballPath).size;
+    console.log(tarballPath);
+    console.error(`  agent: ${opts.agent}`);
+    console.error(`  label: ${opts.label ?? "(none)"}`);
+    console.error(`  size:  ${humanBytes(size)}`);
+});
+sessionSnapshot
+    .command("list")
+    .description("List session snapshots for an agent (or all agents)")
+    .option("--agent <id>", "Filter to a single agent")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    if (!existsSync(SNAPSHOT_ROOT)) {
+        if (opts.json) {
+            console.log("[]");
+            return;
+        }
+        console.log("(no snapshots — ~/.flair/snapshots/ does not exist yet)");
+        return;
+    }
+    const { readdirSync } = require("node:fs");
+    const rows = [];
+    const agents = opts.agent ? [opts.agent] : readdirSync(SNAPSHOT_ROOT).filter((d) => {
+        try {
+            return statSync(resolve(SNAPSHOT_ROOT, d)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    for (const a of agents) {
+        const dir = resolve(SNAPSHOT_ROOT, a, "sessions");
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".tar.gz"))
+                continue;
+            const p = resolve(dir, f);
+            const s = statSync(p);
+            rows.push({ agent: a, file: f, path: p, size: s.size, mtime: s.mtime.toISOString() });
+        }
+    }
+    rows.sort((a, b) => b.mtime.localeCompare(a.mtime));
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("(no snapshots)");
+        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" : ""}.`);
+});
+sessionSnapshot
+    .command("restore")
+    .description("Extract a session snapshot to a target directory")
+    .requiredOption("--snapshot <path>", "Path to the .tar.gz snapshot")
+    .option("--target <dir>", "Directory to extract into (default: <snapshot>.restored next to the snapshot)")
+    .option("--dry-run", "List the snapshot's contents without extracting")
+    .action(async (opts) => {
+    const snapshotPath = resolve(opts.snapshot);
+    if (!existsSync(snapshotPath)) {
+        console.error(`Error: snapshot does not exist: ${snapshotPath}`);
+        process.exit(1);
+    }
+    if (opts.dryRun) {
+        console.log("(dry-run) snapshot contents:");
+        const entries = [];
+        await tarList({ file: snapshotPath, onReadEntry: (entry) => entries.push(`  ${entry.path}  (${humanBytes(entry.size ?? 0)})`) });
+        for (const e of entries)
+            console.log(e);
+        return;
+    }
+    const targetDir = opts.target
+        ? resolve(opts.target)
+        : `${snapshotPath}.restored`;
+    if (existsSync(targetDir)) {
+        console.error(`Error: target directory already exists: ${targetDir}`);
+        console.error(`  Pass --target <new-path> or remove the existing dir.`);
+        process.exit(1);
+    }
+    mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    await tarExtract({ file: snapshotPath, cwd: targetDir });
+    console.log(targetDir);
+    console.error(`  extracted to: ${targetDir}`);
+});
 // ─── Memory and Soul commands ────────────────────────────────────────────────
 const memory = program.command("memory").description("Manage agent memories");
 memory.command("add [content]").requiredOption("--agent <id>")
     .option("--content <text>", "memory content (alias for positional arg)")
     .option("--durability <d>", "standard").option("--tags <csv>")
+    .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content; ops-wkoh)")
+    .option("--subject <text>", "one-line title / entity this memory is about")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {
@@ -4517,13 +5756,95 @@ memory.command("add [content]").requiredOption("--agent <id>")
         process.exit(1);
     }
     const memId = `${opts.agent}-${Date.now()}`;
-    const out = await api("PUT", `/Memory/${memId}`, {
+    const body = {
         id: memId, agentId: opts.agent, content, durability: opts.durability || "standard",
         tags: opts.tags ? String(opts.tags).split(",").map((x) => x.trim()).filter(Boolean) : undefined,
         type: "memory", createdAt: new Date().toISOString(),
-    });
+    };
+    if (opts.summary)
+        body.summary = opts.summary;
+    if (opts.subject)
+        body.subject = opts.subject;
+    const out = await api("PUT", `/Memory/${memId}`, body);
     console.log(JSON.stringify(out, null, 2));
 });
+// ─── flair memory write-task-summary ────────────────────────────────────────
+// Slice 1 of FLAIR-AGENT-CONTEXT-TIERS-B (ops-9wji-B / ops-3xyd). Standalone
+// helper that any agent harness (or a manual operator) can invoke at task
+// close to capture a structured task summary as a persistent Memory row
+// before resetting the session.
+//
+// The shape of this row matters: tags=['task-summary','auto-on-reset'] +
+// subject='task:<beads-id>' + summary populated. Slice 3+4 (harness
+// integrations) will call this as part of the reset pipeline; slice 5+6
+// (operator surfaces) will surface promote/restore controls. Today, this
+// command is independently useful — operator can capture a manual summary
+// at any time.
+//
+// Returns the memory id on stdout (single line, parseable) so the harness
+// can plumb it into the next-dispatch system message.
+memory.command("write-task-summary")
+    .description("Capture a structured task summary as a persistent Memory row (used by session-reset harness; standalone-callable by operators)")
+    .requiredOption("--agent <id>", "Agent the summary belongs to")
+    .requiredOption("--beads <ops-id>", "Bead/PR/task identifier this summary is about (e.g. ops-3xyd)")
+    .requiredOption("--outcome <s>", "Outcome of the task: merged | rejected | abandoned")
+    .option("--summary <text>", "Multi-sentence dense compression (populates Memory.summary; will be the agent's read-time view)")
+    .option("--files-touched <csv>", "Comma-separated list of files touched during the task (becomes part of content)")
+    .option("--lessons <text>", "Lessons learned during the task (becomes part of content)")
+    .option("--derived-from <csv>", "Comma-separated list of source Memory IDs this summary was distilled from")
+    .action(async (opts) => {
+    const validOutcomes = new Set(["merged", "rejected", "abandoned"]);
+    if (!validOutcomes.has(opts.outcome)) {
+        console.error(`Error: --outcome must be one of: merged, rejected, abandoned (got: ${opts.outcome})`);
+        process.exit(1);
+    }
+    if (!opts.summary && !opts.lessons && !opts.filesTouched) {
+        console.error("Error: at least one of --summary, --lessons, --files-touched is required (otherwise the summary has no content)");
+        process.exit(1);
+    }
+    // Build the structured content block. Format chosen to be parseable + readable
+    // — the agent reads it back on bootstrap of the next session.
+    const lines = [];
+    lines.push(`task: ${opts.beads}`);
+    lines.push(`outcome: ${opts.outcome}`);
+    if (opts.filesTouched)
+        lines.push(`files: ${opts.filesTouched}`);
+    if (opts.lessons) {
+        lines.push("");
+        lines.push("lessons:");
+        lines.push(opts.lessons);
+    }
+    if (opts.summary) {
+        lines.push("");
+        lines.push("summary:");
+        lines.push(opts.summary);
+    }
+    const content = lines.join("\n");
+    const memId = `${opts.agent}-task-${opts.beads}-${Date.now()}`;
+    const body = {
+        id: memId,
+        agentId: opts.agent,
+        content,
+        durability: "persistent",
+        tags: ["task-summary", "auto-on-reset"],
+        subject: `task:${opts.beads}`,
+        type: "task-summary",
+        createdAt: new Date().toISOString(),
+    };
+    if (opts.summary)
+        body.summary = opts.summary;
+    if (opts.derivedFrom) {
+        body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
+    }
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body);
+    if (out?.error) {
+        console.error(`Error writing task summary: ${out.error}`);
+        process.exit(1);
+    }
+    // Print just the memory id on stdout so the harness can capture it
+    // without parsing a JSON blob.
+    console.log(memId);
+});
 memory.command("search [query]").requiredOption("--agent <id>")
     .option("--q <query>", "search query (alias for positional arg)")
     .option("--limit <n>", "Max results", "5")
@@ -4629,6 +5950,20 @@ program
     }
 });
 // ─── flair bootstrap ─────────────────────────────────────────────────────────
+//
+// `flair bootstrap` prints agent context (soul, memories) and a structured budget
+// footer summarizing token usage and memory inclusion/truncation. The footer is
+// parseable for downstream agents to react to budget pressure.
+//
+// Budget footer format (printed to stderr):
+//   [budget: <used>/<max> tokens, <included> included, <truncated> truncated]
+//
+// Fields:
+//   - tokens: estimated tokens used / max budget
+//   - included: number of memories/soul entries included in context
+//   - truncated: number of memories excluded due to token budget
+//
+// When truncated &gt; 0, the agent should consider asking for more context or reducing scope.
 program
     .command("bootstrap")
     .description("Cold-start context: get soul + recent memories as formatted text")
@@ -4662,6 +5997,12 @@ program
             console.error("No context available.");
             process.exit(1);
         }
+        // Print budget footer to stderr (parseable, won't interfere with context output)
+        const tokensUsed = result.tokenEstimate ?? 0;
+        const maxTokens = parseInt(opts.maxTokens, 10);
+        const included = result.memoriesIncluded ?? 0;
+        const truncated = result.memoriesTruncated ?? 0;
+        console.error(`[budget: ${tokensUsed}/${maxTokens} tokens, ${included} included, ${truncated} truncated]`);
     }
     catch (err) {
         console.error(`Bootstrap failed: ${err.message}`);
@@ -4757,6 +6098,7 @@ bridge
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--key <path>", "Ed25519 private key path (default: resolved from agent)")
+    .option("--source <path>", "Source directory (for directory-based imports like markdown)")
     .action(async (name, srcArg, opts) => {
     const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
     const cwd = opts.cwd ?? srcArg ?? process.cwd();
@@ -5520,7 +6862,7 @@ program
     };
     const rawOutputPath = opts.output ?? join(homedir(), ".flair", "exports", `${agentId}-${Date.now()}.json`);
     // Canonicalize to prevent path traversal (e.g. ../../etc/passwd)
-    const outputPath = resolvePath(rawOutputPath);
+    const outputPath = resolve(rawOutputPath);
     mkdirSync(join(outputPath, ".."), { recursive: true });
     const fileMode = privateKey ? 0o600 : 0o644;
     writeFileSync(outputPath, JSON.stringify(exportData, null, 2), { mode: fileMode });
@@ -5919,4 +7261,4 @@ if (import.meta.main) {
     await program.parseAsync();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, };
+export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };