@tpsdev-ai/flair 0.15.0 → 0.16.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
 import * as render from "./render.js";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, } from "node:fs";
-import { homedir, hostname, tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
@@ -12,7 +12,7 @@ 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 { fabricUpgrade } from "./fabric-upgrade.js";
-import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { detectClients, 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).
@@ -447,6 +447,117 @@ async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
     }
     throw new Error(`Harper at port ${httpPort} did not respond within ${timeoutMs}ms (${attempt} attempts)`);
 }
+/**
+ * Verify that semantic search ACTUALLY works by storing a memory with a
+ * distinctive phrase and searching for a PARAPHRASE (different words, same
+ * meaning). If embeddings are loaded, the paraphrase recovers the memory by
+ * meaning with a genuine semantic score. If embeddings are NOT loaded,
+ * SemanticSearch falls back to keyword-only scan: the paraphrase shares no
+ * keywords with the stored content, so the memory is NOT recovered (or only via
+ * the `_warning` keyword-fallback marker) → "degraded".
+ *
+ * The probe is authenticated as a real agent (Ed25519) because SemanticSearch
+ * rejects anonymous callers (401) and per-agent scoping requires it. We pick the
+ * given agentId, else FLAIR_AGENT_ID, else the first `.key` in keysDir.
+ *
+ * Exported so the init smoke test and unit tests can reuse the exact same gate.
+ */
+export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
+    // Resolve an agent + key to sign with.
+    let agentId = agentIdOpt || process.env.FLAIR_AGENT_ID || undefined;
+    if (!agentId) {
+        try {
+            const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+            if (keyFiles.length > 0)
+                agentId = keyFiles[0].replace(/\.key$/, "");
+        }
+        catch { /* keysDir missing */ }
+    }
+    if (!agentId) {
+        return { state: "skipped", detail: "no agent id or key found" };
+    }
+    // Find the signing key. Prefer the standard locations (resolveKeyPath), but
+    // fall back to the keysDir we were handed — `flair init` keys live there and
+    // it may not be a standard location (e.g. --keys-dir, tests).
+    let keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        const candidate = join(keysDir, `${agentId}.key`);
+        if (existsSync(candidate))
+            keyPath = candidate;
+    }
+    if (!keyPath) {
+        return { state: "skipped", detail: `no private key for agent '${agentId}'` };
+    }
+    // Distinctive content vs. a PARAPHRASE query with deliberately ZERO shared
+    // content words. If the search recovers the memory it can ONLY be by meaning.
+    //   content: "The feline predator silently stalked its unsuspecting rodent quarry at dusk."
+    //   query:   "a cat hunting a mouse in the evening"
+    // No word in the query appears in the content (cat≠feline, mouse≠rodent,
+    // hunting≠stalked, evening≠dusk), so a keyword scan returns nothing.
+    const marker = `flair-doctor-embed-check-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const id = marker;
+    const content = `The feline predator silently stalked its unsuspecting rodent quarry at dusk. [${marker}]`;
+    const paraphrase = "a cat hunting a mouse in the evening";
+    let stored = false;
+    try {
+        // Write the test memory (ephemeral so it's never durable). PUT /Memory/<id>.
+        const writeRes = await authFetch(baseUrl, agentId, keyPath, "PUT", `/Memory/${id}`, {
+            id, agentId, content, durability: "ephemeral", createdAt: new Date().toISOString(),
+        });
+        if (!writeRes.ok && writeRes.status !== 204) {
+            const text = await writeRes.text().catch(() => "");
+            return { state: "skipped", detail: `could not write probe memory: HTTP ${writeRes.status} ${text.slice(0, 80)}` };
+        }
+        stored = true;
+        // Allow the HNSW index to catch up before searching.
+        await new Promise((r) => setTimeout(r, 1500));
+        // Search by PARAPHRASE. scoring: "raw" so we read the unweighted semantic
+        // similarity (_rawScore) directly, without recency/durability composites
+        // muddying the keyword-vs-semantic distinction.
+        const searchRes = await authFetch(baseUrl, agentId, keyPath, "POST", "/SemanticSearch", {
+            agentId, q: paraphrase, limit: 10, scoring: "raw",
+        });
+        if (!searchRes.ok) {
+            const text = await searchRes.text().catch(() => "");
+            return { state: "skipped", detail: `SemanticSearch failed: HTTP ${searchRes.status} ${text.slice(0, 80)}` };
+        }
+        const data = await searchRes.json();
+        // The server sets _warning ONLY when getMode() === "none" — i.e. the
+        // embedding engine failed to init and the search ran keyword-only. That is
+        // the unambiguous "embeddings not loaded" signal.
+        if (data._warning) {
+            return { state: "degraded", detail: data._warning };
+        }
+        const results = data.results ?? [];
+        const hit = results.find((r) => r.id === id);
+        if (!hit) {
+            // The paraphrase shares no keywords with the content, so a keyword-only
+            // fallback can't find it. Missing the memory == recall-by-meaning is dead.
+            return { state: "degraded", detail: "paraphrase did not recall the probe memory (keyword-only fallback active)" };
+        }
+        // A genuine semantic hit has a positive similarity score. The keyword bonus
+        // is +0.05; since there is no keyword overlap here, any score above that
+        // floor can only come from vector similarity. Require a real semantic score.
+        const score = typeof hit._rawScore === "number" ? hit._rawScore : (hit._score ?? 0);
+        if (score <= 0.05) {
+            return { state: "degraded", detail: `probe recalled with non-semantic score ${score} (keyword/zero)` };
+        }
+        return { state: "ok", score };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { state: "skipped", detail: `probe error: ${message.slice(0, 100)}` };
+    }
+    finally {
+        // Best-effort cleanup of the ephemeral probe memory.
+        if (stored) {
+            try {
+                await authFetch(baseUrl, agentId, keyPath, "DELETE", `/Memory/${id}`);
+            }
+            catch { /* leave the ephemeral row; it'll age out */ }
+        }
+    }
+}
 // Blocks until the given PID is gone (ESRCH from signal 0), or timeout.
 // Used during restart to confirm the old Harper process actually exited before
 // we start polling /Health — otherwise the still-shutting-down old process can
@@ -1231,8 +1342,9 @@ program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── flair init ──────────────────────────────────────────────────────────────
 program
     .command("init")
-    .description("Bootstrap a Flair (Harper) instance for an agent")
+    .description("One-command Flair setup — bootstrap the instance, register an agent, and wire MCP clients")
     .option("--agent-id <id>", "Agent ID to register (omit to bootstrap instance without agent)")
+    .option("--agent <id>", "Alias for --agent-id")
     .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)")
@@ -1241,6 +1353,9 @@ program
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
+    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, all, or none")
+    .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
+    .option("--skip-smoke", "Skip the MCP smoke test")
     .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)")
@@ -1249,7 +1364,7 @@ program
     .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 agentId = opts.agentId ?? opts.agent;
     const target = resolveTarget(opts);
     const opsTarget = resolveOpsTarget(opts);
     // ── Remote init: --target and/or --ops-target drive a remote Flair instance ──
@@ -1426,11 +1541,26 @@ program
         }
         return;
     }
-    // ── Local init (original behavior) ──
+    // ── Local init (full one-command setup) ──
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
+    // Resolve MCP client selection (union of init's auto-wire + the multi-client
+    // detection/wiring that the front-door command provides). `--no-mcp` sets
+    // opts.mcp === false (commander negates the flag). Validate an explicit
+    // --client up front so a typo fails before Harper is touched.
+    const clientOpt = opts.client;
+    const noMcp = opts.mcp === false;
+    const selectedClients = [];
+    if (clientOpt && clientOpt !== "all" && clientOpt !== "none" && !noMcp) {
+        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);
+    }
     // Admin password: determine from opts, env, or generate
     // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
     let adminPass;
@@ -1688,6 +1818,26 @@ program
         if (!verifyRes.ok)
             throw new Error(`Ed25519 auth verification failed: ${verifyRes.status}`);
         console.log("Ed25519 auth verified ✓");
+        // Verify semantic search ACTUALLY works (real embed→paraphrase-search
+        // round-trip). A clean-VM dogfood found semantic search dead out of the box
+        // (sudo/root-owned install can't write the embeddings models symlink →
+        // EACCES) while init reported success. Never report a clean init when
+        // recall-by-meaning is broken. Skipped paths (no key yet) are non-fatal.
+        console.log("Verifying semantic search...");
+        const embedCheck = await verifySemanticSearch(httpUrl, agentId, keysDir);
+        if (embedCheck.state === "ok") {
+            console.log(`Semantic search operational ✓ ${render.wrap(render.c.dim, `(paraphrase recall verified, score ${embedCheck.score.toFixed(2)})`)}`);
+        }
+        else if (embedCheck.state === "degraded") {
+            // LOUD — embeddings not loaded. Same message class as `flair doctor`.
+            console.log(`\n${render.icons.error} ${render.wrap(render.c.red, "Semantic search DEGRADED")} — embeddings not loaded; recall-by-meaning will NOT work.`);
+            console.log(`   ${render.wrap(render.c.dim, `(${embedCheck.detail})`)}`);
+            console.log(`   ${render.wrap(render.c.dim, "Common cause: the embeddings component lacks write access (sudo/root global installs).")}`);
+            console.log(`   ${render.wrap(render.c.dim, "Fix: install without sudo (see README Quick Start), then:")} flair restart && flair doctor`);
+        }
+        else {
+            console.log(`${render.icons.warn} Semantic search not verified ${render.wrap(render.c.dim, `(${embedCheck.detail})`)}`);
+        }
         // Output — admin password printed once, never written to disk
         console.log("\n✅ Flair initialized successfully");
         console.log(`   Agent ID:    ${agentId}`);
@@ -1747,38 +1897,164 @@ program
         }
         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");
+        // ── MCP client wiring ────────────────────────────────────────────────
+        // The full one-command front door: detect installed MCP clients and wire
+        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp` server. Claude
+        // Code is auto-wired into ~/.claude.json (the only client the CLI can
+        // safely modify); other clients get copy-paste snippets. `--no-mcp`
+        // skips wiring entirely; `--client <name>` targets one client; the
+        // default (no flag) wires every detected client.
         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 ✓`);
+        const wiringResults = [];
+        if (!noMcp && clientOpt !== "none") {
+            // Determine which clients to wire.
+            let clients = detectClients();
+            if (selectedClients.length > 0) {
+                clients = clients.filter(c => selectedClients.includes(c.id));
+            }
+            const detected = clients.filter(c => c.detected);
+            if (!clientOpt) {
+                if (detected.length === 0) {
+                    console.log("\n   No MCP clients detected. Run with --client <name> to wire a specific client.");
                 }
                 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   Detected MCP clients: ${detected.map(c => c.label).join(", ")}`);
                 }
             }
-            else {
-                console.log(`\n   MCP config (add to ~/.claude.json):`);
-                console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+            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) {
+                if (clientId === "claude-code") {
+                    // Claude Code gets real auto-wiring into ~/.claude.json (zero-install
+                    // npx form; matches the snippets everywhere else). Other clients only
+                    // get printed instructions — the CLI can't safely edit their configs.
+                    const claudeJsonPath = join(homedir(), ".claude.json");
+                    const flairMcpConfig = {
+                        type: "stdio",
+                        command: "npx",
+                        args: ["-y", "@tpsdev-ai/flair-mcp"],
+                        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(`   ✓ Claude Code already wired in ~/.claude.json`);
+                                wiringResults.push({ client: "claude-code", message: "already wired" });
+                            }
+                            else {
+                                claudeJson.mcpServers = claudeJson.mcpServers || {};
+                                claudeJson.mcpServers.flair = flairMcpConfig;
+                                writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+                                console.log(`   ✓ Claude Code wired in ~/.claude.json (restart Claude Code to pick it up)`);
+                                wiringResults.push({ client: "claude-code", message: "wired ~/.claude.json" });
+                            }
+                        }
+                        else {
+                            console.log(`   MCP config (add to ~/.claude.json):`);
+                            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+                            wiringResults.push({ client: "claude-code", message: "snippet printed (no ~/.claude.json)" });
+                        }
+                    }
+                    catch {
+                        console.log(`   MCP config (add manually to ~/.claude.json):`);
+                        console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+                        wiringResults.push({ client: "claude-code", message: "snippet printed" });
+                    }
+                }
+                else {
+                    let result;
+                    switch (clientId) {
+                        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}`);
+                }
             }
         }
-        catch {
-            console.log(`\n   MCP config (add manually to ~/.claude.json):`);
-            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
+        // ── Smoke-test the MCP server ────────────────────────────────────────
+        // Launch flair-mcp and confirm it answers a JSON-RPC initialize over
+        // stdio. Best-effort: failures warn but never fail the command. Skipped
+        // with --skip-smoke, --no-mcp, --client none, or when nothing was wired.
+        if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
+            console.log("\n   Smoke-testing MCP server...");
+            try {
+                const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                    env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                const initMsg = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "0.1", capabilities: {}, clientInfo: { name: "flair-init", version: "1.0.0" } } });
+                mcpProc.stdin.write(initMsg + "\n");
+                mcpProc.stdin.end();
+                let stdout = "";
+                mcpProc.stdout.on("data", (d) => { stdout += d.toString(); });
+                // A single timer drives the timeout AND cleanup. It MUST be cleared on
+                // settle — an un-cleared setTimeout is a live handle that keeps Node's
+                // event loop alive (the ~60s phantom hang after `flair init` printed
+                // success: the smoke timer + the lingering npx child both pinned the
+                // loop). We clear it on every exit path below.
+                let smokeTimer = null;
+                await new Promise((resolve, reject) => {
+                    const settle = (fn) => {
+                        if (smokeTimer) {
+                            clearTimeout(smokeTimer);
+                            smokeTimer = null;
+                        }
+                        fn();
+                    };
+                    mcpProc.on("exit", (code) => {
+                        settle(() => {
+                            if (code === 0 && stdout.length > 0)
+                                resolve();
+                            else
+                                reject(new Error(`MCP server exited with code ${code}`));
+                        });
+                    });
+                    mcpProc.on("error", (err) => settle(() => reject(err)));
+                    smokeTimer = setTimeout(() => settle(() => { mcpProc.kill("SIGKILL"); reject(new Error("MCP smoke test timed out")); }), 15_000);
+                });
+                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");
+                }
+                finally {
+                    // Reap the child even on the resolve path: the MCP server exits on
+                    // stdin close, but the `npx` wrapper can linger holding the loop.
+                    // SIGKILL is safe — we already have the response we need.
+                    try {
+                        if (mcpProc.exitCode === null)
+                            mcpProc.kill("SIGKILL");
+                    }
+                    catch { /* already gone */ }
+                }
+            }
+            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.");
+            }
         }
     }
     else {
@@ -1802,354 +2078,16 @@ program
         }
         console.log(`\n   Export: FLAIR_URL=${httpUrl}`);
     }
-});
-// ─── 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("--ops-port <port>", "Harper operations API port")
-    .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 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);
-    }
-    // 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, falling back to
-        // the persisted ~/.flair/admin-pass written at first install. Agent
-        // seeding now goes through the ops API (#499), which always requires Basic
-        // admin auth (it does NOT honor authorizeLocal), so a re-run of
-        // `flair install --agent <new-id>` against an already-initialized local
-        // Flair needs a real pass even when no env var is set.
-        adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
-        if (!adminPass) {
-            try {
-                const persisted = join(homedir(), ".flair", "admin-pass");
-                if (existsSync(persisted))
-                    adminPass = readFileSync(persisted, "utf-8").trim();
-            }
-            catch { /* fall through with empty pass */ }
-        }
-    }
-    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 via the Harper operations API. The Agent table is a REST
-        // resource without a POST handler, so the insert body must go to the ops
-        // API (POST <opsUrl>/ with {operation:"insert",...}), NOT the REST root
-        // (which 405s the body as a collection POST to /Agent). This is the same
-        // path `flair agent add` uses. (#499)
-        const seedOpsTarget = opts.opsTarget ?? opsPort;
-        console.log(opts.opsTarget
-            ? `Seeding agent '${agentId}' via operations API (--ops-target)...`
-            : `Seeding agent '${agentId}' via operations API...`);
-        await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, adminUser, 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?"`);
+    // All init work is genuinely done at this point: Harper is installed +
+    // running (detached, unref'd — survives this process exiting), the agent is
+    // registered, semantic search is verified, MCP clients are wired, and the
+    // smoke test ran. The MCP smoke subprocess can leave a lingering npx handle
+    // that pins Node's event loop for ~60s after success ("rc=0 but doesn't
+    // return"). We've cleared/unref'd the known timers above; exit explicitly so
+    // the prompt returns in a couple seconds regardless of any stray handle. The
+    // running Harper instance is unaffected.
+    await new Promise((r) => process.stdout.write("", () => r()));
+    process.exit(0);
 });
 // ─── flair agent ─────────────────────────────────────────────────────────────
 const agent = program.command("agent").description("Manage Flair agents");
@@ -2209,6 +2147,8 @@ agent
     .command("list")
     .description("List all agents")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--agent <id>", "Agent ID to authenticate as via Ed25519 (or FLAIR_AGENT_ID env) when no admin pass")
+    .option("--keys-dir <dir>", "Directory holding the agent's Ed25519 key")
     .option("--port <port>", "Harper HTTP port")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
@@ -2244,13 +2184,39 @@ agent
         agents = await res.json();
     }
     else {
+        // No admin pass → authenticate as the AGENT via Ed25519. The Agent table's
+        // allowRead() is allowVerified — a bare unauthenticated GET /Agent returns
+        // 403 AccessViolation (the dogfood symptom: the natural "did my agent
+        // register?" check errored on a healthy install). A verified agent reads
+        // the principal table for discovery, so sign the request with its key.
         const baseUrl = `http://127.0.0.1:${port}`;
-        const res = await fetch(`${baseUrl}/Agent`, {
-            headers: { "Content-Type": "application/json" },
-        });
+        const agentId = opts.agent ?? process.env.FLAIR_AGENT_ID;
+        const keysDir = opts.keysDir ?? process.env.FLAIR_KEY_DIR ?? defaultKeysDir();
+        let res;
+        if (agentId) {
+            const keyPath = resolveKeyPath(agentId) ?? join(keysDir, `${agentId}.key`);
+            if (!existsSync(keyPath)) {
+                console.error(`${render.icons.error} no key for agent '${agentId}' (looked in ${keysDir}). Pass --admin-pass, --keys-dir, or a registered --agent.`);
+                process.exit(1);
+            }
+            res = await authFetch(baseUrl, agentId, keyPath, "GET", "/Agent");
+        }
+        else {
+            // No agent identity available either. Try anonymously, but if it 403s
+            // (the common case), tell the user exactly how to authenticate rather
+            // than dumping a raw AccessViolation.
+            res = await fetch(`${baseUrl}/Agent`, { headers: { "Content-Type": "application/json" } });
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => "");
-            console.error(`${render.icons.error} ${res.status} ${text}`);
+            if (res.status === 403 && !agentId) {
+                console.error(`${render.icons.error} 403 — listing agents requires authentication.`);
+                console.error(`   Use ${render.wrap(render.c.cyan, "--agent <id>")} (or set FLAIR_AGENT_ID) to authenticate as a registered agent,`);
+                console.error(`   or ${render.wrap(render.c.cyan, "--admin-pass")} / FLAIR_ADMIN_PASS for the admin view.`);
+            }
+            else {
+                console.error(`${render.icons.error} ${res.status} ${text}`);
+            }
             process.exit(1);
         }
         const data = await res.json();
@@ -6718,6 +6684,7 @@ program
     .command("doctor")
     .description("Diagnose common Flair problems and suggest fixes")
     .option("--port <port>", "Harper HTTP port")
+    .option("--agent <id>", "Agent ID to use for the semantic-search round-trip (or FLAIR_AGENT_ID env)")
     .option("--fix", "Automatically fix issues where possible")
     .option("--dry-run", "Show what --fix would do without making changes")
     .action(async (opts) => {
@@ -6880,32 +6847,38 @@ program
     else {
         console.log(`  ${render.icons.warn} No config file at ${render.wrap(render.c.dim, cfgPath)} — using defaults`);
     }
-    // 4. Embeddings check (only if Harper is responding)
+    // 4. Embeddings check — REAL semantic round-trip (only if Harper is responding).
+    //
+    // The dead-simple `{ q: "test" }` probe used to pass even when embeddings were
+    // not loaded: SemanticSearch falls back to keyword-only scan, and an
+    // unauthenticated probe 401s → "cannot verify" → no issue counted. A clean-VM
+    // dogfood found semantic search DEAD out of the box (sudo/root-owned install
+    // can't write the models symlink → EACCES) while `flair doctor` reported
+    // "no issues found". This now stores a memory with a distinctive phrase and
+    // searches for a PARAPHRASE (no shared keywords). If the top result isn't
+    // recovered by MEANING, recall-by-meaning is broken and doctor FAILS LOUDLY.
     if (harperResponding) {
-        try {
-            const testRes = await fetch(`${baseUrl}/SemanticSearch`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ q: "test", limit: 1 }),
-                signal: AbortSignal.timeout(10000),
-            });
-            if (testRes.ok) {
-                const data = await testRes.json();
-                if (data._warning) {
-                    console.log(`  ${render.icons.warn} Embeddings: keyword-only ${render.wrap(render.c.dim, `(${data._warning})`)}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Semantic search quality is degraded")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Check:")} ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
-                    issues++;
-                }
-                else {
-                    console.log(`  ${render.icons.ok} Embeddings: semantic search operational`);
-                }
-            }
-            else if (testRes.status === 401) {
-                console.log(`  ${render.icons.warn} Embeddings: cannot verify ${render.wrap(render.c.dim, "(auth required for SemanticSearch)")}`);
-            }
+        const semanticStatus = await verifySemanticSearch(baseUrl, opts.agent, defaultKeysDir());
+        switch (semanticStatus.state) {
+            case "ok":
+                console.log(`  ${render.icons.ok} Embeddings: semantic search operational ${render.wrap(render.c.dim, `(paraphrase recall verified, score ${semanticStatus.score.toFixed(2)})`)}`);
+                break;
+            case "degraded":
+                // LOUD failure — never report all-clear when recall-by-meaning is dead.
+                console.log(`  ${render.icons.error} Semantic search DEGRADED ${render.wrap(render.c.dim, `— ${semanticStatus.detail}`)}`);
+                console.log(`     ${render.wrap(render.c.red, "Embeddings are not loaded; recall-by-meaning will NOT work.")}`);
+                console.log(`     ${render.wrap(render.c.dim, "Common cause: the embeddings component lacks write access (sudo/root global installs).")}`);
+                console.log(`     ${render.wrap(render.c.dim, "See:")} docs/troubleshooting.md ${render.wrap(render.c.dim, "→ \"Semantic search DEGRADED\"")}`);
+                issues++;
+                break;
+            case "skipped":
+                // Could not run the round-trip (no agent / no key). Don't claim
+                // all-clear — surface that the check was skipped, but don't count it
+                // as a hard issue since the user may simply not have an agent yet.
+                console.log(`  ${render.icons.warn} Embeddings: not verified ${render.wrap(render.c.dim, `(${semanticStatus.detail})`)}`);
+                console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (or set FLAIR_AGENT_ID) so doctor can run a real semantic round-trip.")}`);
+                break;
         }
-        catch { /* fetch error, already flagged */ }
     }
     // 5. Stale PID file (skip if already reported in port check)
     const dataDir = defaultDataDir();