@tpsdev-ai/flair 0.4.16 → 0.5.1

package/dist/cli.js

@@ -6,6 +6,8 @@ import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID } from "node:crypto";
+import { keystore } from "./keystore.js";
+import { signBody } from "../resources/federation-crypto.js";
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
@@ -127,6 +129,11 @@ async function api(method, path, body) {
     if (token) {
         authHeader = `Bearer ${token}`;
     }
+    else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
+        // Admin Basic auth — used by federation, backup, and other admin CLI commands
+        const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+        authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+    }
     else {
         // Extract agentId from body (POST/PUT) or URL query params (GET)
         let agentId = process.env.FLAIR_AGENT_ID || (body && typeof body === "object" ? body.agentId : undefined);
@@ -357,14 +364,37 @@ program
                 // Only applied to install — run needs real HOME for npm/node resolution.
                 const installEnv = { ...env, HOME: join(dataDir, "..") };
                 console.log("Installing Harper...");
+                console.log("Downloading embedding model (nomic-embed-text-v1.5, ~80MB) — this may take a minute...");
                 await new Promise((resolve, reject) => {
                     let output = "";
+                    let dotTimer = null;
                     const install = spawn(process.execPath, [bin, "install"], { cwd: flairPackageDir(), env: installEnv });
+                    // Print progress dots so the terminal doesn't appear frozen during model download
+                    dotTimer = setInterval(() => process.stdout.write("."), 3000);
                     install.stdout?.on("data", (d) => { output += d.toString(); });
                     install.stderr?.on("data", (d) => { output += d.toString(); });
-                    install.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`Harper install failed (${code}): ${output}`)));
-                    install.on("error", reject);
-                    setTimeout(() => { install.kill(); reject(new Error(`Harper install timed out: ${output}`)); }, 60_000);
+                    install.on("exit", (code) => {
+                        if (dotTimer) {
+                            clearInterval(dotTimer);
+                            process.stdout.write("\n");
+                        }
+                        code === 0 ? resolve() : reject(new Error(`Harper install failed (${code}): ${output}`));
+                    });
+                    install.on("error", (err) => {
+                        if (dotTimer) {
+                            clearInterval(dotTimer);
+                            process.stdout.write("\n");
+                        }
+                        reject(err);
+                    });
+                    setTimeout(() => {
+                        install.kill();
+                        if (dotTimer) {
+                            clearInterval(dotTimer);
+                            process.stdout.write("\n");
+                        }
+                        reject(new Error(`Harper install timed out: ${output}`));
+                    }, 60_000);
                 });
             }
             // Start Harper with flair loaded as a component (the "." arg).
@@ -490,7 +520,25 @@ program
         console.log("\n🎭 Set up agent personality (press Enter to skip any):\n");
         const { createInterface } = await import("node:readline");
         const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const ask = (q) => new Promise(r => rl.question(q, r));
+        // Buffered ask: collects rapid input (pasted text) into one answer.
+        // Waits 200ms after last line before resolving, so pasted multiline
+        // blocks are captured as a single answer instead of spilling across prompts.
+        const ask = (q) => new Promise(resolve => {
+            let buffer = "";
+            let timer = null;
+            const finish = () => {
+                rl.removeListener("line", onLine);
+                resolve(buffer.trim());
+            };
+            const onLine = (line) => {
+                buffer += (buffer ? "\n" : "") + line;
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(finish, 200);
+            };
+            process.stdout.write(q);
+            rl.on("line", onLine);
+        });
         const role = await ask("   What's this agent's role? (e.g., \"Senior dev, concise and direct\")\n   > ");
         const project = await ask("   What project is it working on?\n   > ");
         const standards = await ask("   Any coding standards or preferences?\n   > ");
@@ -520,6 +568,25 @@ program
             console.log("\n   No soul entries — you can add them later with: flair soul set --agent " + agentId + " --key role --value \"...\"");
         }
     }
+    else {
+        // --skip-soul or non-interactive: seed sensible defaults so bootstrap returns useful context
+        const defaultSoulEntries = [
+            ["role", "AI assistant [default — customize with 'flair soul set']"],
+            ["personality", "Helpful, precise, and proactive [default — customize with 'flair soul set']"],
+            ["constraints", "Respect user privacy. Be concise. [default — customize with 'flair soul set']"],
+        ];
+        console.log("\nSeeding default soul entries...");
+        for (const [key, value] of defaultSoulEntries) {
+            try {
+                await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
+                console.log(`   ✓ soul:${key} set (default)`);
+            }
+            catch (err) {
+                console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
+            }
+        }
+        console.log(`   Customize with: flair soul set --agent ${agentId} --key role --value "..."`);
+    }
     console.log(`\n   Claude Code: Add to your CLAUDE.md:`);
     console.log(`     At the start of every session, run mcp__flair__bootstrap before responding.`);
     // Auto-wire MCP config into ~/.claude.json if Claude Code is installed
@@ -822,6 +889,373 @@ agent
     }
     console.log(`\n✅ Agent '${id}' removed successfully`);
 });
+// ─── flair principal ─────────────────────────────────────────────────────────
+// 1.0 identity management. The Principal model extends Agent — this is the
+// preferred CLI surface for managing identities going forward.
+const principal = program.command("principal").description("Manage principals (humans and agents)");
+principal
+    .command("add <id>")
+    .description("Create a new principal")
+    .option("--kind <kind>", "Principal kind: human or agent", "agent")
+    .option("--name <name>", "Display name (defaults to id)")
+    .option("--admin", "Grant admin privileges")
+    .option("--trust <tier>", "Default trust tier: endorsed, corroborated, or unverified")
+    .option("--runtime <runtime>", "Runtime: openclaw, claude-code, headless, external")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password for registration")
+    .option("--keys-dir <dir>", "Directory for Ed25519 keys")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (id, opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const keysDir = opts.keysDir ?? defaultKeysDir();
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS;
+    const adminUser = DEFAULT_ADMIN_USER;
+    const kind = opts.kind ?? "agent";
+    const name = opts.name ?? id;
+    const isAdmin = opts.admin ?? false;
+    const trustTier = opts.trust ?? (isAdmin ? "endorsed" : "unverified");
+    const runtime = opts.runtime;
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    // Generate Ed25519 keypair (agents always get one; humans get one for instance-attestation)
+    mkdirSync(keysDir, { recursive: true });
+    const privPath = privKeyPath(id, keysDir);
+    const pubPath = pubKeyPath(id, keysDir);
+    let pubKeyB64url;
+    if (existsSync(privPath)) {
+        console.log(`Reusing existing key: ${privPath}`);
+        const seed = new Uint8Array(readFileSync(privPath));
+        const kp = nacl.sign.keyPair.fromSeed(seed);
+        pubKeyB64url = b64url(kp.publicKey);
+    }
+    else {
+        const kp = nacl.sign.keyPair();
+        const seed = kp.secretKey.slice(0, 32);
+        writeFileSync(privPath, Buffer.from(seed));
+        chmodSync(privPath, 0o600);
+        writeFileSync(pubPath, Buffer.from(kp.publicKey));
+        pubKeyB64url = b64url(kp.publicKey);
+        console.log(`Keypair written: ${privPath}`);
+    }
+    // Insert via operations API with Principal fields
+    const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+    const record = {
+        id,
+        name,
+        displayName: name,
+        kind,
+        type: kind === "human" ? "human" : "agent",
+        status: "active",
+        publicKey: pubKeyB64url,
+        defaultTrustTier: trustTier,
+        admin: isAdmin,
+        runtime: runtime ?? null,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({ operation: "upsert", database: "flair", table: "Agent", records: [record] }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(`✅ Principal '${id}' created`);
+    console.log(`   Kind:       ${kind}`);
+    console.log(`   Trust:      ${trustTier}`);
+    console.log(`   Admin:      ${isAdmin}`);
+    if (runtime)
+        console.log(`   Runtime:    ${runtime}`);
+    console.log(`   Public key: ${pubKeyB64url}`);
+    console.log(`   Private key: ${privPath}`);
+});
+principal
+    .command("list")
+    .description("List all principals")
+    .option("--kind <kind>", "Filter by kind: human or agent")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const kindFilter = opts.kind ? ` WHERE kind = '${opts.kind}'` : "";
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({
+            operation: "sql",
+            sql: `SELECT id, name, kind, status, defaultTrustTier, admin, runtime, createdAt FROM flair.Agent${kindFilter} ORDER BY createdAt`,
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    const records = await res.json();
+    if (records.length === 0) {
+        console.log("No principals found.");
+        return;
+    }
+    // Table format
+    console.log(`${"ID".padEnd(20)} ${"Kind".padEnd(7)} ${"Trust".padEnd(14)} ${"Admin".padEnd(6)} ${"Status".padEnd(12)} ${"Runtime".padEnd(12)} Created`);
+    console.log("─".repeat(95));
+    for (const r of records) {
+        const kind = r.kind ?? "agent";
+        const trust = r.defaultTrustTier ?? "—";
+        const admin = r.admin ? "yes" : "no";
+        const status = r.status ?? "active";
+        const runtime = r.runtime ?? "—";
+        const created = r.createdAt?.slice(0, 10) ?? "—";
+        console.log(`${String(r.id).padEnd(20)} ${kind.padEnd(7)} ${trust.padEnd(14)} ${admin.padEnd(6)} ${status.padEnd(12)} ${runtime.padEnd(12)} ${created}`);
+    }
+});
+principal
+    .command("show <id>")
+    .description("Show principal details")
+    .action(async (id) => {
+    const result = await api("GET", `/Agent/${id}`);
+    console.log(JSON.stringify(result, null, 2));
+});
+principal
+    .command("disable <id>")
+    .description("Deactivate a principal (revokes access, preserves data)")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (id, opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({
+            operation: "update",
+            database: "flair",
+            table: "Agent",
+            records: [{ id, status: "deactivated", updatedAt: new Date().toISOString() }],
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(`✅ Principal '${id}' deactivated`);
+});
+principal
+    .command("promote <id> <tier>")
+    .description("Change a principal's trust tier (endorsed, corroborated, unverified)")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (id, tier, opts) => {
+    const validTiers = ["endorsed", "corroborated", "unverified"];
+    if (!validTiers.includes(tier)) {
+        console.error(`Error: tier must be one of: ${validTiers.join(", ")}`);
+        process.exit(1);
+    }
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({
+            operation: "update",
+            database: "flair",
+            table: "Agent",
+            records: [{ id, defaultTrustTier: tier, updatedAt: new Date().toISOString() }],
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(`✅ Principal '${id}' trust tier set to '${tier}'`);
+});
+// ─── flair idp ───────────────────────────────────────────────────────────────
+// XAA Enterprise IdP configuration (per FLAIR-XAA spec § 4).
+const idp = program.command("idp").description("Manage enterprise IdP configurations (XAA)");
+idp
+    .command("add")
+    .description("Register a trusted enterprise IdP")
+    .requiredOption("--name <name>", "Display name (e.g., 'Harper Corporate')")
+    .requiredOption("--issuer <url>", "IdP issuer URL (e.g., https://accounts.google.com)")
+    .requiredOption("--jwks-uri <url>", "JWKS endpoint URL")
+    .requiredOption("--client-id <id>", "Flair's client_id at this IdP")
+    .option("--required-domain <domain>", "Reject tokens without this domain (hd/tid claim)")
+    .option("--no-jit-provision", "Disable auto-creation of principals for new IdP users")
+    .option("--default-trust <tier>", "Trust tier for JIT principals", "unverified")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const id = `idp_${randomUUID().slice(0, 8)}`;
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const now = new Date().toISOString();
+    const record = {
+        id,
+        name: opts.name,
+        issuer: opts.issuer,
+        jwksUri: opts.jwksUri,
+        clientId: opts.clientId,
+        requiredDomain: opts.requiredDomain ?? null,
+        jitProvision: opts.jitProvision !== false,
+        defaultTrustTier: opts.defaultTrust ?? "unverified",
+        enabled: true,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({ operation: "upsert", database: "flair", table: "IdpConfig", records: [record] }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(`✅ IdP '${opts.name}' registered (id: ${id})`);
+    console.log(`   Issuer:   ${opts.issuer}`);
+    console.log(`   JWKS:     ${opts.jwksUri}`);
+    console.log(`   Client:   ${opts.clientId}`);
+    if (opts.requiredDomain)
+        console.log(`   Domain:   ${opts.requiredDomain}`);
+    console.log(`   JIT:      ${opts.jitProvision !== false}`);
+});
+idp
+    .command("list")
+    .description("List configured IdPs")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({
+            operation: "sql",
+            sql: "SELECT id, name, issuer, requiredDomain, jitProvision, enabled, createdAt FROM flair.IdpConfig ORDER BY createdAt",
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    const records = await res.json();
+    if (records.length === 0) {
+        console.log("No IdPs configured.");
+        return;
+    }
+    for (const r of records) {
+        const status = r.enabled ? "enabled" : "disabled";
+        console.log(`${r.name} (${r.id}) — ${status}`);
+        console.log(`  Issuer: ${r.issuer}`);
+        if (r.requiredDomain)
+            console.log(`  Domain: ${r.requiredDomain}`);
+        console.log(`  JIT: ${r.jitProvision ?? true}`);
+        console.log();
+    }
+});
+idp
+    .command("remove <id>")
+    .description("Remove an IdP configuration")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (id, opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({ operation: "delete", database: "flair", table: "IdpConfig", hash_values: [id] }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(`✅ IdP '${id}' removed`);
+});
+idp
+    .command("test <id>")
+    .description("Test IdP connectivity (fetches JWKS)")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (id, opts) => {
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.IdpConfig WHERE id = '${id}'` }),
+    });
+    const records = await res.json();
+    if (records.length === 0) {
+        console.error(`IdP '${id}' not found`);
+        process.exit(1);
+    }
+    const cfg = records[0];
+    console.log(`Testing IdP: ${cfg.name} (${cfg.issuer})`);
+    console.log(`  JWKS endpoint: ${cfg.jwksUri}`);
+    try {
+        const jwksRes = await fetch(cfg.jwksUri, { signal: AbortSignal.timeout(10_000) });
+        if (!jwksRes.ok) {
+            console.error(`  ❌ JWKS fetch failed: HTTP ${jwksRes.status}`);
+            process.exit(1);
+        }
+        const jwks = await jwksRes.json();
+        const keyCount = jwks.keys?.length ?? 0;
+        console.log(`  ✅ JWKS reachable — ${keyCount} key(s) found`);
+    }
+    catch (err) {
+        console.error(`  ❌ JWKS fetch error: ${err.message}`);
+        process.exit(1);
+    }
+});
 // ─── flair grant / revoke ─────────────────────────────────────────────────────
 program
     .command("grant <from-agent> <to-agent>")
@@ -913,61 +1347,569 @@ program
     console.log(`✅ Grant revoked: '${toAgent}' can no longer read '${fromAgent}'s memories`);
     console.log(`   Removed grant ID: ${grantId}`);
 });
+// ─── Federation signing helpers ──────────────────────────────────────────────
+/**
+ * Load the Ed25519 secret key for the local federation instance.
+ * Tries keystore first, then falls back to DB-stored seed (migration path).
+ */
+async function loadInstanceSecretKey(instanceId, opts) {
+    // Try keystore first
+    const seed = keystore.getPrivateKeySeed(instanceId);
+    if (seed) {
+        return nacl.sign.keyPair.fromSeed(seed).secretKey;
+    }
+    // Fallback: check DB for legacy _keySeed
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.Instance WHERE id = '${instanceId}'` }),
+    });
+    if (res.ok) {
+        const rows = await res.json();
+        if (rows[0]?._keySeed) {
+            const seedFromDb = Buffer.from(rows[0]._keySeed, "base64url");
+            // Migrate to keystore
+            keystore.setPrivateKeySeed(instanceId, new Uint8Array(seedFromDb));
+            return nacl.sign.keyPair.fromSeed(new Uint8Array(seedFromDb)).secretKey;
+        }
+    }
+    throw new Error(`No private key found for instance ${instanceId}. Re-run 'flair federation status' to regenerate.`);
+}
+/**
+ * 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 };
+}
+// ─── flair federation ────────────────────────────────────────────────────────
+const federation = program.command("federation").description("Manage federation (hub-and-spoke sync)");
+federation
+    .command("status")
+    .description("Show federation status and peer connections")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (opts) => {
+    try {
+        const instance = await api("GET", "/FederationInstance");
+        console.log(`Instance: ${instance.id} (${instance.role})`);
+        console.log(`Public key: ${instance.publicKey}`);
+        console.log(`Status: ${instance.status}`);
+        console.log();
+        const { peers } = await api("GET", "/FederationPeers");
+        if (peers.length === 0) {
+            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`);
+            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"}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+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")
+    .action(async (hubUrl, opts) => {
+    try {
+        const instance = await api("GET", "/FederationInstance");
+        console.log(`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.");
+            process.exit(1);
+        }
+        // Load secret key and sign the pairing request
+        const secretKey = await loadInstanceSecretKey(instance.id, opts);
+        const pairBody = {
+            instanceId: instance.id,
+            publicKey: instance.publicKey,
+            role: "spoke",
+            pairingToken: opts.token,
+        };
+        const signedBody = signRequestBody(pairBody, secretKey);
+        const res = await fetch(`${hubUrl}/FederationPair`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(signedBody),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`Pairing failed: ${res.status} ${text}`);
+            process.exit(1);
+        }
+        const result = await res.json();
+        console.log(`✅ Paired with hub: ${result.instance?.id ?? hubUrl}`);
+        // Record the hub as our peer locally
+        const opsPort = resolveOpsPort(opts);
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+        if (adminPass) {
+            const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+            await fetch(`http://127.0.0.1:${opsPort}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({
+                    operation: "upsert", database: "flair", table: "Peer",
+                    records: [{
+                            id: result.instance?.id ?? "hub",
+                            publicKey: result.instance?.publicKey ?? "",
+                            role: "hub", endpoint: hubUrl, status: "paired",
+                            pairedAt: new Date().toISOString(),
+                            createdAt: new Date().toISOString(),
+                            updatedAt: new Date().toISOString(),
+                        }],
+                }),
+            });
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+federation
+    .command("token")
+    .description("Generate a one-time pairing token (run on the hub)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--ttl <minutes>", "Token TTL in minutes (default: 60)", "60")
+    .action(async (opts) => {
+    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 opsPort = resolveOpsPort(opts);
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        await fetch(`http://127.0.0.1:${opsPort}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: auth },
+            body: JSON.stringify({
+                operation: "upsert", database: "flair", table: "PairingToken",
+                records: [{
+                        id: token,
+                        createdAt: new Date().toISOString(),
+                        expiresAt,
+                    }],
+            }),
+        });
+        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}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+federation
+    .command("sync")
+    .description("Push local changes to the hub")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password")
+    .option("--ops-port <port>", "Harper operations API port")
+    .action(async (opts) => {
+    try {
+        const { peers } = await api("GET", "/FederationPeers");
+        const hub = peers.find((p) => p.role === "hub" && p.status !== "revoked");
+        if (!hub) {
+            console.error("No hub peer configured. Use 'flair federation pair' first.");
+            process.exit(1);
+        }
+        console.log(`Syncing to hub: ${hub.id}...`);
+        const since = hub.lastSyncAt ?? new Date(0).toISOString();
+        const opsPort = resolveOpsPort(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");
+        for (const table of tables) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: auth },
+                    body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.${table} WHERE updatedAt > '${since}'` }),
+                });
+                if (res.ok) {
+                    for (const row of await res.json()) {
+                        records.push({ table, id: row.id, data: row, updatedAt: row.updatedAt ?? row.createdAt, originatorInstanceId: instance.id });
+                    }
+                }
+            }
+            catch { }
+        }
+        if (records.length === 0) {
+            console.log("No changes since last sync.");
+            return;
+        }
+        // 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) {
+            console.error(`Sync failed: ${syncRes.status} ${await syncRes.text().catch(() => "")}`);
+            process.exit(1);
+        }
+        const result = await syncRes.json();
+        console.log(`✅ Synced ${result.merged} records (${result.skipped} skipped) in ${result.durationMs}ms`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair rem ───────────────────────────────────────────────────────────────
+// Memory hygiene and reflection: light (NREM), rapid (REM), restorative (deep).
+const rem = program.command("rem").description("Memory hygiene and reflection");
+rem
+    .command("light")
+    .description("NREM — quick cleanup: delete expired, archive old, consolidate candidates")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
+    .option("--dry-run", "Preview changes without applying them")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    const dryRun = !!opts.dryRun;
+    console.log(`\n-- rem light${dryRun ? " (dry run)" : ""} --`);
+    if (agentId)
+        console.log(`Agent: ${agentId}`);
+    try {
+        // Step 1: Maintenance — expire + archive
+        const maint = await api("POST", "/MemoryMaintenance", {
+            ...(agentId ? { agentId } : {}),
+            dryRun,
+        });
+        if (maint.error) {
+            console.error(`Maintenance error: ${maint.error}`);
+            process.exit(1);
+        }
+        const s = maint.stats ?? {};
+        console.log("\nCleanup");
+        console.log(`  Expired (deleted): ${s.expired ?? 0}`);
+        console.log(`  Archived (soft):   ${s.archived ?? 0}`);
+        console.log(`  Total scanned:     ${s.total ?? 0}`);
+        if (s.errors)
+            console.log(`  Errors:            ${s.errors}`);
+        // Step 2: Consolidation candidates
+        if (!agentId) {
+            console.log("\nConsolidation skipped — no agent ID (pass --agent or set FLAIR_AGENT_ID)");
+            return;
+        }
+        const consol = await api("POST", "/ConsolidateMemories", {
+            agentId,
+            scope: "all",
+        });
+        if (consol.error) {
+            console.error(`Consolidation error: ${consol.error}`);
+            process.exit(1);
+        }
+        const candidates = consol.candidates ?? [];
+        const promote = candidates.filter((c) => c.suggestion === "promote");
+        const archive = candidates.filter((c) => c.suggestion === "archive");
+        console.log("\nConsolidation candidates");
+        console.log(`  Promote: ${promote.length}`);
+        console.log(`  Archive: ${archive.length}`);
+        if (promote.length > 0) {
+            console.log("\n  Promote:");
+            for (const c of promote) {
+                console.log(`    [${c.memory?.id ?? "?"}] ${c.reason}`);
+            }
+        }
+        if (archive.length > 0) {
+            console.log("\n  Archive:");
+            for (const c of archive) {
+                console.log(`    [${c.memory?.id ?? "?"}] ${c.reason}`);
+            }
+        }
+        console.log(`\nDone.${dryRun ? " No changes applied (dry run)." : ""}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+rem
+    .command("rapid")
+    .description("REM — reflection/learning: generate a structured LLM reflection prompt")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
+    .option("--focus <type>", "lessons_learned | patterns | decisions | errors", "lessons_learned")
+    .option("--since <date>", "ISO timestamp lower bound (default: 24h ago)")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("Error: --agent <id> or FLAIR_AGENT_ID env required");
+        process.exit(1);
+    }
+    console.log(`\n-- rem rapid --`);
+    console.log(`Agent: ${agentId}  Focus: ${opts.focus}`);
+    try {
+        const body = {
+            agentId,
+            focus: opts.focus,
+        };
+        if (opts.since)
+            body.since = opts.since;
+        const result = await api("POST", "/ReflectMemories", body);
+        if (result.error) {
+            console.error(`Reflection error: ${result.error}`);
+            process.exit(1);
+        }
+        console.log(`\nSource memories: ${result.count ?? 0}`);
+        if (result.suggestedTags?.length) {
+            console.log(`Tags: ${result.suggestedTags.join(", ")}`);
+        }
+        console.log("\n--- Reflection Prompt ---");
+        console.log(result.prompt ?? "(no prompt returned)");
+        console.log("--- End Prompt ---\n");
+        console.log("Feed the prompt above to your LLM, then write insights back with:");
+        console.log("  flair memory add --agent <id> --content <insight> --durability persistent");
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+rem
+    .command("restorative")
+    .description("Deep audit: full maintenance + consolidation (olderThan=7d) + reflection")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
+    .option("--dry-run", "Preview maintenance changes without applying them")
+    .action(async (opts) => {
+    const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+    const dryRun = !!opts.dryRun;
+    console.log(`\n== rem restorative${dryRun ? " (dry run)" : ""} ==`);
+    if (agentId)
+        console.log(`Agent: ${agentId}`);
+    try {
+        // Step 1: Maintenance
+        console.log("\n[1/3] Maintenance...");
+        const maint = await api("POST", "/MemoryMaintenance", {
+            ...(agentId ? { agentId } : {}),
+            dryRun,
+        });
+        if (maint.error) {
+            console.error(`Maintenance error: ${maint.error}`);
+            process.exit(1);
+        }
+        const s = maint.stats ?? {};
+        console.log(`  Expired: ${s.expired ?? 0}  Archived: ${s.archived ?? 0}  Scanned: ${s.total ?? 0}${s.errors ? `  Errors: ${s.errors}` : ""}`);
+        // Step 2: Consolidation (skip if no agentId)
+        if (agentId) {
+            console.log("\n[2/3] Consolidation (scope=all, olderThan=7d)...");
+            const consol = await api("POST", "/ConsolidateMemories", {
+                agentId,
+                scope: "all",
+                olderThan: "7d",
+            });
+            if (consol.error) {
+                console.error(`Consolidation error: ${consol.error}`);
+                process.exit(1);
+            }
+            const candidates = consol.candidates ?? [];
+            const promote = candidates.filter((c) => c.suggestion === "promote");
+            const archive = candidates.filter((c) => c.suggestion === "archive");
+            console.log(`  Promote candidates: ${promote.length}  Archive candidates: ${archive.length}`);
+            for (const c of promote) {
+                console.log(`    promote [${c.memory?.id ?? "?"}] ${c.reason}`);
+            }
+            for (const c of archive) {
+                console.log(`    archive [${c.memory?.id ?? "?"}] ${c.reason}`);
+            }
+        }
+        else {
+            console.log("\n[2/3] Consolidation skipped — no agent ID");
+        }
+        // Step 3: Reflection
+        if (agentId) {
+            console.log("\n[3/3] Reflection (scope=all)...");
+            const reflect = await api("POST", "/ReflectMemories", {
+                agentId,
+                scope: "all",
+            });
+            if (reflect.error) {
+                console.error(`Reflection error: ${reflect.error}`);
+                process.exit(1);
+            }
+            console.log(`  Source memories: ${reflect.count ?? 0}`);
+            if (reflect.suggestedTags?.length) {
+                console.log(`  Tags: ${reflect.suggestedTags.join(", ")}`);
+            }
+            console.log("\n--- Reflection Prompt ---");
+            console.log(reflect.prompt ?? "(no prompt returned)");
+            console.log("--- End Prompt ---");
+        }
+        else {
+            console.log("\n[3/3] Reflection skipped — no agent ID");
+        }
+        console.log(`\nRestorative cycle complete.${dryRun ? " No changes applied (dry run)." : ""}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
 // ─── flair status ─────────────────────────────────────────────────────────────
 program
     .command("status")
-    .description("Check Flair (Harper) instance health and agent count")
+    .description("Show Flair instance status, memory stats, and agent info")
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--json", "Output as JSON")
+    .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
     const baseUrl = opts.url ?? `http://127.0.0.1:${port}`;
     let healthy = false;
-    let agentCount = null;
-    let version = null;
+    let healthData = null;
+    // 1. Basic health check — try unauthenticated first, then with admin auth
     try {
-        const res = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) });
-        healthy = res.status > 0;
-        if (res.headers.get("content-type")?.includes("application/json")) {
-            const body = await res.json().catch(() => null);
-            if (body?.version)
-                version = body.version;
+        let res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok && res.status === 401) {
+            // Harper requires auth (authorizeLocal: true) — retry with admin credentials
+            const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+            if (adminPass) {
+                res = await fetch(`${baseUrl}/Health`, {
+                    headers: { Authorization: `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}` },
+                    signal: AbortSignal.timeout(5000),
+                });
+            }
         }
+        healthy = res.ok;
     }
     catch { /* unreachable */ }
+    // 2. Try authenticated /HealthDetail for rich stats
     if (healthy) {
-        try {
-            const agents = await fetch(`${baseUrl}/Agent`, { signal: AbortSignal.timeout(3000) });
-            if (agents.ok) {
-                const list = await agents.json().catch(() => null);
-                if (Array.isArray(list))
-                    agentCount = list.length;
+        const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
+        if (agentId) {
+            const keyPath = resolveKeyPath(agentId);
+            if (keyPath) {
+                try {
+                    const authHeader = buildEd25519Auth(agentId, "GET", "/HealthDetail", keyPath);
+                    const res = await fetch(`${baseUrl}/HealthDetail`, {
+                        headers: { Authorization: authHeader },
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (res.ok) {
+                        healthData = await res.json().catch(() => null);
+                    }
+                }
+                catch { /* fall through to basic output */ }
+            }
+        }
+        // Fallback: try admin basic auth if available
+        if (!healthData) {
+            const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS;
+            if (adminPass) {
+                try {
+                    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+                    const res = await fetch(`${baseUrl}/HealthDetail`, {
+                        headers: { Authorization: auth },
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (res.ok) {
+                        healthData = await res.json().catch(() => null);
+                    }
+                }
+                catch { /* fall through to basic output */ }
             }
         }
-        catch { /* best effort */ }
-    }
-    const status = healthy ? "🟢 running" : "🔴 unreachable";
-    console.log(`Flair status: ${status}`);
-    console.log(`  URL:     ${baseUrl}`);
-    console.log(`  Flair:   v${__pkgVersion}`);
-    if (version)
-        console.log(`  Harper:  ${version}`);
-    if (agentCount !== null)
-        console.log(`  Agents:  ${agentCount}`);
-    if (!healthy)
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData }, null, 2));
+        if (!healthy)
+            process.exit(1);
+        return;
+    }
+    if (!healthy) {
+        console.log(`Flair v${__pkgVersion} — 🔴 unreachable`);
+        console.log(`  URL:  ${baseUrl}`);
+        console.log(`\n  Run: flair start  or  flair doctor`);
         process.exit(1);
+    }
+    // Format uptime
+    const uptimeSec = healthData?.uptimeSeconds;
+    let uptimeStr = "";
+    if (uptimeSec != null) {
+        const d = Math.floor(uptimeSec / 86400);
+        const h = Math.floor((uptimeSec % 86400) / 3600);
+        const m = Math.floor((uptimeSec % 3600) / 60);
+        uptimeStr = d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`;
+    }
+    // Format last write as relative time
+    let lastWriteStr = "";
+    if (healthData?.lastWrite) {
+        const ago = Date.now() - new Date(healthData.lastWrite).getTime();
+        const mins = Math.floor(ago / 60000);
+        const hrs = Math.floor(ago / 3600000);
+        const days = Math.floor(ago / 86400000);
+        lastWriteStr = days > 0 ? `${days}d ago` : hrs > 0 ? `${hrs}h ago` : mins > 0 ? `${mins}m ago` : "just now";
+    }
+    const pid = healthData?.pid ?? "";
+    const agents = healthData?.agents;
+    const memories = healthData?.memories;
+    console.log(`Flair v${__pkgVersion} — 🟢 running${pid ? ` (PID ${pid}` : ""}${uptimeStr ? `, uptime ${uptimeStr})` : pid ? ")" : ""}`);
+    console.log(`  URL:        ${baseUrl}`);
+    if (memories) {
+        const embStr = memories.withEmbeddings > 0
+            ? `${memories.withEmbeddings} with embeddings`
+            : "";
+        const hashStr = memories.hashFallback > 0
+            ? `${memories.hashFallback} hash-fallback`
+            : "";
+        const detail = [embStr, hashStr].filter(Boolean).join(", ");
+        console.log(`  Memories:   ${memories.total}${detail ? ` (${detail})` : ""}`);
+    }
+    if (agents) {
+        const nameStr = agents.names?.length > 0 ? ` (${agents.names.join(", ")})` : "";
+        console.log(`  Agents:     ${agents.count}${nameStr}`);
+    }
+    if (healthData?.soulEntries != null) {
+        console.log(`  Soul:       ${healthData.soulEntries} entries`);
+    }
+    if (lastWriteStr) {
+        console.log(`  Last write: ${lastWriteStr}`);
+    }
+    console.log(`  Health:     ✅ all checks passing`);
 });
 // ─── flair upgrade ────────────────────────────────────────────────────────────
 program
     .command("upgrade")
     .description("Upgrade Flair and related packages to latest versions")
-    .action(async () => {
+    .option("--check", "Only check for updates, don't install")
+    .option("--restart", "Restart Flair after upgrade")
+    .action(async (opts) => {
+    const { execSync } = await import("node:child_process");
+    const checkOnly = opts.check ?? false;
     console.log("Checking for updates...\n");
     const packages = [
         "@tpsdev-ai/flair",
         "@tpsdev-ai/flair-client",
         "@tpsdev-ai/flair-mcp",
     ];
+    const upgrades = [];
     for (const pkg of packages) {
         try {
             const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, { signal: AbortSignal.timeout(5000) });
@@ -975,22 +1917,67 @@ program
                 continue;
             const data = await res.json();
             const latest = data.version ?? "unknown";
-            // Check installed version
             let installed = "not installed";
             try {
-                const { execSync } = await import("node:child_process");
-                installed = execSync(`npm list -g ${pkg} --depth=0 2>/dev/null | grep ${pkg} || echo "not installed"`, { encoding: "utf-8" }).trim();
-                const match = installed.match(/@(\d+\.\d+\.\d+)/);
+                const out = execSync(`npm list -g ${pkg} --depth=0 2>/dev/null || true`, { encoding: "utf-8" }).trim();
+                const match = out.match(/@(\d+\.\d+[\d.a-z-]*)/);
                 installed = match ? match[1] : "not installed";
             }
             catch { /* best effort */ }
             const upToDate = installed === latest;
             const icon = upToDate ? "✅" : "⬆️";
             console.log(`  ${icon} ${pkg}: ${installed} → ${latest}${upToDate ? " (current)" : ""}`);
+            if (!upToDate && installed !== "not installed") {
+                upgrades.push({ pkg, installed, latest });
+            }
         }
         catch { /* skip unavailable packages */ }
     }
-    console.log("\nTo upgrade: npm install -g @tpsdev-ai/flair@latest");
+    if (upgrades.length === 0) {
+        console.log("\n✅ Everything is up to date.");
+        return;
+    }
+    if (checkOnly) {
+        console.log(`\n${upgrades.length} update${upgrades.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        return;
+    }
+    // Perform upgrade
+    console.log(`\nUpgrading ${upgrades.length} package${upgrades.length > 1 ? "s" : ""}...\n`);
+    for (const { pkg, latest } of upgrades) {
+        try {
+            console.log(`  Installing ${pkg}@${latest}...`);
+            execSync(`npm install -g ${pkg}@${latest}`, { stdio: "pipe" });
+            console.log(`  ✅ ${pkg}@${latest} installed`);
+        }
+        catch (err) {
+            console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
+        }
+    }
+    if (opts.restart) {
+        console.log("\nRestarting Flair...");
+        try {
+            const port = resolveHttpPort({});
+            const label = "ai.tpsdev.flair";
+            const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+            if (process.platform === "darwin" && existsSync(plistPath)) {
+                try {
+                    execSync(`launchctl stop ${label}`, { stdio: "pipe" });
+                }
+                catch { }
+                await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                console.log("✅ Flair restarted with new version");
+            }
+            else {
+                console.log("Run: flair restart");
+            }
+        }
+        catch {
+            console.log("Run: flair restart");
+        }
+    }
+    else {
+        console.log("\nRun: flair restart  to use the new version");
+    }
 });
 // ─── flair stop ───────────────────────────────────────────────────────────────
 program
@@ -1035,6 +2022,83 @@ program
         console.log("Flair is not running (nothing found on port " + port + ").");
     }
 });
+// ─── flair start ──────────────────────────────────────────────────────────────
+program
+    .command("start")
+    .description("Start Flair (Harper) — requires a prior 'flair init'")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (opts) => {
+    const port = resolveHttpPort(opts);
+    // Check if already running
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/Health`, { signal: AbortSignal.timeout(2000) });
+        if (res.status > 0) {
+            console.log(`Flair is already running on port ${port}.`);
+            return;
+        }
+    }
+    catch { /* not running — good */ }
+    const dataDir = defaultDataDir();
+    if (!existsSync(dataDir)) {
+        console.error("❌ No Flair data directory found. Run 'flair init' first.");
+        process.exit(1);
+    }
+    const platform = process.platform;
+    if (platform === "darwin") {
+        const label = "ai.tpsdev.flair";
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        if (existsSync(plistPath)) {
+            try {
+                const { execSync } = await import("node:child_process");
+                try {
+                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
+                }
+                catch { }
+                execSync(`launchctl start ${label}`, { stdio: "pipe" });
+                await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                console.log("✅ Flair started (launchd)");
+                return;
+            }
+            catch (err) {
+                console.error(`launchd start failed, falling back to direct start: ${err.message}`);
+            }
+        }
+    }
+    // Direct start (Linux, or macOS fallback when no launchd plist)
+    const bin = harperBin();
+    if (!bin) {
+        console.error("❌ Harper binary not found. Run 'flair init' first.");
+        process.exit(1);
+    }
+    const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
+    const opsPort = resolveOpsPort(opts);
+    const env = {
+        ...process.env,
+        ROOTPATH: dataDir,
+        DEFAULTS_MODE: "dev",
+        HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
+        HTTP_PORT: String(port),
+        OPERATIONSAPI_NETWORK_PORT: String(opsPort),
+        LOCAL_STUDIO: "false",
+    };
+    // Only set HDB_ADMIN_PASSWORD if we have a real value — empty string
+    // would strip Harper's auth on an existing install
+    if (adminPass) {
+        env.HDB_ADMIN_PASSWORD = adminPass;
+    }
+    const proc = spawn(process.execPath, [bin, "run", "."], {
+        cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
+    });
+    proc.unref();
+    try {
+        await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+        console.log(`✅ Flair started on port ${port}`);
+    }
+    catch {
+        console.error("❌ Flair failed to start within timeout. Check logs in " + join(dataDir, "harper.log"));
+        process.exit(1);
+    }
+});
 // ─── flair restart ────────────────────────────────────────────────────────────
 program
     .command("restart")
@@ -1280,80 +2344,71 @@ program
 // ─── flair test ───────────────────────────────────────────────────────────────
 program
     .command("test")
-    .description("Verify Flair is working: store, search, bootstrap, cleanup")
-    .requiredOption("--agent <id>", "Agent ID to test with")
+    .description("Verify the full Flair stack: write, search, and delete a test memory")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
-    const port = resolveHttpPort(opts);
-    const baseUrl = `http://127.0.0.1:${port}`;
-    const agentId = opts.agent;
-    const keysDir = defaultKeysDir();
-    const privPath = privKeyPath(agentId, keysDir);
-    if (!existsSync(privPath)) {
-        console.error(`❌ Key not found: ${privPath}`);
-        console.error(`   Run: flair init --agent-id ${agentId}`);
+    const green = (s) => `\x1b[32m${s}\x1b[0m`;
+    const red = (s) => `\x1b[31m${s}\x1b[0m`;
+    const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
+    if (!agentId && !process.env.FLAIR_ADMIN_PASS) {
+        console.error(red("Error: set --agent / FLAIR_AGENT_ID or FLAIR_ADMIN_PASS"));
         process.exit(1);
     }
-    const testId = `test-${agentId}-${Date.now()}`;
-    const testContent = `Flair test memory (${new Date().toISOString()})`;
+    const baseUrl = `http://127.0.0.1:${resolveHttpPort(opts)}`;
+    console.log(`\nFlair test (url: ${baseUrl})\n`);
     let passed = 0;
     let failed = 0;
+    let memoryId = null;
     const check = async (name, fn) => {
         try {
             const ok = await fn();
             if (ok) {
-                console.log(`  ✅ ${name}`);
+                console.log(`  ${green("PASS")} ${name}`);
                 passed++;
             }
             else {
-                console.log(`  ❌ ${name}`);
+                console.log(`  ${red("FAIL")} ${name}`);
                 failed++;
             }
         }
         catch (e) {
-            console.log(`  ❌ ${name}: ${e.message?.slice(0, 100)}`);
+            console.log(`  ${red("FAIL")} ${name}: ${e.message?.slice(0, 120)}`);
             failed++;
         }
     };
-    console.log(`\nFlair test (agent: ${agentId}, url: ${baseUrl})\n`);
-    // 1. Health
-    await check("Health check", async () => {
-        const res = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
-        return res.status > 0;
-    });
-    // 2. Store
-    await check("Memory store", async () => {
-        const res = await authFetch(baseUrl, agentId, privPath, "PUT", `/Memory/${testId}`, {
-            id: testId, agentId, content: testContent, durability: "ephemeral",
-            createdAt: new Date().toISOString(), archived: false,
-        });
-        return res.ok;
-    });
-    // 3. Search
-    await check("Semantic search", async () => {
-        await new Promise(r => setTimeout(r, 2000)); // wait for indexing
-        const res = await authFetch(baseUrl, agentId, privPath, "POST", "/SemanticSearch", {
-            agentId, q: "flair test memory", limit: 5,
-        });
-        if (!res.ok)
-            return false;
-        const data = await res.json();
-        return (data.results?.length ?? 0) > 0;
+    // 1. Write a test memory via POST /Memory
+    await check("Write test memory (POST /Memory)", async () => {
+        const body = {
+            content: "flair test \u2014 this will be deleted",
+            durability: "ephemeral",
+            createdAt: new Date().toISOString(),
+        };
+        if (agentId)
+            body.agentId = agentId;
+        const result = await api("POST", "/Memory", body);
+        // id may be returned directly or nested
+        memoryId = result?.id ?? result?.[0]?.id ?? null;
+        return !!memoryId || result?.ok === true;
     });
-    // 4. Bootstrap
-    await check("Bootstrap context", async () => {
-        const res = await authFetch(baseUrl, agentId, privPath, "POST", "/BootstrapMemories", {
-            agentId, maxTokens: 1000,
-        });
-        if (!res.ok)
-            return false;
-        const data = await res.json();
-        return (data.context?.length ?? 0) > 0;
+    // 2. Search for the test memory via POST /SemanticSearch
+    await check("Search for test memory (POST /SemanticSearch)", async () => {
+        await new Promise(r => setTimeout(r, 1500)); // allow indexing
+        const body = { q: "flair test", limit: 5 };
+        if (agentId)
+            body.agentId = agentId;
+        const result = await api("POST", "/SemanticSearch", body);
+        return (result?.results?.length ?? 0) > 0;
     });
-    // 5. Cleanup
-    await check("Memory delete", async () => {
-        const res = await authFetch(baseUrl, agentId, privPath, "DELETE", `/Memory/${testId}`);
-        return res.ok || res.status === 204;
+    // 3. Delete the test memory via DELETE /Memory/<id>
+    await check("Delete test memory (DELETE /Memory/<id>)", async () => {
+        if (!memoryId) {
+            // If write returned ok without an id, skip deletion cleanly
+            console.log(`       (skipped — no id returned from write step)`);
+            return true;
+        }
+        await api("DELETE", `/Memory/${memoryId}`, agentId ? { agentId } : undefined);
+        return true;
     });
     console.log(`\n${passed} passed, ${failed} failed`);
     if (failed > 0)
@@ -2238,4 +3293,9 @@ program
         }
     }
 });
-await program.parseAsync();
+// Run CLI only when this is the entry point (not when imported for testing)
+if (import.meta.main) {
+    await program.parseAsync();
+}
+// ─── Exported for testing ─────────────────────────────────────────────────────
+export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, signRequestBody, b64, b64url, program, };