@tpsdev-ai/flair 0.6.2 → 0.8.0

package/dist/cli.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import nacl from "tweetnacl";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve as resolvePath } from "node:path";
+import { load as parseYaml } from "js-yaml";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, } from "node:fs";
+import { homedir, hostname, tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
-import { createPrivateKey, sign as nodeCryptoSign, randomUUID } from "node:crypto";
+import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
+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";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -30,6 +33,50 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
+// ─── Secret detection helpers ────────────────────────
+/**
+ * Check if a value looks like a real secret/password/token.
+ * Triggers warning when:
+ *   - length >= 8
+ *   - contains only alphanumerics and URL-safe punctuation (._-)
+ *   - NOT a URL (doesn't contain ://)
+ */
+function isLikelyRealSecret(value) {
+    if (!value || value.length < 8)
+        return false;
+    if (value.includes("://"))
+        return false; // exclude URLs
+    // Match typical password/token format: alphanumerics + URL-safe punct
+    const pattern = /^[A-Za-z0-9._-]+$/;
+    return pattern.test(value);
+}
+/**
+ * Determine if we should show an inline-secret warning.
+ *
+ * @param optValue - The value from the command line option
+ * @param fromEnv - Whether the value came from an environment variable (true = no warning)
+ * @param secretFlagNames - Set of flag names that carry secrets
+ * @param flagName - The flag being checked
+ * @returns true if warning should be shown
+ */
+function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagName) {
+    // Skip if no value provided
+    if (!optValue || optValue === "")
+        return false;
+    // Skip URLs (not secrets)
+    if (flagName === "--target" || flagName === "--url")
+        return false;
+    // Only warn for secret-bearing flags
+    if (!secretFlagNames.has(flagName))
+        return false;
+    // Skip if value came from env (not argv)
+    if (fromEnv)
+        return false;
+    // Check if value looks like a real secret
+    if (!isLikelyRealSecret(optValue))
+        return false;
+    return true;
+}
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
@@ -103,6 +150,64 @@ function resolveOpsPort(opts) {
     // Default: httpPort - 1
     return resolveHttpPort(opts) - 1;
 }
+// ─── Target resolution (remote Flair instance) ─────────────────────────────────
+// --target <url> (or FLAIR_TARGET env) points all CLI operations at a remote
+// Flair instance instead of localhost. This enables bootstrapping and
+// managing Fabric-deployed Flair instances.
+function resolveTarget(opts) {
+    return opts.target || process.env.FLAIR_TARGET || undefined;
+}
+/** Resolve the ops API target URL from --ops-target flag or FLAIR_OPS_TARGET env.
+ *  Returns undefined if neither is set (caller should fall back to derivation or localhost).
+ */
+function resolveOpsTarget(opts) {
+    return opts.opsTarget || process.env.FLAIR_OPS_TARGET || undefined;
+}
+/** Derive the ops API URL from a Flair base URL.
+ *  Convention: ops port = HTTP port - 1.
+ *  If target has an explicit port, use port-1 (validated: must be 1-65535).
+ *  If no explicit port: https → 442 (443-1), http → 19925 (19926-1), bare host → https://<host>:19925.
+ *  Throws on unparseable URLs.
+ */
+/** Compute the effective ops API URL for remote commands.
+ *  - If --ops-target is set, use it directly (no derivation).
+ *  - Else if --target is set, derive ops URL via resolveOpsUrlFromTarget.
+ *  - Else return undefined (fall back to localhost resolution).
+ */
+function resolveEffectiveOpsUrl(opts) {
+    const opsTarget = resolveOpsTarget(opts);
+    if (opsTarget)
+        return opsTarget.replace(/\/$/, "");
+    const target = resolveTarget(opts);
+    if (target)
+        return resolveOpsUrlFromTarget(target);
+    return undefined;
+}
+function resolveOpsUrlFromTarget(targetUrl) {
+    // Normalise bare hosts: add https:// prefix so URL parser can handle them.
+    const normalised = targetUrl.includes("://") ? targetUrl : `https://${targetUrl}`;
+    const url = new URL(normalised);
+    const port = parseInt(url.port, 10);
+    if (!isNaN(port) && port > 0 && port <= 65535) {
+        const opsPort = port - 1;
+        if (opsPort < 1)
+            throw new Error(`Derived ops port ${opsPort} is out of range; target port must be > 1`);
+        url.port = String(opsPort);
+        return url.toString().replace(/\/$/, "");
+    }
+    // No valid explicit port — reject port 0 or out-of-range
+    if (url.port !== "" && url.port !== undefined) {
+        throw new Error(`Invalid target port: ${url.port} (must be 1-65535)`);
+    }
+    // No explicit port — infer from scheme
+    if (url.protocol === "https:") {
+        url.port = "442";
+    }
+    else {
+        url.port = String(DEFAULT_OPS_PORT);
+    }
+    return url.toString().replace(/\/$/, "");
+}
 function writeConfig(port) {
     const p = configPath();
     mkdirSync(join(homedir(), ".flair"), { recursive: true });
@@ -136,22 +241,40 @@ function b64(bytes) {
 function b64url(bytes) {
     return Buffer.from(bytes).toString("base64url");
 }
-async function api(method, path, body) {
+function isLocalBase(base) {
+    try {
+        const url = new URL(base);
+        return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
+    }
+    catch {
+        return !base;
+    }
+}
+async function api(method, path, body, options) {
     // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
+    // When baseUrl is provided (--target), use it directly.
     const savedPort = readPortFromConfig();
     const defaultUrl = savedPort ? `http://127.0.0.1:${savedPort}` : `http://127.0.0.1:${DEFAULT_PORT}`;
-    const base = process.env.FLAIR_URL || defaultUrl;
+    const base = options?.baseUrl ?? (process.env.FLAIR_URL || defaultUrl);
+    const isLocal = isLocalBase(base);
     // Auth resolution order:
     // 1. FLAIR_TOKEN env → Bearer token (backward compat)
-    // 2. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
-    // 3. --agent flag extracted from body.agentId + key file → Ed25519 signature
-    // 4. No auth (will 401 on any authenticated endpoint)
+    // 2. FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD env → Basic admin auth (remote targets only).
+    //    For local targets with authorizeLocal=true, skip Basic auth and let Harper handle it.
+    // 3. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
+    // 4. No auth (Harper authorizeLocal handles local; remote will 401)
+    //
+    // NOTE: this function is for the Harper HTTP/REST API only. The Harper
+    // operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
+    // does NOT honor authorizeLocal — it always requires Basic admin auth, and
+    // those helpers send it unconditionally. authorizeLocal=true affects this
+    // path; it does not affect ops-API calls.
     let authHeader;
     const token = process.env.FLAIR_TOKEN;
     if (token) {
         authHeader = `Bearer ${token}`;
     }
-    else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
+    else if (!isLocal && (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")}`;
@@ -174,7 +297,8 @@ async function api(method, path, body) {
                 }
                 catch (err) {
                     // Key exists but auth build failed — warn and continue without auth
-                    console.error(`Warning: Ed25519 auth failed for agent '${agentId}': ${err.message}`);
+                    const message = err instanceof Error ? err.message : String(err);
+                    console.error(`Warning: Ed25519 auth failed for agent '${agentId}': ${message}`);
                 }
             }
         }
@@ -303,9 +427,22 @@ function readHarperPid(dataDir) {
         return null;
     }
 }
-async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass) {
-    const url = `http://127.0.0.1:${opsPort}/`;
-    const auth = Buffer.from(`${adminUser}:${adminPass}`).toString("base64");
+/**
+ * Seed an agent record via the Harper operations API.
+ * Accepts either a port number (localhost) or a full URL string (--target).
+ *
+ * `adminPass` is typed as optional but in practice the Harper operations API
+ * always requires Basic admin auth — every existing call site passes one.
+ * The optional signature leaves headroom for a future Harper that honors
+ * `authorizeLocal` on its ops endpoint; until then, callers must pass it.
+ */
+export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, adminUser, adminPass) {
+    const url = typeof opsPortOrUrl === "number"
+        ? `http://127.0.0.1:${opsPortOrUrl}/`
+        : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    // Send Basic auth whenever the caller passed an adminPass. The caller decides
+    // when to omit it (e.g., local target with authorizeLocal=true).
+    const auth = adminPass !== undefined ? Buffer.from(`${adminUser}:${adminPass}`).toString("base64") : undefined;
     const body = {
         operation: "insert",
         database: "flair",
@@ -314,8 +451,9 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
     };
     const res = await fetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
         body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
@@ -324,6 +462,301 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
+// Seed an agent record via the Harper REST API.
+// Uses localhost and the given HTTP port.
+export async function seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass) {
+    const baseUrl = `http://127.0.0.1:${httpPort}`;
+    const body = {
+        operation: "insert",
+        database: "flair",
+        table: "Agent",
+        records: [{ id: agentId, name: agentId, publicKey: pubKeyB64url, createdAt: new Date().toISOString() }],
+    };
+    // Only send Authorization header if adminPass is provided.
+    // Matches the auth pattern in api() which respects authorizeLocal=true.
+    const headers = { "Content-Type": "application/json" };
+    if (adminPass) {
+        headers.Authorization = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+    }
+    const res = await fetch(`${baseUrl}/Agent`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
+            return;
+        throw new Error(`REST API insert failed (${res.status}): ${text}`);
+    }
+}
+// ─── FederationInstance seed via ops API ──────────────────────────────────────
+//
+// Remote init writes FederationInstance through the ops API (Basic auth with
+// admin:admin-pass), not the REST API (which needs server-side HDB_ADMIN_PASSWORD
+// — unavailable on Fabric).  Same pattern as seedAgentViaOpsApi above.
+//
+// `adminPass` is optional in the signature for symmetry with seedAgentViaOpsApi
+// and to keep the door open for a future Harper that honors authorizeLocal on
+// its ops endpoint. Today the Harper operations API always requires Basic admin
+// auth; every current caller passes it.
+export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId, publicKey, role, adminUser, adminPass) {
+    const url = typeof opsPortOrUrl === "number"
+        ? `http://127.0.0.1:${opsPortOrUrl}/`
+        : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    // Send Basic auth whenever the caller passed an adminPass. The caller decides
+    // when to omit it (e.g., local target with authorizeLocal=true).
+    const auth = adminPass !== undefined ? Buffer.from(`${adminUser}:${adminPass}`).toString("base64") : undefined;
+    const now = new Date().toISOString();
+    const body = {
+        operation: "insert",
+        database: "flair",
+        table: "Instance",
+        records: [{
+                id: instanceId,
+                publicKey,
+                role,
+                status: "active",
+                createdAt: now,
+                updatedAt: now,
+            }],
+    };
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
+            return;
+        throw new Error(`Federation Instance insert via ops API failed (${res.status}): ${text}`);
+    }
+}
+// ─── Provision Flair on Harper Fabric (ops-2kyi) ───────────────────────────
+//
+// Atomic provisioning for a fresh Harper Fabric cluster: builds a deploy
+// tarball with .env baked in, deploys via ops API, waits for restart, and
+// creates the super_user admin account.
+export async function callOpsApi(opsUrl, body, user, pass) {
+    const url = `${opsUrl.replace(/\/$/, "")}/`;
+    const auth = Buffer.from(`${user}:${pass}`).toString("base64");
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Ops API call failed (${res.status}): ${text}`);
+    }
+    return res.json();
+}
+export async function buildDeployTarball(projectRoot, flairAdminPass) {
+    const tmpDir = mkdtempSync(join(tmpdir(), "flair-deploy-"));
+    try {
+        // Copy deployment files into temp directory
+        const entries = ["dist", "schemas", "config.yaml", "package.json", "LICENSE", "README.md", "SECURITY.md"];
+        if (existsSync(join(projectRoot, "ui")))
+            entries.push("ui");
+        for (const entry of entries) {
+            const src = join(projectRoot, entry);
+            const dst = join(tmpDir, entry);
+            if (existsSync(src)) {
+                cpSync(src, dst, { recursive: true });
+            }
+        }
+        // Write .env with 600 permissions
+        const envContent = [
+            `HDB_ADMIN_PASSWORD=${flairAdminPass}`,
+            `FLAIR_ADMIN_PASSWORD=${flairAdminPass}`,
+            "",
+        ].join("\n");
+        writeFileSync(join(tmpDir, ".env"), envContent, { mode: 0o600 });
+        // Build compressed tarball
+        const tarballPath = join(tmpDir, "deploy.tar.gz");
+        await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, entries);
+        const buf = readFileSync(tarballPath);
+        return { tarballB64: buf.toString("base64") };
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+export async function waitForFlairRestart(targetUrl, maxWaitMs = 30_000) {
+    const url = `${targetUrl.replace(/\/$/, "")}/FederationPair`;
+    const intervalMs = 1_000;
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({}),
+                signal: AbortSignal.timeout(5_000),
+            });
+            const text = await res.text().catch(() => "");
+            // The resource handler responds with "instanceId and publicKey required"
+            // when the deployment is live and Flair is serving requests.
+            if (text.includes("instanceId and publicKey required"))
+                return;
+        }
+        catch {
+            // Not ready yet — keep polling
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Flair did not respond within ${maxWaitMs / 1000}s`);
+}
+export async function provisionFabric(target, opsTarget, clusterAdminUser, clusterAdminPass, flairAdminPass) {
+    const projectRoot = process.cwd();
+    // 1. Build and deploy component tarball
+    console.log("Building deploy tarball...");
+    const { tarballB64 } = await buildDeployTarball(projectRoot, flairAdminPass);
+    console.log("Deploying via ops API...");
+    await callOpsApi(opsTarget, {
+        operation: "deploy_component",
+        project: "flair",
+        payload: tarballB64,
+        restart: "rolling",
+    }, clusterAdminUser, clusterAdminPass);
+    // 2. Wait for restart
+    console.log("Waiting for Flair to restart...");
+    await waitForFlairRestart(target);
+    console.log("Flair is running ✓");
+    // 3. Provision Harper super_user
+    // Since ops-lzmg is merged, the username doesn't have to be "admin".
+    // We can use the cluster-admin user directly if it's already a super_user.
+    // Check if cluster admin is already a super_user first:
+    let clusterAdminIsSuperUser = false;
+    try {
+        const userInfo = await callOpsApi(opsTarget, {
+            operation: "list_users",
+        }, clusterAdminUser, clusterAdminPass);
+        // list_users returns an array of user objects with role/permission info
+        const users = Array.isArray(userInfo) ? userInfo : [];
+        const adminRecord = users.find((u) => u.username === clusterAdminUser || u.user?.username === clusterAdminUser);
+        clusterAdminIsSuperUser = !!(adminRecord?.role?.permission?.super_user ??
+            adminRecord?.permission?.super_user ??
+            false);
+    }
+    catch {
+        // If we can't check, assume not and proceed with add_user
+    }
+    if (clusterAdminIsSuperUser) {
+        console.log(`Cluster admin '${clusterAdminUser}' is already a super_user — skipping user provisioning`);
+    }
+    else {
+        console.log(`Provisioning Harper user 'admin' as super_user...`);
+        try {
+            await callOpsApi(opsTarget, {
+                operation: "add_user",
+                username: "admin",
+                password: flairAdminPass,
+                role: "super_user",
+                active: true,
+            }, clusterAdminUser, clusterAdminPass);
+            console.log("User 'admin' created ✓");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("already exists") || msg.includes("duplicate")) {
+                // Idempotent: fall back to alter_user
+                console.log("User 'admin' already exists — updating password...");
+                await callOpsApi(opsTarget, {
+                    operation: "alter_user",
+                    username: "admin",
+                    password: flairAdminPass,
+                    role: "super_user",
+                    active: true,
+                }, clusterAdminUser, clusterAdminPass);
+                console.log("User 'admin' updated ✓");
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+}
+// ─── 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
@@ -369,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": [
@@ -515,7 +977,8 @@ async function runSoulWizard(agentId) {
             }
         }
         catch (err) {
-            console.log(`\n   Couldn't parse JSON (${err.message}). Falling back to custom prompts.`);
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(`\n   Couldn't parse JSON (${message}). Falling back to custom prompts.`);
             entries = await customSoulPrompts(ask);
         }
     }
@@ -542,24 +1005,263 @@ program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── flair init ──────────────────────────────────────────────────────────────
 program
     .command("init")
-    .description("Bootstrap a local Flair (Harper) instance for an agent")
-    .option("--agent-id <id>", "Agent ID to register", "local")
+    .description("Bootstrap a Flair (Harper) instance for an agent")
+    .option("--agent-id <id>", "Agent ID to register (omit to bootstrap instance without agent)")
     .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (generated if omitted)")
+    .option("--admin-pass-file <path>", "Read admin password from file (chmod 600 recommended)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .option("--remote", "When used with --target, init as hub for remote federation")
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
+    .option("--force", "Skip confirmation prompt for remote writes (required with --target)")
+    .option("--cluster-admin-user <user>", "Harper cluster admin username (env: FLAIR_CLUSTER_ADMIN_USER)")
+    .option("--cluster-admin-pass <pass>", "Harper cluster admin password (env: FLAIR_CLUSTER_ADMIN_PASS)")
+    .option("--flair-admin-pass <pass>", "Password for Flair's admin user (env: FLAIR_ADMIN_PASS; generated if omitted)")
     .action(async (opts) => {
     const agentId = opts.agentId;
+    const target = resolveTarget(opts);
+    const opsTarget = resolveOpsTarget(opts);
+    // ── Remote init: --target and/or --ops-target drive a remote Flair instance ──
+    if (target || opsTarget) {
+        // When -only- --ops-target is provided, attempt to derive REST URL
+        if (!target && opsTarget) {
+            console.error("Error: --ops-target requires --target as well. Pass --target <rest-url> for the REST API surface.");
+            console.error("  Currently only explicit --ops-target + --target combination is supported.");
+            process.exit(1);
+        }
+        const baseUrl = target.replace(/\/$/, "");
+        // --ops-target overrides derivation; otherwise derive from --target
+        const opsUrl = opsTarget ? opsTarget.replace(/\/$/, "") : resolveOpsUrlFromTarget(baseUrl);
+        // Check for cluster-admin provisioning (new atomic flow)
+        const clusterAdminUser = opts.clusterAdminUser || process.env.FLAIR_CLUSTER_ADMIN_USER;
+        const clusterAdminPass = opts.clusterAdminPass || process.env.FLAIR_CLUSTER_ADMIN_PASS;
+        let flairAdminPass = opts.flairAdminPass || process.env.FLAIR_ADMIN_PASS;
+        let didProvision = false;
+        if (clusterAdminUser && clusterAdminPass) {
+            // ── New provisioning path: deploy Flair to Fabric, wait, provision super_user ──
+            if (!opts.force) {
+                console.error("Error: --force is required with --target/--ops-target (remote init provisions a live Fabric instance)");
+                console.error("  Pass --force to confirm this is intended.");
+                process.exit(1);
+            }
+            // Generate flair admin pass if not provided
+            if (!flairAdminPass) {
+                flairAdminPass = randomBytes(24).toString("base64url");
+            }
+            // Write the flair admin pass to secrets directory
+            const secretsDir = join(homedir(), ".tps", "secrets");
+            mkdirSync(secretsDir, { recursive: true });
+            const secretPath = join(secretsDir, "flair-fabric-hdb");
+            writeFileSync(secretPath, flairAdminPass + "\n", { mode: 0o600 });
+            console.log(`Admin password written to ${secretPath}`);
+            // 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 ──
+            if (!opts.adminPass) {
+                console.error("Error: --admin-pass is required with --target/--ops-target (remote init without --cluster-admin-user/--cluster-admin-pass)");
+                console.error("  Use --cluster-admin-user and --cluster-admin-pass for automated Fabric provisioning.");
+                process.exit(1);
+            }
+            if (!opts.force) {
+                const displayTarget = target || opsTarget;
+                console.error(`Error: --force is required with --target/--ops-target. Remote init writes to a live Flair instance at ${displayTarget}.`);
+                console.error("  Pass --force to confirm this is intended.");
+                process.exit(1);
+            }
+            flairAdminPass = opts.adminPass;
+        }
+        const adminUser = DEFAULT_ADMIN_USER;
+        const auth = `Basic ${Buffer.from(`${adminUser}:${flairAdminPass}`).toString("base64")}`;
+        const role = opts.remote ? "hub" : undefined;
+        // Generate or reuse keypair (only if --agent-id provided, or --remote needs
+        // a public key for the FederationInstance row)
+        let pubKeyB64url;
+        let privPath;
+        let instanceId;
+        if (agentId || role) {
+            const keysDir = opts.keysDir ?? defaultKeysDir();
+            mkdirSync(keysDir, { recursive: true });
+            if (agentId) {
+                privPath = privKeyPath(agentId, keysDir);
+                const pubPath = pubKeyPath(agentId, keysDir);
+                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 {
+                    console.log("Generating Ed25519 keypair...");
+                    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} ✓`);
+                }
+                // Seed agent via remote ops API
+                console.log(`Seeding agent '${agentId}' on ${baseUrl}...`);
+                await seedAgentViaOpsApi(opsUrl, agentId, pubKeyB64url, adminUser, flairAdminPass);
+                console.log(`Agent '${agentId}' registered on remote instance ✓`);
+            }
+            else {
+                // No agentId -- generate throwaway keypair for FederationInstance row
+                console.log("Generating federation instance keypair...");
+                const kp = nacl.sign.keyPair();
+                pubKeyB64url = b64url(kp.publicKey);
+            }
+        }
+        else {
+            console.log("No --agent-id provided -- skipping agent registration");
+        }
+        // Write FederationInstance row if --remote (hub role)
+        if (role) {
+            if (!pubKeyB64url) {
+                const kp = nacl.sign.keyPair();
+                pubKeyB64url = b64url(kp.publicKey);
+            }
+            instanceId = randomUUID();
+            console.log(`Writing federation Instance (role=${role}) via ops API...`);
+            await seedFederationInstanceViaOpsApi(opsUrl, instanceId, pubKeyB64url, role, adminUser, flairAdminPass);
+            console.log(`Federation Instance created: ${instanceId} (${role}) ✓`);
+        }
+        // Verify connectivity
+        if (didProvision) {
+            // Use /FederationInstance with Basic auth (not /Health which false-401s on Fabric)
+            console.log("Verifying remote connectivity...");
+            const verifyRes = await fetch(`${baseUrl}/FederationInstance`, {
+                headers: { Authorization: auth },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!verifyRes.ok) {
+                const body = await verifyRes.text().catch(() => "");
+                console.error(`Remote verification failed (${verifyRes.status}): ${body}`);
+                process.exit(1);
+            }
+            console.log("✓ Hub ready at " + baseUrl);
+        }
+        else {
+            // Existing behavior: /Health check (already-running Flair)
+            console.log("Verifying remote connectivity...");
+            const verifyRes = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(5000) });
+            if (!verifyRes.ok) {
+                console.error(`Remote health check failed: ${verifyRes.status}`);
+                process.exit(1);
+            }
+            console.log("Remote Flair instance healthy ✓");
+        }
+        // Print summary
+        if (didProvision) {
+            const pkg = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf-8"));
+            const flavor = pkg.version || "(unknown)";
+            const displayTarget = target || opsTarget;
+            console.log(`\n✓ Flair hub deployed to ${displayTarget}`);
+            console.log(`  Component: flair@${flavor}`);
+            console.log(`  Admin user: ${adminUser} (pass written to ${join(homedir(), ".tps", "secrets", "flair-fabric-hdb")})`);
+            if (instanceId)
+                console.log(`  Instance: ${instanceId} (role=${role})`);
+            console.log(`  Federation: ready — run \`flair federation token\` to mint a pairing token`);
+        }
+        else {
+            console.log(`\n✅ Remote Flair initialized`);
+            if (agentId)
+                console.log(`   Agent ID:    ${agentId}`);
+            console.log(`   Target:      ${baseUrl}`);
+            if (agentId)
+                console.log(`   Private key: ${privPath}`);
+            if (role)
+                console.log(`   Role:         ${role}`);
+            console.log(`\n   Export: FLAIR_URL=${baseUrl}`);
+        }
+        return;
+    }
+    // ── Local init (original behavior) ──
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
-    // Admin password: generate if not provided, NEVER written to disk
-    const adminPass = opts.adminPass ?? Buffer.from(nacl.randomBytes(18)).toString("base64url");
+    // Admin password: determine from opts, env, or generate
+    // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
+    let adminPass;
+    let passwordSource = "generated";
+    // Warn if --admin-pass is passed inline (not from env)
+    if (shouldShowInlineSecretWarning(opts.adminPass, false, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-file <path> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
+    // Read from file if provided
+    if (opts.adminPassFile) {
+        if (!existsSync(opts.adminPassFile)) {
+            console.error(`Error: --admin-pass-file path does not exist: ${opts.adminPassFile}`);
+            process.exit(1);
+        }
+        const fileContent = readFileSync(opts.adminPassFile, "utf-8");
+        adminPass = fileContent.trim();
+        if (!adminPass) {
+            console.error(`Error: admin password file is empty or contains only whitespace: ${opts.adminPassFile}`);
+            process.exit(1);
+        }
+        passwordSource = "file";
+    }
+    else if (process.env.FLAIR_ADMIN_PASS) {
+        adminPass = process.env.FLAIR_ADMIN_PASS;
+        passwordSource = "env";
+    }
+    else if (process.env.HDB_ADMIN_PASSWORD) {
+        adminPass = process.env.HDB_ADMIN_PASSWORD;
+        passwordSource = "env";
+    }
+    else if (opts.adminPass) {
+        // Inline admin pass (deprecated)
+        adminPass = opts.adminPass;
+        // Don't generate - don't write to file
+        passwordSource = "env"; // Treat same as env for display purposes
+    }
+    else {
+        // Generate new password and write to file atomically
+        adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+        passwordSource = "generated";
+        // Atomic write: create temp file in same dir, then rename
+        const flairDir = join(homedir(), ".flair");
+        mkdirSync(flairDir, { recursive: true });
+        const adminPassPath = join(flairDir, "admin-pass");
+        const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
+        const finalTempPath = join(tempPath, "admin-pass");
+        try {
+            writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
+            renameSync(finalTempPath, adminPassPath);
+            rmSync(tempPath, { recursive: true, force: true });
+        }
+        catch (err) {
+            // Clean up temp dir on failure
+            try {
+                rmSync(tempPath, { recursive: true, force: true });
+            }
+            catch { }
+            throw err;
+        }
+    }
     const adminUser = DEFAULT_ADMIN_USER;
+    // If we generated the password, report where it was saved
+    if (passwordSource === "generated") {
+        const adminPassPath = join(homedir(), ".flair", "admin-pass");
+        console.log(`Admin password saved to: ${adminPassPath}`);
+    }
     // Check Node.js version
     const major = parseInt(process.version.slice(1), 10);
     if (major < 18)
@@ -719,150 +1421,515 @@ program
     }
     // Persist port to config so other commands can find this instance
     writeConfig(httpPort);
-    // Generate or reuse keypair
-    mkdirSync(keysDir, { recursive: true });
-    const privPath = privKeyPath(agentId, keysDir);
-    const pubPath = pubKeyPath(agentId, 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 {
-        console.log("Generating Ed25519 keypair...");
-        const kp = nacl.sign.keyPair();
-        // Store only the 32-byte seed (first 32 bytes of secretKey)
-        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} ✓`);
-    }
-    // Seed agent via operations API
-    console.log(`Seeding agent '${agentId}' via operations API...`);
-    await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass);
-    console.log(`Agent '${agentId}' registered ✓`);
-    // Verify Ed25519 auth
-    console.log("Verifying Ed25519 auth...");
-    const httpUrl = `http://127.0.0.1:${httpPort}`;
-    const verifyRes = await authFetch(httpUrl, agentId, privPath, "GET", `/Agent/${agentId}`);
-    if (!verifyRes.ok)
-        throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
-    console.log("Ed25519 auth verified ✓");
-    // Output — admin password printed once, never written to disk
-    console.log("\n✅ Flair initialized successfully");
-    console.log(`   Agent ID:    ${agentId}`);
-    console.log(`   Flair URL:   ${httpUrl}`);
-    console.log(`   Private key: ${privPath}`);
-    if (!opts.adminPass && !alreadyRunning) {
-        console.log(`\n   ┌─────────────────────────────────────────────────┐`);
-        console.log(`   │  Harper admin credentials (save these now):     │`);
-        console.log(`   │                                                 │`);
-        console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
-        console.log(`   │  Password: ${adminPass.padEnd(37)}│`);
-        console.log(`   │                                                 │`);
-        console.log(`   │  ⚠️  The password won't be shown again.         │`);
-        console.log(`   └─────────────────────────────────────────────────┘`);
-    }
-    console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
-    // ── First-run soul setup ──────────────────────────────────────────────
-    // Interactive wizard to set initial personality (see runSoulWizard).
-    // Skipped with --skip-soul or when stdin is not a TTY (CI, scripts, pipe).
-    //
-    // Non-TTY / --skip-soul used to seed placeholder text like
-    // "AI assistant [default]" — it leaked into bootstrap output and
-    // confused users. Now those paths leave the soul empty and nudge the
-    // user toward `flair soul set` / `flair doctor` instead.
-    if (!opts.skipSoul && process.stdin.isTTY) {
-        const soulEntries = await runSoulWizard(agentId);
-        if (soulEntries.length > 0) {
-            console.log("");
-            for (const [key, value] of soulEntries) {
-                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`);
-                }
-                catch (err) {
-                    console.warn(`   ⚠ soul:${key} failed: ${err.message}`);
+    if (agentId) {
+        // Generate or reuse keypair
+        mkdirSync(keysDir, { recursive: true });
+        const privPath = privKeyPath(agentId, keysDir);
+        const pubPath = pubKeyPath(agentId, 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 {
+            console.log("Generating Ed25519 keypair...");
+            const kp = nacl.sign.keyPair();
+            // Store only the 32-byte seed (first 32 bytes of secretKey)
+            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} ✓`);
+        }
+        // Seed agent via operations API
+        console.log(`Seeding agent '${agentId}' via operations API...`);
+        await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adminPass);
+        console.log(`Agent '${agentId}' registered ✓`);
+        // Verify Ed25519 auth
+        console.log("Verifying Ed25519 auth...");
+        const httpUrl = `http://127.0.0.1:${httpPort}`;
+        const verifyRes = await authFetch(httpUrl, agentId, privPath, "GET", `/Agent/${agentId}`);
+        if (!verifyRes.ok)
+            throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
+        console.log("Ed25519 auth verified ✓");
+        // Output — admin password printed once, never written to disk
+        console.log("\n✅ Flair initialized successfully");
+        console.log(`   Agent ID:    ${agentId}`);
+        console.log(`   Flair URL:   ${httpUrl}`);
+        console.log(`   Private key: ${privPath}`);
+        // Display admin credentials when password was generated or from a file
+        // Do NOT display when from env (to avoid showing the env var value)
+        if (passwordSource !== "env" && !alreadyRunning) {
+            const passDisplay = passwordSource === "file"
+                ? opts.adminPassFile ?? "(file path)"
+                : "~/.flair/admin-pass";
+            console.log(`\n   ┌─────────────────────────────────────────────────┐`);
+            console.log(`   │  Harper admin credentials (save these now):     │`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
+            console.log(`   │  Password: ${passDisplay.padEnd(37)}│`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  ⚠️  The password won't be shown again.         │`);
+            console.log(`   └─────────────────────────────────────────────────┘`);
+        }
+        console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
+        // ── First-run soul setup ──────────────────────────────────────────────
+        // Interactive wizard to set initial personality (see runSoulWizard).
+        // Skipped with --skip-soul or when stdin is not a TTY (CI, scripts, pipe).
+        //
+        // Non-TTY / --skip-soul used to seed placeholder text like
+        // "AI assistant [default]" — it leaked into bootstrap output and
+        // confused users. Now those paths leave the soul empty and nudge the
+        // user toward `flair soul set` / `flair doctor` instead.
+        if (!opts.skipSoul && process.stdin.isTTY) {
+            const soulEntries = await runSoulWizard(agentId);
+            if (soulEntries.length > 0) {
+                console.log("");
+                for (const [key, value] of soulEntries) {
+                    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`);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.warn(`   ⚠ soul:${key} failed: ${message}`);
+                    }
                 }
+                console.log(`\n   ${soulEntries.length} soul entries saved.`);
+                console.log(`   Preview what an agent will see: flair bootstrap --agent ${agentId}`);
+            }
+            else {
+                console.log(`\n   No soul entries saved. Add later with:`);
+                console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
+                console.log(`   Or run \`flair doctor\` anytime for a nudge.`);
             }
-            console.log(`\n   ${soulEntries.length} soul entries saved.`);
-            console.log(`   Preview what an agent will see: flair bootstrap --agent ${agentId}`);
         }
         else {
-            console.log(`\n   No soul entries saved. Add later with:`);
+            const reason = opts.skipSoul ? "--skip-soul" : "non-interactive";
+            console.log(`\n   Soul prompts skipped (${reason}). Add entries with:`);
             console.log(`     flair soul set --agent ${agentId} --key role --value "..."`);
-            console.log(`   Or run \`flair doctor\` anytime for a nudge.`);
         }
-    }
-    else {
-        const reason = opts.skipSoul ? "--skip-soul" : "non-interactive";
-        console.log(`\n   Soul prompts skipped (${reason}). Add entries with:`);
-        console.log(`     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
-    const claudeJsonPath = join(homedir(), ".claude.json");
-    const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
-    const flairMcpConfig = {
-        type: "stdio",
-        command: "flair-mcp",
-        args: [],
-        env: mcpEnv,
-    };
-    try {
-        if (existsSync(claudeJsonPath)) {
-            const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
-            const existing = claudeJson.mcpServers?.flair;
-            if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
-                console.log(`\n   MCP config already set in ~/.claude.json ✓`);
+        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
+        const claudeJsonPath = join(homedir(), ".claude.json");
+        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+        const flairMcpConfig = {
+            type: "stdio",
+            command: "flair-mcp",
+            args: [],
+            env: mcpEnv,
+        };
+        try {
+            if (existsSync(claudeJsonPath)) {
+                const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+                const existing = claudeJson.mcpServers?.flair;
+                if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
+                    console.log(`\n   MCP config already set in ~/.claude.json ✓`);
+                }
+                else {
+                    claudeJson.mcpServers = claudeJson.mcpServers || {};
+                    claudeJson.mcpServers.flair = flairMcpConfig;
+                    writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+                    console.log(`\n   MCP config written to ~/.claude.json ✓`);
+                    console.log(`   Restart Claude Code to pick up the new config.`);
+                }
             }
             else {
-                claudeJson.mcpServers = claudeJson.mcpServers || {};
-                claudeJson.mcpServers.flair = flairMcpConfig;
-                writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
-                console.log(`\n   MCP config written to ~/.claude.json ✓`);
-                console.log(`   Restart Claude Code to pick up the new config.`);
+                console.log(`\n   MCP config (add to ~/.claude.json):`);
+                console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
             }
         }
-        else {
-            console.log(`\n   MCP config (add to ~/.claude.json):`);
+        catch {
+            console.log(`\n   MCP config (add manually to ~/.claude.json):`);
             console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
         }
     }
-    catch {
-        console.log(`\n   MCP config (add manually to ~/.claude.json):`);
-        console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+    else {
+        const httpUrl = `http://127.0.0.1:${httpPort}`;
+        console.log("\n✅ Flair initialized (no agent registered)");
+        console.log(`   Flair URL:   ${httpUrl}`);
+        // Display admin credentials when password was generated or from a file
+        // Do NOT display when from env (to avoid showing the env var value)
+        if (passwordSource !== "env" && !alreadyRunning) {
+            const passDisplay = passwordSource === "file"
+                ? opts.adminPassFile ?? "(file path)"
+                : "~/.flair/admin-pass";
+            console.log(`\n   ┌─────────────────────────────────────────────────┐`);
+            console.log(`   │  Harper admin credentials (save these now):     │`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  Username: ${DEFAULT_ADMIN_USER.padEnd(37)}│`);
+            console.log(`   │  Password: ${passDisplay.padEnd(37)}│`);
+            console.log(`   │                                                 │`);
+            console.log(`   │  ⚠️  The password won't be shown again.         │`);
+            console.log(`   └─────────────────────────────────────────────────┘`);
+        }
+        console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
     }
 });
-// ─── flair agent ─────────────────────────────────────────────────────────────
-const agent = program.command("agent").description("Manage Flair agents");
-agent
-    .command("add <id>")
-    .description("Register a new agent in a running Flair instance")
-    .option("--name <name>", "Display name (defaults to id)")
+// ─── flair install ───────────────────────────────────────────────────────────
+program
+    .command("install")
+    .description("One-command Flair setup — init, agent, and MCP client wiring")
+    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, all, or none")
+    .option("--agent <id>", "Agent ID (defaults to hostname short-form)")
+    .option("--no-mcp", "Skip MCP wiring (init + agent only)")
     .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) => {
+    .option("--data-dir <dir>", "Harper data directory")
+    .option("--keys-dir <dir>", "Directory for Ed25519 keys")
+    .option("--skip-smoke", "Skip MCP smoke test")
+    .action(async (opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
-    const adminPass = opts.adminPass;
-    const adminUser = DEFAULT_ADMIN_USER;
-    const name = opts.name ?? id;
-    if (!adminPass) {
-        console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table)");
-        process.exit(1);
+    const dataDir = opts.dataDir ?? defaultDataDir();
+    // Resolve client selection
+    const clientOpt = opts.client;
+    const noMcp = opts.noMcp === true;
+    const selectedClients = [];
+    if (clientOpt === "none" || noMcp) {
+        // Skip MCP entirely — just init + agent
+    }
+    else if (clientOpt === "all") {
+        // Wire all detected clients
+    }
+    else if (clientOpt) {
+        // Wire a specific client
+        const valid = ["claude-code", "codex", "gemini", "cursor"];
+        if (!valid.includes(clientOpt)) {
+            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, all, none`);
+            process.exit(1);
+        }
+        selectedClients.push(clientOpt);
     }
-    mkdirSync(keysDir, { recursive: true });
-    const privPath = privKeyPath(id, keysDir);
-    const pubPath = pubKeyPath(id, keysDir);
+    // If no --client flag: interactive detection later
+    // ── Step 1: Ensure Flair is initialized ──
+    let alreadyInitialized = false;
+    let alreadyRunning = false;
+    let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+    const adminUser = DEFAULT_ADMIN_USER;
+    // Check if Flair is already initialized (config with port exists)
+    try {
+        const cp = configPath();
+        if (existsSync(cp)) {
+            const yaml = readFileSync(cp, "utf-8");
+            if (yaml.match(/port:\s*\d+/)) {
+                alreadyInitialized = true;
+                console.log("Flair already initialized — skipping init.");
+            }
+        }
+    }
+    catch { /* not initialized */ }
+    if (!alreadyInitialized) {
+        const major = parseInt(process.version.slice(1), 10);
+        if (major < 18)
+            throw new Error(`Node.js >= 18 required (found ${process.version})`);
+        // Only generate a password if none provided via env (fresh install)
+        // If we generate, write it atomically to ~/.flair/admin-pass
+        let adminPassGenerated = false;
+        if (!adminPass) {
+            adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+            adminPassGenerated = true;
+            // Atomic write: create temp file in same dir, then rename
+            const flairDir = join(homedir(), ".flair");
+            mkdirSync(flairDir, { recursive: true });
+            const adminPassPath = join(flairDir, "admin-pass");
+            const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
+            const finalTempPath = join(tempPath, "admin-pass");
+            try {
+                writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
+                renameSync(finalTempPath, adminPassPath);
+                rmSync(tempPath, { recursive: true, force: true });
+            }
+            catch (err) {
+                // Clean up temp dir on failure
+                try {
+                    rmSync(tempPath, { recursive: true, force: true });
+                }
+                catch { }
+                throw err;
+            }
+            console.log(`Admin password saved to: ${adminPassPath}`);
+        }
+        // Check if Harper is already running on this port
+        try {
+            const res = await fetch(`http://127.0.0.1:${httpPort}/health`, { signal: AbortSignal.timeout(1000) });
+            if (res.status > 0) {
+                alreadyRunning = true;
+                console.log(`Harper already running on port ${httpPort} — skipping start`);
+            }
+        }
+        catch { /* not running */ }
+        if (!alreadyRunning) {
+            const bin = harperBin();
+            if (!bin)
+                throw new Error("@harperfast/harper not found in node_modules.\nRun: npm install @harperfast/harper");
+            mkdirSync(dataDir, { recursive: true });
+            const alreadyInstalled = existsSync(join(dataDir, "harper-config.yaml"));
+            const harperSetConfig = JSON.stringify({
+                rootPath: dataDir,
+                http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
+                operationsApi: { network: { port: opsPort, cors: true }, domainSocket: join(dataDir, "operations-server") },
+                mqtt: { network: { port: null }, webSocket: false },
+                localStudio: { enabled: false },
+                authentication: { authorizeLocal: true, enableSessions: true },
+            });
+            const env = {
+                ...process.env,
+                ROOTPATH: dataDir,
+                HARPER_SET_CONFIG: harperSetConfig,
+                DEFAULTS_MODE: "dev",
+                HDB_ADMIN_USERNAME: adminUser,
+                HDB_ADMIN_PASSWORD: adminPass,
+                THREADS_COUNT: "1",
+                NODE_HOSTNAME: "localhost",
+                HTTP_PORT: String(httpPort),
+                OPERATIONSAPI_NETWORK_PORT: String(opsPort),
+                LOCAL_STUDIO: "false",
+            };
+            if (alreadyInstalled) {
+                console.log("Existing Harper installation found — skipping install.");
+            }
+            else {
+                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 });
+                    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) => {
+                        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
+            console.log(`Starting Harper on port ${httpPort}...`);
+            const proc = spawn(process.execPath, [bin, "run", "."], { cwd: flairPackageDir(), env, detached: true, stdio: "ignore" });
+            proc.unref();
+        }
+        // Wait for health
+        console.log("Waiting for Harper health check...");
+        await waitForHealth(httpPort, adminUser, adminPass, STARTUP_TIMEOUT_MS);
+        console.log("Harper is healthy ✓");
+        // Write config so other commands can find this instance
+        writeConfig(httpPort);
+    }
+    else {
+        // Flair already initialized — resolve admin pass from env or running instance
+        adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+    }
+    const httpUrl = `http://127.0.0.1:${httpPort}`;
+    // ── Step 2: Detect MCP clients ──
+    let clients = detectClients();
+    if (selectedClients.length > 0) {
+        // Explicit --client flag — override detection
+        if (clientOpt === "all" || clientOpt === "none" || noMcp) {
+            // all/none handled below
+        }
+        else {
+            // Filter to only the selected client (preserving wire function from detectClients)
+            clients = clients.filter(c => selectedClients.includes(c.id));
+        }
+    }
+    if (!clientOpt && !noMcp) {
+        // No --client flag — print detected clients
+        const detected = clients.filter(c => c.detected);
+        if (detected.length === 0) {
+            console.log("No MCP clients detected. Run with --client <name> to wire a specific client.");
+        }
+        else {
+            console.log(`Detected MCP clients: ${detected.map(c => c.label).join(", ")}`);
+        }
+    }
+    // ── Step 3: Resolve agent identity ──
+    const agentId = opts.agent ?? (() => {
+        try {
+            const hn = hostname();
+            return hn.split(".")[0];
+        }
+        catch {
+            return "flair-agent";
+        }
+    })();
+    // Validate agentId to prevent path traversal
+    const VALID_AGENT_ID = /^[a-zA-Z0-9_-]+$/;
+    if (!VALID_AGENT_ID.test(agentId)) {
+        throw new Error(`Invalid agent ID: ${agentId}. Agent ID must contain only letters, numbers, underscores, and hyphens.`);
+    }
+    let agentExists = false;
+    // Check if agent already exists locally
+    const privPath = privKeyPath(agentId, keysDir);
+    if (existsSync(privPath)) {
+        agentExists = true;
+        console.log(`Agent '${agentId}' already exists ✓`);
+    }
+    else {
+        // Create agent
+        mkdirSync(keysDir, { recursive: true });
+        const pubPath = pubKeyPath(agentId, keysDir);
+        console.log("Generating Ed25519 keypair...");
+        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));
+        const pubKeyB64url = b64url(kp.publicKey);
+        console.log(`Keypair written: ${privPath} ✓`);
+        // Seed agent - use REST API for local Harper, Ops API only when --ops-target is specified
+        if (opts.opsTarget) {
+            // Remote Harper via explicit ops target
+            console.log(`Seeding agent '${agentId}' via operations API (--ops-target)...`);
+            await seedAgentViaOpsApi(opts.opsTarget, agentId, pubKeyB64url, adminUser, adminPass);
+        }
+        else {
+            // Local Harper - use REST API
+            console.log(`Seeding agent '${agentId}' via REST API...`);
+            await seedAgentViaRestApi(httpPort, agentId, pubKeyB64url, adminPass);
+        }
+        console.log(`Agent '${agentId}' registered ✓`);
+    }
+    // ── Step 4: Wire MCP clients ──
+    const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+    const wiringResults = [];
+    if (!noMcp && clientOpt !== "none") {
+        const toWire = clientOpt === "all"
+            ? clients.filter(c => c.detected).map(c => c.id)
+            : selectedClients.length > 0
+                ? selectedClients
+                : clients.filter(c => c.detected).map(c => c.id);
+        for (const clientId of toWire) {
+            let result;
+            switch (clientId) {
+                case "claude-code":
+                    result = wireClaudeCode(mcpEnv);
+                    break;
+                case "codex":
+                    result = wireCodex(mcpEnv);
+                    break;
+                case "gemini":
+                    result = wireGemini(mcpEnv);
+                    break;
+                case "cursor":
+                    result = wireCursor(mcpEnv);
+                    break;
+                default: result = { ok: false, message: `Unknown client: ${clientId}` };
+            }
+            wiringResults.push({ client: clientId, message: result.message });
+            console.log(`  ${result.ok ? "✓" : "✗"} ${result.message}`);
+        }
+    }
+    // ── Step 5: Smoke test the MCP server ──
+    if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
+        console.log("Smoke-testing MCP server...");
+        try {
+            // Launch flair-mcp and send initialize request over stdio
+            const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
+                stdio: ["pipe", "pipe", "pipe"],
+                timeout: 15_000,
+            });
+            // Send initialize request
+            const initMsg = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "0.1", capabilities: {}, clientInfo: { name: "flair-install", version: "1.0.0" } } });
+            mcpProc.stdin.write(initMsg + "\n");
+            mcpProc.stdin.end();
+            let stdout = "";
+            mcpProc.stdout.on("data", (d) => { stdout += d.toString(); });
+            await new Promise((resolve, reject) => {
+                mcpProc.on("exit", (code) => {
+                    if (code === 0 && stdout.length > 0) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`MCP server exited with code ${code}`));
+                    }
+                });
+                mcpProc.on("error", reject);
+                setTimeout(() => { mcpProc.kill(); reject(new Error("MCP smoke test timed out")); }, 15_000);
+            });
+            // Check for a valid JSON-RPC response
+            try {
+                const lines = stdout.split("\n").filter(l => l.trim());
+                for (const line of lines) {
+                    const parsed = JSON.parse(line);
+                    if (parsed.jsonrpc === "2.0" && parsed.id === 1 && !parsed.error) {
+                        console.log("  ✓ MCP server responded");
+                        break;
+                    }
+                }
+            }
+            catch {
+                console.log("  ⚠ MCP server responded but response could not be parsed");
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(`  ⚠ MCP smoke test failed: ${message}`);
+            console.log("  Use --skip-smoke to bypass.");
+        }
+    }
+    // ── Step 6: Summary ──
+    console.log("");
+    console.log("✓ Flair installed.");
+    console.log(`   Agent: ${agentId}`);
+    if (existsSync(privKeyPath(agentId, keysDir))) {
+        console.log(`   Private key: ${privKeyPath(agentId, keysDir)}`);
+    }
+    console.log(`   Local: ${httpUrl}`);
+    console.log(`   MCP: ${wiringResults.length > 0 ? wiringResults.map(r => r.client).join(", ") + " ✓ wired" : "none wired"}`);
+    console.log("");
+    console.log(`   Try it: in Claude Code, ask the agent "what do you remember about me?"`);
+});
+// ─── flair agent ─────────────────────────────────────────────────────────────
+const agent = program.command("agent").description("Manage Flair agents");
+agent
+    .command("add <id>")
+    .description("Register a new agent in a running Flair instance")
+    .option("--name <name>", "Display name (defaults to id)")
+    .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 httpPort = resolveHttpPort(opts);
+    const opsPort = resolveOpsPort(opts);
+    const keysDir = opts.keysDir ?? defaultKeysDir();
+    const adminPass = opts.adminPass;
+    const adminUser = DEFAULT_ADMIN_USER;
+    const name = opts.name ?? id;
+    if (!adminPass) {
+        console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table)");
+        process.exit(1);
+    }
+    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}`);
@@ -891,7 +1958,13 @@ agent
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
-    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    // fromEnv is true ONLY when the resolved value came from env (no inline override).
+    const adminPassFromEnv = !opts.adminPass && (!!process.env.FLAIR_ADMIN_PASS || !!process.env.HDB_ADMIN_PASSWORD);
+    if (shouldShowInlineSecretWarning(opts.adminPass, adminPassFromEnv, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-from <file> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
     if (adminPass) {
         // Use admin basic auth against ops API to list agents directly
         const opsPort = resolveOpsPort(opts);
@@ -899,18 +1972,37 @@ agent
         const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
-            body: JSON.stringify({ operation: "sql", sql: "SELECT id, name, createdAt FROM flair.Agent ORDER BY createdAt" }),
+            body: JSON.stringify({ operation: "search_by_value", schema: "flair", table: "Agent", search_attribute: "id", search_type: "starts_with", search_value: "", get_attributes: ["id", "name", "createdAt"] }),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => "");
             console.error(`Error: ${res.status} ${text}`);
             process.exit(1);
         }
-        console.log(JSON.stringify(await res.json(), null, 2));
+        const agents = await res.json();
+        agents.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+        console.log(JSON.stringify(agents, null, 2));
     }
     else {
-        // Try agent-authed API (requires FLAIR_AGENT_ID to be set)
-        console.log(JSON.stringify(await api("GET", "/Agent"), null, 2));
+        // Localhost operator path: allow IDs-only enumeration without per-agent auth
+        // This treats localhost as a trusted boundary for read-only public metadata
+        const baseUrl = `http://127.0.0.1:${port}`;
+        const res = await fetch(`${baseUrl}/Agent`, {
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`Error: ${res.status} ${text}`);
+            process.exit(1);
+        }
+        const data = await res.json();
+        // Filter to IDs-only to respect the localhost trust boundary
+        if (Array.isArray(data)) {
+            console.log(JSON.stringify(data.map((a) => ({ id: a.id, name: a.name, createdAt: a.createdAt })), null, 2));
+        }
+        else {
+            console.log(JSON.stringify(data, null, 2));
+        }
     }
 });
 agent
@@ -927,6 +2019,12 @@ agent
     .action(async (id, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
+    // fromEnv is true ONLY when the resolved value came from env (no inline override).
+    const adminPassFromEnv = !opts.adminPass && !!process.env.FLAIR_ADMIN_PASS;
+    if (shouldShowInlineSecretWarning(opts.adminPass, adminPassFromEnv, new Set(["--admin-pass"]), "--admin-pass")) {
+        console.error("warning: --admin-pass passed inline. Consider --admin-pass-from <file> or FLAIR_ADMIN_PASS env " +
+            "to keep secrets out of shell history.");
+    }
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     const adminUser = DEFAULT_ADMIN_USER;
     const keysDir = opts.keysDir ?? defaultKeysDir();
@@ -1204,14 +2302,20 @@ principal
         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 conditions = opts.kind
+        ? [{ search_attribute: "kind", search_type: "equals", search_value: opts.kind }]
+        : [{ search_attribute: "id", search_type: "starts_with", search_value: "" }];
     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`,
+            operation: "search_by_conditions",
+            schema: "flair",
+            table: "Agent",
+            operator: "and",
+            conditions,
+            get_attributes: ["id", "name", "kind", "status", "defaultTrustTier", "admin", "runtime", "createdAt"],
         }),
     });
     if (!res.ok) {
@@ -1220,6 +2324,7 @@ principal
         process.exit(1);
     }
     const records = await res.json();
+    records.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
     if (records.length === 0) {
         console.log("No principals found.");
         return;
@@ -1382,8 +2487,13 @@ idp
         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",
+            operation: "search_by_value",
+            schema: "flair",
+            table: "IdpConfig",
+            search_attribute: "id",
+            search_type: "starts_with",
+            search_value: "",
+            get_attributes: ["id", "name", "issuer", "requiredDomain", "jitProvision", "enabled", "createdAt"],
         }),
     });
     if (!res.ok) {
@@ -1392,6 +2502,7 @@ idp
         process.exit(1);
     }
     const records = await res.json();
+    records.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
     if (records.length === 0) {
         console.log("No IdPs configured.");
         return;
@@ -1443,18 +2554,14 @@ idp
         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) {
+    let cfg;
+    try {
+        cfg = await api("GET", `/IdpConfig/${id}`);
+    }
+    catch {
         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 {
@@ -1468,7 +2575,8 @@ idp
         console.log(`  ✅ JWKS reachable — ${keyCount} key(s) found`);
     }
     catch (err) {
-        console.error(`  ❌ JWKS fetch error: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`  ❌ JWKS fetch error: ${message}`);
         process.exit(1);
     }
 });
@@ -1581,7 +2689,7 @@ async function loadInstanceSecretKey(instanceId, opts) {
     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}'` }),
+        body: JSON.stringify({ operation: "search_by_value", schema: "flair", table: "Instance", search_attribute: "id", search_type: "equals", search_value: instanceId, get_attributes: ["*"] }),
     });
     if (res.ok) {
         const rows = await res.json();
@@ -1598,23 +2706,37 @@ 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
     .command("status")
     .description("Show federation status and peer connections")
     .option("--port <port>", "Harper HTTP port")
+    .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 (opts) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     try {
-        const instance = await api("GET", "/FederationInstance");
+        const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
         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");
+        const { peers } = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
         if (peers.length === 0) {
             console.log("No peers configured. Use 'flair federation pair' to connect to a hub.");
         }
@@ -1632,33 +2754,210 @@ 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")
+    .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) => {
+    const target = resolveTarget(opts);
+    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     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.");
+        const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+        console.log(`${target ? "Remote" : "Local"} instance: ${instance.id} (${instance.role})`);
+        // 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);
         }
-        // Load secret key and sign the pairing request
+        // 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,
+            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) {
@@ -1668,12 +2967,12 @@ federation
         }
         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);
+        // Record the hub as our peer — locally or remotely depending on --target
         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}/`, {
+            const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
+            await fetch(`${opsEndpoint}/`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", Authorization: auth },
                 body: JSON.stringify({
@@ -1687,6 +2986,7 @@ federation
                             updatedAt: new Date().toISOString(),
                         }],
                 }),
+                signal: AbortSignal.timeout(10_000),
             });
         }
     }
@@ -1702,16 +3002,21 @@ federation
     .option("--admin-pass <pass>", "Admin password")
     .option("--ops-port <port>", "Harper operations API port")
     .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 opsPort = resolveOpsPort(opts);
+        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")}`;
-        await fetch(`http://127.0.0.1:${opsPort}/`, {
+        // 1. Persist the PairingToken record
+        const opsRes = await fetch(`${opsEndpoint}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: auth },
             body: JSON.stringify({
@@ -1722,78 +3027,514 @@ federation
                         expiresAt,
                     }],
             }),
+            signal: AbortSignal.timeout(10_000),
         });
-        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}`);
+        if (!opsRes.ok) {
+            const detail = await opsRes.text().catch(() => "");
+            throw new Error(`Failed to persist pairing token (${opsRes.status}): ${detail || "no body"}`);
+        }
+        // 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}`);
         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) => {
+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");
+        const { peers } = await api("GET", "/FederationPeers", undefined, apiOpts);
         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);
+            return { pushed: 0, skipped: 0, error: new Error("No hub peer configured. Use 'flair federation pair' first.") };
         }
         console.log(`Syncing to hub: ${hub.id}...`);
         const since = hub.lastSyncAt ?? new Date(0).toISOString();
-        const opsPort = resolveOpsPort(opts);
+        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")}`;
         const tables = ["Memory", "Soul", "Agent", "Relationship"];
-        const records = [];
-        const instance = await api("GET", "/FederationInstance");
+        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 {
-                const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+                res = await fetch(`${opsEndpoint}/`, {
                     method: "POST",
                     headers: { "Content-Type": "application/json", Authorization: auth },
-                    body: JSON.stringify({ operation: "sql", sql: `SELECT * FROM flair.${table} WHERE updatedAt > '${since}'` }),
+                    body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table, operator: "and", conditions: [{ search_attribute: "updatedAt", search_type: "greater_than", search_value: since }], get_attributes: ["*"] }),
+                    signal: AbortSignal.timeout(15_000),
                 });
-                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 (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: 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;
+            }
+            // Send final partial batch for this table
+            if (batch.length > 0) {
+                const result = await sendBatch(batch);
+                totalMerged += result.merged;
+                totalSkipped += result.skipped;
+                totalBatches++;
             }
-            catch { }
         }
-        if (records.length === 0) {
+        if (totalBatches === 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);
+            return { pushed: 0, skipped: 0 };
         }
-        const result = await syncRes.json();
-        console.log(`✅ Synced ${result.merged} records (${result.skipped} skipped) in ${result.durationMs}ms`);
+        console.log(`✅ Synced ${totalMerged} records (${totalSkipped} skipped) across ${totalBatches} batches`);
+        return { pushed: totalMerged, skipped: totalSkipped };
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
+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")
+    .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 (opts) => {
+    const r = await runFederationSyncOnce(opts);
+    if (r.error) {
+        console.error(`Error: ${r.error.message}`);
+        process.exit(1);
+    }
+});
+export async function runFederationWatch(opts) {
+    const intervalMs = Math.max(5, parseFloat(opts.interval) || 30) * 1000;
+    let stopped = false;
+    const stop = () => { stopped = true; };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    console.log(`flair federation watch — interval ${intervalMs / 1000}s. Ctrl-C to stop.`);
+    try {
+        while (!stopped) {
+            try {
+                const r = await runFederationSyncOnce(opts);
+                const ts = new Date().toISOString();
+                if (r.error)
+                    console.error(`[${ts}] sync error: ${r.error.message}`);
+                else
+                    console.log(`[${ts}] sync ok — pushed ${r.pushed}, skipped ${r.skipped}`);
+            }
+            catch (err) {
+                console.error(`[${new Date().toISOString()}] watch loop error: ${err.message}`);
+            }
+            // Sleep but exit early on signal
+            const t = Date.now();
+            while (!stopped && Date.now() - t < intervalMs) {
+                const remaining = intervalMs - (Date.now() - t);
+                await new Promise((r) => setTimeout(r, Math.min(250, remaining)));
+            }
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
+    console.log("flair federation watch — stopped.");
+}
+federation
+    .command("watch")
+    .description("Run federation sync in a loop (foreground daemon)")
+    .option("--interval <seconds>", "Seconds between syncs", "30")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--admin-pass <pass>", "Admin password")
+    .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) => {
+    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).
@@ -1956,31 +3697,294 @@ rem
             }
         }
         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",
+            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 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 (reflect.error) {
-                console.error(`Reflection error: ${reflect.error}`);
+            if (soulWrite?.error) {
+                console.error(`Error writing Soul: ${soulWrite.error}`);
                 process.exit(1);
             }
-            console.log(`  Source memories: ${reflect.count ?? 0}`);
-            if (reflect.suggestedTags?.length) {
-                console.log(`  Tags: ${reflect.suggestedTags.join(", ")}`);
+            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.log("\n--- Reflection Prompt ---");
-            console.log(reflect.prompt ?? "(no prompt returned)");
-            console.log("--- End Prompt ---");
+            console.error(`Error: candidate ${candidateId} ${_d.message}`);
+            process.exit(1);
         }
-        else {
-            console.log("\n[3/3] Reflection skipped — no agent ID");
+        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(`\nRestorative cycle complete.${dryRun ? " No changes applied (dry run)." : ""}`);
+        console.log(`✅ Candidate ${candidateId} rejected by ${reviewerId}`);
+        console.log(`   Reason: ${opts.reason}`);
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -2055,9 +4059,63 @@ 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);
-    const baseUrl = opts.url ?? `http://127.0.0.1:${port}`;
+    // --target takes precedence, then --url, then FLAIR_TARGET, then FLAIR_URL, then localhost
+    const baseUrl = opts.target || opts.url || process.env.FLAIR_TARGET || (process.env.FLAIR_URL ?? `http://127.0.0.1:${port}`);
     let healthy = false;
     let healthData = null;
     try {
@@ -2114,12 +4172,23 @@ const statusCmd = program
     .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("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
     .option("--json", "Output as JSON")
     .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;
@@ -2127,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;
@@ -2142,17 +4221,42 @@ const statusCmd = program
     const agents = healthData?.agents;
     const memories = healthData?.memories;
     const warnings = Array.isArray(healthData?.warnings) ? healthData.warnings : [];
-    const hasWarn = warnings.some((w) => w.level === "warn");
-    // Header state-word stays "running" whenever the process is alive; the
-    // icon conveys health (🟢 clean / 🟡 warnings). 🔴 unreachable is already
-    // handled above by the `!healthy` early-exit. Decoupling state from
-    // health keeps the smoke-test `grep -q "running"` stable across tiers.
+    // Scope warnings to the filtered agent if --agent is set
+    const scopedWarnings = opts.agent && healthData?.agents?.perAgent
+        ? warnings.filter((w) => {
+            // Hash-fallback warnings contain agent-specific counts
+            if (w.message.includes("hash-fallback")) {
+                const match = w.message.match(/\b(\d+)\/(\d+) \((\d+)%\)/);
+                if (match) {
+                    const hashCount = parseInt(match[1]);
+                    const totalCount = parseInt(match[2]);
+                    const agentRow = healthData.agents.perAgent.find((r) => r.id === opts.agent);
+                    if (agentRow && agentRow.hashFallback === hashCount && agentRow.memoryCount === totalCount) {
+                        return true;
+                    }
+                    return false;
+                }
+            }
+            // Mixed-model warnings are fleet-wide; keep them
+            if (w.message.includes("multiple embedding models"))
+                return true;
+            // Federation warnings are fleet-wide; keep them
+            if (w.message.includes("federation"))
+                return true;
+            // REM warnings are fleet-wide; keep them
+            if (w.message.includes("REM") || w.message.includes("nightly"))
+                return true;
+            // Default: keep fleet-wide warnings
+            return !w.message.includes(opts.agent);
+        })
+        : warnings;
+    const hasWarn = scopedWarnings.some((w) => w.level === "warn");
     const headerIcon = hasWarn ? "🟡" : "🟢";
     console.log(`Flair v${__pkgVersion} — ${headerIcon} running${pid ? ` (PID ${pid}` : ""}${uptimeStr ? `, uptime ${uptimeStr})` : pid ? ")" : ""}`);
     console.log(`  URL:        ${baseUrl}`);
-    if (warnings.length > 0) {
-        console.log(`\n⚠ Warnings:  ${warnings.length}`);
-        for (const w of warnings)
+    if (scopedWarnings.length > 0) {
+        console.log(`\n⚠ Warnings:  ${scopedWarnings.length}`);
+        for (const w of scopedWarnings)
             console.log(`  • ${w.level} ${w.message}`);
     }
     if (memories) {
@@ -2248,6 +4352,9 @@ const statusCmd = program
         if (f.pendingTokens > 0)
             console.log(`  Pairing:     ${f.pendingTokens} unconsumed token(s)`);
     }
+    else {
+        console.log("\nFederation: not configured");
+    }
     if (healthData?.oauth) {
         const lines = oauthSummaryLines(healthData.oauth);
         for (const line of lines)
@@ -2263,6 +4370,9 @@ const statusCmd = program
         if (b.lastExport)
             console.log(`  Last export: ${relativeTime(b.lastExport)}`);
     }
+    else {
+        console.log("\nBridges: none installed");
+    }
     if (healthData?.disk) {
         const d = healthData.disk;
         console.log("\nDisk:");
@@ -2270,8 +4380,8 @@ const statusCmd = program
         console.log(`  Snapshots:   ${d.snapshotDir} — ${humanBytes(d.snapshotBytes ?? 0)}`);
     }
     console.log("");
-    if (warnings.length > 0)
-        console.log(`  Health:     ⚠ ${warnings.length} warning(s)`);
+    if (scopedWarnings.length > 0)
+        console.log(`  Health:     ⚠ ${scopedWarnings.length} warning(s)`);
     else
         console.log(`  Health:     ✅ all checks passing`);
 });
@@ -2407,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)
@@ -2445,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;
@@ -2476,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" });
@@ -2488,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 {
@@ -2806,7 +4965,7 @@ program
 program
     .command("reembed")
     .description("Re-generate embeddings for memories with stale or missing model tags")
-    .requiredOption("--agent <id>", "Agent ID to re-embed memories for")
+    .option("--agent <id>", "Agent ID to re-embed memories for (defaults to all agents with stale rows)")
     .option("--stale-only", "Only re-embed memories with mismatched model tag")
     .option("--dry-run", "Show count without modifying")
     .option("--port <port>", "Harper HTTP port")
@@ -2821,28 +4980,165 @@ program
     const batchSize = Number(opts.batchSize);
     const delayMs = Number(opts.delayMs);
     const currentModel = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
-    console.log(`Re-embedding memories for agent: ${agentId}`);
+    if (agentId) {
+        console.log(`Re-embedding memories for agent: ${agentId}`);
+    }
+    else {
+        console.log("Re-embedding memories for all agents with stale rows");
+    }
     console.log(`Current model: ${currentModel}`);
     if (staleOnly)
         console.log("Mode: stale-only (skipping up-to-date memories)");
     if (dryRun)
         console.log("Mode: dry-run (no modifications)");
     console.log("");
+    // When no agent specified, use admin auth to fetch all memories
+    if (!agentId) {
+        const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
+        if (!adminPass) {
+            console.error("❌ Admin password required when --agent is not specified (set FLAIR_ADMIN_PASS or HDB_ADMIN_PASSWORD)");
+            process.exit(1);
+        }
+        // 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: 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 via ops API: ${searchRes.status}`);
+            process.exit(1);
+        }
+        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) {
+            if (!m.content)
+                continue;
+            if (staleOnly && m.embeddingModel === currentModel)
+                continue;
+            const agent = m.agentId || "unknown";
+            if (!byAgent.has(agent))
+                byAgent.set(agent, []);
+            byAgent.get(agent).push(m);
+        }
+        // Process each agent
+        let totalProcessed = 0;
+        let totalErrors = 0;
+        const agentCount = byAgent.size;
+        let agentIndex = 0;
+        for (const [agent, memories] of byAgent) {
+            agentIndex++;
+            console.log(`\nAgent ${agentIndex}/${agentCount}: ${agent}`);
+            console.log(`  Memories to re-embed: ${memories.length}`);
+            const keysDir = defaultKeysDir();
+            const privPath = privKeyPath(agent, keysDir);
+            if (!existsSync(privPath)) {
+                console.error(`  ❌ Key not found: ${privPath} — skipping`);
+                continue;
+            }
+            if (dryRun)
+                continue;
+            let processed = 0;
+            let errors = 0;
+            for (let i = 0; i < memories.length; i += batchSize) {
+                const batch = memories.slice(i, i + batchSize);
+                for (const memory of batch) {
+                    try {
+                        const updateRes = await authFetch(baseUrl, agent, privPath, "PUT", `/Memory/${memory.id}`, {
+                            id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined, agentId: memory.agentId || agent,
+                        });
+                        if (updateRes.ok)
+                            processed++;
+                        else
+                            errors++;
+                    }
+                    catch {
+                        errors++;
+                    }
+                }
+                const pct = Math.round(((i + batch.length) / memories.length) * 100);
+                process.stdout.write(`  \r  Re-embedded ${processed}/${memories.length} (${pct}%)${errors > 0 ? ` [${errors} errors]` : ""}`);
+                if (i + batchSize < memories.length)
+                    await new Promise(r => setTimeout(r, delayMs));
+            }
+            console.log(`\n  ✅ Agent ${agent}: ${processed} updated, ${errors} errors`);
+            totalProcessed += processed;
+            totalErrors += errors;
+        }
+        console.log(`\n\n✅ Re-embedding complete: ${totalProcessed} updated, ${totalErrors} errors`);
+        return;
+    }
+    // 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;
@@ -2869,7 +5165,7 @@ program
         for (const memory of batch) {
             try {
                 const updateRes = await authFetch(baseUrl, agentId, privPath, "PUT", `/Memory/${memory.id}`, {
-                    id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined,
+                    id: memory.id, content: memory.content, embedding: undefined, embeddingModel: undefined, agentId: memory.agentId || opts.agent,
                 });
                 if (updateRes.ok)
                     processed++;
@@ -2919,7 +5215,8 @@ program
             }
         }
         catch (e) {
-            console.log(`  ${red("FAIL")} ${name}: ${e.message?.slice(0, 120)}`);
+            const message = e instanceof Error ? e.message : String(e);
+            console.log(`  ${red("FAIL")} ${name}: ${message?.slice(0, 120)}`);
             failed++;
         }
     };
@@ -2963,6 +5260,13 @@ program
         process.exit(1);
 });
 // ─── flair deploy ─────────────────────────────────────────────────────────────
+// NOTE on env-var naming for `flair deploy`: the FABRIC_* env vars below intentionally
+// do NOT carry the FLAIR_ prefix that the rest of the CLI uses (FLAIR_ADMIN_PASS,
+// FLAIR_TARGET, FLAIR_PAIRING_TOKEN, etc.). FABRIC_* credentials are shared with
+// the broader TPS tooling stack — multiple tools deploy to the same Harper Fabric
+// org/cluster with the same auth, and demanding a tool-specific prefix would force
+// operators to maintain duplicated env vars. Per Kern review on PR #306: the
+// inconsistency is deliberate, document it here so the next agent doesn't "fix" it.
 program
     .command("deploy")
     .description("Deploy Flair as a component to a remote Harper Fabric cluster")
@@ -3287,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) {
@@ -3299,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")
@@ -3411,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")
@@ -3444,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}`);
@@ -3539,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();
@@ -4302,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 });
@@ -4441,9 +7001,264 @@ program
         console.log(`Souls: ${(data.souls ?? []).length}`);
     }
 });
+// ─── flair migrate-harness-memory ───────────────────────────────────────────
+/** Resolve the memory directory path for a target harness. */
+function resolveMemoryDir(target, agentId) {
+    switch (target) {
+        case "claude-code": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".claude", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".claude", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "openclaw": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".openclaw", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".openclaw", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "pi": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".pi", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".pi", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        default:
+            throw new Error(`Unknown target: ${target}. Valid: claude-code, openclaw, pi`);
+    }
+}
+/** Parse a memory file with YAML frontmatter. */
+function parseMemoryFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n");
+    if (!lines[0].startsWith("---")) {
+        return { meta: {}, body: raw };
+    }
+    let endIdx = 1;
+    while (endIdx < lines.length && !lines[endIdx].startsWith("---")) {
+        endIdx++;
+    }
+    const frontmatterLines = lines.slice(1, endIdx);
+    const bodyLines = lines.slice(endIdx + 1);
+    const yamlContent = frontmatterLines.join("\n");
+    const meta = parseYaml(yamlContent) || {};
+    return {
+        meta: {
+            name: meta.name,
+            description: meta.description,
+            type: meta.type,
+            tags: Array.isArray(meta.tags) ? meta.tags : (meta.tags ? [meta.tags] : []),
+        },
+        body: bodyLines.join("\n").trim(),
+    };
+}
+/** Map memory type to durability. */
+function mapDurability(type) {
+    switch (type) {
+        case "feedback":
+        case "reference":
+            return "permanent";
+        case "project":
+        case "user":
+            return "persistent";
+        default:
+            return "standard";
+    }
+}
+/** Extract keywords from filename for tags. */
+function extractKeywordsFromFilename(filename) {
+    const base = filename.replace(/\.md$/, "");
+    const withoutType = base.replace(/^(feedback|project|reference|user)_/, "");
+    const parts = withoutType.split(/[_-]+/).map(p => p.toLowerCase());
+    const stopwords = new Set(["the", "and", "for", "with", "about", "on", "in", "to", "of", "a", "an"]);
+    return parts.filter(p => p.length > 2 && !stopwords.has(p));
+}
+program
+    .command("migrate-harness-memory")
+    .description("Migrate harness-local memories to Flair")
+    .requiredOption("--target <target>", "Target harness: claude-code, openclaw, pi")
+    .requiredOption("--agent <id>", "Agent ID to write memories under")
+    .option("--dry-run", "Show what would be migrated without writing")
+    .action(async (opts) => {
+    const target = opts.target;
+    const agentId = opts.agent;
+    const dryRun = !!opts.dryRun;
+    let memoryDir;
+    try {
+        memoryDir = resolveMemoryDir(target, agentId);
+    }
+    catch (e) {
+        console.error(`Error resolving memory directory: ${e.message}`);
+        process.exit(1);
+    }
+    if (!existsSync(memoryDir)) {
+        console.error(`Error: Memory directory not found: ${memoryDir}`);
+        process.exit(1);
+    }
+    const migratedDir = join(memoryDir, ".migrated");
+    if (!dryRun) {
+        mkdirSync(migratedDir, { recursive: true, mode: 0o700 });
+    }
+    console.log(`Migrating memories from ${memoryDir} to Flair (agentId=${agentId})`);
+    if (dryRun)
+        console.log("  (DRY RUN - no files will be modified)");
+    const files = readdirSync(memoryDir, { withFileTypes: true })
+        .filter(d => d.isFile() && d.name.endsWith(".md") && d.name !== "MEMORY.md")
+        .map(d => d.name)
+        .sort();
+    if (files.length === 0) {
+        console.log("No memory files found.");
+        return;
+    }
+    console.log(`Found ${files.length} memory file(s) to migrate.`);
+    let successCount = 0;
+    let skipCount = 0;
+    let failCount = 0;
+    for (const filename of files) {
+        const sourcePath = join(memoryDir, filename);
+        const migratedPath = join(migratedDir, filename);
+        if (existsSync(migratedPath)) {
+            console.log(`  ${filename}: already migrated, skipping`);
+            skipCount++;
+            continue;
+        }
+        console.log(`  Processing: ${filename}...`);
+        let parsed;
+        try {
+            parsed = parseMemoryFile(sourcePath);
+        }
+        catch (e) {
+            console.error(`    Failed to parse: ${e.message}`);
+            failCount++;
+            continue;
+        }
+        let type = parsed.meta.type;
+        if (!type) {
+            if (filename.startsWith("feedback_"))
+                type = "feedback";
+            else if (filename.startsWith("project_"))
+                type = "project";
+            else if (filename.startsWith("reference_"))
+                type = "reference";
+            else
+                type = "session";
+        }
+        const durability = mapDurability(type);
+        const tags = [...(parsed.meta.tags || [])];
+        const filenameTags = extractKeywordsFromFilename(filename);
+        for (const t of filenameTags) {
+            if (!tags.includes(t))
+                tags.push(t);
+        }
+        tags.push(type);
+        const content = parsed.body;
+        console.log(`    Type: ${type}, Durability: ${durability}`);
+        console.log(`    Tags: ${tags.join(", ")}`);
+        console.log(`    Content preview: ${content.slice(0, 100)}${content.length > 100 ? "..." : ""}`);
+        if (!dryRun) {
+            console.log(`    Writing to Flair...`);
+            try {
+                const DEFAULT_PORT = 19926;
+                const httpUrl = `http://127.0.0.1:${DEFAULT_PORT}`;
+                const agentKeyId = `${agentId}.key`;
+                const keysDir = join(homedir(), ".flair", "keys");
+                const keyPath = join(keysDir, agentKeyId);
+                let authSuccess = false;
+                if (existsSync(keyPath)) {
+                    const memoryId = `${agentId}-${randomUUID()}`;
+                    const body = {
+                        id: memoryId,
+                        agentId: agentId,
+                        content: content,
+                        type: type,
+                        durability: durability,
+                        tags: tags,
+                        createdAt: new Date().toISOString(),
+                    };
+                    const memoryPath = `/Memory/${memoryId}`;
+                    const res = await authFetch(httpUrl, agentId, keyPath, "PUT", memoryPath, body);
+                    if (res.ok) {
+                        authSuccess = true;
+                        console.log(`    Write to Flair successful (Ed25519 auth)`);
+                    }
+                }
+                if (!authSuccess) {
+                    const adminPass = process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD || "";
+                    if (adminPass) {
+                        const memoryId = `${agentId}-${randomUUID()}`;
+                        const body = {
+                            id: memoryId,
+                            agentId: agentId,
+                            content: content,
+                            type: type,
+                            durability: durability,
+                            tags: tags,
+                            createdAt: new Date().toISOString(),
+                        };
+                        const memoryPath = `/Memory/${memoryId}`;
+                        const auth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+                        const res = await fetch(`${httpUrl}${memoryPath}`, {
+                            method: "PUT",
+                            headers: {
+                                Authorization: auth,
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify(body),
+                            signal: AbortSignal.timeout(10000),
+                        });
+                        if (res.ok) {
+                            console.log(`    Write to Flair successful (Basic auth)`);
+                        }
+                        else {
+                            const text = await res.text();
+                            throw new Error(`HTTP ${res.status}: ${text}`);
+                        }
+                    }
+                    else {
+                        throw new Error("No authentication method available");
+                    }
+                }
+                renameSync(sourcePath, migratedPath);
+                console.log(`    Moved to .migrated/${filename}`);
+            }
+            catch (e) {
+                console.error(`    Failed: ${e.message}`);
+                failCount++;
+                continue;
+            }
+        }
+        else {
+            console.log(`    [dry-run] Would write to Flair and move to .migrated/${filename}`);
+        }
+        successCount++;
+    }
+    console.log(`\nMigration complete:`);
+    console.log(`  Processed: ${files.length}`);
+    console.log(`  Successful: ${successCount}`);
+    console.log(`  Skipped: ${skipCount}`);
+    console.log(`  Failed: ${failCount}`);
+    if (failCount > 0) {
+        process.exit(1);
+    }
+});
 // 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, };
+export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };