@tpsdev-ai/flair 0.20.0 → 0.21.0

package/dist/cli.js

@@ -12,7 +12,9 @@ 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, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { checkVersion, formatVersionNudge } from "./version-check.js";
+import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, } from "./doctor-client.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).
@@ -35,6 +37,39 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
+// Per-record principalId (federation-edge-hardening slice 3a) — INFORMATIONAL
+// only; the receiver (resources/Federation.ts) never treats it as verified
+// identity or uses it in any auth decision. Sourced from the write-time
+// provenance stamp (memory-provenance slice 1, Memory.ts's buildProvenance)
+// when present. `provenance` is persisted as a JSON STRING (not an object),
+// so it must be parsed — a raw `row.provenance?.verified?.agentId` would
+// silently always be undefined. Soul/Agent/Relationship rows never carry a
+// provenance stamp today, so this is a no-op for them.
+function principalIdFromRow(row) {
+    if (typeof row?.provenance !== "string" || row.provenance.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(row.provenance)?.verified?.agentId ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Federation push private-visibility filter — inlined for the SAME reason as
+// the crypto helpers above (see comment there; also resources/memory-
+// visibility.ts, the canonical definition; the two must stay in sync).
+//
+// federation-edge-hardening slice 2 (the office-visibility read leak: one rule, one place): the
+// push side of federation sync (runFederationSyncOnce below) must exclude
+// `private` Memory rows from what gets sent to peers, using the EXACT same
+// "not private" semantics as resources/memory-read-scope.ts's resolveReadScope()
+// — a record with NO visibility field (legacy, pre-dates the field) is NOT
+// private and must keep syncing exactly as before. Only `visibility ===
+// "private"` is excluded; null/undefined/"shared"/anything else is included.
+const FEDERATION_PRIVATE_VISIBILITY = "private";
+function isFederationPrivateVisibility(visibility) {
+    return visibility === FEDERATION_PRIVATE_VISIBILITY;
+}
 // ─── Secret detection helpers ────────────────────────
 /**
  * Check if a value looks like a real secret/password/token.
@@ -113,6 +148,38 @@ export function readAdminPassFileSecure(path) {
     }
     return content;
 }
+function defaultAdminPassPath() {
+    return join(homedir(), ".flair", "admin-pass");
+}
+/**
+ * Resolve an admin password for LOCAL-only CLI convenience (`agent add`,
+ * `principal add`) without requiring `--admin-pass` on every call (#590).
+ *
+ * Resolution order: explicit value (the `--admin-pass` flag) → `FLAIR_ADMIN_PASS`
+ * env → the secure `~/.flair/admin-pass` file `flair init` already writes with
+ * mode 0600 (read via `readAdminPassFileSecure`, which enforces that mode).
+ *
+ * When `isRemoteTarget` is true, ONLY the explicit value is honored — the env
+ * and file legs are skipped entirely. This is the security-critical guard: a
+ * `--target`/`--ops-target` deploy must never silently reuse THIS machine's
+ * local admin secret against someone else's Harper instance. Remote callers
+ * keep requiring an explicit `--admin-pass`.
+ *
+ * Throws (via readAdminPassFileSecure) if the file exists but has unsafe
+ * permissions, so a misconfigured file surfaces as an actionable chmod error
+ * instead of a generic "admin pass required" message.
+ */
+function resolveLocalAdminPass(explicit, isRemoteTarget = false, adminPassPath = defaultAdminPassPath()) {
+    if (explicit)
+        return explicit;
+    if (isRemoteTarget)
+        return undefined;
+    if (process.env.FLAIR_ADMIN_PASS)
+        return process.env.FLAIR_ADMIN_PASS;
+    if (!existsSync(adminPassPath))
+        return undefined;
+    return readAdminPassFileSecure(adminPassPath);
+}
 function defaultKeysDir() {
     return join(homedir(), ".flair", "keys");
 }
@@ -558,6 +625,90 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         }
     }
 }
+// ─── Doctor: client-integration network checks (flair#588) ────────────────────
+//
+// The pure filesystem checks (MCP block parsing, CLAUDE.md, SessionStart hook)
+// live in src/doctor-client.ts. These two are network-dependent and live here
+// because they reuse authFetch/resolveKeyPath, which are private to this file.
+/**
+ * Quick, offline-tolerant reachability probe for a Flair instance's HTTP
+ * endpoint — GETs /Health with a short timeout. Never hangs, never throws:
+ * any failure (timeout, DNS, connection refused, bad URL) is "unreachable".
+ * Mirrors the doctor action's own probePort helper (3000ms AbortSignal.timeout
+ * style), but takes a full URL since client configs point at arbitrary hosts.
+ */
+export async function probeFlairReachable(url, timeoutMs = 2000) {
+    try {
+        const res = await fetch(`${url.replace(/\/+$/, "")}/Health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return res.status > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is `agentId` actually registered on the Flair instance at `baseUrl`? Signs
+ * GET /Agent/:id with the agent's own key (same pattern as the `flair init`
+ * verification at line ~2043 and `flair agent rotate` at line ~2596) —
+ * reuses authFetch/resolveKeyPath rather than duplicating the signing logic.
+ *
+ *   200            -> "registered"
+ *   401/403 carrying the server's "unknown_agent" signal -> "not-registered"
+ *     (see below — this is the actual live behavior for a missing agent, NOT
+ *     404)
+ *   any other status, or a network error/timeout -> "unreachable" (could not
+ *     verify one way or the other — e.g. a bare 401/403/500 doesn't tell us
+ *     whether the agent exists, so we don't claim NOT registered on those)
+ *   no local key found for agentId (checked resolveKeyPath, then keysDir) -> "no-key"
+ *     (can't sign the request at all — distinct from "unreachable" so the
+ *     caller can print an accurate reason)
+ *
+ * Why not 404: an unregistered agent never actually reaches the /Agent/:id
+ * resource handler (which is where a 404 would come from) — Flair's own
+ * signed-auth middleware (resources/auth-middleware.ts) rejects the request
+ * first, once it can't find an Agent record matching the signing identity.
+ * On current main that's an explicit `401 {"error":"unknown_agent"}` — Live-
+ * verified 2026-07-07 against a local Flair instance with a resolvable-but-
+ * unregistered signing key: `401 Unauthorized`, body `{"error":"unknown_agent"}`.
+ * Some server versions/paths may instead surface Harper's native
+ * AccessViolation as a 403 for the same condition, so both codes are checked
+ * — but ONLY when the response also carries the unknown-agent marker; a bare
+ * 401/403 without it (e.g. a real AccessViolation for an agent that exists
+ * but fails a resource-level authorization check) stays "unreachable", since
+ * the server can't always distinguish "agent doesn't exist" from "signing key
+ * doesn't match a known agent" and we don't want to falsely claim
+ * not-registered on that ambiguity. We only make the not-registered call
+ * because we ALREADY have a local signing key that resolved for this
+ * agentId (checked above) — so this isn't a client-side key problem, and the
+ * server naming the agent unknown is a reliable, actionable signal.
+ */
+export async function checkAgentRegistered(baseUrl, agentId, keysDir) {
+    let keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        const candidate = join(keysDir, `${agentId}.key`);
+        if (existsSync(candidate))
+            keyPath = candidate;
+    }
+    if (!keyPath) {
+        return { state: "no-key", detail: `no local key for agent '${agentId}' to sign the check` };
+    }
+    try {
+        const res = await authFetch(baseUrl, agentId, keyPath, "GET", `/Agent/${agentId}`);
+        if (res.ok)
+            return { state: "registered" };
+        if (res.status === 404)
+            return { state: "not-registered" };
+        const text = await res.text().catch(() => "");
+        if ((res.status === 401 || res.status === 403) && /unknown_agent/i.test(text)) {
+            return { state: "not-registered", detail: `HTTP ${res.status} ${text.slice(0, 80)}` };
+        }
+        return { state: "unreachable", detail: `HTTP ${res.status} ${text.slice(0, 80)}` };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { state: "unreachable", detail: `instance unreachable: ${message.slice(0, 100)}` };
+    }
+}
 // 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
@@ -689,7 +840,7 @@ export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId,
         throw new Error(`Federation Instance insert via ops API failed (${res.status}): ${text}`);
     }
 }
-// ─── Provision Flair on Harper Fabric (ops-2kyi) ───────────────────────────
+// ─── Provision Flair on Harper Fabric ──────────────────────────────────────
 //
 // Atomic provisioning for a fresh Harper Fabric cluster: builds a deploy
 // tarball with .env baked in, deploys via ops API, waits for restart, and
@@ -782,7 +933,7 @@ export async function provisionFabric(target, opsTarget, clusterAdminUser, clust
     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".
+    // Since custom-admin-username support 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;
@@ -1161,7 +1312,7 @@ export function probeOpenclawPluginVersion(extensionName) {
 /**
  * Whether a package's status line should be printed in the default `flair
  * upgrade` listing. Suppresses optional-because-openclaw-is-absent lines
- * (ops-p42n) — pure noise on machines without openclaw — unless `--all`
+ * — pure noise on machines without openclaw — unless `--all`
  * (showAll) is set. All other statuses always print.
  */
 export function shouldPrintUpgradeLine(status, showAll) {
@@ -1367,6 +1518,8 @@ program
     .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("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
+    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code only)")
     .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)")
@@ -1906,8 +2059,6 @@ program
             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.`);
         // ── 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
@@ -1976,6 +2127,30 @@ program
                         console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
                         wiringResults.push({ client: "claude-code", message: "snippet printed" });
                     }
+                    // ── CLAUDE.md bootstrap line (flair#597) ──────────────────────────
+                    // The MCP block alone isn't a working setup — Claude Code also needs
+                    // the bootstrap instruction in CLAUDE.md, or it never calls
+                    // mcp__flair__bootstrap and memory silently does nothing. Applied
+                    // automatically here (same "just do it" shape as the MCP block
+                    // above); --skip-claude-md opts out and prints the exact line to
+                    // add by hand instead.
+                    const claudeMdResult = applyOrReportClaudeMdBootstrap(process.cwd(), homedir(), !!opts.skipClaudeMd);
+                    console.log(`   ${claudeMdResult.ok ? "✓" : "•"} ${claudeMdResult.message}`);
+                    if (claudeMdResult.hint) {
+                        for (const line of claudeMdResult.hint.split("\n"))
+                            console.log(`   ${line}`);
+                    }
+                    // ── SessionStart hook (flair#597) ─────────────────────────────────
+                    // Auto-recall on session start needs this hook wired into
+                    // ~/.claude/settings.json — without it, mcp__flair__bootstrap only
+                    // ever runs if the agent remembers to call it itself.
+                    // --skip-hook opts out and prints the exact JSON to add by hand.
+                    const hookResult = applyOrReportSessionStartHook(homedir(), agentId, !!opts.skipHook);
+                    console.log(`   ${hookResult.ok ? "✓" : "•"} ${hookResult.message}`);
+                    if (hookResult.hint) {
+                        for (const line of hookResult.hint.split("\n"))
+                            console.log(`   ${line}`);
+                    }
                 }
                 else {
                     let result;
@@ -2116,7 +2291,6 @@ agent
     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;
     // Where to seed the Agent record. Default is localhost (opsPort). When
@@ -2124,8 +2298,27 @@ agent
     // (#514 — agent add could only ever hit localhost ops). Precedence matches
     // `flair import`: explicit --ops-target > derive from --target > localhost.
     const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.target, opsTarget: opts.opsTarget }) ?? opsPort;
+    const isRemoteTarget = typeof seedOpsTarget === "string";
+    // #590 — local convenience fallback: FLAIR_ADMIN_PASS env, then the secure
+    // ~/.flair/admin-pass file `flair init` already writes (mode 0600). Never
+    // applied for a remote target — see resolveLocalAdminPass.
+    let adminPass;
+    try {
+        adminPass = resolveLocalAdminPass(opts.adminPass, isRemoteTarget);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     if (!adminPass) {
-        console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table)");
+        if (isRemoteTarget) {
+            console.error("Error: --admin-pass is required for agent add when targeting a remote instance " +
+                "(--target/--ops-target) — the local ~/.flair/admin-pass fallback is not used for remote targets.");
+        }
+        else {
+            console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table). " +
+                "Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
+        }
         process.exit(1);
     }
     mkdirSync(keysDir, { recursive: true });
@@ -2501,15 +2694,26 @@ principal
     .action(async (id, opts) => {
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
-    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS;
     const adminUser = DEFAULT_ADMIN_USER;
     const kind = opts.kind ?? "agent";
     const name = opts.name ?? id;
     const isAdmin = opts.admin ?? false;
     const trustTier = opts.trust ?? (isAdmin ? "endorsed" : "unverified");
     const runtime = opts.runtime;
+    // #590 — same local-only fallback as `agent add`: FLAIR_ADMIN_PASS env, then
+    // the secure ~/.flair/admin-pass file (mode 0600). `principal add` has no
+    // --target/--ops-target (always localhost), so the fallback always applies.
+    let adminPass;
+    try {
+        adminPass = resolveLocalAdminPass(opts.adminPass);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     if (!adminPass) {
-        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required (or ensure ~/.flair/admin-pass exists, " +
+            "created by `flair init`)");
         process.exit(1);
     }
     // Generate Ed25519 keypair (agents always get one; humans get one for instance-attestation)
@@ -3662,15 +3866,54 @@ export async function runFederationSyncOnce(opts) {
                 }
                 const batch = await res.json();
                 // For null-updatedAt rows, use createdAt as the effective timestamp.
-                // Skip rows created before the last sync cursor.
-                rows = rows.concat(batch.filter((r) => r.updatedAt !== null || r.createdAt > since));
+                // Skip rows created before the last sync cursor. Only Memory carries
+                // a `visibility` field (Soul/Agent/Relationship don't — see
+                // schemas/memory.graphql vs agent.graphql), so the private-exclusion
+                // filter only applies there; on the other 3 tables `row.visibility`
+                // is always undefined, which isFederationPrivateVisibility() treats
+                // as non-private (included) — a no-op for them.
+                rows = rows.concat(batch
+                    .filter((r) => r.updatedAt !== null || r.createdAt > since)
+                    .filter((r) => table !== "Memory" || !isFederationPrivateVisibility(r.visibility)));
             }
             if (rows.length === 0)
                 continue;
+            // Records are signed (below) before they're batched, so the secret key
+            // is needed here rather than only inside sendBatch. Still deferred
+            // until we know THIS table has rows to send — preserves the "don't
+            // load the key on a no-op run" property the original lazy load had.
+            if (!secretKey)
+                secretKey = await loadInstanceSecretKey(instance.id, opts);
             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 updatedAt = row.updatedAt ?? row.createdAt;
+                const originatorInstanceId = instance.id;
+                // Per-record signature (federation-edge-hardening slice 3a): signed by
+                // THIS instance — the originator — over a versioned canonical form, so
+                // a receiver (including a hub relaying this record onward to other
+                // spokes) can verify authorship independent of who forwarded the
+                // batch. Closes the hub-relay forgery hole — see
+                // resources/Federation.ts FederationSync.post's verification gate.
+                //
+                // CONTRACT — must match Federation.ts's verification payload
+                // byte-for-byte: keys { v, table, id, data, updatedAt,
+                // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
+                // doesn't matter, but the field SET and values do. `v: 1` versions the
+                // canonical form itself: bump it on BOTH sides together if the signed
+                // field set ever changes, so an old signature fails closed instead of
+                // silently mis-verifying under a new form.
+                //
+                // Additive/backward-compatible: pre-3a receivers don't read
+                // `signature`/`principalId` at all and merge exactly as before.
+                const signature = signBody({ v: 1, table, id: row.id, data: row, updatedAt, originatorInstanceId }, secretKey);
+                const sr = { table, id: row.id, data: row, updatedAt, originatorInstanceId, signature };
+                // Informational only (see principalIdFromRow) — never verified by the
+                // receiver as proof of authorship. Omitted entirely when the row
+                // carries no write-time provenance stamp.
+                const principalId = principalIdFromRow(row);
+                if (principalId)
+                    sr.principalId = principalId;
                 const srBytes = JSON.stringify(sr).length;
                 if (batch.length >= BUDGET_RECORDS || (batch.length > 0 && batchBytes + srBytes > BUDGET_BYTES)) {
                     const result = await sendBatch(batch);
@@ -3721,7 +3964,7 @@ export async function runFederationSyncOnce(opts) {
             console.warn(`⚠️  Local hub.lastSyncAt advance error: ${advErr?.message ?? advErr}. Next poll will re-send memories.`);
         }
         if (totalBatches === 0) {
-            // ops-c7t9: no-change syncs must still ping the hub so it updates the
+            // No-change syncs must still ping the hub so it updates the
             // spoke's lastSyncAt (liveness). Without this, idle-but-alive spokes
             // look indistinguishable from dead ones on the hub dashboard.
             try {
@@ -4964,7 +5207,7 @@ function oauthDetailLines(o) {
 }
 // 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.
+// config-vs-daemon port drift. Order is ad-hoc — first hit wins.
 //
 // 9926: original default (long-running early installs predate the bump)
 // 19926: current default (DEFAULT_PORT)
@@ -5081,16 +5324,23 @@ const statusCmd = program
     .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
+    // config-vs-daemon port drift. 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);
     }
+    // Version-behind check (flair#587) — offline-tolerant + cached, so this
+    // never adds meaningful latency or fails `status` when the registry is
+    // unreachable. Independent of Harper health; runs either way.
+    const versionCheckResult = await checkVersion(__pkgVersion);
+    const versionNudge = formatVersionNudge(versionCheckResult);
     if (opts.json) {
         const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...healthData };
         if (discoveredPort != null)
             out.discoveredPort = discoveredPort;
+        if (versionCheckResult.latest)
+            out.latestVersion = versionCheckResult.latest;
         console.log(JSON.stringify(out, null, 2));
         if (!healthy)
             process.exit(1);
@@ -5110,6 +5360,10 @@ const statusCmd = program
         else {
             console.log(`\n  Run: flair start  or  flair doctor`);
         }
+        if (versionNudge) {
+            const color = versionNudge.severity === "red" ? render.c.red : render.c.yellow;
+            console.log(`\n  ${render.wrap(color, "⚠")} ${render.wrap(color, versionNudge.message)}`);
+        }
         process.exit(1);
     }
     const uptimeSec = healthData?.uptimeSeconds;
@@ -5162,6 +5416,10 @@ const statusCmd = program
     const metaParts = [pidPart, uptimePart].filter(Boolean).join(render.wrap(render.c.dim, " · "));
     console.log(`${versionStr} ${render.wrap(render.c.dim, "—")} ${runStatus}${metaParts ? `  ${metaParts}` : ""}`);
     console.log(render.kv("URL", baseUrl));
+    if (versionNudge) {
+        const color = versionNudge.severity === "red" ? render.c.red : render.c.yellow;
+        console.log(`\n  ${render.wrap(color, "⚠")} ${render.wrap(color, versionNudge.message)}`);
+    }
     if (scopedWarnings.length > 0) {
         console.log(`\n${render.wrap(render.c.bold, "Warnings")}  ${render.wrap(render.c.dim, `(${scopedWarnings.length})`)}`);
         for (const w of scopedWarnings) {
@@ -5884,7 +6142,7 @@ program
             kind: "bin",
             // Older flair-mcp installs (e.g. 0.10.0) either aren't on PATH or
             // don't support `--version`, so the bin probe returns null even when
-            // the package IS globally installed (ops-p42n). Fall back to the lib
+            // the package IS globally installed. Fall back to the lib
             // probe, which require.resolves the package.json from a sibling global
             // install regardless of PATH or --version support. kind stays "bin" so
             // it remains npm-upgradeable (npm install -g), not the openclaw path.
@@ -5927,7 +6185,7 @@ program
             }
             findings.push({ name, installed, latest, status, kind });
             // Suppress the line for openclaw plugins that are optional-because-
-            // openclaw-is-absent (ops-p42n): on machines without openclaw the
+            // openclaw-is-absent: on machines without openclaw the
             // "○ … not installed (openclaw not detected) → … (install via …)"
             // line is pure noise. Still print it when openclaw IS installed
             // (current/outdated) or under --all.
@@ -5946,7 +6204,7 @@ program
         }
         catch { /* skip unavailable packages */ }
     }
-    // Scope footer (ops-p42n): make explicit what `flair upgrade` does and
+    // Scope footer: make explicit what `flair upgrade` does and
     // doesn't cover, so "were the others checked?" has a one-line answer.
     console.log("\nScope: npm-global packages (flair, flair-mcp) + openclaw plugins. Other integrations (pi-flair, langgraph-flair, n8n-nodes-flair, hermes-flair) upgrade in their own ecosystems (pi / pip / n8n).");
     const outdated = findings.filter((f) => f.status === "outdated");
@@ -6648,9 +6906,17 @@ program
     .option("--no-restart", "Do not restart the component after deploy (default: restart=true)")
     .option("--dry-run", "Resolve package, validate args, skip the deploy call")
     .option("--package-root <dir>", "Override package root (mainly for testing)")
+    .option("--deployment-timeout <ms>", "Milliseconds harper waits for cluster-wide peer replication (env: FABRIC_DEPLOYMENT_TIMEOUT; default: 600000 — harper's own 120s default is too short for Fabric)")
+    .option("--install-timeout <ms>", "Milliseconds harper waits for package install (env: FABRIC_INSTALL_TIMEOUT; default: 600000)")
+    .option("--no-verify", "Skip post-deploy served-API verification (default: verify — on by design, so the CLI can't report success on an empty/broken deploy)")
+    .option("--verify-timeout <ms>", "Milliseconds to wait for the served API to settle after harper's post-deploy restart before verifying (default: 300000)")
+    .option("--verify-resource <name>", "Resource to verify is serving after deploy (repeatable; default: derived from the deployed package's dist/resources)", (val, prev) => [...prev, val], [])
+    .option("--deploy-retries <n>", "Retry the full harper deploy this many times on a detected flaky peer-replication failure ONLY — a normal deploy failure (auth, bad package, ...) never retries (default: 2; 0 disables)", "2")
+    .option("--ignore-replication-errors", "If peer replication is still failing once retries are exhausted, treat it as a non-fatal warning and succeed with an origin-only deploy (the peer catches up via federation sync or a later deploy)")
     .action(async (opts) => {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
+    const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
     const dim = (s) => `\x1b[2m${s}\x1b[0m`;
     const deployOpts = {
         fabricOrg: opts.fabricOrg ?? process.env.FABRIC_ORG,
@@ -6665,6 +6931,14 @@ program
         restart: opts.restart !== false,
         dryRun: opts.dryRun ?? false,
         packageRoot: opts.packageRoot,
+        deploymentTimeoutMs: Number(opts.deploymentTimeout ?? process.env.FABRIC_DEPLOYMENT_TIMEOUT ?? 600_000),
+        installTimeoutMs: Number(opts.installTimeout ?? process.env.FABRIC_INSTALL_TIMEOUT ?? 600_000),
+        verify: opts.verify !== false,
+        verifyResources: opts.verifyResource?.length ? opts.verifyResource : undefined,
+        verifyTimeoutMs: Number(opts.verifyTimeout ?? 300_000),
+        deployRetries: Number(opts.deployRetries ?? 2),
+        ignoreReplicationErrors: opts.ignoreReplicationErrors ?? false,
+        onProgress: (msg) => console.log(dim(`  ${msg}`)),
     };
     const errors = validateDeployOptions(deployOpts);
     if (errors.length) {
@@ -6689,7 +6963,12 @@ program
             console.log(dim(`  package root: ${result.packageRoot}`));
             return;
         }
-        console.log(`\n${green("✓")} Flair ${result.version} deployed`);
+        if (result.replicationWarning) {
+            console.log(`\n${yellow("⚠")} Flair ${result.version} deployed to the ORIGIN NODE ONLY — peer replication did not complete (see warning above). The peer will catch up via federation sync or a later deploy.`);
+        }
+        else {
+            console.log(`\n${green("✓")} Flair ${result.version} deployed${deployOpts.verify ? " and verified serving" : ""}`);
+        }
         console.log(`\n  URL:     ${result.url}`);
         console.log(`  Project: ${result.project}`);
         console.log(`\nNext steps:`);
@@ -6703,6 +6982,15 @@ program
         if (hint?.includes("401") || hint?.includes("unauthoriz")) {
             console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
         }
+        if (hint?.includes("component is not serving")) {
+            console.error(dim("  hint: harper reported success but the served API disagrees — check the Fabric Studio component logs for the real deploy error, then retry"));
+        }
+        if (hint?.includes("did not settle")) {
+            console.error(dim("  hint: Harper may still be restarting — check Fabric Studio, or retry with a longer --verify-timeout"));
+        }
+        if (hint?.includes("peer replication failed after")) {
+            console.error(dim("  hint: pass --ignore-replication-errors to accept an origin-only deploy, or re-run once the peer link recovers"));
+        }
         process.exit(1);
     }
 });
@@ -6726,6 +7014,24 @@ program
     let issues = 0;
     let harperResponding = false;
     console.log(`\n${render.wrap(render.c.bold, "🩺 Flair Doctor")}\n`);
+    // 0. Version check (flair#587) — offline-tolerant + cached, independent
+    // of Harper being up. A gap of ≥2 minor versions (or any major) is
+    // treated as loud/red — heuristic for "likely missed a security fix"
+    // since we don't have advisory data, only the version gap. A red gap
+    // counts as an issue (exit 1); a quieter yellow gap (one minor, or
+    // patch-only) is printed but doesn't fail doctor.
+    const versionCheckResult = await checkVersion(__pkgVersion);
+    const versionNudge = formatVersionNudge(versionCheckResult);
+    if (versionNudge) {
+        const color = versionNudge.severity === "red" ? render.c.red : render.c.yellow;
+        const icon = versionNudge.severity === "red" ? render.wrap(render.c.red, "✗") : render.icons.warn;
+        console.log(`  ${icon} ${render.wrap(color, versionNudge.message)}`);
+        if (versionNudge.severity === "red")
+            issues++;
+    }
+    else if (versionCheckResult.latest) {
+        console.log(`  ${render.icons.ok} flair ${__pkgVersion} is current`);
+    }
     // Helper: try to reach Harper on a given port
     async function probePort(p) {
         try {
@@ -6952,6 +7258,150 @@ program
             issues++;
         }
     }
+    // 7. Client integration (flair#588) — the first 6 checks diagnose the
+    // SERVER side. This diagnoses whether Flair is actually wired to a real
+    // MCP client (Claude Code, Codex, Gemini, Cursor): the MCP block present
+    // + reachable + the configured agent genuinely registered (every detected
+    // client), plus CLAUDE.md + the SessionStart hook (Claude Code only,
+    // since only Claude Code has those mechanisms). Reuses detectClients()
+    // rather than reimplementing client detection.
+    console.log(`\n  ${render.wrap(render.c.bold, "Client integration")}`);
+    // Prompt y/N before a content-editing fix, but only when interactive —
+    // in a non-TTY context (CI, scripts) --fix itself is the consent signal,
+    // matching how doctor's other --fix branches already behave unprompted.
+    // Mirrors the confirm pattern at `flair fabric upgrade` (~line 6258).
+    async function confirmFix(question) {
+        if (!process.stdin.isTTY)
+            return true;
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((res) => rl.question(question, (a) => { rl.close(); res(a); }));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    const detectedClients = detectClients().filter((c) => c.detected);
+    if (detectedClients.length === 0) {
+        console.log(`  ${render.icons.info} No MCP client detected — skipping client-integration checks`);
+    }
+    else {
+        let claudeCodeAgentId;
+        let anyKnownAgentId;
+        for (const client of detectedClients) {
+            const block = readClientMcpBlock(client.id, homedir());
+            if (client.id === "claude-code" && block.agentId)
+                claudeCodeAgentId = block.agentId;
+            if (block.agentId)
+                anyKnownAgentId = anyKnownAgentId ?? block.agentId;
+            if (!block.present) {
+                console.log(`  ${render.icons.error} ${client.label}: no Flair MCP server configured in ${render.wrap(render.c.dim, block.configPath)}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would wire")} ${client.label} (writes ${block.configPath})`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Wire ${client.label} now? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId;
+                            if (!fixAgentId) {
+                                console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent id known — pass --agent <id>`);
+                            }
+                            else {
+                                const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: block.flairUrl || baseUrl };
+                                const wireResult = client.id === "claude-code" ? wireClaudeCode(wireEnv) :
+                                    client.id === "codex" ? wireCodex(wireEnv) :
+                                        client.id === "gemini" ? wireGemini(wireEnv) :
+                                            wireCursor(wireEnv);
+                                console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
+                            }
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
+                }
+                issues++;
+                continue;
+            }
+            console.log(`  ${render.icons.ok} ${client.label}: MCP server configured (${render.wrap(render.c.dim, block.configPath)})`);
+            const reachable = await probeFlairReachable(block.flairUrl);
+            if (!reachable) {
+                console.log(`     ${render.icons.warn} FLAIR_URL ${render.wrap(render.c.dim, block.flairUrl)} not reachable — cannot verify agent registration`);
+                continue;
+            }
+            console.log(`     ${render.icons.ok} FLAIR_URL ${render.wrap(render.c.dim, block.flairUrl)} reachable`);
+            const reg = await checkAgentRegistered(block.flairUrl, block.agentId, defaultKeysDir());
+            if (reg.state === "registered") {
+                console.log(`     ${render.icons.ok} agent '${block.agentId}' registered`);
+            }
+            else if (reg.state === "not-registered") {
+                console.log(`     ${render.icons.error} agent '${block.agentId}' is NOT registered on this Flair instance`);
+                console.log(`        ${render.wrap(render.c.dim, "Fix:")} flair agent add ${block.agentId}`);
+                issues++;
+            }
+            else {
+                console.log(`     ${render.icons.warn} could not verify agent registration ${render.wrap(render.c.dim, `(${reg.detail})`)}`);
+            }
+        }
+        // Claude-Code-specific: CLAUDE.md + SessionStart hook. Only Claude Code
+        // has these mechanisms, so only run them when claude-code was detected.
+        if (detectedClients.some((c) => c.id === "claude-code")) {
+            const claudeMd = checkClaudeMdBootstrap(process.cwd(), homedir());
+            if (claudeMd.present) {
+                console.log(`  ${render.icons.ok} CLAUDE.md: bootstrap instruction present (${render.wrap(render.c.dim, claudeMd.path)})`);
+            }
+            else {
+                console.log(`  ${render.icons.error} CLAUDE.md: bootstrap instruction not found (checked ${render.wrap(render.c.dim, join(process.cwd(), "CLAUDE.md"))} and ${render.wrap(render.c.dim, join(homedir(), ".claude", "CLAUDE.md"))})`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would append bootstrap instruction to")} ${join(process.cwd(), "CLAUDE.md")}`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Add the Flair bootstrap line to ./CLAUDE.md? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixRes = fixClaudeMdBootstrap(process.cwd());
+                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the mcp__flair__bootstrap line to ./CLAUDE.md)")}`);
+                }
+                issues++;
+            }
+            const hook = checkSessionStartHook(homedir());
+            if (hook.present) {
+                console.log(`  ${render.icons.ok} SessionStart hook: flair-session-start wired in ${render.wrap(render.c.dim, hook.path)}`);
+            }
+            else {
+                console.log(`  ${render.icons.error} SessionStart hook: not found in ${render.wrap(render.c.dim, hook.path)}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would add SessionStart hook to")} ${hook.path}`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Add the flair-session-start SessionStart hook to ${hook.path}? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
+                            const fixRes = fixSessionStartHook(homedir(), fixAgentId);
+                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the flair-session-start SessionStart hook)")}`);
+                }
+                issues++;
+            }
+        }
+    }
     // Summary
     console.log("");
     if (issues === 0) {
@@ -6965,7 +7415,7 @@ program
         process.exit(1);
 });
 // ─── flair session snapshot ──────────────────────────────────────────────────
-// Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B (ops-9wji-B / ops-ojht). Snapshot a
+// Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B. 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
@@ -7120,10 +7570,10 @@ 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("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
-    .option("--visibility <value>", "Writer-controlled sharing intent (sets Memory.visibility): 'private' (owner-only, never visible to a grant-holder) or 'shared' (visible to owner + any agent holding a read/search MemoryGrant). Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private (flair#509, ops-2dm3)")
+    .option("--visibility <value>", "Writer-controlled sharing intent (sets Memory.visibility): 'private' (owner-only, never visible to any other agent) or 'shared' (visible to owner + every other agent on this instance — open within the org, not gated by a MemoryGrant). Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private (flair#509)")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {
@@ -7149,7 +7599,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
     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
+// Slice 1 of FLAIR-AGENT-CONTEXT-TIERS-B. 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.
@@ -7166,7 +7616,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
 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("--beads <ops-id>", "Bead/PR/task identifier this summary is about")
     .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)")
@@ -7362,7 +7812,7 @@ memory.command("list")
 });
 // ─── flair memory hygiene ────────────────────────────────────────────────────
 // Detect + remove junk memory rows that accumulate over time. Surfaced from
-// the 2026-05-07 manual cleanup (ops-ucyy): an instance had 627 records, ~250 of
+// a 2026-05-07 manual cleanup: an instance had 627 records, ~250 of
 // them were noise — `*-compact-*` ID fragments from an old pipeline, pangram
 // test content ("the quick brown fox..." / "Flair 251 test ..."), and
 // near-empty rows (<25 chars). We did the cleanup ad-hoc with raw curl + jq;
@@ -7377,8 +7827,8 @@ memory.command("list")
 // Default is all three, dry-run. Flip --apply to actually delete. Always
 // requires admin pass to read across agent scopes (uses ops API).
 //
-// Federation note: this only deletes on the local instance. ops-esun
-// (federation distributed-delete via tombstones) is the systemic answer for
+// Federation note: this only deletes on the local instance. Federation
+// distributed-delete via tombstones is the systemic answer for
 // fan-out — until that lands, run `flair memory hygiene` on each peer.
 // Exported for unit testing — keeps the predicate logic separable from
 // the CLI plumbing, ops-API fetching, and confirmation flow.
@@ -7498,7 +7948,7 @@ memory.command("hygiene")
     console.log(`\n\n✅ Deleted ${deleted} rows.`);
     console.log("");
     console.log("Note: this is a local-instance delete. Federated peers will keep their copies until");
-    console.log("ops-esun (tombstone-based distributed delete) lands. Until then, run `flair memory");
+    console.log("tombstone-based distributed delete lands. Until then, run `flair memory");
     console.log("hygiene --apply` on each peer to fan out.");
 });
 // ─── flair search (top-level shortcut) ───────────────────────────────────────
@@ -9236,7 +9686,7 @@ presence
 });
 // ─── flair workspace ─────────────────────────────────────────────────────────
 //
-// Coordination write surface (ops-wmgx / Kris #510). `workspace set` writes the
+// Coordination write surface (Kris #510). `workspace set` writes the
 // agent's OWN WorkspaceState via a signed POST /WorkspaceState. Identity comes
 // from the Ed25519 signature — the body carries NO agentId, so an agent can only
 // write as itself (the WorkspaceState.post() handler overwrites agentId from the
@@ -9306,7 +9756,7 @@ workspace
 });
 // ─── flair orgevent ──────────────────────────────────────────────────────────
 //
-// Coordination write surface (ops-wmgx / Kris #510). `orgevent` publishes an
+// Coordination write surface (Kris #510). `orgevent` publishes an
 // OrgEvent ATTRIBUTED to the authenticated agent via a signed POST /OrgEvent.
 // The event's authorId comes from the Ed25519 signature — the body carries NO
 // authorId, so an agent CANNOT forge another agent's events (the OrgEvent.post()
@@ -9389,4 +9839,4 @@ if (import.meta.main) {
     await runCli();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };
+export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, };